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 an inline event where code to 65increment a counter can be directly inlined with the translation. 66Currently only a simple increment is supported. This is not atomic so 67can miss counts. If you want absolute precision you should use a 68callback which can then ensure atomicity itself. 69 70Finally when QEMU exits all the registered *atexit* callbacks are 71invoked. 72 73Exposure of QEMU internals 74~~~~~~~~~~~~~~~~~~~~~~~~~~ 75 76The plugin architecture actively avoids leaking implementation details 77about how QEMU's translation works to the plugins. While there are 78conceptions such as translation time and translation blocks the 79details are opaque to plugins. The plugin is able to query select 80details of instructions and system configuration only through the 81exported *qemu_plugin* functions. 82 83However the following assumptions can be made: 84 85Translation Blocks 86++++++++++++++++++ 87 88All code will go through a translation phase although not all 89translations will be necessarily be executed. You need to instrument 90actual executions to track what is happening. 91 92It is quite normal to see the same address translated multiple times. 93If you want to track the code in system emulation you should examine 94the underlying physical address (``qemu_plugin_insn_haddr``) to take 95into account the effects of virtual memory although if the system does 96paging this will change too. 97 98Not all instructions in a block will always execute so if its 99important to track individual instruction execution you need to 100instrument them directly. However asynchronous interrupts will not 101change control flow mid-block. 102 103Instructions 104++++++++++++ 105 106Instruction instrumentation runs before the instruction executes. You 107can be can be sure the instruction will be dispatched, but you can't 108be sure it will complete. Generally this will be because of a 109synchronous exception (e.g. SIGILL) triggered by the instruction 110attempting to execute. If you want to be sure you will need to 111instrument the next instruction as well. See the ``execlog.c`` plugin 112for examples of how to track this and finalise details after execution. 113 114Memory Accesses 115+++++++++++++++ 116 117Memory callbacks are called after a successful load or store. 118Unsuccessful operations (i.e. faults) will not be visible to memory 119instrumentation although the execution side effects can be observed 120(e.g. entering a exception handler). 121 122System Idle and Resume States 123+++++++++++++++++++++++++++++ 124 125The ``qemu_plugin_register_vcpu_idle_cb`` and 126``qemu_plugin_register_vcpu_resume_cb`` functions can be used to track 127when CPUs go into and return from sleep states when waiting for 128external I/O. Be aware though that these may occur less frequently 129than in real HW due to the inefficiencies of emulation giving less 130chance for the CPU to idle. 131 132Internals 133--------- 134 135Locking 136~~~~~~~ 137 138We have to ensure we cannot deadlock, particularly under MTTCG. For 139this we acquire a lock when called from plugin code. We also keep the 140list of callbacks under RCU so that we do not have to hold the lock 141when calling the callbacks. This is also for performance, since some 142callbacks (e.g. memory access callbacks) might be called very 143frequently. 144 145 * A consequence of this is that we keep our own list of CPUs, so that 146 we do not have to worry about locking order wrt cpu_list_lock. 147 * Use a recursive lock, since we can get registration calls from 148 callbacks. 149 150As a result registering/unregistering callbacks is "slow", since it 151takes a lock. But this is very infrequent; we want performance when 152calling (or not calling) callbacks, not when registering them. Using 153RCU is great for this. 154 155We support the uninstallation of a plugin at any time (e.g. from 156plugin callbacks). This allows plugins to remove themselves if they no 157longer want to instrument the code. This operation is asynchronous 158which means callbacks may still occur after the uninstall operation is 159requested. The plugin isn't completely uninstalled until the safe work 160has executed while all vCPUs are quiescent. 161 162Plugin API 163========== 164 165The following API is generated from the inline documentation in 166``include/qemu/qemu-plugin.h``. Please ensure any updates to the API 167include the full kernel-doc annotations. 168 169.. kernel-doc:: include/qemu/qemu-plugin.h 170