QEMU TCG Plugins
QEMU TCG plugins provide a way for users to run experiments taking advantage of the total system control emulation can have over a guest. It provides a mechanism for plugins to subscribe to events during translation and execution and optionally callback into the plugin during these events. TCG plugins are unable to change the system state only monitor it passively. However they can do this down to an individual instruction granularity including potentially subscribing to all load and store operations.
Usage
Any QEMU binary with TCG support has plugins enabled by default. Earlier releases needed to be explicitly enabled with:
configure --enable-plugins
Once built a program can be run with multiple plugins loaded each with their own arguments:
$QEMU $OTHER_QEMU_ARGS \
    -plugin contrib/plugin/libhowvec.so,inline=on,count=hint \
    -plugin contrib/plugin/libhotblocks.so
Arguments are plugin specific and can be used to modify their behaviour. In this case the howvec plugin is being asked to use inline ops to count and break down the hint instructions by type.
Linux user-mode emulation also evaluates the environment variable
QEMU_PLUGIN:
QEMU_PLUGIN="file=contrib/plugins/libhowvec.so,inline=on,count=hint" $QEMU
Writing plugins
API versioning
This is a new feature for QEMU and it does allow people to develop out-of-tree plugins that can be dynamically linked into a running QEMU process. However the project reserves the right to change or break the API should it need to do so. The best way to avoid this is to submit your plugin upstream so they can be updated if/when the API changes.
All plugins need to declare a symbol which exports the plugin API version they were built against. This can be done simply by:
QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION;
The core code will refuse to load a plugin that doesn’t export a
qemu_plugin_version symbol or if plugin version is outside of QEMU’s
supported range of API versions.
Additionally the qemu_info_t structure which is passed to the
qemu_plugin_install method of a plugin will detail the minimum and
current API versions supported by QEMU. The API version will be
incremented if new APIs are added. The minimum API version will be
incremented if existing APIs are changed or removed.
Lifetime of the query handle
Each callback provides an opaque anonymous information handle which can usually be further queried to find out information about a translation, instruction or operation. The handles themselves are only valid during the lifetime of the callback so it is important that any information that is needed is extracted during the callback and saved by the plugin.
Plugin life cycle
First the plugin is loaded and the public qemu_plugin_install function is called. The plugin will then register callbacks for various plugin events. Generally plugins will register a handler for the atexit if they want to dump a summary of collected information once the program/system has finished running.
When a registered event occurs the plugin callback is invoked. The callbacks may provide additional information. In the case of a translation event the plugin has an option to enumerate the instructions in a block of instructions and optionally register callbacks to some or all instructions when they are executed.
There is also a facility to add an inline event where code to increment a counter can be directly inlined with the translation. Currently only a simple increment is supported. This is not atomic so can miss counts. If you want absolute precision you should use a callback which can then ensure atomicity itself.
Finally when QEMU exits all the registered atexit callbacks are invoked.
Exposure of QEMU internals
The plugin architecture actively avoids leaking implementation details about how QEMU’s translation works to the plugins. While there are conceptions such as translation time and translation blocks the details are opaque to plugins. The plugin is able to query select details of instructions and system configuration only through the exported qemu_plugin functions.
Internals
Locking
We have to ensure we cannot deadlock, particularly under MTTCG. For this we acquire a lock when called from plugin code. We also keep the list of callbacks under RCU so that we do not have to hold the lock when calling the callbacks. This is also for performance, since some callbacks (e.g. memory access callbacks) might be called very frequently.
A consequence of this is that we keep our own list of CPUs, so that we do not have to worry about locking order wrt cpu_list_lock.
Use a recursive lock, since we can get registration calls from callbacks.
As a result registering/unregistering callbacks is “slow”, since it takes a lock. But this is very infrequent; we want performance when calling (or not calling) callbacks, not when registering them. Using RCU is great for this.
We support the uninstallation of a plugin at any time (e.g. from plugin callbacks). This allows plugins to remove themselves if they no longer want to instrument the code. This operation is asynchronous which means callbacks may still occur after the uninstall operation is requested. The plugin isn’t completely uninstalled until the safe work has executed while all vCPUs are quiescent.
Example Plugins
There are a number of plugins included with QEMU and you are
encouraged to contribute your own plugins plugins upstream. There is a
contrib/plugins directory where they can go. There are also some
basic plugins that are used to test and exercise the API during the
make check-tcg target in tests\plugins.
- tests/plugins/empty.c 
Purely a test plugin for measuring the overhead of the plugins system itself. Does no instrumentation.
- tests/plugins/bb.c 
A very basic plugin which will measure execution in course terms as each basic block is executed. By default the results are shown once execution finishes:
$ qemu-aarch64 -plugin tests/plugin/libbb.so \
    -d plugin ./tests/tcg/aarch64-linux-user/sha1
SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
bb's: 2277338, insns: 158483046
Behaviour can be tweaked with the following arguments:
inline=true|false
Use faster inline addition of a single counter. Not per-cpu and not thread safe.
idle=true|false
Dump the current execution stats whenever the guest vCPU idles
- tests/plugins/insn.c 
This is a basic instruction level instrumentation which can count the number of instructions executed on each core/thread:
$ qemu-aarch64 -plugin tests/plugin/libinsn.so \
    -d plugin ./tests/tcg/aarch64-linux-user/threadcount
Created 10 threads
Done
cpu 0 insns: 46765
cpu 1 insns: 3694
cpu 2 insns: 3694
cpu 3 insns: 2994
cpu 4 insns: 1497
cpu 5 insns: 1497
cpu 6 insns: 1497
cpu 7 insns: 1497
total insns: 63135
Behaviour can be tweaked with the following arguments:
inline=true|false
Use faster inline addition of a single counter. Not per-cpu and not thread safe.
sizes=true|false
Give a summary of the instruction sizes for the execution
match=<string>
Only instrument instructions matching the string prefix. Will show some basic stats including how many instructions have executed since the last execution. For example:
$ qemu-aarch64 -plugin tests/plugin/libinsn.so,match=bl \ -d plugin ./tests/tcg/aarch64-linux-user/sha512-vector ... 0x40069c, 'bl #0x4002b0', 10 hits, 1093 match hits, Δ+1257 since last match, 98 avg insns/match 0x4006ac, 'bl #0x403690', 10 hits, 1094 match hits, Δ+47 since last match, 98 avg insns/match 0x4037fc, 'bl #0x4002b0', 18 hits, 1095 match hits, Δ+22 since last match, 98 avg insns/match 0x400720, 'bl #0x403690', 10 hits, 1096 match hits, Δ+58 since last match, 98 avg insns/match 0x4037fc, 'bl #0x4002b0', 19 hits, 1097 match hits, Δ+22 since last match, 98 avg insns/match 0x400730, 'bl #0x403690', 10 hits, 1098 match hits, Δ+33 since last match, 98 avg insns/match 0x4037ac, 'bl #0x4002b0', 12 hits, 1099 match hits, Δ+20 since last match, 98 avg insns/match ...
For more detailed execution tracing see the execlog plugin for
other options.
- tests/plugins/mem.c 
Basic instruction level memory instrumentation:
$ qemu-aarch64 -plugin tests/plugin/libmem.so,inline=true \
    -d plugin ./tests/tcg/aarch64-linux-user/sha1
SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
inline mem accesses: 79525013
Behaviour can be tweaked with the following arguments:
inline=true|false
Use faster inline addition of a single counter. Not per-cpu and not thread safe.
callback=true|false
Use callbacks on each memory instrumentation.
hwaddr=true|false
Count IO accesses (only for system emulation)
- tests/plugins/syscall.c 
A basic syscall tracing plugin. This only works for user-mode. By default it will give a summary of syscall stats at the end of the run:
$ qemu-aarch64 -plugin tests/plugin/libsyscall \
    -d plugin ./tests/tcg/aarch64-linux-user/threadcount
Created 10 threads
Done
syscall no.  calls  errors
226          12     0
99           11     11
115          11     0
222          11     0
93           10     0
220          10     0
233          10     0
215          8      0
214          4      0
134          2      0
64           2      0
96           1      0
94           1      0
80           1      0
261          1      0
78           1      0
160          1      0
135          1      0
- contrib/plugins/hotblocks.c 
The hotblocks plugin allows you to examine the where hot paths of execution are in your program. Once the program has finished you will get a sorted list of blocks reporting the starting PC, translation count, number of instructions and execution count. This will work best with linux-user execution as system emulation tends to generate re-translations as blocks from different programs get swapped in and out of system memory.
If your program is single-threaded you can use the inline option for
slightly faster (but not thread safe) counters.
Example:
$ qemu-aarch64 \
  -plugin contrib/plugins/libhotblocks.so -d plugin \
  ./tests/tcg/aarch64-linux-user/sha1
SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
collected 903 entries in the hash table
pc, tcount, icount, ecount
0x0000000041ed10, 1, 5, 66087
0x000000004002b0, 1, 4, 66087
...
- contrib/plugins/hotpages.c 
Similar to hotblocks but this time tracks memory accesses:
$ qemu-aarch64 \
  -plugin contrib/plugins/libhotpages.so -d plugin \
  ./tests/tcg/aarch64-linux-user/sha1
SHA1=15dd99a1991e0b3826fede3deffc1feba42278e6
Addr, RCPUs, Reads, WCPUs, Writes
0x000055007fe000, 0x0001, 31747952, 0x0001, 8835161
0x000055007ff000, 0x0001, 29001054, 0x0001, 8780625
0x00005500800000, 0x0001, 687465, 0x0001, 335857
0x0000000048b000, 0x0001, 130594, 0x0001, 355
0x0000000048a000, 0x0001, 1826, 0x0001, 11
The hotpages plugin can be configured using the following arguments:
sortby=reads|writes|address
Log the data sorted by either the number of reads, the number of writes, or memory address. (Default: entries are sorted by the sum of reads and writes)
io=on
Track IO addresses. Only relevant to full system emulation. (Default: off)
pagesize=N
The page size used. (Default: N = 4096)
- contrib/plugins/howvec.c 
This is an instruction classifier so can be used to count different
types of instructions. It has a number of options to refine which get
counted. You can give a value to the count argument for a class of
instructions to break it down fully, so for example to see all the system
registers accesses:
$ qemu-system-aarch64 $(QEMU_ARGS) \
  -append "root=/dev/sda2 systemd.unit=benchmark.service" \
  -smp 4 -plugin ./contrib/plugins/libhowvec.so,count=sreg -d plugin
which will lead to a sorted list after the class breakdown:
Instruction Classes:
Class:   UDEF                   not counted
Class:   SVE                    (68 hits)
Class:   PCrel addr             (47789483 hits)
Class:   Add/Sub (imm)          (192817388 hits)
Class:   Logical (imm)          (93852565 hits)
Class:   Move Wide (imm)        (76398116 hits)
Class:   Bitfield               (44706084 hits)
Class:   Extract                (5499257 hits)
Class:   Cond Branch (imm)      (147202932 hits)
Class:   Exception Gen          (193581 hits)
Class:     NOP                  not counted
Class:   Hints                  (6652291 hits)
Class:   Barriers               (8001661 hits)
Class:   PSTATE                 (1801695 hits)
Class:   System Insn            (6385349 hits)
Class:   System Reg             counted individually
Class:   Branch (reg)           (69497127 hits)
Class:   Branch (imm)           (84393665 hits)
Class:   Cmp & Branch           (110929659 hits)
Class:   Tst & Branch           (44681442 hits)
Class:   AdvSimd ldstmult       (736 hits)
Class:   ldst excl              (9098783 hits)
Class:   Load Reg (lit)         (87189424 hits)
Class:   ldst noalloc pair      (3264433 hits)
Class:   ldst pair              (412526434 hits)
Class:   ldst reg (imm)         (314734576 hits)
Class: Loads & Stores           (2117774 hits)
Class: Data Proc Reg            (223519077 hits)
Class: Scalar FP                (31657954 hits)
Individual Instructions:
Instr: mrs x0, sp_el0           (2682661 hits)  (op=0xd5384100/  System Reg)
Instr: mrs x1, tpidr_el2        (1789339 hits)  (op=0xd53cd041/  System Reg)
Instr: mrs x2, tpidr_el2        (1513494 hits)  (op=0xd53cd042/  System Reg)
Instr: mrs x0, tpidr_el2        (1490823 hits)  (op=0xd53cd040/  System Reg)
Instr: mrs x1, sp_el0           (933793 hits)   (op=0xd5384101/  System Reg)
Instr: mrs x2, sp_el0           (699516 hits)   (op=0xd5384102/  System Reg)
Instr: mrs x4, tpidr_el2        (528437 hits)   (op=0xd53cd044/  System Reg)
Instr: mrs x30, ttbr1_el1       (480776 hits)   (op=0xd538203e/  System Reg)
Instr: msr ttbr1_el1, x30       (480713 hits)   (op=0xd518203e/  System Reg)
Instr: msr vbar_el1, x30        (480671 hits)   (op=0xd518c01e/  System Reg)
...
To find the argument shorthand for the class you need to examine the
source code of the plugin at the moment, specifically the *opt
argument in the InsnClassExecCount tables.
- contrib/plugins/lockstep.c 
This is a debugging tool for developers who want to find out when and where execution diverges after a subtle change to TCG code generation. It is not an exact science and results are likely to be mixed once asynchronous events are introduced. While the use of -icount can introduce determinism to the execution flow it doesn’t always follow the translation sequence will be exactly the same. Typically this is caused by a timer firing to service the GUI causing a block to end early. However in some cases it has proved to be useful in pointing people at roughly where execution diverges. The only argument you need for the plugin is a path for the socket the two instances will communicate over:
$ qemu-system-sparc -monitor none -parallel none \
  -net none -M SS-20 -m 256 -kernel day11/zImage.elf \
  -plugin ./contrib/plugins/liblockstep.so,sockpath=lockstep-sparc.sock \
  -d plugin,nochain
which will eventually report:
qemu-system-sparc: warning: nic lance.0 has no peer
@ 0x000000ffd06678 vs 0x000000ffd001e0 (2/1 since last)
@ 0x000000ffd07d9c vs 0x000000ffd06678 (3/1 since last)
Δ insn_count @ 0x000000ffd07d9c (809900609) vs 0x000000ffd06678 (809900612)
  previously @ 0x000000ffd06678/10 (809900609 insns)
  previously @ 0x000000ffd001e0/4 (809900599 insns)
  previously @ 0x000000ffd080ac/2 (809900595 insns)
  previously @ 0x000000ffd08098/5 (809900593 insns)
  previously @ 0x000000ffd080c0/1 (809900588 insns)
- contrib/plugins/hwprofile.c 
The hwprofile tool can only be used with system emulation and allows the user to see what hardware is accessed how often. It has a number of options:
track=read or track=write
By default the plugin tracks both reads and writes. You can use one of these options to limit the tracking to just one class of accesses.
source
Will include a detailed break down of what the guest PC that made the access was. Not compatible with the pattern option. Example output:
cirrus-low-memory @ 0xfffffd00000a0000 pc:fffffc0000005cdc, 1, 256 pc:fffffc0000005ce8, 1, 256 pc:fffffc0000005cec, 1, 256
pattern
Instead break down the accesses based on the offset into the HW region. This can be useful for seeing the most used registers of a device. Example output:
pci0-conf @ 0xfffffd01fe000000 off:00000004, 1, 1 off:00000010, 1, 3 off:00000014, 1, 3 off:00000018, 1, 2 off:0000001c, 1, 2 off:00000020, 1, 2 ...
- contrib/plugins/execlog.c 
The execlog tool traces executed instructions with memory access. It can be used for debugging and security analysis purposes. Please be aware that this will generate a lot of output.
The plugin needs default argument:
$ qemu-system-arm $(QEMU_ARGS) \
  -plugin ./contrib/plugins/libexeclog.so -d plugin
which will output an execution trace following this structure:
# vCPU, vAddr, opcode, disassembly[, load/store, memory addr, device]...
0, 0xa12, 0xf8012400, "movs r4, #0"
0, 0xa14, 0xf87f42b4, "cmp r4, r6"
0, 0xa16, 0xd206, "bhs #0xa26"
0, 0xa18, 0xfff94803, "ldr r0, [pc, #0xc]", load, 0x00010a28, RAM
0, 0xa1a, 0xf989f000, "bl #0xd30"
0, 0xd30, 0xfff9b510, "push {r4, lr}", store, 0x20003ee0, RAM, store, 0x20003ee4, RAM
0, 0xd32, 0xf9893014, "adds r0, #0x14"
0, 0xd34, 0xf9c8f000, "bl #0x10c8"
0, 0x10c8, 0xfff96c43, "ldr r3, [r0, #0x44]", load, 0x200000e4, RAM
the output can be filtered to only track certain instructions or
addresses using the ifilter or afilter options. You can stack the
arguments if required:
$ qemu-system-arm $(QEMU_ARGS) \
  -plugin ./contrib/plugins/libexeclog.so,ifilter=st1w,afilter=0x40001808 -d plugin
- contrib/plugins/cache.c 
Cache modelling plugin that measures the performance of a given L1 cache configuration, and optionally a unified L2 per-core cache when a given working set is run:
$ qemu-x86_64 -plugin ./contrib/plugins/libcache.so \
    -d plugin -D cache.log ./tests/tcg/x86_64-linux-user/float_convs
will report the following:
core #, data accesses, data misses, dmiss rate, insn accesses, insn misses, imiss rate
0       996695         508             0.0510%  2642799        18617           0.7044%
address, data misses, instruction
0x424f1e (_int_malloc), 109, movq %rax, 8(%rcx)
0x41f395 (_IO_default_xsputn), 49, movb %dl, (%rdi, %rax)
0x42584d (ptmalloc_init.part.0), 33, movaps %xmm0, (%rax)
0x454d48 (__tunables_init), 20, cmpb $0, (%r8)
...
address, fetch misses, instruction
0x4160a0 (__vfprintf_internal), 744, movl $1, %ebx
0x41f0a0 (_IO_setb), 744, endbr64
0x415882 (__vfprintf_internal), 744, movq %r12, %rdi
0x4268a0 (__malloc), 696, andq $0xfffffffffffffff0, %rax
...
The plugin has a number of arguments, all of them are optional:
limit=N
Print top N icache and dcache thrashing instructions along with their address, number of misses, and its disassembly. (default: 32)
icachesize=N
iblksize=B
iassoc=A
Instruction cache configuration arguments. They specify the cache size, block size, and associativity of the instruction cache, respectively. (default: N = 16384, B = 64, A = 8)
dcachesize=N
dblksize=B
dassoc=A
Data cache configuration arguments. They specify the cache size, block size, and associativity of the data cache, respectively. (default: N = 16384, B = 64, A = 8)
evict=POLICY
Sets the eviction policy to POLICY. Available policies are:
lru,fifo, andrand. The plugin will use the specified policy for both instruction and data caches. (default: POLICY =lru)
cores=N
Sets the number of cores for which we maintain separate icache and dcache. (default: for linux-user, N = 1, for full system emulation: N = cores available to guest)
l2=on
Simulates a unified L2 cache (stores blocks for both instructions and data) using the default L2 configuration (cache size = 2MB, associativity = 16-way, block size = 64B).
l2cachesize=N
l2blksize=B
l2assoc=A
L2 cache configuration arguments. They specify the cache size, block size, and associativity of the L2 cache, respectively. Setting any of the L2 configuration arguments implies
l2=on. (default: N = 2097152 (2MB), B = 64, A = 16)
API
The following API is generated from the inline documentation in
include/qemu/qemu-plugin.h. Please ensure any updates to the API
include the full kernel-doc annotations.
- 
type qemu_plugin_id_t
- Unique plugin ID 
- 
struct qemu_info_t
- system information for plugins 
Definition
struct qemu_info_t {
  const char *target_name;
  struct {
    int min;
    int cur;
  } version;
  bool system_emulation;
  union {
    struct {
      int smp_vcpus;
      int max_vcpus;
    } system;
  };
};
Members
- target_name
- string describing architecture 
- version
- minimum and current plugin API level 
- system_emulation
- is this a full system emulation? 
- {unnamed_union}
- anonymous 
- system
- information relevant to system emulation 
Description
This structure provides for some limited information about the system to allow the plugin to make decisions on how to proceed. For example it might only be suitable for running on some guest architectures or when under full system emulation.
- 
int qemu_plugin_install(qemu_plugin_id_t id, const qemu_info_t *info, int argc, char **argv)
- Install a plugin 
Parameters
- qemu_plugin_id_t id
- this plugin’s opaque ID 
- const qemu_info_t *info
- a block describing some details about the guest 
- int argc
- number of arguments 
- char **argv
- array of arguments (argc elements) 
Description
All plugins must export this symbol which is called when the plugin is first loaded. Calling qemu_plugin_uninstall() from this function is a bug.
Note
info is only live during the call. Copy any information we want to keep. argv remains valid throughout the lifetime of the loaded plugin.
Return
0 on successful loading, !0 for an error.
- 
qemu_plugin_simple_cb_t
- Typedef: simple callback 
Syntax
void qemu_plugin_simple_cb_t (qemu_plugin_id_t id)
Parameters
- qemu_plugin_id_t id
- the unique qemu_plugin_id_t 
Description
This callback passes no information aside from the unique id.
- 
qemu_plugin_udata_cb_t
- Typedef: callback with user data 
Syntax
void qemu_plugin_udata_cb_t (qemu_plugin_id_t id, void *userdata)
Parameters
- qemu_plugin_id_t id
- the unique qemu_plugin_id_t 
- void *userdata
- a pointer to some user data supplied when the callback was registered. 
- 
qemu_plugin_vcpu_simple_cb_t
- Typedef: vcpu callback 
Syntax
void qemu_plugin_vcpu_simple_cb_t (qemu_plugin_id_t id, unsigned int vcpu_index)
Parameters
- qemu_plugin_id_t id
- the unique qemu_plugin_id_t 
- unsigned int vcpu_index
- the current vcpu context 
- 
qemu_plugin_vcpu_udata_cb_t
- Typedef: vcpu callback 
Syntax
void qemu_plugin_vcpu_udata_cb_t (unsigned int vcpu_index, void *userdata)
Parameters
- unsigned int vcpu_index
- the current vcpu context 
- void *userdata
- a pointer to some user data supplied when the callback was registered. 
- 
void qemu_plugin_uninstall(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb)
- Uninstall a plugin 
Parameters
- qemu_plugin_id_t id
- this plugin’s opaque ID 
- qemu_plugin_simple_cb_t cb
- callback to be called once the plugin has been removed 
Description
Do NOT assume that the plugin has been uninstalled once this function returns. Plugins are uninstalled asynchronously, and therefore the given plugin receives callbacks until cb is called.
Note
Calling this function from qemu_plugin_install() is a bug.
- 
void qemu_plugin_reset(qemu_plugin_id_t id, qemu_plugin_simple_cb_t cb)
- Reset a plugin 
Parameters
- qemu_plugin_id_t id
- this plugin’s opaque ID 
- qemu_plugin_simple_cb_t cb
- callback to be called once the plugin has been reset 
Description
Unregisters all callbacks for the plugin given by id.
Do NOT assume that the plugin has been reset once this function returns. Plugins are reset asynchronously, and therefore the given plugin receives callbacks until cb is called.
- 
void qemu_plugin_register_vcpu_init_cb(qemu_plugin_id_t id, qemu_plugin_vcpu_simple_cb_t cb)
- register a vCPU initialization callback 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_vcpu_simple_cb_t cb
- callback function 
Description
The cb function is called every time a vCPU is initialized.
See also: qemu_plugin_register_vcpu_exit_cb()
- 
void qemu_plugin_register_vcpu_exit_cb(qemu_plugin_id_t id, qemu_plugin_vcpu_simple_cb_t cb)
- register a vCPU exit callback 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_vcpu_simple_cb_t cb
- callback function 
Description
The cb function is called every time a vCPU exits.
See also: qemu_plugin_register_vcpu_init_cb()
- 
void qemu_plugin_register_vcpu_idle_cb(qemu_plugin_id_t id, qemu_plugin_vcpu_simple_cb_t cb)
- register a vCPU idle callback 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_vcpu_simple_cb_t cb
- callback function 
Description
The cb function is called every time a vCPU idles.
- 
void qemu_plugin_register_vcpu_resume_cb(qemu_plugin_id_t id, qemu_plugin_vcpu_simple_cb_t cb)
- register a vCPU resume callback 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_vcpu_simple_cb_t cb
- callback function 
Description
The cb function is called every time a vCPU resumes execution.
- 
enum qemu_plugin_cb_flags
- type of callback 
Constants
- QEMU_PLUGIN_CB_NO_REGS
- callback does not access the CPU’s regs 
- QEMU_PLUGIN_CB_R_REGS
- callback reads the CPU’s regs 
- QEMU_PLUGIN_CB_RW_REGS
- callback reads and writes the CPU’s regs 
Note
currently unused, plugins cannot read or change system register state.
- 
qemu_plugin_vcpu_tb_trans_cb_t
- Typedef: translation callback 
Syntax
void qemu_plugin_vcpu_tb_trans_cb_t (qemu_plugin_id_t id, struct qemu_plugin_tb *tb)
Parameters
- qemu_plugin_id_t id
- unique plugin id 
- struct qemu_plugin_tb *tb
- opaque handle used for querying and instrumenting a block. 
- 
void qemu_plugin_register_vcpu_tb_trans_cb(qemu_plugin_id_t id, qemu_plugin_vcpu_tb_trans_cb_t cb)
- register a translate cb 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_vcpu_tb_trans_cb_t cb
- callback function 
Description
The cb function is called every time a translation occurs. The cb function is passed an opaque qemu_plugin_type which it can query for additional information including the list of translated instructions. At this point the plugin can register further callbacks to be triggered when the block or individual instruction executes.
- 
void qemu_plugin_register_vcpu_tb_exec_cb(struct qemu_plugin_tb *tb, qemu_plugin_vcpu_udata_cb_t cb, enum qemu_plugin_cb_flags flags, void *userdata)
- register execution callback 
Parameters
- struct qemu_plugin_tb *tb
- the opaque qemu_plugin_tb handle for the translation 
- qemu_plugin_vcpu_udata_cb_t cb
- callback function 
- enum qemu_plugin_cb_flags flags
- does the plugin read or write the CPU’s registers? 
- void *userdata
- any plugin data to pass to the cb? 
Description
The cb function is called every time a translated unit executes.
- 
enum qemu_plugin_op
- describes an inline op 
Constants
- QEMU_PLUGIN_INLINE_ADD_U64
- add an immediate value uint64_t 
Note
currently only a single inline op is supported.
- 
void qemu_plugin_register_vcpu_tb_exec_inline(struct qemu_plugin_tb *tb, enum qemu_plugin_op op, void *ptr, uint64_t imm)
- execution inline op 
Parameters
- struct qemu_plugin_tb *tb
- the opaque qemu_plugin_tb handle for the translation 
- enum qemu_plugin_op op
- the type of qemu_plugin_op (e.g. ADD_U64) 
- void *ptr
- the target memory location for the op 
- uint64_t imm
- the op data (e.g. 1) 
Description
Insert an inline op to every time a translated unit executes. Useful if you just want to increment a single counter somewhere in memory.
Note
ops are not atomic so in multi-threaded/multi-smp situations you will get inexact results.
- 
void qemu_plugin_register_vcpu_insn_exec_cb(struct qemu_plugin_insn *insn, qemu_plugin_vcpu_udata_cb_t cb, enum qemu_plugin_cb_flags flags, void *userdata)
- register insn execution cb 
Parameters
- struct qemu_plugin_insn *insn
- the opaque qemu_plugin_insn handle for an instruction 
- qemu_plugin_vcpu_udata_cb_t cb
- callback function 
- enum qemu_plugin_cb_flags flags
- does the plugin read or write the CPU’s registers? 
- void *userdata
- any plugin data to pass to the cb? 
Description
The cb function is called every time an instruction is executed
- 
void qemu_plugin_register_vcpu_insn_exec_inline(struct qemu_plugin_insn *insn, enum qemu_plugin_op op, void *ptr, uint64_t imm)
- insn execution inline op 
Parameters
- struct qemu_plugin_insn *insn
- the opaque qemu_plugin_insn handle for an instruction 
- enum qemu_plugin_op op
- the type of qemu_plugin_op (e.g. ADD_U64) 
- void *ptr
- the target memory location for the op 
- uint64_t imm
- the op data (e.g. 1) 
Description
Insert an inline op to every time an instruction executes. Useful if you just want to increment a single counter somewhere in memory.
- 
size_t qemu_plugin_tb_n_insns(const struct qemu_plugin_tb *tb)
- query helper for number of insns in TB 
Parameters
- const struct qemu_plugin_tb *tb
- opaque handle to TB passed to callback 
Return
number of instructions in this block
- 
uint64_t qemu_plugin_tb_vaddr(const struct qemu_plugin_tb *tb)
- query helper for vaddr of TB start 
Parameters
- const struct qemu_plugin_tb *tb
- opaque handle to TB passed to callback 
Return
virtual address of block start
- 
struct qemu_plugin_insn *qemu_plugin_tb_get_insn(const struct qemu_plugin_tb *tb, size_t idx)
- retrieve handle for instruction 
Parameters
- const struct qemu_plugin_tb *tb
- opaque handle to TB passed to callback 
- size_t idx
- instruction number, 0 indexed 
Description
The returned handle can be used in follow up helper queries as well as when instrumenting an instruction. It is only valid for the lifetime of the callback.
Return
opaque handle to instruction
- 
const void *qemu_plugin_insn_data(const struct qemu_plugin_insn *insn)
- return ptr to instruction data 
Parameters
- const struct qemu_plugin_insn *insn
- opaque instruction handle from qemu_plugin_tb_get_insn() 
Note
data is only valid for duration of callback. See qemu_plugin_insn_size() to calculate size of stream.
Return
pointer to a stream of bytes containing the value of this instructions opcode.
- 
size_t qemu_plugin_insn_size(const struct qemu_plugin_insn *insn)
- return size of instruction 
Parameters
- const struct qemu_plugin_insn *insn
- opaque instruction handle from qemu_plugin_tb_get_insn() 
Return
size of instruction in bytes
- 
uint64_t qemu_plugin_insn_vaddr(const struct qemu_plugin_insn *insn)
- return vaddr of instruction 
Parameters
- const struct qemu_plugin_insn *insn
- opaque instruction handle from qemu_plugin_tb_get_insn() 
Return
virtual address of instruction
- 
void *qemu_plugin_insn_haddr(const struct qemu_plugin_insn *insn)
- return hardware addr of instruction 
Parameters
- const struct qemu_plugin_insn *insn
- opaque instruction handle from qemu_plugin_tb_get_insn() 
Return
hardware (physical) target address of instruction
- 
type qemu_plugin_meminfo_t
- opaque memory transaction handle 
Description
This can be further queried using the qemu_plugin_mem_* query functions.
- 
unsigned int qemu_plugin_mem_size_shift(qemu_plugin_meminfo_t info)
- get size of access 
Parameters
- qemu_plugin_meminfo_t info
- opaque memory transaction handle 
Return
size of access in ^2 (0=byte, 1=16bit, 2=32bit etc…)
- 
bool qemu_plugin_mem_is_sign_extended(qemu_plugin_meminfo_t info)
- was the access sign extended 
Parameters
- qemu_plugin_meminfo_t info
- opaque memory transaction handle 
Return
true if it was, otherwise false
- 
bool qemu_plugin_mem_is_big_endian(qemu_plugin_meminfo_t info)
- was the access big endian 
Parameters
- qemu_plugin_meminfo_t info
- opaque memory transaction handle 
Return
true if it was, otherwise false
- 
bool qemu_plugin_mem_is_store(qemu_plugin_meminfo_t info)
- was the access a store 
Parameters
- qemu_plugin_meminfo_t info
- opaque memory transaction handle 
Return
true if it was, otherwise false
- 
struct qemu_plugin_hwaddr *qemu_plugin_get_hwaddr(qemu_plugin_meminfo_t info, uint64_t vaddr)
- return handle for memory operation 
Parameters
- qemu_plugin_meminfo_t info
- opaque memory info structure 
- uint64_t vaddr
- the virtual address of the memory operation 
Description
For system emulation returns a qemu_plugin_hwaddr handle to query details about the actual physical address backing the virtual address. For linux-user guests it just returns NULL.
This handle is only valid for the duration of the callback. Any information about the handle should be recovered before the callback returns.
- 
bool qemu_plugin_hwaddr_is_io(const struct qemu_plugin_hwaddr *haddr)
- query whether memory operation is IO 
Parameters
- const struct qemu_plugin_hwaddr *haddr
- address handle from qemu_plugin_get_hwaddr() 
Description
Returns true if the handle’s memory operation is to memory-mapped IO, or false if it is to RAM
- 
uint64_t qemu_plugin_hwaddr_phys_addr(const struct qemu_plugin_hwaddr *haddr)
- query physical address for memory operation 
Parameters
- const struct qemu_plugin_hwaddr *haddr
- address handle from qemu_plugin_get_hwaddr() 
Description
Returns the physical address associated with the memory operation
Note that the returned physical address may not be unique if you are dealing with multiple address spaces.
- 
qemu_plugin_vcpu_mem_cb_t
- Typedef: memory callback function type 
Syntax
void qemu_plugin_vcpu_mem_cb_t (unsigned int vcpu_index, qemu_plugin_meminfo_t info, uint64_t vaddr, void *userdata)
Parameters
- unsigned int vcpu_index
- the executing vCPU 
- qemu_plugin_meminfo_t info
- an opaque handle for further queries about the memory 
- uint64_t vaddr
- the virtual address of the transaction 
- void *userdata
- any user data attached to the callback 
- 
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)
- register memory access callback 
Parameters
- struct qemu_plugin_insn *insn
- handle for instruction to instrument 
- qemu_plugin_vcpu_mem_cb_t cb
- callback of type qemu_plugin_vcpu_mem_cb_t 
- enum qemu_plugin_cb_flags flags
- (currently unused) callback flags 
- enum qemu_plugin_mem_rw rw
- monitor reads, writes or both 
- void *userdata
- opaque pointer for userdata 
Description
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_inline(struct qemu_plugin_insn *insn, enum qemu_plugin_mem_rw rw, enum qemu_plugin_op op, void *ptr, uint64_t imm)
- register an inline op to any memory access 
Parameters
- struct qemu_plugin_insn *insn
- handle for instruction to instrument 
- enum qemu_plugin_mem_rw rw
- apply to reads, writes or both 
- enum qemu_plugin_op op
- the op, of type qemu_plugin_op 
- void *ptr
- pointer memory for the op 
- uint64_t imm
- immediate data for op 
Description
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.
- 
char *qemu_plugin_insn_disas(const struct qemu_plugin_insn *insn)
- return disassembly string for instruction 
Parameters
- const struct qemu_plugin_insn *insn
- instruction reference 
Description
Returns an allocated string containing the disassembly
- 
const char *qemu_plugin_insn_symbol(const struct qemu_plugin_insn *insn)
- best effort symbol lookup 
Parameters
- const struct qemu_plugin_insn *insn
- instruction reference 
Description
Return a static string referring to the symbol. This is dependent on the binary QEMU is running having provided a symbol table.
- 
void qemu_plugin_vcpu_for_each(qemu_plugin_id_t id, qemu_plugin_vcpu_simple_cb_t cb)
- iterate over the existing vCPU 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_vcpu_simple_cb_t cb
- callback function 
Description
The cb function is called once for each existing vCPU.
See also: qemu_plugin_register_vcpu_init_cb()
- 
void qemu_plugin_register_atexit_cb(qemu_plugin_id_t id, qemu_plugin_udata_cb_t cb, void *userdata)
- register exit callback 
Parameters
- qemu_plugin_id_t id
- plugin ID 
- qemu_plugin_udata_cb_t cb
- callback 
- void *userdata
- user data for callback 
Description
The cb function is called once execution has finished. Plugins should be able to free all their resources at this point much like after a reset/uninstall callback is called.
In user-mode it is possible a few un-instrumented instructions from child threads may run before the host kernel reaps the threads.
- 
void qemu_plugin_outs(const char *string)
- output string via QEMU’s logging system 
Parameters
- const char *string
- a string 
- 
bool qemu_plugin_bool_parse(const char *name, const char *val, bool *ret)
- parses a boolean argument in the form of “<argname>=[on|yes|true|off|no|false]” 
Parameters
- const char *name
- argument name, the part before the equals sign 
- const char *val
- argument value, what’s after the equals sign 
- bool *ret
- output return value 
Description
returns true if the combination name**=**val parses correctly to a boolean argument, and false otherwise
- 
const char *qemu_plugin_path_to_binary(void)
- path to binary file being executed 
Parameters
- void
- no arguments 
Description
Return a string representing the path to the binary. For user-mode this is the main executable. For system emulation we currently return NULL. The user should g_free() the string once no longer needed.
- 
uint64_t qemu_plugin_start_code(void)
- returns start of text segment 
Parameters
- void
- no arguments 
Description
Returns the nominal start address of the main text segment in user-mode. Currently returns 0 for system emulation.
- 
uint64_t qemu_plugin_end_code(void)
- returns end of text segment 
Parameters
- void
- no arguments 
Description
Returns the nominal end address of the main text segment in user-mode. Currently returns 0 for system emulation.
- 
uint64_t qemu_plugin_entry_code(void)
- returns start address for module 
Parameters
- void
- no arguments 
Description
Returns the nominal entry address of the main text segment in user-mode. Currently returns 0 for system emulation.