1*8ea6abf0SAlex Bennée.. 2*8ea6abf0SAlex Bennée Copyright (C) 2017, Emilio G. Cota <cota@braap.org> 3*8ea6abf0SAlex Bennée Copyright (c) 2019, Linaro Limited 4*8ea6abf0SAlex Bennée Written by Emilio Cota and Alex Bennée 5*8ea6abf0SAlex Bennée 6*8ea6abf0SAlex Bennée================ 7*8ea6abf0SAlex BennéeQEMU TCG Plugins 8*8ea6abf0SAlex Bennée================ 9*8ea6abf0SAlex Bennée 10*8ea6abf0SAlex BennéeQEMU TCG plugins provide a way for users to run experiments taking 11*8ea6abf0SAlex Bennéeadvantage of the total system control emulation can have over a guest. 12*8ea6abf0SAlex BennéeIt provides a mechanism for plugins to subscribe to events during 13*8ea6abf0SAlex Bennéetranslation and execution and optionally callback into the plugin 14*8ea6abf0SAlex Bennéeduring these events. TCG plugins are unable to change the system state 15*8ea6abf0SAlex Bennéeonly monitor it passively. However they can do this down to an 16*8ea6abf0SAlex Bennéeindividual instruction granularity including potentially subscribing 17*8ea6abf0SAlex Bennéeto all load and store operations. 18*8ea6abf0SAlex Bennée 19*8ea6abf0SAlex BennéeAPI Stability 20*8ea6abf0SAlex Bennée============= 21*8ea6abf0SAlex Bennée 22*8ea6abf0SAlex BennéeThis is a new feature for QEMU and it does allow people to develop 23*8ea6abf0SAlex Bennéeout-of-tree plugins that can be dynamically linked into a running QEMU 24*8ea6abf0SAlex Bennéeprocess. However the project reserves the right to change or break the 25*8ea6abf0SAlex BennéeAPI should it need to do so. The best way to avoid this is to submit 26*8ea6abf0SAlex Bennéeyour plugin upstream so they can be updated if/when the API changes. 27*8ea6abf0SAlex Bennée 28*8ea6abf0SAlex Bennée 29*8ea6abf0SAlex BennéeExposure of QEMU internals 30*8ea6abf0SAlex Bennée-------------------------- 31*8ea6abf0SAlex Bennée 32*8ea6abf0SAlex BennéeThe plugin architecture actively avoids leaking implementation details 33*8ea6abf0SAlex Bennéeabout how QEMU's translation works to the plugins. While there are 34*8ea6abf0SAlex Bennéeconceptions such as translation time and translation blocks the 35*8ea6abf0SAlex Bennéedetails are opaque to plugins. The plugin is able to query select 36*8ea6abf0SAlex Bennéedetails of instructions and system configuration only through the 37*8ea6abf0SAlex Bennéeexported *qemu_plugin* functions. The types used to describe 38*8ea6abf0SAlex Bennéeinstructions and events are opaque to the plugins themselves. 39*8ea6abf0SAlex Bennée 40*8ea6abf0SAlex BennéeUsage 41*8ea6abf0SAlex Bennée===== 42*8ea6abf0SAlex Bennée 43*8ea6abf0SAlex BennéeThe QEMU binary needs to be compiled for plugin support: 44*8ea6abf0SAlex Bennée 45*8ea6abf0SAlex Bennée:: 46*8ea6abf0SAlex Bennée configure --enable-plugins 47*8ea6abf0SAlex Bennée 48*8ea6abf0SAlex BennéeOnce built a program can be run with multiple plugins loaded each with 49*8ea6abf0SAlex Bennéetheir own arguments: 50*8ea6abf0SAlex Bennée 51*8ea6abf0SAlex Bennée:: 52*8ea6abf0SAlex Bennée $QEMU $OTHER_QEMU_ARGS \ 53*8ea6abf0SAlex Bennée -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ 54*8ea6abf0SAlex Bennée -plugin tests/plugin/libhotblocks.so 55*8ea6abf0SAlex Bennée 56*8ea6abf0SAlex BennéeArguments are plugin specific and can be used to modify their 57*8ea6abf0SAlex Bennéebehaviour. In this case the howvec plugin is being asked to use inline 58*8ea6abf0SAlex Bennéeops to count and break down the hint instructions by type. 59*8ea6abf0SAlex Bennée 60*8ea6abf0SAlex BennéePlugin Life cycle 61*8ea6abf0SAlex Bennée================= 62*8ea6abf0SAlex Bennée 63*8ea6abf0SAlex BennéeFirst the plugin is loaded and the public qemu_plugin_install function 64*8ea6abf0SAlex Bennéeis called. The plugin will then register callbacks for various plugin 65*8ea6abf0SAlex Bennéeevents. Generally plugins will register a handler for the *atexit* 66*8ea6abf0SAlex Bennéeif they want to dump a summary of collected information once the 67*8ea6abf0SAlex Bennéeprogram/system has finished running. 68*8ea6abf0SAlex Bennée 69*8ea6abf0SAlex BennéeWhen a registered event occurs the plugin callback is invoked. The 70*8ea6abf0SAlex Bennéecallbacks may provide additional information. In the case of a 71*8ea6abf0SAlex Bennéetranslation event the plugin has an option to enumerate the 72*8ea6abf0SAlex Bennéeinstructions in a block of instructions and optionally register 73*8ea6abf0SAlex Bennéecallbacks to some or all instructions when they are executed. 74*8ea6abf0SAlex Bennée 75*8ea6abf0SAlex BennéeThere is also a facility to add an inline event where code to 76*8ea6abf0SAlex Bennéeincrement a counter can be directly inlined with the translation. 77*8ea6abf0SAlex BennéeCurrently only a simple increment is supported. This is not atomic so 78*8ea6abf0SAlex Bennéecan miss counts. If you want absolute precision you should use a 79*8ea6abf0SAlex Bennéecallback which can then ensure atomicity itself. 80*8ea6abf0SAlex Bennée 81*8ea6abf0SAlex BennéeFinally when QEMU exits all the registered *atexit* callbacks are 82*8ea6abf0SAlex Bennéeinvoked. 83*8ea6abf0SAlex Bennée 84*8ea6abf0SAlex BennéeInternals 85*8ea6abf0SAlex Bennée========= 86*8ea6abf0SAlex Bennée 87*8ea6abf0SAlex BennéeLocking 88*8ea6abf0SAlex Bennée------- 89*8ea6abf0SAlex Bennée 90*8ea6abf0SAlex BennéeWe have to ensure we cannot deadlock, particularly under MTTCG. For 91*8ea6abf0SAlex Bennéethis we acquire a lock when called from plugin code. We also keep the 92*8ea6abf0SAlex Bennéelist of callbacks under RCU so that we do not have to hold the lock 93*8ea6abf0SAlex Bennéewhen calling the callbacks. This is also for performance, since some 94*8ea6abf0SAlex Bennéecallbacks (e.g. memory access callbacks) might be called very 95*8ea6abf0SAlex Bennéefrequently. 96*8ea6abf0SAlex Bennée 97*8ea6abf0SAlex Bennée * A consequence of this is that we keep our own list of CPUs, so that 98*8ea6abf0SAlex Bennée we do not have to worry about locking order wrt cpu_list_lock. 99*8ea6abf0SAlex Bennée * Use a recursive lock, since we can get registration calls from 100*8ea6abf0SAlex Bennée callbacks. 101*8ea6abf0SAlex Bennée 102*8ea6abf0SAlex BennéeAs a result registering/unregistering callbacks is "slow", since it 103*8ea6abf0SAlex Bennéetakes a lock. But this is very infrequent; we want performance when 104*8ea6abf0SAlex Bennéecalling (or not calling) callbacks, not when registering them. Using 105*8ea6abf0SAlex BennéeRCU is great for this. 106*8ea6abf0SAlex Bennée 107*8ea6abf0SAlex BennéeWe support the uninstallation of a plugin at any time (e.g. from 108*8ea6abf0SAlex Bennéeplugin callbacks). This allows plugins to remove themselves if they no 109*8ea6abf0SAlex Bennéelonger want to instrument the code. This operation is asynchronous 110*8ea6abf0SAlex Bennéewhich means callbacks may still occur after the uninstall operation is 111*8ea6abf0SAlex Bennéerequested. The plugin isn't completely uninstalled until the safe work 112*8ea6abf0SAlex Bennéehas executed while all vCPUs are quiescent. 113