plugins: add missing docstrings to qemu-plugin.h
This patch adds docstrings for typedefs and function declarations in include/plugins/qemu-plugin.h that were previously missing. This resolves inconsistencies in the docs, e.g., the description for qemu_plugin_read_register() referring to qemu_plugin_register_flush_cb() but code cache flush callbacks not being documented themselves. Signed-off-by: Florian Hofhammer <florian.hofhammer@epfl.ch> Reviewed-by: Pierrick Bouvier <pierrick.bouvier@linaro.org> Link: https://lore.kernel.org/qemu-devel/20260311-add-missing-plugin-docs-v3-1-d68b9135e397@epfl.ch Signed-off-by: Pierrick Bouvier <pierrick.bouvier@linaro.org>
Florian Hofhammer committed
Mar 11, 2026 at 11:25 UTC
71b424ca7644e2546da3f07fce3c33980d85602e
1 file changed
+93
-11
include/plugins/qemu-plugin.h
+93
-11
@@ -339,12 +339,28 @@ enum qemu_plugin_cb_flags {
339
QEMU_PLUGIN_CB_RW_REGS_PC,
340
};
341
342
+/**
343
+ * enum qemu_plugin_mem_rw - type of memory access
344
+ *
345
+ * @QEMU_PLUGIN_MEM_R: memory read access only
346
+ * @QEMU_PLUGIN_MEM_W: memory write access only
347
+ * @QEMU_PLUGIN_MEM_RW: memory read and write access
348
+ */
349
enum qemu_plugin_mem_rw {
350
QEMU_PLUGIN_MEM_R = 1,
351
QEMU_PLUGIN_MEM_W,
352
QEMU_PLUGIN_MEM_RW,
353
};
354
355
+/**
356
+ * enum qemu_plugin_mem_value_type - size of memory value
357
+ *
358
+ * @QEMU_PLUGIN_MEM_VALUE_U8: unsigned 8-bit value
359
+ * @QEMU_PLUGIN_MEM_VALUE_U16: unsigned 16-bit value
360
+ * @QEMU_PLUGIN_MEM_VALUE_U32: unsigned 32-bit value
361
+ * @QEMU_PLUGIN_MEM_VALUE_U64: unsigned 64-bit value
362
+ * @QEMU_PLUGIN_MEM_VALUE_U128: unsigned 128-bit value
363
+ */
364
enum qemu_plugin_mem_value_type {
365
QEMU_PLUGIN_MEM_VALUE_U8,
366
QEMU_PLUGIN_MEM_VALUE_U16,
@@ -353,7 +369,13 @@ enum qemu_plugin_mem_value_type {
369
QEMU_PLUGIN_MEM_VALUE_U128,
370
};
371
356
-/* typedef qemu_plugin_mem_value - value accessed during a load/store */
372
+/**
373
+ * typedef qemu_plugin_mem_value - value accessed during a load/store
374
+ *
375
+ * @type: the memory access size
376
+ * @data: the value accessed during the memory operation (value after
377
+ * read/write)
378
+ */
379
typedef struct {
380
enum qemu_plugin_mem_value_type type;
381
union {
@@ -462,7 +484,6 @@ void qemu_plugin_register_vcpu_tb_exec_cond_cb(struct qemu_plugin_tb *tb,
484
* @QEMU_PLUGIN_INLINE_ADD_U64: add an immediate value uint64_t
485
* @QEMU_PLUGIN_INLINE_STORE_U64: store an immediate value uint64_t
486
*/
465
-
487
enum qemu_plugin_op {
488
QEMU_PLUGIN_INLINE_ADD_U64,
489
QEMU_PLUGIN_INLINE_STORE_U64,
@@ -803,6 +824,20 @@ const void *qemu_plugin_request_time_control(void);
824
QEMU_PLUGIN_API
825
void qemu_plugin_update_ns(const void *handle, int64_t time);
826
827
+/**
828
+ * typedef qemu_plugin_vcpu_syscall_cb_t - vCPU syscall callback function type
829
+ * @id: plugin id
830
+ * @vcpu_index: the executing vCPU
831
+ * @num: the syscall number
832
+ * @a1: the 1st syscall argument
833
+ * @a2: the 2nd syscall argument
834
+ * @a3: the 3rd syscall argument
835
+ * @a4: the 4th syscall argument
836
+ * @a5: the 5th syscall argument
837
+ * @a6: the 6th syscall argument
838
+ * @a7: the 7th syscall argument
839
+ * @a8: the 8th syscall argument
840
+ */
841
typedef void
842
(*qemu_plugin_vcpu_syscall_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_index,
843
int64_t num, uint64_t a1, uint64_t a2,
@@ -836,24 +871,62 @@ typedef bool
871
uint64_t a6, uint64_t a7, uint64_t a8,
872
uint64_t *sysret);
873
839
-QEMU_PLUGIN_API
840
-void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id,
841
- qemu_plugin_vcpu_syscall_cb_t cb);
842
-
874
+/**
875
+ * typedef qemu_plugin_vcpu_syscall_ret_cb_t - vCPU syscall return callback
876
+ * function type
877
+ * @id: plugin id
878
+ * @vcpu_index: the executing vCPU
879
+ * @num: the syscall number
880
+ * @ret: the syscall return value
881
+ */
882
typedef void
844
-(*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_idx,
883
+(*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id,
884
+ unsigned int vcpu_index,
885
int64_t num, int64_t ret);
886
887
+/**
888
+ * qemu_plugin_register_vcpu_syscall_cb() - register a syscall entry callback
889
+ * @id: plugin id
890
+ * @cb: callback of type qemu_plugin_vcpu_syscall_cb_t
891
+ *
892
+ * This registers a callback for every syscall executed by the guest. The @cb
893
+ * function is executed before a syscall is handled by the host.
894
+ */
895
QEMU_PLUGIN_API
848
-void
849
-qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id,
850
- qemu_plugin_vcpu_syscall_ret_cb_t cb);
896
+void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id,
897
+ qemu_plugin_vcpu_syscall_cb_t cb);
898
899
+/**
900
+ * qemu_plugin_register_vcpu_syscall_filter_cb() - register a syscall filter
901
+ * callback
902
+ * @id: plugin id
903
+ * @cb: callback of type qemu_plugin_vcpu_syscall_filter_cb_t
904
+ *
905
+ * This registers a callback for every syscall executed by the guest. The @cb
906
+ * function is executed before a syscall is handled by the host. If the
907
+ * callback returns true, the syscall is filtered and will not be executed by
908
+ * the host. The callback must then set the syscall return value via the
909
+ * corresponding pointer passed to it.
910
+ */
911
QEMU_PLUGIN_API
912
void
913
qemu_plugin_register_vcpu_syscall_filter_cb(qemu_plugin_id_t id,
914
qemu_plugin_vcpu_syscall_filter_cb_t cb);
915
916
+/**
917
+ * qemu_plugin_register_vcpu_syscall_ret_cb() - register a syscall entry
918
+ * callback
919
+ * @id: plugin id
920
+ * @cb: callback of type qemu_plugin_vcpu_syscall_ret_cb_t
921
+ *
922
+ * This registers a callback for every syscall executed by the guest. The @cb
923
+ * function is executed upon return from the host syscall before execution is
924
+ * handed back to the guest.
925
+ */
926
+QEMU_PLUGIN_API
927
+void
928
+qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id,
929
+ qemu_plugin_vcpu_syscall_ret_cb_t cb);
930
931
/**
932
* qemu_plugin_insn_disas() - return disassembly string for instruction
@@ -861,7 +934,6 @@ qemu_plugin_register_vcpu_syscall_filter_cb(qemu_plugin_id_t id,
934
*
935
* Returns an allocated string containing the disassembly
936
*/
864
-
937
QEMU_PLUGIN_API
938
char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn);
939
@@ -888,6 +960,16 @@ QEMU_PLUGIN_API
960
void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id,
961
qemu_plugin_vcpu_simple_cb_t cb);
962
963
+/**
964
+ * qemu_plugin_register_flush_cb() - register code cache flush callback
965
+ * @id: plugin ID
966
+ * @cb: callback
967
+ *
968
+ * The @cb function is called every time the code cache is flushed.
969
+ * The callback can be used to free resources associated with existing
970
+ * translated blocks in a plugin. @cb is guaranteed to run with all cpus being
971
+ * stopped, thus no lock is required within it.
972
+ */
973
QEMU_PLUGIN_API
974
void qemu_plugin_register_flush_cb(qemu_plugin_id_t id,
975
qemu_plugin_simple_cb_t cb);