Re: [PATCH trivial] plugins: add missing docstrings to qemu-plugin.h

On 3/9/26 9:21 AM, Florian Hofhammer wrote:
> 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 <[email protected]>
> ---
> Hi,
> 
> While working on a QEMU plugin and browsing the online docs at
> https://www.qemu.org/docs/master/devel/tcg-plugins.html, I noticed that
> some of the API functions were not actually documented.
> 
> I went through the include/plugins/qemu-plugin.h header file and added
> docstrings where they were missing, hoping of course that I documented
> the correct functionality based on my understanding of the plugin
> internals.
> 
> I hope that's useful and I didn't miss anything!
>

Thanks for the effort, that's always welcome to add documentation on a 
public API like this!

> Best regards,
> Florian
> 
> --
> Florian Hofhammer
> ---
>   include/plugins/qemu-plugin.h | 98 ++++++++++++++++++++++++++++++++++++++-----
>   1 file changed, 88 insertions(+), 10 deletions(-)
> 
> diff --git a/include/plugins/qemu-plugin.h b/include/plugins/qemu-plugin.h
> index 827e8e1787..fcf5af52ed 100644
> --- a/include/plugins/qemu-plugin.h
> +++ b/include/plugins/qemu-plugin.h
> @@ -339,12 +339,28 @@ enum qemu_plugin_cb_flags {
>       QEMU_PLUGIN_CB_RW_REGS_PC,
>   };
>   
> +/**
> + * enum qemu_plugin_mem_rw - type of memory access
> + *
> + * @QEMU_PLUGIN_MEM_R: memory read access only
> + * @QEMU_PLUGIN_MEM_W: memory write access only
> + * @QEMU_PLUGIN_MEM_RW: memory read and write access
> + */
>   enum qemu_plugin_mem_rw {
>       QEMU_PLUGIN_MEM_R = 1,
>       QEMU_PLUGIN_MEM_W,
>       QEMU_PLUGIN_MEM_RW,
>   };
>   
> +/**
> + * enum qemu_plugin_mem_value_type - size of memory value
> + *
> + * @QEMU_PLUGIN_MEM_VALUE_U8: unsigned 8-bit value
> + * @QEMU_PLUGIN_MEM_VALUE_U16: unsigned 16-bit value
> + * @QEMU_PLUGIN_MEM_VALUE_U32: unsigned 32-bit value
> + * @QEMU_PLUGIN_MEM_VALUE_U64: unsigned 64-bit value
> + * @QEMU_PLUGIN_MEM_VALUE_U128: unsigned 128-bit value
> + */
>   enum qemu_plugin_mem_value_type {
>       QEMU_PLUGIN_MEM_VALUE_U8,
>       QEMU_PLUGIN_MEM_VALUE_U16,
> @@ -353,7 +369,13 @@ enum qemu_plugin_mem_value_type {
>       QEMU_PLUGIN_MEM_VALUE_U128,
>   };
>   
> -/* typedef qemu_plugin_mem_value - value accessed during a load/store */
> +/**
> + * typedef qemu_plugin_mem_value - value accessed during a load/store
> + *
> + * @type: the memory access size
> + * @data: the value accessed during the memory operation (value after
> + *        read/write)
> + */
>   typedef struct {
>       enum qemu_plugin_mem_value_type type;
>       union {
> @@ -462,7 +484,6 @@ void qemu_plugin_register_vcpu_tb_exec_cond_cb(struct qemu_plugin_tb *tb,
>    * @QEMU_PLUGIN_INLINE_ADD_U64: add an immediate value uint64_t
>    * @QEMU_PLUGIN_INLINE_STORE_U64: store an immediate value uint64_t
>    */
> -
>   enum qemu_plugin_op {
>       QEMU_PLUGIN_INLINE_ADD_U64,
>       QEMU_PLUGIN_INLINE_STORE_U64,
> @@ -803,6 +824,20 @@ const void *qemu_plugin_request_time_control(void);
>   QEMU_PLUGIN_API
>   void qemu_plugin_update_ns(const void *handle, int64_t time);
>   
> +/**
> + * typedef qemu_plugin_vcpu_syscall_cb_t - vCPU syscall callback function type
> + * @id: plugin id
> + * @vcpu_index: the executing vCPU
> + * @num: the syscall number
> + * @a1: the 1st syscall argument
> + * @a2: the 2nd syscall argument
> + * @a3: the 3rd syscall argument
> + * @a4: the 4th syscall argument
> + * @a5: the 5th syscall argument
> + * @a6: the 6th syscall argument
> + * @a7: the 7th syscall argument
> + * @a8: the 8th syscall argument
> + */
>   typedef void
>   (*qemu_plugin_vcpu_syscall_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_index,
>                                    int64_t num, uint64_t a1, uint64_t a2,
> @@ -836,24 +871,61 @@ typedef bool
>                                           uint64_t a6, uint64_t a7, uint64_t a8,
>                                           uint64_t *sysret);
>   
> -QEMU_PLUGIN_API
> -void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id,
> -                                          qemu_plugin_vcpu_syscall_cb_t cb);
> -
> +/**
> + * typedef qemu_plugin_vcpu_syscall_ret_cb_t - vCPU syscall return callback
> + * function type
> + * @id: plugin id
> + * @vcpu_index: the executing vCPU
> + * @num: the syscall number
> + * @ret: the syscall return value
> + */
>   typedef void
>   (*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_idx,
>                                        int64_t num, int64_t ret);
>   
> +/**
> + * qemu_plugin_register_vcpu_syscall_cb() - register a syscall entry callback
> + * @id: plugin id
> + * @cb: callback of type qemu_plugin_vcpu_syscall_cb_t
> + *
> + * This registers a callback for every syscall executed by the guest. The @cb
> + * function is executed before a syscall is handled by the host.
> + */
>   QEMU_PLUGIN_API
> -void
> -qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id,
> -                                         qemu_plugin_vcpu_syscall_ret_cb_t cb);
> +void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id,
> +                                          qemu_plugin_vcpu_syscall_cb_t cb);
>   
> +/**
> + * qemu_plugin_register_vcpu_syscall_filter_cb() - register a syscall filter
> + * callback
> + * @id: plugin id
> + * @cb: callback of type qemu_plugin_vcpu_syscall_filter_cb_t
> + *
> + * This registers a callback for every syscall executed by the guest. The @cb
> + * function is executed before a syscall is handled by the host. If the
> + * callback returns true, the syscall is filtered and will not be executed by
> + * the host. The callback must then set the syscall return value via the
> + * corresponding pointer passed to it.
> + */
>   QEMU_PLUGIN_API
>   void
>   qemu_plugin_register_vcpu_syscall_filter_cb(qemu_plugin_id_t id,
>                                               qemu_plugin_vcpu_syscall_filter_cb_t cb);
>   
> +/**
> + * qemu_plugin_register_vcpu_syscall_ret_cb() - register a syscall entry
> + * callback
> + * @id: plugin id
> + * @cb: callback of type qemu_plugin_vcpu_syscall_ret_cb_t
> + *
> + * This registers a callback for every syscall executed by the guest. The @cb
> + * function is executed upon return from the host syscall before execution is
> + * handed back to the guest.
> + */
> +QEMU_PLUGIN_API
> +void
> +qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id,
> +                                         qemu_plugin_vcpu_syscall_ret_cb_t cb);
>   
>   /**
>    * qemu_plugin_insn_disas() - return disassembly string for instruction
> @@ -861,7 +933,6 @@ qemu_plugin_register_vcpu_syscall_filter_cb(qemu_plugin_id_t id,
>    *
>    * Returns an allocated string containing the disassembly
>    */
> -
>   QEMU_PLUGIN_API
>   char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn);
>   
> @@ -888,6 +959,13 @@ QEMU_PLUGIN_API
>   void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id,
>                                  qemu_plugin_vcpu_simple_cb_t cb);
>   
> +/**
> + * qemu_plugin_register_flush_cb() - register code cache flush callback
> + * @id: plugin ID
> + * @cb: callback
> + *
> + * The @cb function is called every time the code cache is flushed.
> + */

Thanks, I was thinking to document this since someone asked a question 
on IRC a few weeks ago.

May you add here:
"This callback can be used to free resources associated with existing 
translated blocks in a plugin. @cb is guaranteed to run with all cpus 
being stopped, thus no lock is required within it."

>   QEMU_PLUGIN_API
>   void qemu_plugin_register_flush_cb(qemu_plugin_id_t id,
>                                      qemu_plugin_simple_cb_t cb);
> 
> ---
> base-commit: 7608a95d2e0bd8c8d069ab77824d02586dd94648
> change-id: 20260309-add-missing-plugin-docs-159d7ff315f9
> 

Regards,
Pierrick