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