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
17 * For best performance, build the plugin with -fvisibility=hidden so that
18 * QEMU_PLUGIN_LOCAL is implicit. Then, just mark qemu_plugin_install with
19 * QEMU_PLUGIN_EXPORT. For more info, see
20 * https://gcc.gnu.org/wiki/Visibility
22 #if defined _WIN32 || defined __CYGWIN__
24 #define QEMU_PLUGIN_EXPORT __declspec(dllexport)
26 #define QEMU_PLUGIN_EXPORT __declspec(dllimport)
28 #define QEMU_PLUGIN_LOCAL
31 #define QEMU_PLUGIN_EXPORT __attribute__((visibility("default")))
32 #define QEMU_PLUGIN_LOCAL __attribute__((visibility("hidden")))
34 #define QEMU_PLUGIN_EXPORT
35 #define QEMU_PLUGIN_LOCAL
39 typedef uint64_t qemu_plugin_id_t
;
44 * The plugin API will pass a minimum and current API version that
45 * QEMU currently supports. The minimum API will be incremented if an
46 * API needs to be deprecated.
48 * The plugins export the API they were built against by exposing the
49 * symbol qemu_plugin_version which can be checked.
52 extern QEMU_PLUGIN_EXPORT
int qemu_plugin_version
;
54 #define QEMU_PLUGIN_VERSION 0
57 /* string describing architecture */
58 const char *target_name
;
63 /* is this a full system emulation? */
64 bool system_emulation
;
67 * smp_vcpus may change if vCPUs can be hot-plugged, max_vcpus
68 * is the system-wide limit.
78 * qemu_plugin_install() - Install a plugin
79 * @id: this plugin's opaque ID
80 * @info: a block describing some details about the guest
81 * @argc: number of arguments
82 * @argv: array of arguments (@argc elements)
84 * All plugins must export this symbol.
86 * Note: Calling qemu_plugin_uninstall() from this function is a bug. To raise
87 * an error during install, return !0.
89 * Note: @info is only live during the call. Copy any information we
92 * Note: @argv remains valid throughout the lifetime of the loaded plugin.
94 QEMU_PLUGIN_EXPORT
int qemu_plugin_install(qemu_plugin_id_t id
,
95 const qemu_info_t
*info
,
96 int argc
, char **argv
);
99 * Prototypes for the various callback styles we will be registering
100 * in the following functions.
102 typedef void (*qemu_plugin_simple_cb_t
)(qemu_plugin_id_t id
);
104 typedef void (*qemu_plugin_udata_cb_t
)(qemu_plugin_id_t id
, void *userdata
);
106 typedef void (*qemu_plugin_vcpu_simple_cb_t
)(qemu_plugin_id_t id
,
107 unsigned int vcpu_index
);
109 typedef void (*qemu_plugin_vcpu_udata_cb_t
)(unsigned int vcpu_index
,
113 * qemu_plugin_uninstall() - Uninstall a plugin
114 * @id: this plugin's opaque ID
115 * @cb: callback to be called once the plugin has been removed
117 * Do NOT assume that the plugin has been uninstalled once this function
118 * returns. Plugins are uninstalled asynchronously, and therefore the given
119 * plugin receives callbacks until @cb is called.
121 * Note: Calling this function from qemu_plugin_install() is a bug.
123 void qemu_plugin_uninstall(qemu_plugin_id_t id
, qemu_plugin_simple_cb_t cb
);
126 * qemu_plugin_reset() - Reset a plugin
127 * @id: this plugin's opaque ID
128 * @cb: callback to be called once the plugin has been reset
130 * Unregisters all callbacks for the plugin given by @id.
132 * Do NOT assume that the plugin has been reset once this function returns.
133 * Plugins are reset asynchronously, and therefore the given plugin receives
134 * callbacks until @cb is called.
136 void qemu_plugin_reset(qemu_plugin_id_t id
, qemu_plugin_simple_cb_t cb
);
139 * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback
141 * @cb: callback function
143 * The @cb function is called every time a vCPU is initialized.
145 * See also: qemu_plugin_register_vcpu_exit_cb()
147 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id
,
148 qemu_plugin_vcpu_simple_cb_t cb
);
151 * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback
153 * @cb: callback function
155 * The @cb function is called every time a vCPU exits.
157 * See also: qemu_plugin_register_vcpu_init_cb()
159 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id
,
160 qemu_plugin_vcpu_simple_cb_t cb
);
163 * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback
165 * @cb: callback function
167 * The @cb function is called every time a vCPU idles.
169 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id
,
170 qemu_plugin_vcpu_simple_cb_t cb
);
173 * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback
175 * @cb: callback function
177 * The @cb function is called every time a vCPU resumes execution.
179 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id
,
180 qemu_plugin_vcpu_simple_cb_t cb
);
183 * Opaque types that the plugin is given during the translation and
184 * instrumentation phase.
186 struct qemu_plugin_tb
;
187 struct qemu_plugin_insn
;
189 enum qemu_plugin_cb_flags
{
190 QEMU_PLUGIN_CB_NO_REGS
, /* callback does not access the CPU's regs */
191 QEMU_PLUGIN_CB_R_REGS
, /* callback reads the CPU's regs */
192 QEMU_PLUGIN_CB_RW_REGS
, /* callback reads and writes the CPU's regs */
195 enum qemu_plugin_mem_rw
{
196 QEMU_PLUGIN_MEM_R
= 1,
202 * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb
204 * @cb: callback function
206 * The @cb function is called every time a translation occurs. The @cb
207 * function is passed an opaque qemu_plugin_type which it can query
208 * for additional information including the list of translated
209 * instructions. At this point the plugin can register further
210 * callbacks to be triggered when the block or individual instruction
213 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t
)(qemu_plugin_id_t id
,
214 struct qemu_plugin_tb
*tb
);
216 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id
,
217 qemu_plugin_vcpu_tb_trans_cb_t cb
);
220 * qemu_plugin_register_vcpu_tb_trans_exec_cb() - register execution callback
221 * @tb: the opaque qemu_plugin_tb handle for the translation
222 * @cb: callback function
223 * @flags: does the plugin read or write the CPU's registers?
224 * @userdata: any plugin data to pass to the @cb?
226 * The @cb function is called every time a translated unit executes.
228 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb
*tb
,
229 qemu_plugin_vcpu_udata_cb_t cb
,
230 enum qemu_plugin_cb_flags flags
,
233 enum qemu_plugin_op
{
234 QEMU_PLUGIN_INLINE_ADD_U64
,
238 * qemu_plugin_register_vcpu_tb_trans_exec_inline() - execution inline op
239 * @tb: the opaque qemu_plugin_tb handle for the translation
240 * @op: the type of qemu_plugin_op (e.g. ADD_U64)
241 * @ptr: the target memory location for the op
242 * @imm: the op data (e.g. 1)
244 * Insert an inline op to every time a translated unit executes.
245 * Useful if you just want to increment a single counter somewhere in
248 void qemu_plugin_register_vcpu_tb_exec_inline(struct qemu_plugin_tb
*tb
,
249 enum qemu_plugin_op op
,
250 void *ptr
, uint64_t imm
);
253 * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb
254 * @insn: the opaque qemu_plugin_insn handle for an instruction
255 * @cb: callback function
256 * @flags: does the plugin read or write the CPU's registers?
257 * @userdata: any plugin data to pass to the @cb?
259 * The @cb function is called every time an instruction is executed
261 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn
*insn
,
262 qemu_plugin_vcpu_udata_cb_t cb
,
263 enum qemu_plugin_cb_flags flags
,
267 * qemu_plugin_register_vcpu_insn_exec_inline() - insn execution inline op
268 * @insn: the opaque qemu_plugin_insn handle for an instruction
269 * @cb: callback function
270 * @op: the type of qemu_plugin_op (e.g. ADD_U64)
271 * @ptr: the target memory location for the op
272 * @imm: the op data (e.g. 1)
274 * Insert an inline op to every time an instruction executes. Useful
275 * if you just want to increment a single counter somewhere in memory.
277 void qemu_plugin_register_vcpu_insn_exec_inline(struct qemu_plugin_insn
*insn
,
278 enum qemu_plugin_op op
,
279 void *ptr
, uint64_t imm
);
282 * Helpers to query information about the instructions in a block
284 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb
*tb
);
286 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb
*tb
);
288 struct qemu_plugin_insn
*
289 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb
*tb
, size_t idx
);
291 const void *qemu_plugin_insn_data(const struct qemu_plugin_insn
*insn
);
293 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn
*insn
);
295 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn
*insn
);
296 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn
*insn
);
299 * Memory Instrumentation
301 * The anonymous qemu_plugin_meminfo_t and qemu_plugin_hwaddr types
302 * can be used in queries to QEMU to get more information about a
303 * given memory access.
305 typedef uint32_t qemu_plugin_meminfo_t
;
306 struct qemu_plugin_hwaddr
;
308 /* meminfo queries */
309 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info
);
310 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info
);
311 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info
);
312 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info
);
315 * qemu_plugin_get_hwaddr():
316 * @vaddr: the virtual address of the memory operation
318 * For system emulation returns a qemu_plugin_hwaddr handle to query
319 * details about the actual physical address backing the virtual
320 * address. For linux-user guests it just returns NULL.
322 * This handle is *only* valid for the duration of the callback. Any
323 * information about the handle should be recovered before the
326 struct qemu_plugin_hwaddr
*qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info
,
330 * The following additional queries can be run on the hwaddr structure
331 * to return information about it. For non-IO accesses the device
332 * offset will be into the appropriate block of RAM.
334 bool qemu_plugin_hwaddr_is_io(struct qemu_plugin_hwaddr
*hwaddr
);
335 uint64_t qemu_plugin_hwaddr_device_offset(const struct qemu_plugin_hwaddr
*haddr
);
338 (*qemu_plugin_vcpu_mem_cb_t
)(unsigned int vcpu_index
,
339 qemu_plugin_meminfo_t info
, uint64_t vaddr
,
342 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn
*insn
,
343 qemu_plugin_vcpu_mem_cb_t cb
,
344 enum qemu_plugin_cb_flags flags
,
345 enum qemu_plugin_mem_rw rw
,
348 void qemu_plugin_register_vcpu_mem_inline(struct qemu_plugin_insn
*insn
,
349 enum qemu_plugin_mem_rw rw
,
350 enum qemu_plugin_op op
, void *ptr
,
356 (*qemu_plugin_vcpu_syscall_cb_t
)(qemu_plugin_id_t id
, unsigned int vcpu_index
,
357 int64_t num
, uint64_t a1
, uint64_t a2
,
358 uint64_t a3
, uint64_t a4
, uint64_t a5
,
359 uint64_t a6
, uint64_t a7
, uint64_t a8
);
361 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id
,
362 qemu_plugin_vcpu_syscall_cb_t cb
);
365 (*qemu_plugin_vcpu_syscall_ret_cb_t
)(qemu_plugin_id_t id
, unsigned int vcpu_idx
,
366 int64_t num
, int64_t ret
);
369 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id
,
370 qemu_plugin_vcpu_syscall_ret_cb_t cb
);
374 * qemu_plugin_insn_disas() - return disassembly string for instruction
375 * @insn: instruction reference
377 * Returns an allocated string containing the disassembly
380 char *qemu_plugin_insn_disas(const struct qemu_plugin_insn
*insn
);
383 * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU
385 * @cb: callback function
387 * The @cb function is called once for each existing vCPU.
389 * See also: qemu_plugin_register_vcpu_init_cb()
391 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id
,
392 qemu_plugin_vcpu_simple_cb_t cb
);
394 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id
,
395 qemu_plugin_simple_cb_t cb
);
397 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id
,
398 qemu_plugin_udata_cb_t cb
, void *userdata
);
400 /* returns -1 in user-mode */
401 int qemu_plugin_n_vcpus(void);
403 /* returns -1 in user-mode */
404 int qemu_plugin_n_max_vcpus(void);
407 * qemu_plugin_outs() - output string via QEMU's logging system
410 void qemu_plugin_outs(const char *string
);
412 #endif /* QEMU_PLUGIN_API_H */