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

On 09/03/2026 18:25, Pierrick Bouvier wrote:
> 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!

No worries, it's also helping myself when I look up the APIs :)

> 
>> 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."

Ok, thanks for the clarification! I wasn't aware of those detailed
semantics, will add 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

Best regards,
Florian