xref: /openbmc/qemu/include/qemu/qemu-plugin.h (revision 847a65dd)
1 /*
2  * Copyright (C) 2017, Emilio G. Cota <cota@braap.org>
3  * Copyright (C) 2019, Linaro
4  *
5  * License: GNU GPL, version 2 or later.
6  *   See the COPYING file in the top-level directory.
7  *
8  * SPDX-License-Identifier: GPL-2.0-or-later
9  */
10 
11 #ifndef QEMU_QEMU_PLUGIN_H
12 #define QEMU_QEMU_PLUGIN_H
13 
14 #include <glib.h>
15 #include <inttypes.h>
16 #include <stdbool.h>
17 #include <stddef.h>
18 
19 /*
20  * For best performance, build the plugin with -fvisibility=hidden so that
21  * QEMU_PLUGIN_LOCAL is implicit. Then, just mark qemu_plugin_install with
22  * QEMU_PLUGIN_EXPORT. For more info, see
23  *   https://gcc.gnu.org/wiki/Visibility
24  */
25 #if defined _WIN32 || defined __CYGWIN__
26   #ifdef CONFIG_PLUGIN
27     #define QEMU_PLUGIN_EXPORT __declspec(dllimport)
28     #define QEMU_PLUGIN_API __declspec(dllexport)
29   #else
30     #define QEMU_PLUGIN_EXPORT __declspec(dllexport)
31     #define QEMU_PLUGIN_API __declspec(dllimport)
32   #endif
33   #define QEMU_PLUGIN_LOCAL
34 #else
35   #define QEMU_PLUGIN_EXPORT __attribute__((visibility("default")))
36   #define QEMU_PLUGIN_LOCAL  __attribute__((visibility("hidden")))
37   #define QEMU_PLUGIN_API
38 #endif
39 
40 /**
41  * typedef qemu_plugin_id_t - Unique plugin ID
42  */
43 typedef uint64_t qemu_plugin_id_t;
44 
45 /*
46  * Versioning plugins:
47  *
48  * The plugin API will pass a minimum and current API version that
49  * QEMU currently supports. The minimum API will be incremented if an
50  * API needs to be deprecated.
51  *
52  * The plugins export the API they were built against by exposing the
53  * symbol qemu_plugin_version which can be checked.
54  *
55  * version 2:
56  * - removed qemu_plugin_n_vcpus and qemu_plugin_n_max_vcpus
57  * - Remove qemu_plugin_register_vcpu_{tb, insn, mem}_exec_inline.
58  *   Those functions are replaced by *_per_vcpu variants, which guarantee
59  *   thread-safety for operations.
60  */
61 
62 extern QEMU_PLUGIN_EXPORT int qemu_plugin_version;
63 
64 #define QEMU_PLUGIN_VERSION 3
65 
66 /**
67  * struct qemu_info_t - system information for plugins
68  *
69  * This structure provides for some limited information about the
70  * system to allow the plugin to make decisions on how to proceed. For
71  * example it might only be suitable for running on some guest
72  * architectures or when under full system emulation.
73  */
74 typedef struct qemu_info_t {
75     /** @target_name: string describing architecture */
76     const char *target_name;
77     /** @version: minimum and current plugin API level */
78     struct {
79         int min;
80         int cur;
81     } version;
82     /** @system_emulation: is this a full system emulation? */
83     bool system_emulation;
84     union {
85         /** @system: information relevant to system emulation */
86         struct {
87             /** @system.smp_vcpus: initial number of vCPUs */
88             int smp_vcpus;
89             /** @system.max_vcpus: maximum possible number of vCPUs */
90             int max_vcpus;
91         } system;
92     };
93 } qemu_info_t;
94 
95 /**
96  * qemu_plugin_install() - Install a plugin
97  * @id: this plugin's opaque ID
98  * @info: a block describing some details about the guest
99  * @argc: number of arguments
100  * @argv: array of arguments (@argc elements)
101  *
102  * All plugins must export this symbol which is called when the plugin
103  * is first loaded. Calling qemu_plugin_uninstall() from this function
104  * is a bug.
105  *
106  * Note: @info is only live during the call. Copy any information we
107  * want to keep. @argv remains valid throughout the lifetime of the
108  * loaded plugin.
109  *
110  * Return: 0 on successful loading, !0 for an error.
111  */
112 QEMU_PLUGIN_EXPORT int qemu_plugin_install(qemu_plugin_id_t id,
113                                            const qemu_info_t *info,
114                                            int argc, char **argv);
115 
116 /**
117  * typedef qemu_plugin_simple_cb_t - simple callback
118  * @id: the unique qemu_plugin_id_t
119  *
120  * This callback passes no information aside from the unique @id.
121  */
122 typedef void (*qemu_plugin_simple_cb_t)(qemu_plugin_id_t id);
123 
124 /**
125  * typedef qemu_plugin_udata_cb_t - callback with user data
126  * @id: the unique qemu_plugin_id_t
127  * @userdata: a pointer to some user data supplied when the callback
128  * was registered.
129  */
130 typedef void (*qemu_plugin_udata_cb_t)(qemu_plugin_id_t id, void *userdata);
131 
132 /**
133  * typedef qemu_plugin_vcpu_simple_cb_t - vcpu callback
134  * @id: the unique qemu_plugin_id_t
135  * @vcpu_index: the current vcpu context
136  */
137 typedef void (*qemu_plugin_vcpu_simple_cb_t)(qemu_plugin_id_t id,
138                                              unsigned int vcpu_index);
139 
140 /**
141  * typedef qemu_plugin_vcpu_udata_cb_t - vcpu callback
142  * @vcpu_index: the current vcpu context
143  * @userdata: a pointer to some user data supplied when the callback
144  * was registered.
145  */
146 typedef void (*qemu_plugin_vcpu_udata_cb_t)(unsigned int vcpu_index,
147                                             void *userdata);
148 
149 /**
150  * qemu_plugin_uninstall() - Uninstall a plugin
151  * @id: this plugin's opaque ID
152  * @cb: callback to be called once the plugin has been removed
153  *
154  * Do NOT assume that the plugin has been uninstalled once this function
155  * returns. Plugins are uninstalled asynchronously, and therefore the given
156  * plugin receives callbacks until @cb is called.
157  *
158  * Note: Calling this function from qemu_plugin_install() is a bug.
159  */
160 QEMU_PLUGIN_API
161 void qemu_plugin_uninstall(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb);
162 
163 /**
164  * qemu_plugin_reset() - Reset a plugin
165  * @id: this plugin's opaque ID
166  * @cb: callback to be called once the plugin has been reset
167  *
168  * Unregisters all callbacks for the plugin given by @id.
169  *
170  * Do NOT assume that the plugin has been reset once this function returns.
171  * Plugins are reset asynchronously, and therefore the given plugin receives
172  * callbacks until @cb is called.
173  */
174 QEMU_PLUGIN_API
175 void qemu_plugin_reset(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb);
176 
177 /**
178  * qemu_plugin_register_vcpu_init_cb() - register a vCPU initialization callback
179  * @id: plugin ID
180  * @cb: callback function
181  *
182  * The @cb function is called every time a vCPU is initialized.
183  *
184  * See also: qemu_plugin_register_vcpu_exit_cb()
185  */
186 QEMU_PLUGIN_API
187 void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id,
188                                        qemu_plugin_vcpu_simple_cb_t cb);
189 
190 /**
191  * qemu_plugin_register_vcpu_exit_cb() - register a vCPU exit callback
192  * @id: plugin ID
193  * @cb: callback function
194  *
195  * The @cb function is called every time a vCPU exits.
196  *
197  * See also: qemu_plugin_register_vcpu_init_cb()
198  */
199 QEMU_PLUGIN_API
200 void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id,
201                                        qemu_plugin_vcpu_simple_cb_t cb);
202 
203 /**
204  * qemu_plugin_register_vcpu_idle_cb() - register a vCPU idle callback
205  * @id: plugin ID
206  * @cb: callback function
207  *
208  * The @cb function is called every time a vCPU idles.
209  */
210 QEMU_PLUGIN_API
211 void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id,
212                                        qemu_plugin_vcpu_simple_cb_t cb);
213 
214 /**
215  * qemu_plugin_register_vcpu_resume_cb() - register a vCPU resume callback
216  * @id: plugin ID
217  * @cb: callback function
218  *
219  * The @cb function is called every time a vCPU resumes execution.
220  */
221 QEMU_PLUGIN_API
222 void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id,
223                                          qemu_plugin_vcpu_simple_cb_t cb);
224 
225 /** struct qemu_plugin_tb - Opaque handle for a translation block */
226 struct qemu_plugin_tb;
227 /** struct qemu_plugin_insn - Opaque handle for a translated instruction */
228 struct qemu_plugin_insn;
229 /** struct qemu_plugin_scoreboard - Opaque handle for a scoreboard */
230 struct qemu_plugin_scoreboard;
231 
232 /**
233  * typedef qemu_plugin_u64 - uint64_t member of an entry in a scoreboard
234  *
235  * This field allows to access a specific uint64_t member in one given entry,
236  * located at a specified offset. Inline operations expect this as entry.
237  */
238 typedef struct {
239     struct qemu_plugin_scoreboard *score;
240     size_t offset;
241 } qemu_plugin_u64;
242 
243 /**
244  * enum qemu_plugin_cb_flags - type of callback
245  *
246  * @QEMU_PLUGIN_CB_NO_REGS: callback does not access the CPU's regs
247  * @QEMU_PLUGIN_CB_R_REGS: callback reads the CPU's regs
248  * @QEMU_PLUGIN_CB_RW_REGS: callback reads and writes the CPU's regs
249  *
250  * Note: currently QEMU_PLUGIN_CB_RW_REGS is unused, plugins cannot change
251  * system register state.
252  */
253 enum qemu_plugin_cb_flags {
254     QEMU_PLUGIN_CB_NO_REGS,
255     QEMU_PLUGIN_CB_R_REGS,
256     QEMU_PLUGIN_CB_RW_REGS,
257 };
258 
259 enum qemu_plugin_mem_rw {
260     QEMU_PLUGIN_MEM_R = 1,
261     QEMU_PLUGIN_MEM_W,
262     QEMU_PLUGIN_MEM_RW,
263 };
264 
265 /**
266  * enum qemu_plugin_cond - condition to enable callback
267  *
268  * @QEMU_PLUGIN_COND_NEVER: false
269  * @QEMU_PLUGIN_COND_ALWAYS: true
270  * @QEMU_PLUGIN_COND_EQ: is equal?
271  * @QEMU_PLUGIN_COND_NE: is not equal?
272  * @QEMU_PLUGIN_COND_LT: is less than?
273  * @QEMU_PLUGIN_COND_LE: is less than or equal?
274  * @QEMU_PLUGIN_COND_GT: is greater than?
275  * @QEMU_PLUGIN_COND_GE: is greater than or equal?
276  */
277 enum qemu_plugin_cond {
278     QEMU_PLUGIN_COND_NEVER,
279     QEMU_PLUGIN_COND_ALWAYS,
280     QEMU_PLUGIN_COND_EQ,
281     QEMU_PLUGIN_COND_NE,
282     QEMU_PLUGIN_COND_LT,
283     QEMU_PLUGIN_COND_LE,
284     QEMU_PLUGIN_COND_GT,
285     QEMU_PLUGIN_COND_GE,
286 };
287 
288 /**
289  * typedef qemu_plugin_vcpu_tb_trans_cb_t - translation callback
290  * @id: unique plugin id
291  * @tb: opaque handle used for querying and instrumenting a block.
292  */
293 typedef void (*qemu_plugin_vcpu_tb_trans_cb_t)(qemu_plugin_id_t id,
294                                                struct qemu_plugin_tb *tb);
295 
296 /**
297  * qemu_plugin_register_vcpu_tb_trans_cb() - register a translate cb
298  * @id: plugin ID
299  * @cb: callback function
300  *
301  * The @cb function is called every time a translation occurs. The @cb
302  * function is passed an opaque qemu_plugin_type which it can query
303  * for additional information including the list of translated
304  * instructions. At this point the plugin can register further
305  * callbacks to be triggered when the block or individual instruction
306  * executes.
307  */
308 QEMU_PLUGIN_API
309 void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id,
310                                            qemu_plugin_vcpu_tb_trans_cb_t cb);
311 
312 /**
313  * qemu_plugin_register_vcpu_tb_exec_cb() - register execution callback
314  * @tb: the opaque qemu_plugin_tb handle for the translation
315  * @cb: callback function
316  * @flags: does the plugin read or write the CPU's registers?
317  * @userdata: any plugin data to pass to the @cb?
318  *
319  * The @cb function is called every time a translated unit executes.
320  */
321 QEMU_PLUGIN_API
322 void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb *tb,
323                                           qemu_plugin_vcpu_udata_cb_t cb,
324                                           enum qemu_plugin_cb_flags flags,
325                                           void *userdata);
326 
327 /**
328  * qemu_plugin_register_vcpu_tb_exec_cond_cb() - register conditional callback
329  * @tb: the opaque qemu_plugin_tb handle for the translation
330  * @cb: callback function
331  * @cond: condition to enable callback
332  * @entry: first operand for condition
333  * @imm: second operand for condition
334  * @flags: does the plugin read or write the CPU's registers?
335  * @userdata: any plugin data to pass to the @cb?
336  *
337  * The @cb function is called when a translated unit executes if
338  * entry @cond imm is true.
339  * If condition is QEMU_PLUGIN_COND_ALWAYS, condition is never interpreted and
340  * this function is equivalent to qemu_plugin_register_vcpu_tb_exec_cb.
341  * If condition QEMU_PLUGIN_COND_NEVER, condition is never interpreted and
342  * callback is never installed.
343  */
344 QEMU_PLUGIN_API
345 void qemu_plugin_register_vcpu_tb_exec_cond_cb(struct qemu_plugin_tb *tb,
346                                                qemu_plugin_vcpu_udata_cb_t cb,
347                                                enum qemu_plugin_cb_flags flags,
348                                                enum qemu_plugin_cond cond,
349                                                qemu_plugin_u64 entry,
350                                                uint64_t imm,
351                                                void *userdata);
352 
353 /**
354  * enum qemu_plugin_op - describes an inline op
355  *
356  * @QEMU_PLUGIN_INLINE_ADD_U64: add an immediate value uint64_t
357  * @QEMU_PLUGIN_INLINE_STORE_U64: store an immediate value uint64_t
358  */
359 
360 enum qemu_plugin_op {
361     QEMU_PLUGIN_INLINE_ADD_U64,
362     QEMU_PLUGIN_INLINE_STORE_U64,
363 };
364 
365 /**
366  * qemu_plugin_register_vcpu_tb_exec_inline_per_vcpu() - execution inline op
367  * @tb: the opaque qemu_plugin_tb handle for the translation
368  * @op: the type of qemu_plugin_op (e.g. ADD_U64)
369  * @entry: entry to run op
370  * @imm: the op data (e.g. 1)
371  *
372  * Insert an inline op on a given scoreboard entry.
373  */
374 QEMU_PLUGIN_API
375 void qemu_plugin_register_vcpu_tb_exec_inline_per_vcpu(
376     struct qemu_plugin_tb *tb,
377     enum qemu_plugin_op op,
378     qemu_plugin_u64 entry,
379     uint64_t imm);
380 
381 /**
382  * qemu_plugin_register_vcpu_insn_exec_cb() - register insn execution cb
383  * @insn: the opaque qemu_plugin_insn handle for an instruction
384  * @cb: callback function
385  * @flags: does the plugin read or write the CPU's registers?
386  * @userdata: any plugin data to pass to the @cb?
387  *
388  * The @cb function is called every time an instruction is executed
389  */
390 QEMU_PLUGIN_API
391 void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn *insn,
392                                             qemu_plugin_vcpu_udata_cb_t cb,
393                                             enum qemu_plugin_cb_flags flags,
394                                             void *userdata);
395 
396 /**
397  * qemu_plugin_register_vcpu_insn_exec_cond_cb() - conditional insn execution cb
398  * @insn: the opaque qemu_plugin_insn handle for an instruction
399  * @cb: callback function
400  * @flags: does the plugin read or write the CPU's registers?
401  * @cond: condition to enable callback
402  * @entry: first operand for condition
403  * @imm: second operand for condition
404  * @userdata: any plugin data to pass to the @cb?
405  *
406  * The @cb function is called when an instruction executes if
407  * entry @cond imm is true.
408  * If condition is QEMU_PLUGIN_COND_ALWAYS, condition is never interpreted and
409  * this function is equivalent to qemu_plugin_register_vcpu_insn_exec_cb.
410  * If condition QEMU_PLUGIN_COND_NEVER, condition is never interpreted and
411  * callback is never installed.
412  */
413 QEMU_PLUGIN_API
414 void qemu_plugin_register_vcpu_insn_exec_cond_cb(
415     struct qemu_plugin_insn *insn,
416     qemu_plugin_vcpu_udata_cb_t cb,
417     enum qemu_plugin_cb_flags flags,
418     enum qemu_plugin_cond cond,
419     qemu_plugin_u64 entry,
420     uint64_t imm,
421     void *userdata);
422 
423 /**
424  * qemu_plugin_register_vcpu_insn_exec_inline_per_vcpu() - insn exec inline op
425  * @insn: the opaque qemu_plugin_insn handle for an instruction
426  * @op: the type of qemu_plugin_op (e.g. ADD_U64)
427  * @entry: entry to run op
428  * @imm: the op data (e.g. 1)
429  *
430  * Insert an inline op to every time an instruction executes.
431  */
432 QEMU_PLUGIN_API
433 void qemu_plugin_register_vcpu_insn_exec_inline_per_vcpu(
434     struct qemu_plugin_insn *insn,
435     enum qemu_plugin_op op,
436     qemu_plugin_u64 entry,
437     uint64_t imm);
438 
439 /**
440  * qemu_plugin_tb_n_insns() - query helper for number of insns in TB
441  * @tb: opaque handle to TB passed to callback
442  *
443  * Returns: number of instructions in this block
444  */
445 QEMU_PLUGIN_API
446 size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb *tb);
447 
448 /**
449  * qemu_plugin_tb_vaddr() - query helper for vaddr of TB start
450  * @tb: opaque handle to TB passed to callback
451  *
452  * Returns: virtual address of block start
453  */
454 QEMU_PLUGIN_API
455 uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb *tb);
456 
457 /**
458  * qemu_plugin_tb_get_insn() - retrieve handle for instruction
459  * @tb: opaque handle to TB passed to callback
460  * @idx: instruction number, 0 indexed
461  *
462  * The returned handle can be used in follow up helper queries as well
463  * as when instrumenting an instruction. It is only valid for the
464  * lifetime of the callback.
465  *
466  * Returns: opaque handle to instruction
467  */
468 QEMU_PLUGIN_API
469 struct qemu_plugin_insn *
470 qemu_plugin_tb_get_insn(const struct qemu_plugin_tb *tb, size_t idx);
471 
472 /**
473  * qemu_plugin_insn_data() - copy instruction data
474  * @insn: opaque instruction handle from qemu_plugin_tb_get_insn()
475  * @dest: destination into which data is copied
476  * @len: length of dest
477  *
478  * Returns the number of bytes copied, minimum of @len and insn size.
479  */
480 QEMU_PLUGIN_API
481 size_t qemu_plugin_insn_data(const struct qemu_plugin_insn *insn,
482                              void *dest, size_t len);
483 
484 /**
485  * qemu_plugin_insn_size() - return size of instruction
486  * @insn: opaque instruction handle from qemu_plugin_tb_get_insn()
487  *
488  * Returns: size of instruction in bytes
489  */
490 QEMU_PLUGIN_API
491 size_t qemu_plugin_insn_size(const struct qemu_plugin_insn *insn);
492 
493 /**
494  * qemu_plugin_insn_vaddr() - return vaddr of instruction
495  * @insn: opaque instruction handle from qemu_plugin_tb_get_insn()
496  *
497  * Returns: virtual address of instruction
498  */
499 QEMU_PLUGIN_API
500 uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn *insn);
501 
502 /**
503  * qemu_plugin_insn_haddr() - return hardware addr of instruction
504  * @insn: opaque instruction handle from qemu_plugin_tb_get_insn()
505  *
506  * Returns: hardware (physical) target address of instruction
507  */
508 QEMU_PLUGIN_API
509 void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn *insn);
510 
511 /**
512  * typedef qemu_plugin_meminfo_t - opaque memory transaction handle
513  *
514  * This can be further queried using the qemu_plugin_mem_* query
515  * functions.
516  */
517 typedef uint32_t qemu_plugin_meminfo_t;
518 /** struct qemu_plugin_hwaddr - opaque hw address handle */
519 struct qemu_plugin_hwaddr;
520 
521 /**
522  * qemu_plugin_mem_size_shift() - get size of access
523  * @info: opaque memory transaction handle
524  *
525  * Returns: size of access in ^2 (0=byte, 1=16bit, 2=32bit etc...)
526  */
527 QEMU_PLUGIN_API
528 unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info);
529 /**
530  * qemu_plugin_mem_is_sign_extended() - was the access sign extended
531  * @info: opaque memory transaction handle
532  *
533  * Returns: true if it was, otherwise false
534  */
535 QEMU_PLUGIN_API
536 bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info);
537 /**
538  * qemu_plugin_mem_is_big_endian() - was the access big endian
539  * @info: opaque memory transaction handle
540  *
541  * Returns: true if it was, otherwise false
542  */
543 QEMU_PLUGIN_API
544 bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info);
545 /**
546  * qemu_plugin_mem_is_store() - was the access a store
547  * @info: opaque memory transaction handle
548  *
549  * Returns: true if it was, otherwise false
550  */
551 QEMU_PLUGIN_API
552 bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info);
553 
554 /**
555  * qemu_plugin_get_hwaddr() - return handle for memory operation
556  * @info: opaque memory info structure
557  * @vaddr: the virtual address of the memory operation
558  *
559  * For system emulation returns a qemu_plugin_hwaddr handle to query
560  * details about the actual physical address backing the virtual
561  * address. For linux-user guests it just returns NULL.
562  *
563  * This handle is *only* valid for the duration of the callback. Any
564  * information about the handle should be recovered before the
565  * callback returns.
566  */
567 QEMU_PLUGIN_API
568 struct qemu_plugin_hwaddr *qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info,
569                                                   uint64_t vaddr);
570 
571 /*
572  * The following additional queries can be run on the hwaddr structure to
573  * return information about it - namely whether it is for an IO access and the
574  * physical address associated with the access.
575  */
576 
577 /**
578  * qemu_plugin_hwaddr_is_io() - query whether memory operation is IO
579  * @haddr: address handle from qemu_plugin_get_hwaddr()
580  *
581  * Returns true if the handle's memory operation is to memory-mapped IO, or
582  * false if it is to RAM
583  */
584 QEMU_PLUGIN_API
585 bool qemu_plugin_hwaddr_is_io(const struct qemu_plugin_hwaddr *haddr);
586 
587 /**
588  * qemu_plugin_hwaddr_phys_addr() - query physical address for memory operation
589  * @haddr: address handle from qemu_plugin_get_hwaddr()
590  *
591  * Returns the physical address associated with the memory operation
592  *
593  * Note that the returned physical address may not be unique if you are dealing
594  * with multiple address spaces.
595  */
596 QEMU_PLUGIN_API
597 uint64_t qemu_plugin_hwaddr_phys_addr(const struct qemu_plugin_hwaddr *haddr);
598 
599 /*
600  * Returns a string representing the device. The string is valid for
601  * the lifetime of the plugin.
602  */
603 QEMU_PLUGIN_API
604 const char *qemu_plugin_hwaddr_device_name(const struct qemu_plugin_hwaddr *h);
605 
606 /**
607  * typedef qemu_plugin_vcpu_mem_cb_t - memory callback function type
608  * @vcpu_index: the executing vCPU
609  * @info: an opaque handle for further queries about the memory
610  * @vaddr: the virtual address of the transaction
611  * @userdata: any user data attached to the callback
612  */
613 typedef void (*qemu_plugin_vcpu_mem_cb_t) (unsigned int vcpu_index,
614                                            qemu_plugin_meminfo_t info,
615                                            uint64_t vaddr,
616                                            void *userdata);
617 
618 /**
619  * qemu_plugin_register_vcpu_mem_cb() - register memory access callback
620  * @insn: handle for instruction to instrument
621  * @cb: callback of type qemu_plugin_vcpu_mem_cb_t
622  * @flags: (currently unused) callback flags
623  * @rw: monitor reads, writes or both
624  * @userdata: opaque pointer for userdata
625  *
626  * This registers a full callback for every memory access generated by
627  * an instruction. If the instruction doesn't access memory no
628  * callback will be made.
629  *
630  * The callback reports the vCPU the access took place on, the virtual
631  * address of the access and a handle for further queries. The user
632  * can attach some userdata to the callback for additional purposes.
633  *
634  * Other execution threads will continue to execute during the
635  * callback so the plugin is responsible for ensuring it doesn't get
636  * confused by making appropriate use of locking if required.
637  */
638 QEMU_PLUGIN_API
639 void qemu_plugin_register_vcpu_mem_cb(struct qemu_plugin_insn *insn,
640                                       qemu_plugin_vcpu_mem_cb_t cb,
641                                       enum qemu_plugin_cb_flags flags,
642                                       enum qemu_plugin_mem_rw rw,
643                                       void *userdata);
644 
645 /**
646  * qemu_plugin_register_vcpu_mem_inline_per_vcpu() - inline op for mem access
647  * @insn: handle for instruction to instrument
648  * @rw: apply to reads, writes or both
649  * @op: the op, of type qemu_plugin_op
650  * @entry: entry to run op
651  * @imm: immediate data for @op
652  *
653  * This registers a inline op every memory access generated by the
654  * instruction.
655  */
656 QEMU_PLUGIN_API
657 void qemu_plugin_register_vcpu_mem_inline_per_vcpu(
658     struct qemu_plugin_insn *insn,
659     enum qemu_plugin_mem_rw rw,
660     enum qemu_plugin_op op,
661     qemu_plugin_u64 entry,
662     uint64_t imm);
663 
664 /**
665  * qemu_plugin_request_time_control() - request the ability to control time
666  *
667  * This grants the plugin the ability to control system time. Only one
668  * plugin can control time so if multiple plugins request the ability
669  * all but the first will fail.
670  *
671  * Returns an opaque handle or NULL if fails
672  */
673 QEMU_PLUGIN_API
674 const void *qemu_plugin_request_time_control(void);
675 
676 /**
677  * qemu_plugin_update_ns() - update system emulation time
678  * @handle: opaque handle returned by qemu_plugin_request_time_control()
679  * @time: time in nanoseconds
680  *
681  * This allows an appropriately authorised plugin (i.e. holding the
682  * time control handle) to move system time forward to @time. For
683  * user-mode emulation the time is not changed by this as all reported
684  * time comes from the host kernel.
685  *
686  * Start time is 0.
687  */
688 QEMU_PLUGIN_API
689 void qemu_plugin_update_ns(const void *handle, int64_t time);
690 
691 typedef void
692 (*qemu_plugin_vcpu_syscall_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_index,
693                                  int64_t num, uint64_t a1, uint64_t a2,
694                                  uint64_t a3, uint64_t a4, uint64_t a5,
695                                  uint64_t a6, uint64_t a7, uint64_t a8);
696 
697 QEMU_PLUGIN_API
698 void qemu_plugin_register_vcpu_syscall_cb(qemu_plugin_id_t id,
699                                           qemu_plugin_vcpu_syscall_cb_t cb);
700 
701 typedef void
702 (*qemu_plugin_vcpu_syscall_ret_cb_t)(qemu_plugin_id_t id, unsigned int vcpu_idx,
703                                      int64_t num, int64_t ret);
704 
705 QEMU_PLUGIN_API
706 void
707 qemu_plugin_register_vcpu_syscall_ret_cb(qemu_plugin_id_t id,
708                                          qemu_plugin_vcpu_syscall_ret_cb_t cb);
709 
710 
711 /**
712  * qemu_plugin_insn_disas() - return disassembly string for instruction
713  * @insn: instruction reference
714  *
715  * Returns an allocated string containing the disassembly
716  */
717 
718 QEMU_PLUGIN_API
719 char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn);
720 
721 /**
722  * qemu_plugin_insn_symbol() - best effort symbol lookup
723  * @insn: instruction reference
724  *
725  * Return a static string referring to the symbol. This is dependent
726  * on the binary QEMU is running having provided a symbol table.
727  */
728 QEMU_PLUGIN_API
729 const char *qemu_plugin_insn_symbol(const struct qemu_plugin_insn *insn);
730 
731 /**
732  * qemu_plugin_vcpu_for_each() - iterate over the existing vCPU
733  * @id: plugin ID
734  * @cb: callback function
735  *
736  * The @cb function is called once for each existing vCPU.
737  *
738  * See also: qemu_plugin_register_vcpu_init_cb()
739  */
740 QEMU_PLUGIN_API
741 void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id,
742                                qemu_plugin_vcpu_simple_cb_t cb);
743 
744 QEMU_PLUGIN_API
745 void qemu_plugin_register_flush_cb(qemu_plugin_id_t id,
746                                    qemu_plugin_simple_cb_t cb);
747 
748 /**
749  * qemu_plugin_register_atexit_cb() - register exit callback
750  * @id: plugin ID
751  * @cb: callback
752  * @userdata: user data for callback
753  *
754  * The @cb function is called once execution has finished. Plugins
755  * should be able to free all their resources at this point much like
756  * after a reset/uninstall callback is called.
757  *
758  * In user-mode it is possible a few un-instrumented instructions from
759  * child threads may run before the host kernel reaps the threads.
760  */
761 QEMU_PLUGIN_API
762 void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id,
763                                     qemu_plugin_udata_cb_t cb, void *userdata);
764 
765 /* returns how many vcpus were started at this point */
766 int qemu_plugin_num_vcpus(void);
767 
768 /**
769  * qemu_plugin_outs() - output string via QEMU's logging system
770  * @string: a string
771  */
772 QEMU_PLUGIN_API
773 void qemu_plugin_outs(const char *string);
774 
775 /**
776  * qemu_plugin_bool_parse() - parses a boolean argument in the form of
777  * "<argname>=[on|yes|true|off|no|false]"
778  *
779  * @name: argument name, the part before the equals sign
780  * @val: argument value, what's after the equals sign
781  * @ret: output return value
782  *
783  * returns true if the combination @name=@val parses correctly to a boolean
784  * argument, and false otherwise
785  */
786 QEMU_PLUGIN_API
787 bool qemu_plugin_bool_parse(const char *name, const char *val, bool *ret);
788 
789 /**
790  * qemu_plugin_path_to_binary() - path to binary file being executed
791  *
792  * Return a string representing the path to the binary. For user-mode
793  * this is the main executable. For system emulation we currently
794  * return NULL. The user should g_free() the string once no longer
795  * needed.
796  */
797 QEMU_PLUGIN_API
798 const char *qemu_plugin_path_to_binary(void);
799 
800 /**
801  * qemu_plugin_start_code() - returns start of text segment
802  *
803  * Returns the nominal start address of the main text segment in
804  * user-mode. Currently returns 0 for system emulation.
805  */
806 QEMU_PLUGIN_API
807 uint64_t qemu_plugin_start_code(void);
808 
809 /**
810  * qemu_plugin_end_code() - returns end of text segment
811  *
812  * Returns the nominal end address of the main text segment in
813  * user-mode. Currently returns 0 for system emulation.
814  */
815 QEMU_PLUGIN_API
816 uint64_t qemu_plugin_end_code(void);
817 
818 /**
819  * qemu_plugin_entry_code() - returns start address for module
820  *
821  * Returns the nominal entry address of the main text segment in
822  * user-mode. Currently returns 0 for system emulation.
823  */
824 QEMU_PLUGIN_API
825 uint64_t qemu_plugin_entry_code(void);
826 
827 /** struct qemu_plugin_register - Opaque handle for register access */
828 struct qemu_plugin_register;
829 
830 /**
831  * typedef qemu_plugin_reg_descriptor - register descriptions
832  *
833  * @handle: opaque handle for retrieving value with qemu_plugin_read_register
834  * @name: register name
835  * @feature: optional feature descriptor, can be NULL
836  */
837 typedef struct {
838     struct qemu_plugin_register *handle;
839     const char *name;
840     const char *feature;
841 } qemu_plugin_reg_descriptor;
842 
843 /**
844  * qemu_plugin_get_registers() - return register list for current vCPU
845  *
846  * Returns a potentially empty GArray of qemu_plugin_reg_descriptor.
847  * Caller frees the array (but not the const strings).
848  *
849  * Should be used from a qemu_plugin_register_vcpu_init_cb() callback
850  * after the vCPU is initialised, i.e. in the vCPU context.
851  */
852 QEMU_PLUGIN_API
853 GArray *qemu_plugin_get_registers(void);
854 
855 /**
856  * qemu_plugin_read_register() - read register for current vCPU
857  *
858  * @handle: a @qemu_plugin_reg_handle handle
859  * @buf: A GByteArray for the data owned by the plugin
860  *
861  * This function is only available in a context that register read access is
862  * explicitly requested via the QEMU_PLUGIN_CB_R_REGS flag.
863  *
864  * Returns the size of the read register. The content of @buf is in target byte
865  * order. On failure returns -1.
866  */
867 QEMU_PLUGIN_API
868 int qemu_plugin_read_register(struct qemu_plugin_register *handle,
869                               GByteArray *buf);
870 
871 /**
872  * qemu_plugin_scoreboard_new() - alloc a new scoreboard
873  *
874  * @element_size: size (in bytes) for one entry
875  *
876  * Returns a pointer to a new scoreboard. It must be freed using
877  * qemu_plugin_scoreboard_free.
878  */
879 QEMU_PLUGIN_API
880 struct qemu_plugin_scoreboard *qemu_plugin_scoreboard_new(size_t element_size);
881 
882 /**
883  * qemu_plugin_scoreboard_free() - free a scoreboard
884  * @score: scoreboard to free
885  */
886 QEMU_PLUGIN_API
887 void qemu_plugin_scoreboard_free(struct qemu_plugin_scoreboard *score);
888 
889 /**
890  * qemu_plugin_scoreboard_find() - get pointer to an entry of a scoreboard
891  * @score: scoreboard to query
892  * @vcpu_index: entry index
893  *
894  * Returns address of entry of a scoreboard matching a given vcpu_index. This
895  * address can be modified later if scoreboard is resized.
896  */
897 QEMU_PLUGIN_API
898 void *qemu_plugin_scoreboard_find(struct qemu_plugin_scoreboard *score,
899                                   unsigned int vcpu_index);
900 
901 /* Macros to define a qemu_plugin_u64 */
902 #define qemu_plugin_scoreboard_u64(score) \
903     (qemu_plugin_u64) {score, 0}
904 #define qemu_plugin_scoreboard_u64_in_struct(score, type, member) \
905     (qemu_plugin_u64) {score, offsetof(type, member)}
906 
907 /**
908  * qemu_plugin_u64_add() - add a value to a qemu_plugin_u64 for a given vcpu
909  * @entry: entry to query
910  * @vcpu_index: entry index
911  * @added: value to add
912  */
913 QEMU_PLUGIN_API
914 void qemu_plugin_u64_add(qemu_plugin_u64 entry, unsigned int vcpu_index,
915                          uint64_t added);
916 
917 /**
918  * qemu_plugin_u64_get() - get value of a qemu_plugin_u64 for a given vcpu
919  * @entry: entry to query
920  * @vcpu_index: entry index
921  */
922 QEMU_PLUGIN_API
923 uint64_t qemu_plugin_u64_get(qemu_plugin_u64 entry, unsigned int vcpu_index);
924 
925 /**
926  * qemu_plugin_u64_set() - set value of a qemu_plugin_u64 for a given vcpu
927  * @entry: entry to query
928  * @vcpu_index: entry index
929  * @val: new value
930  */
931 QEMU_PLUGIN_API
932 void qemu_plugin_u64_set(qemu_plugin_u64 entry, unsigned int vcpu_index,
933                          uint64_t val);
934 
935 /**
936  * qemu_plugin_u64_sum() - return sum of all vcpu entries in a scoreboard
937  * @entry: entry to sum
938  */
939 QEMU_PLUGIN_API
940 uint64_t qemu_plugin_u64_sum(qemu_plugin_u64 entry);
941 
942 #endif /* QEMU_QEMU_PLUGIN_H */
943