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================ 7QEMU TCG Plugins 8================ 9 10QEMU TCG plugins provide a way for users to run experiments taking 11advantage of the total system control emulation can have over a guest. 12It provides a mechanism for plugins to subscribe to events during 13translation and execution and optionally callback into the plugin 14during these events. TCG plugins are unable to change the system state 15only monitor it passively. However they can do this down to an 16individual instruction granularity including potentially subscribing 17to all load and store operations. 18 19API Stability 20============= 21 22This is a new feature for QEMU and it does allow people to develop 23out-of-tree plugins that can be dynamically linked into a running QEMU 24process. However the project reserves the right to change or break the 25API should it need to do so. The best way to avoid this is to submit 26your plugin upstream so they can be updated if/when the API changes. 27 28API versioning 29-------------- 30 31All plugins need to declare a symbol which exports the plugin API 32version they were built against. This can be done simply by:: 33 34 QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION; 35 36The core code will refuse to load a plugin that doesn't export a 37`qemu_plugin_version` symbol or if plugin version is outside of QEMU's 38supported range of API versions. 39 40Additionally the `qemu_info_t` structure which is passed to the 41`qemu_plugin_install` method of a plugin will detail the minimum and 42current API versions supported by QEMU. The API version will be 43incremented if new APIs are added. The minimum API version will be 44incremented if existing APIs are changed or removed. 45 46Exposure of QEMU internals 47-------------------------- 48 49The plugin architecture actively avoids leaking implementation details 50about how QEMU's translation works to the plugins. While there are 51conceptions such as translation time and translation blocks the 52details are opaque to plugins. The plugin is able to query select 53details of instructions and system configuration only through the 54exported *qemu_plugin* functions. 55 56Query Handle Lifetime 57--------------------- 58 59Each callback provides an opaque anonymous information handle which 60can usually be further queried to find out information about a 61translation, instruction or operation. The handles themselves are only 62valid during the lifetime of the callback so it is important that any 63information that is needed is extracted during the callback and saved 64by the plugin. 65 66Usage 67===== 68 69The QEMU binary needs to be compiled for plugin support:: 70 71 configure --enable-plugins 72 73Once built a program can be run with multiple plugins loaded each with 74their own arguments:: 75 76 $QEMU $OTHER_QEMU_ARGS \ 77 -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ 78 -plugin tests/plugin/libhotblocks.so 79 80Arguments are plugin specific and can be used to modify their 81behaviour. In this case the howvec plugin is being asked to use inline 82ops to count and break down the hint instructions by type. 83 84Plugin Life cycle 85================= 86 87First the plugin is loaded and the public qemu_plugin_install function 88is called. The plugin will then register callbacks for various plugin 89events. Generally plugins will register a handler for the *atexit* 90if they want to dump a summary of collected information once the 91program/system has finished running. 92 93When a registered event occurs the plugin callback is invoked. The 94callbacks may provide additional information. In the case of a 95translation event the plugin has an option to enumerate the 96instructions in a block of instructions and optionally register 97callbacks to some or all instructions when they are executed. 98 99There is also a facility to add an inline event where code to 100increment a counter can be directly inlined with the translation. 101Currently only a simple increment is supported. This is not atomic so 102can miss counts. If you want absolute precision you should use a 103callback which can then ensure atomicity itself. 104 105Finally when QEMU exits all the registered *atexit* callbacks are 106invoked. 107 108Internals 109========= 110 111Locking 112------- 113 114We have to ensure we cannot deadlock, particularly under MTTCG. For 115this we acquire a lock when called from plugin code. We also keep the 116list of callbacks under RCU so that we do not have to hold the lock 117when calling the callbacks. This is also for performance, since some 118callbacks (e.g. memory access callbacks) might be called very 119frequently. 120 121 * A consequence of this is that we keep our own list of CPUs, so that 122 we do not have to worry about locking order wrt cpu_list_lock. 123 * Use a recursive lock, since we can get registration calls from 124 callbacks. 125 126As a result registering/unregistering callbacks is "slow", since it 127takes a lock. But this is very infrequent; we want performance when 128calling (or not calling) callbacks, not when registering them. Using 129RCU is great for this. 130 131We support the uninstallation of a plugin at any time (e.g. from 132plugin callbacks). This allows plugins to remove themselves if they no 133longer want to instrument the code. This operation is asynchronous 134which means callbacks may still occur after the uninstall operation is 135requested. The plugin isn't completely uninstalled until the safe work 136has executed while all vCPUs are quiescent. 137