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
;
42 /* string describing architecture */
43 const char *target_name
;
44 /* is this a full system emulation? */
45 bool system_emulation
;
48 * smp_vcpus may change if vCPUs can be hot-plugged, max_vcpus
49 * is the system-wide limit.
59 * qemu_plugin_install() - Install a plugin
60 * @id: this plugin's opaque ID
61 * @info: a block describing some details about the guest
62 * @argc: number of arguments
63 * @argv: array of arguments (@argc elements)
65 * All plugins must export this symbol.
67 * Note: Calling qemu_plugin_uninstall() from this function is a bug. To raise
68 * an error during install, return !0.
70 * Note: @info is only live during the call. Copy any information we
73 * Note: @argv remains valid throughout the lifetime of the loaded plugin.
75 QEMU_PLUGIN_EXPORT
int qemu_plugin_install(qemu_plugin_id_t id
,
76 const qemu_info_t
*info
,
77 int argc
, char **argv
);
80 * Prototypes for the various callback styles we will be registering
81 * in the following functions.
83 typedef void (*qemu_plugin_simple_cb_t
)(qemu_plugin_id_t id
);
85 typedef void (*qemu_plugin_udata_cb_t
)(qemu_plugin_id_t id
, void *userdata
);
87 typedef void (*qemu_plugin_vcpu_simple_cb_t
)(qemu_plugin_id_t id
,
88 unsigned int vcpu_index
);
90 typedef void (*qemu_plugin_vcpu_udata_cb_t
)(unsigned int vcpu_index
,
94 * qemu_plugin_uninstall() - Uninstall a plugin
95 * @id: this plugin's opaque ID
96 * @cb: callback to be called once the plugin has been removed
98 * Do NOT assume that the plugin has been uninstalled once this function
99 * returns. Plugins are uninstalled asynchronously, and therefore the given
100 * plugin receives callbacks until @cb is called.
102 * Note: Calling this function from qemu_plugin_install() is a bug.
104 void qemu_plugin_uninstall(qemu_plugin_id_t id
, qemu_plugin_simple_cb_t cb
);
107 * qemu_plugin_reset() - Reset a plugin
108 * @id: this plugin's opaque ID
109 * @cb: callback to be called once the plugin has been reset
111 * Unregisters all callbacks for the plugin given by @id.
113 * Do NOT assume that the plugin has been reset once this function returns.
114 * Plugins are reset asynchronously, and therefore the given plugin receives
115 * callbacks until @cb is called.
117 void qemu_plugin_reset(qemu_plugin_id_t id
, qemu_plugin_simple_cb_t cb
);
120 * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback
122 * @cb: callback function
124 * The @cb function is called every time a vCPU is initialized.
126 * See also: qemu_plugin_register_vcpu_exit_cb()
128 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id
,
129 qemu_plugin_vcpu_simple_cb_t cb
);
132 * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback
134 * @cb: callback function
136 * The @cb function is called every time a vCPU exits.
138 * See also: qemu_plugin_register_vcpu_init_cb()
140 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id
,
141 qemu_plugin_vcpu_simple_cb_t cb
);
144 * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback
146 * @cb: callback function
148 * The @cb function is called every time a vCPU idles.
150 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id
,
151 qemu_plugin_vcpu_simple_cb_t cb
);
154 * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback
156 * @cb: callback function
158 * The @cb function is called every time a vCPU resumes execution.
160 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id
,
161 qemu_plugin_vcpu_simple_cb_t cb
);
164 * Opaque types that the plugin is given during the translation and
165 * instrumentation phase.
167 struct qemu_plugin_tb
;
168 struct qemu_plugin_insn
;
170 enum qemu_plugin_cb_flags
{
171 QEMU_PLUGIN_CB_NO_REGS
, /* callback does not access the CPU's regs */
172 QEMU_PLUGIN_CB_R_REGS
, /* callback reads the CPU's regs */
173 QEMU_PLUGIN_CB_RW_REGS
, /* callback reads and writes the CPU's regs */
176 enum qemu_plugin_mem_rw
{
177 QEMU_PLUGIN_MEM_R
= 1,
183 * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb
185 * @cb: callback function
187 * The @cb function is called every time a translation occurs. The @cb
188 * function is passed an opaque qemu_plugin_type which it can query
189 * for additional information including the list of translated
190 * instructions. At this point the plugin can register further
191 * callbacks to be triggered when the block or individual instruction
194 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t
)(qemu_plugin_id_t id
,
195 struct qemu_plugin_tb
*tb
);
197 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id
,
198 qemu_plugin_vcpu_tb_trans_cb_t cb
);
201 * qemu_plugin_register_vcpu_tb_trans_exec_cb() - register execution callback
202 * @tb: the opaque qemu_plugin_tb handle for the translation
203 * @cb: callback function
204 * @flags: does the plugin read or write the CPU's registers?
205 * @userdata: any plugin data to pass to the @cb?
207 * The @cb function is called every time a translated unit executes.
209 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb
*tb
,
210 qemu_plugin_vcpu_udata_cb_t cb
,
211 enum qemu_plugin_cb_flags flags
,
214 enum qemu_plugin_op
{
215 QEMU_PLUGIN_INLINE_ADD_U64
,
219 * qemu_plugin_register_vcpu_tb_trans_exec_inline() - execution inline op
220 * @tb: the opaque qemu_plugin_tb handle for the translation
221 * @op: the type of qemu_plugin_op (e.g. ADD_U64)
222 * @ptr: the target memory location for the op
223 * @imm: the op data (e.g. 1)
225 * Insert an inline op to every time a translated unit executes.
226 * Useful if you just want to increment a single counter somewhere in
229 void qemu_plugin_register_vcpu_tb_exec_inline(struct qemu_plugin_tb
*tb
,
230 enum qemu_plugin_op op
,
231 void *ptr
, uint64_t imm
);
234 * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb
235 * @insn: the opaque qemu_plugin_insn handle for an instruction
236 * @cb: callback function
237 * @flags: does the plugin read or write the CPU's registers?
238 * @userdata: any plugin data to pass to the @cb?
240 * The @cb function is called every time an instruction is executed
242 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn
*insn
,
243 qemu_plugin_vcpu_udata_cb_t cb
,
244 enum qemu_plugin_cb_flags flags
,
248 * qemu_plugin_register_vcpu_insn_exec_inline() - insn execution inline op
249 * @insn: the opaque qemu_plugin_insn handle for an instruction
250 * @cb: callback function
251 * @op: the type of qemu_plugin_op (e.g. ADD_U64)
252 * @ptr: the target memory location for the op
253 * @imm: the op data (e.g. 1)
255 * Insert an inline op to every time an instruction executes. Useful
256 * if you just want to increment a single counter somewhere in memory.
258 void qemu_plugin_register_vcpu_insn_exec_inline(struct qemu_plugin_insn
*insn
,
259 enum qemu_plugin_op op
,
260 void *ptr
, uint64_t imm
);
263 * Helpers to query information about the instructions in a block
265 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb
*tb
);
267 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb
*tb
);
269 struct qemu_plugin_insn
*
270 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb
*tb
, size_t idx
);
272 const void *qemu_plugin_insn_data(const struct qemu_plugin_insn
*insn
);
274 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn
*insn
);
276 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn
*insn
);
277 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn
*insn
);
280 * Memory Instrumentation
282 * The anonymous qemu_plugin_meminfo_t and qemu_plugin_hwaddr types
283 * can be used in queries to QEMU to get more information about a
284 * given memory access.
286 typedef uint32_t qemu_plugin_meminfo_t
;
287 struct qemu_plugin_hwaddr
;
289 /* meminfo queries */
290 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info
);
291 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info
);
292 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info
);
293 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info
);
296 * qemu_plugin_get_hwaddr():
297 * @vaddr: the virtual address of the memory operation
299 * For system emulation returns a qemu_plugin_hwaddr handle to query
300 * details about the actual physical address backing the virtual
301 * address. For linux-user guests it just returns NULL.
303 * This handle is *only* valid for the duration of the callback. Any
304 * information about the handle should be recovered before the
307 struct qemu_plugin_hwaddr
*qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info
,
311 * The following additional queries can be run on the hwaddr structure
312 * to return information about it. For non-IO accesses the device
313 * offset will be into the appropriate block of RAM.
315 bool qemu_plugin_hwaddr_is_io(struct qemu_plugin_hwaddr
*hwaddr
);
316 uint64_t qemu_plugin_hwaddr_device_offset(const struct qemu_plugin_hwaddr
*haddr
);
319 (*qemu_plugin_vcpu_mem_cb_t
)(unsigned int vcpu_index
,
320 qemu_plugin_meminfo_t info
, uint64_t vaddr
,
323 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn
*insn
,
324 qemu_plugin_vcpu_mem_cb_t cb
,
325 enum qemu_plugin_cb_flags flags
,
326 enum qemu_plugin_mem_rw rw
,
329 void qemu_plugin_register_vcpu_mem_inline(struct qemu_plugin_insn
*insn
,
330 enum qemu_plugin_mem_rw rw
,
331 enum qemu_plugin_op op
, void *ptr
,
337 (*qemu_plugin_vcpu_syscall_cb_t
)(qemu_plugin_id_t id
, unsigned int vcpu_index
,
338 int64_t num
, uint64_t a1
, uint64_t a2
,
339 uint64_t a3
, uint64_t a4
, uint64_t a5
,
340 uint64_t a6
, uint64_t a7
, uint64_t a8
);
342 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id
,
343 qemu_plugin_vcpu_syscall_cb_t cb
);
346 (*qemu_plugin_vcpu_syscall_ret_cb_t
)(qemu_plugin_id_t id
, unsigned int vcpu_idx
,
347 int64_t num
, int64_t ret
);
350 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id
,
351 qemu_plugin_vcpu_syscall_ret_cb_t cb
);
355 * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU
357 * @cb: callback function
359 * The @cb function is called once for each existing vCPU.
361 * See also: qemu_plugin_register_vcpu_init_cb()
363 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id
,
364 qemu_plugin_vcpu_simple_cb_t cb
);
366 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id
,
367 qemu_plugin_simple_cb_t cb
);
369 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id
,
370 qemu_plugin_udata_cb_t cb
, void *userdata
);
372 /* returns -1 in user-mode */
373 int qemu_plugin_n_vcpus(void);
375 /* returns -1 in user-mode */
376 int qemu_plugin_n_max_vcpus(void);
378 #endif /* QEMU_PLUGIN_API_H */