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