xref: /openbmc/qemu/docs/devel/tcg-plugins.rst (revision 2e1cacfb)
1..
2   Copyright (C) 2017, Emilio G. Cota <cota@braap.org>
3   Copyright (c) 2019, Linaro Limited
4   Written by Emilio Cota and Alex Bennée
5
6.. _TCG Plugins:
7
8QEMU TCG Plugins
9================
10
11
12Writing plugins
13---------------
14
15API versioning
16~~~~~~~~~~~~~~
17
18This is a new feature for QEMU and it does allow people to develop
19out-of-tree plugins that can be dynamically linked into a running QEMU
20process. However the project reserves the right to change or break the
21API should it need to do so. The best way to avoid this is to submit
22your plugin upstream so they can be updated if/when the API changes.
23
24All plugins need to declare a symbol which exports the plugin API
25version they were built against. This can be done simply by::
26
27  QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION;
28
29The core code will refuse to load a plugin that doesn't export a
30``qemu_plugin_version`` symbol or if plugin version is outside of QEMU's
31supported range of API versions.
32
33Additionally the ``qemu_info_t`` structure which is passed to the
34``qemu_plugin_install`` method of a plugin will detail the minimum and
35current API versions supported by QEMU. The API version will be
36incremented if new APIs are added. The minimum API version will be
37incremented if existing APIs are changed or removed.
38
39Lifetime of the query handle
40~~~~~~~~~~~~~~~~~~~~~~~~~~~~
41
42Each callback provides an opaque anonymous information handle which
43can usually be further queried to find out information about a
44translation, instruction or operation. The handles themselves are only
45valid during the lifetime of the callback so it is important that any
46information that is needed is extracted during the callback and saved
47by the plugin.
48
49Plugin life cycle
50~~~~~~~~~~~~~~~~~
51
52First the plugin is loaded and the public qemu_plugin_install function
53is called. The plugin will then register callbacks for various plugin
54events. Generally plugins will register a handler for the *atexit*
55if they want to dump a summary of collected information once the
56program/system has finished running.
57
58When a registered event occurs the plugin callback is invoked. The
59callbacks may provide additional information. In the case of a
60translation event the plugin has an option to enumerate the
61instructions in a block of instructions and optionally register
62callbacks to some or all instructions when they are executed.
63
64There is also a facility to add inline instructions doing various operations,
65like adding or storing an immediate value. It is also possible to execute a
66callback conditionally, with condition being evaluated inline. All those inline
67operations are associated to a ``scoreboard``, which is a thread-local storage
68automatically expanded when new cores/threads are created and that can be
69accessed/modified in a thread-safe way without any lock needed. Combining inline
70operations and conditional callbacks offer a more efficient way to instrument
71binaries, compared to classic callbacks.
72
73Finally when QEMU exits all the registered *atexit* callbacks are
74invoked.
75
76Exposure of QEMU internals
77~~~~~~~~~~~~~~~~~~~~~~~~~~
78
79The plugin architecture actively avoids leaking implementation details
80about how QEMU's translation works to the plugins. While there are
81conceptions such as translation time and translation blocks the
82details are opaque to plugins. The plugin is able to query select
83details of instructions and system configuration only through the
84exported *qemu_plugin* functions.
85
86However the following assumptions can be made:
87
88Translation Blocks
89++++++++++++++++++
90
91All code will go through a translation phase although not all
92translations will be necessarily be executed. You need to instrument
93actual executions to track what is happening.
94
95It is quite normal to see the same address translated multiple times.
96If you want to track the code in system emulation you should examine
97the underlying physical address (``qemu_plugin_insn_haddr``) to take
98into account the effects of virtual memory although if the system does
99paging this will change too.
100
101Not all instructions in a block will always execute so if its
102important to track individual instruction execution you need to
103instrument them directly. However asynchronous interrupts will not
104change control flow mid-block.
105
106Instructions
107++++++++++++
108
109Instruction instrumentation runs before the instruction executes. You
110can be can be sure the instruction will be dispatched, but you can't
111be sure it will complete. Generally this will be because of a
112synchronous exception (e.g. SIGILL) triggered by the instruction
113attempting to execute. If you want to be sure you will need to
114instrument the next instruction as well. See the ``execlog.c`` plugin
115for examples of how to track this and finalise details after execution.
116
117Memory Accesses
118+++++++++++++++
119
120Memory callbacks are called after a successful load or store.
121Unsuccessful operations (i.e. faults) will not be visible to memory
122instrumentation although the execution side effects can be observed
123(e.g. entering a exception handler).
124
125System Idle and Resume States
126+++++++++++++++++++++++++++++
127
128The ``qemu_plugin_register_vcpu_idle_cb`` and
129``qemu_plugin_register_vcpu_resume_cb`` functions can be used to track
130when CPUs go into and return from sleep states when waiting for
131external I/O. Be aware though that these may occur less frequently
132than in real HW due to the inefficiencies of emulation giving less
133chance for the CPU to idle.
134
135Internals
136---------
137
138Locking
139~~~~~~~
140
141We have to ensure we cannot deadlock, particularly under MTTCG. For
142this we acquire a lock when called from plugin code. We also keep the
143list of callbacks under RCU so that we do not have to hold the lock
144when calling the callbacks. This is also for performance, since some
145callbacks (e.g. memory access callbacks) might be called very
146frequently.
147
148  * A consequence of this is that we keep our own list of CPUs, so that
149    we do not have to worry about locking order wrt cpu_list_lock.
150  * Use a recursive lock, since we can get registration calls from
151    callbacks.
152
153As a result registering/unregistering callbacks is "slow", since it
154takes a lock. But this is very infrequent; we want performance when
155calling (or not calling) callbacks, not when registering them. Using
156RCU is great for this.
157
158We support the uninstallation of a plugin at any time (e.g. from
159plugin callbacks). This allows plugins to remove themselves if they no
160longer want to instrument the code. This operation is asynchronous
161which means callbacks may still occur after the uninstall operation is
162requested. The plugin isn't completely uninstalled until the safe work
163has executed while all vCPUs are quiescent.
164
165Plugin API
166==========
167
168The following API is generated from the inline documentation in
169``include/qemu/qemu-plugin.h``. Please ensure any updates to the API
170include the full kernel-doc annotations.
171
172.. kernel-doc:: include/qemu/qemu-plugin.h
173