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

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

[Florian Hofhammer]

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>
---
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!

Best regards,
Florian

Changes in v2:
- Added semantics clarification to the qemu_plugin_register_flush_cb()
  docstring (suggested by Pierrick)
- Link to v1: https://lore.kernel.org/qemu-devel/20260309-add-missing-plugin-docs-v1-1-41dddcd177c8@epfl.ch
---
 include/plugins/qemu-plugin.h | 101 +++++++++++++++++++++++++++++++++++++-----
 1 file changed, 91 insertions(+), 10 deletions(-)

diff --git a/include/plugins/qemu-plugin.h b/include/plugins/qemu-plugin.h
index 827e8e1787..0089e72850 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,16 @@ 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.
+ * The 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

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

[Pierrick Bouvier]

On 3/10/26 12:49 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 <florian.hofhammer@epfl.ch>
> ---
> 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!
> 
> Best regards,
> Florian
> 
> Changes in v2:
> - Added semantics clarification to the qemu_plugin_register_flush_cb()
>    docstring (suggested by Pierrick)
> - Link to v1: https://lore.kernel.org/qemu-devel/20260309-add-missing-plugin-docs-v1-1-41dddcd177c8@epfl.ch
> ---
>   include/plugins/qemu-plugin.h | 101 +++++++++++++++++++++++++++++++++++++-----
>   1 file changed, 91 insertions(+), 10 deletions(-)
> 

Thanks, looks good.
It seems there are warnings (and thus errors) about missing parameters.
Warning: 
/home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h:883 
function parameter 'vcpu_idx' not described in 
'qemu_plugin_vcpu_syscall_ret_cb_t'
Warning: 
/home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h:883 
function parameter 'vcpu_idx' not described in 
'qemu_plugin_vcpu_syscall_ret_cb_t'
WARNING: kernel-doc 
'/home/runner/work/qemu-ci/qemu-ci/build/pyvenv/bin/python3 
/home/runner/work/qemu-ci/qemu-ci/docs/../scripts/kernel-doc.py -rst 
-enable-lineno -Werror 
/home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h'

Could you add those and check doc builds with warnings for v3?

Thanks,
Pierrick

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

[Florian Hofhammer]

On 10/03/2026 20:36, Pierrick Bouvier wrote:
> On 3/10/26 12:49 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 <florian.hofhammer@epfl.ch>
>> ---
>> 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!
>>
>> Best regards,
>> Florian
>>
>> Changes in v2:
>> - Added semantics clarification to the qemu_plugin_register_flush_cb()
>>    docstring (suggested by Pierrick)
>> - Link to v1: https://lore.kernel.org/qemu-devel/20260309-add-missing-plugin-docs-v1-1-41dddcd177c8@epfl.ch
>> ---
>>   include/plugins/qemu-plugin.h | 101 +++++++++++++++++++++++++++++++++++++-----
>>   1 file changed, 91 insertions(+), 10 deletions(-)
>>
> 
> Thanks, looks good.
> It seems there are warnings (and thus errors) about missing parameters.
> Warning: /home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h:883 function parameter 'vcpu_idx' not described in 'qemu_plugin_vcpu_syscall_ret_cb_t'
> Warning: /home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h:883 function parameter 'vcpu_idx' not described in 'qemu_plugin_vcpu_syscall_ret_cb_t'
> WARNING: kernel-doc '/home/runner/work/qemu-ci/qemu-ci/build/pyvenv/bin/python3 /home/runner/work/qemu-ci/qemu-ci/docs/../scripts/kernel-doc.py -rst -enable-lineno -Werror /home/runner/work/qemu-ci/qemu-ci/docs/../include/plugins/qemu-plugin.h'

Hmmm, I should have caught that locally. My apologies! Seems I made a
mistake when copying docstring snippets: other functions use vcpu_index
as a parameter name, but qemu_plugin_vcpu_syscall_ret_cb_t uses
vcpu_idx. I adjusted the parameter name in the v3 series so that it
matches the docstring and the other functions' naming scheme.

> 
> Could you add those and check doc builds with warnings for v3?
> 
> Thanks,
> Pierrick

Best regards,
Florian