2 * Copyright (C) 2017, Emilio G. Cota <cota@braap.org>
3 * Copyright (C) 2019, Linaro
5 * License: GNU GPL, version 2 or later.
6 * See the COPYING file in the top-level directory.
8 * SPDX-License-Identifier: GPL-2.0-or-later
10 #ifndef QEMU_PLUGIN_API_H
11 #define QEMU_PLUGIN_API_H
18 * For best performance, build the plugin with -fvisibility=hidden so that
19 * QEMU_PLUGIN_LOCAL is implicit. Then, just mark qemu_plugin_install with
20 * QEMU_PLUGIN_EXPORT. For more info, see
21 * https://gcc.gnu.org/wiki/Visibility
23 #if defined _WIN32 || defined __CYGWIN__
25 #define QEMU_PLUGIN_EXPORT __declspec(dllexport)
27 #define QEMU_PLUGIN_EXPORT __declspec(dllimport)
29 #define QEMU_PLUGIN_LOCAL
31 #define QEMU_PLUGIN_EXPORT __attribute__((visibility("default")))
32 #define QEMU_PLUGIN_LOCAL __attribute__((visibility("hidden")))
35 typedef uint64_t qemu_plugin_id_t
;
40 * The plugin API will pass a minimum and current API version that
41 * QEMU currently supports. The minimum API will be incremented if an
42 * API needs to be deprecated.
44 * The plugins export the API they were built against by exposing the
45 * symbol qemu_plugin_version which can be checked.
48 extern QEMU_PLUGIN_EXPORT
int qemu_plugin_version
;
50 #define QEMU_PLUGIN_VERSION 0
53 /* string describing architecture */
54 const char *target_name
;
59 /* is this a full system emulation? */
60 bool system_emulation
;
63 * smp_vcpus may change if vCPUs can be hot-plugged, max_vcpus
64 * is the system-wide limit.
74 * qemu_plugin_install() - Install a plugin
75 * @id: this plugin's opaque ID
76 * @info: a block describing some details about the guest
77 * @argc: number of arguments
78 * @argv: array of arguments (@argc elements)
80 * All plugins must export this symbol.
82 * Note: Calling qemu_plugin_uninstall() from this function is a bug. To raise
83 * an error during install, return !0.
85 * Note: @info is only live during the call. Copy any information we
88 * Note: @argv remains valid throughout the lifetime of the loaded plugin.
90 QEMU_PLUGIN_EXPORT
int qemu_plugin_install(qemu_plugin_id_t id
,
91 const qemu_info_t
*info
,
92 int argc
, char **argv
);
95 * Prototypes for the various callback styles we will be registering
96 * in the following functions.
98 typedef void (*qemu_plugin_simple_cb_t
)(qemu_plugin_id_t id
);
100 typedef void (*qemu_plugin_udata_cb_t
)(qemu_plugin_id_t id
, void *userdata
);
102 typedef void (*qemu_plugin_vcpu_simple_cb_t
)(qemu_plugin_id_t id
,
103 unsigned int vcpu_index
);
105 typedef void (*qemu_plugin_vcpu_udata_cb_t
)(unsigned int vcpu_index
,
109 * qemu_plugin_uninstall() - Uninstall a plugin
110 * @id: this plugin's opaque ID
111 * @cb: callback to be called once the plugin has been removed
113 * Do NOT assume that the plugin has been uninstalled once this function
114 * returns. Plugins are uninstalled asynchronously, and therefore the given
115 * plugin receives callbacks until @cb is called.
117 * Note: Calling this function from qemu_plugin_install() is a bug.
119 void qemu_plugin_uninstall(qemu_plugin_id_t id
, qemu_plugin_simple_cb_t cb
);
122 * qemu_plugin_reset() - Reset a plugin
123 * @id: this plugin's opaque ID
124 * @cb: callback to be called once the plugin has been reset
126 * Unregisters all callbacks for the plugin given by @id.
128 * Do NOT assume that the plugin has been reset once this function returns.
129 * Plugins are reset asynchronously, and therefore the given plugin receives
130 * callbacks until @cb is called.
132 void qemu_plugin_reset(qemu_plugin_id_t id
, qemu_plugin_simple_cb_t cb
);
135 * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback
137 * @cb: callback function
139 * The @cb function is called every time a vCPU is initialized.
141 * See also: qemu_plugin_register_vcpu_exit_cb()
143 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id
,
144 qemu_plugin_vcpu_simple_cb_t cb
);
147 * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback
149 * @cb: callback function
151 * The @cb function is called every time a vCPU exits.
153 * See also: qemu_plugin_register_vcpu_init_cb()
155 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id
,
156 qemu_plugin_vcpu_simple_cb_t cb
);
159 * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback
161 * @cb: callback function
163 * The @cb function is called every time a vCPU idles.
165 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id
,
166 qemu_plugin_vcpu_simple_cb_t cb
);
169 * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback
171 * @cb: callback function
173 * The @cb function is called every time a vCPU resumes execution.
175 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id
,
176 qemu_plugin_vcpu_simple_cb_t cb
);
179 * Opaque types that the plugin is given during the translation and
180 * instrumentation phase.
182 struct qemu_plugin_tb
;
183 struct qemu_plugin_insn
;
185 enum qemu_plugin_cb_flags
{
186 QEMU_PLUGIN_CB_NO_REGS
, /* callback does not access the CPU's regs */
187 QEMU_PLUGIN_CB_R_REGS
, /* callback reads the CPU's regs */
188 QEMU_PLUGIN_CB_RW_REGS
, /* callback reads and writes the CPU's regs */
191 enum qemu_plugin_mem_rw
{
192 QEMU_PLUGIN_MEM_R
= 1,
198 * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb
200 * @cb: callback function
202 * The @cb function is called every time a translation occurs. The @cb
203 * function is passed an opaque qemu_plugin_type which it can query
204 * for additional information including the list of translated
205 * instructions. At this point the plugin can register further
206 * callbacks to be triggered when the block or individual instruction
209 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t
)(qemu_plugin_id_t id
,
210 struct qemu_plugin_tb
*tb
);
212 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id
,
213 qemu_plugin_vcpu_tb_trans_cb_t cb
);
216 * qemu_plugin_register_vcpu_tb_trans_exec_cb() - register execution callback
217 * @tb: the opaque qemu_plugin_tb handle for the translation
218 * @cb: callback function
219 * @flags: does the plugin read or write the CPU's registers?
220 * @userdata: any plugin data to pass to the @cb?
222 * The @cb function is called every time a translated unit executes.
224 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb
*tb
,
225 qemu_plugin_vcpu_udata_cb_t cb
,
226 enum qemu_plugin_cb_flags flags
,
229 enum qemu_plugin_op
{
230 QEMU_PLUGIN_INLINE_ADD_U64
,
234 * qemu_plugin_register_vcpu_tb_trans_exec_inline() - execution inline op
235 * @tb: the opaque qemu_plugin_tb handle for the translation
236 * @op: the type of qemu_plugin_op (e.g. ADD_U64)
237 * @ptr: the target memory location for the op
238 * @imm: the op data (e.g. 1)
240 * Insert an inline op to every time a translated unit executes.
241 * Useful if you just want to increment a single counter somewhere in
244 void qemu_plugin_register_vcpu_tb_exec_inline(struct qemu_plugin_tb
*tb
,
245 enum qemu_plugin_op op
,
246 void *ptr
, uint64_t imm
);
249 * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb
250 * @insn: the opaque qemu_plugin_insn handle for an instruction
251 * @cb: callback function
252 * @flags: does the plugin read or write the CPU's registers?
253 * @userdata: any plugin data to pass to the @cb?
255 * The @cb function is called every time an instruction is executed
257 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn
*insn
,
258 qemu_plugin_vcpu_udata_cb_t cb
,
259 enum qemu_plugin_cb_flags flags
,
263 * qemu_plugin_register_vcpu_insn_exec_inline() - insn execution inline op
264 * @insn: the opaque qemu_plugin_insn handle for an instruction
265 * @cb: callback function
266 * @op: the type of qemu_plugin_op (e.g. ADD_U64)
267 * @ptr: the target memory location for the op
268 * @imm: the op data (e.g. 1)
270 * Insert an inline op to every time an instruction executes. Useful
271 * if you just want to increment a single counter somewhere in memory.
273 void qemu_plugin_register_vcpu_insn_exec_inline(struct qemu_plugin_insn
*insn
,
274 enum qemu_plugin_op op
,
275 void *ptr
, uint64_t imm
);
278 * Helpers to query information about the instructions in a block
280 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb
*tb
);
282 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb
*tb
);
284 struct qemu_plugin_insn
*
285 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb
*tb
, size_t idx
);
287 const void *qemu_plugin_insn_data(const struct qemu_plugin_insn
*insn
);
289 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn
*insn
);
291 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn
*insn
);
292 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn
*insn
);
295 * Memory Instrumentation
297 * The anonymous qemu_plugin_meminfo_t and qemu_plugin_hwaddr types
298 * can be used in queries to QEMU to get more information about a
299 * given memory access.
301 typedef uint32_t qemu_plugin_meminfo_t
;
302 struct qemu_plugin_hwaddr
;
304 /* meminfo queries */
305 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info
);
306 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info
);
307 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info
);
308 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info
);
311 * qemu_plugin_get_hwaddr():
312 * @vaddr: the virtual address of the memory operation
314 * For system emulation returns a qemu_plugin_hwaddr handle to query
315 * details about the actual physical address backing the virtual
316 * address. For linux-user guests it just returns NULL.
318 * This handle is *only* valid for the duration of the callback. Any
319 * information about the handle should be recovered before the
322 struct qemu_plugin_hwaddr
*qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info
,
326 * The following additional queries can be run on the hwaddr structure
327 * to return information about it. For non-IO accesses the device
328 * offset will be into the appropriate block of RAM.
330 bool qemu_plugin_hwaddr_is_io(const struct qemu_plugin_hwaddr
*haddr
);
331 uint64_t qemu_plugin_hwaddr_device_offset(const struct qemu_plugin_hwaddr
*haddr
);
334 * Returns a string representing the device. The string is valid for
335 * the lifetime of the plugin.
337 const char *qemu_plugin_hwaddr_device_name(const struct qemu_plugin_hwaddr
*h
);
340 (*qemu_plugin_vcpu_mem_cb_t
)(unsigned int vcpu_index
,
341 qemu_plugin_meminfo_t info
, uint64_t vaddr
,
344 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn
*insn
,
345 qemu_plugin_vcpu_mem_cb_t cb
,
346 enum qemu_plugin_cb_flags flags
,
347 enum qemu_plugin_mem_rw rw
,
350 void qemu_plugin_register_vcpu_mem_inline(struct qemu_plugin_insn
*insn
,
351 enum qemu_plugin_mem_rw rw
,
352 enum qemu_plugin_op op
, void *ptr
,
358 (*qemu_plugin_vcpu_syscall_cb_t
)(qemu_plugin_id_t id
, unsigned int vcpu_index
,
359 int64_t num
, uint64_t a1
, uint64_t a2
,
360 uint64_t a3
, uint64_t a4
, uint64_t a5
,
361 uint64_t a6
, uint64_t a7
, uint64_t a8
);
363 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id
,
364 qemu_plugin_vcpu_syscall_cb_t cb
);
367 (*qemu_plugin_vcpu_syscall_ret_cb_t
)(qemu_plugin_id_t id
, unsigned int vcpu_idx
,
368 int64_t num
, int64_t ret
);
371 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id
,
372 qemu_plugin_vcpu_syscall_ret_cb_t cb
);
376 * qemu_plugin_insn_disas() - return disassembly string for instruction
377 * @insn: instruction reference
379 * Returns an allocated string containing the disassembly
382 char *qemu_plugin_insn_disas(const struct qemu_plugin_insn
*insn
);
385 * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU
387 * @cb: callback function
389 * The @cb function is called once for each existing vCPU.
391 * See also: qemu_plugin_register_vcpu_init_cb()
393 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id
,
394 qemu_plugin_vcpu_simple_cb_t cb
);
396 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id
,
397 qemu_plugin_simple_cb_t cb
);
399 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id
,
400 qemu_plugin_udata_cb_t cb
, void *userdata
);
402 /* returns -1 in user-mode */
403 int qemu_plugin_n_vcpus(void);
405 /* returns -1 in user-mode */
406 int qemu_plugin_n_max_vcpus(void);
409 * qemu_plugin_outs() - output string via QEMU's logging system
412 void qemu_plugin_outs(const char *string
);
414 #endif /* QEMU_PLUGIN_API_H */