[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH 06/11] include/qemu: add documentation for memory callbacks
From: |
Alex Bennée |
Subject: |
[PATCH 06/11] include/qemu: add documentation for memory callbacks |
Date: |
Fri, 10 Mar 2023 10:31:18 +0000 |
Some API documentation was missed, rectify that.
Fixes: https://gitlab.com/qemu-project/qemu/-/issues/1497
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
include/qemu/qemu-plugin.h | 47 ++++++++++++++++++++++++++++++++++----
1 file changed, 43 insertions(+), 4 deletions(-)
diff --git a/include/qemu/qemu-plugin.h b/include/qemu/qemu-plugin.h
index d0e9d03adf..50a9957279 100644
--- a/include/qemu/qemu-plugin.h
+++ b/include/qemu/qemu-plugin.h
@@ -481,17 +481,56 @@ uint64_t qemu_plugin_hwaddr_phys_addr(const struct
qemu_plugin_hwaddr *haddr);
*/
const char *qemu_plugin_hwaddr_device_name(const struct qemu_plugin_hwaddr *h);
-typedef void
-(*qemu_plugin_vcpu_mem_cb_t)(unsigned int vcpu_index,
- qemu_plugin_meminfo_t info, uint64_t vaddr,
- void *userdata);
+/**
+ * typedef qemu_plugin_vcpu_mem_cb_t - memory callback function type
+ * @vcpu_index: the executing vCPU
+ * @info: an opaque handle for further queries about the memory
+ * @vaddr: the virtual address of the transaction
+ * @userdata: any user data attached to the callback
+ */
+typedef void (*qemu_plugin_vcpu_mem_cb_t) (unsigned int vcpu_index,
+ qemu_plugin_meminfo_t info,
+ uint64_t vaddr,
+ void *userdata);
+/**
+ * qemu_plugin_register_vcpu_mem_cb() - register memory access callback
+ * @insn: handle for instruction to instrument
+ * @cb: callback of type qemu_plugin_vcpu_mem_cb_t
+ * @flags: (currently unused) callback flags
+ * @rw: monitor reads, writes or both
+ * @userdata: opaque pointer for userdata
+ *
+ * This registers a full callback for every memory access generated by
+ * an instruction. If the instruction doesn't access memory no
+ * callback will be made.
+ *
+ * The callback reports the vCPU the access took place on, the virtual
+ * address of the access and a handle for further queries. The user
+ * can attach some userdata to the callback for additional purposes.
+ *
+ * Other execution threads will continue to execute during the
+ * callback so the plugin is responsible for ensuring it doesn't get
+ * confused by making appropriate use of locking if required.
+ */
void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn *insn,
qemu_plugin_vcpu_mem_cb_t cb,
enum qemu_plugin_cb_flags flags,
enum qemu_plugin_mem_rw rw,
void *userdata);
+/**
+ * qemu_plugin_register_vcpu_mem_inline() - register an inline op to any
memory access
+ * @insn: handle for instruction to instrument
+ * @rw: apply to reads, writes or both
+ * @op: the op, of type qemu_plugin_op
+ * @ptr: pointer memory for the op
+ * @imm: immediate data for @op
+ *
+ * This registers a inline op every memory access generated by the
+ * instruction. This provides for a lightweight but not thread-safe
+ * way of counting the number of operations done.
+ */
void qemu_plugin_register_vcpu_mem_inline(struct qemu_plugin_insn *insn,
enum qemu_plugin_mem_rw rw,
enum qemu_plugin_op op, void *ptr,
--
2.39.2
- [PATCH 00/11] tweaks and fixes for 8.0-rc1 (tests, plugins, docs), Alex Bennée, 2023/03/10
- [PATCH 01/11] tests/avocado: update AArch64 tests to Alpine 3.17.2, Alex Bennée, 2023/03/10
- [PATCH 02/11] tests/docker: all add DOCKER_BUILDKIT to RUNC environment, Alex Bennée, 2023/03/10
- [PATCH 03/11] scripts/ci: add libslirp-devel to build-environment, Alex Bennée, 2023/03/10
- [PATCH 06/11] include/qemu: add documentation for memory callbacks,
Alex Bennée <=
- [PATCH 09/11] tests/tcg: disable pauth for aarch64 gdb tests, Alex Bennée, 2023/03/10
- Re: [PATCH 09/11] tests/tcg: disable pauth for aarch64 gdb tests, Richard Henderson, 2023/03/10
- Re: [PATCH 09/11] tests/tcg: disable pauth for aarch64 gdb tests, Peter Maydell, 2023/03/10
- Re: [PATCH 09/11] tests/tcg: disable pauth for aarch64 gdb tests, Alex Bennée, 2023/03/10
- Re: [PATCH 09/11] tests/tcg: disable pauth for aarch64 gdb tests, Peter Maydell, 2023/03/13
- Re: [PATCH 09/11] tests/tcg: disable pauth for aarch64 gdb tests, Luis Machado, 2023/03/13