From: Alex Bennée Date: Tue, 12 Nov 2019 16:28:53 +0000 (+0000) Subject: docs/devel: rename plugins.rst to tcg-plugins.rst X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=8ea6abf0d06c8a86af93bfc8135301aae1480b1f;p=qemu.git docs/devel: rename plugins.rst to tcg-plugins.rst This makes it a bit clearer what this is about. Signed-off-by: Alex Bennée Reviewed-by: Philippe Mathieu-Daudé --- diff --git a/MAINTAINERS b/MAINTAINERS index dfb7932608..5e5e3e52d6 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -2371,6 +2371,7 @@ F: tcg/ TCG Plugins M: Alex Bennée S: Maintained +F: docs/devel/tcg-plugins.rst F: plugins/ F: tests/plugin diff --git a/docs/devel/index.rst b/docs/devel/index.rst index 2ff058bae3..c86a3cdff2 100644 --- a/docs/devel/index.rst +++ b/docs/devel/index.rst @@ -22,4 +22,4 @@ Contents: decodetree secure-coding-practices tcg - plugins + tcg-plugins diff --git a/docs/devel/plugins.rst b/docs/devel/plugins.rst deleted file mode 100644 index b18fb6729e..0000000000 --- a/docs/devel/plugins.rst +++ /dev/null @@ -1,112 +0,0 @@ -.. - Copyright (C) 2017, Emilio G. Cota - Copyright (c) 2019, Linaro Limited - Written by Emilio Cota and Alex Bennée - -================ -QEMU TCG Plugins -================ - -QEMU TCG plugins provide a way for users to run experiments taking -advantage of the total system control emulation can have over a guest. -It provides a mechanism for plugins to subscribe to events during -translation and execution and optionally callback into the plugin -during these events. TCG plugins are unable to change the system state -only monitor it passively. However they can do this down to an -individual instruction granularity including potentially subscribing -to all load and store operations. - -API Stability -============= - -This is a new feature for QEMU and it does allow people to develop -out-of-tree plugins that can be dynamically linked into a running QEMU -process. However the project reserves the right to change or break the -API should it need to do so. The best way to avoid this is to submit -your plugin upstream so they can be updated if/when the API changes. - - -Exposure of QEMU internals --------------------------- - -The plugin architecture actively avoids leaking implementation details -about how QEMU's translation works to the plugins. While there are -conceptions such as translation time and translation blocks the -details are opaque to plugins. The plugin is able to query select -details of instructions and system configuration only through the -exported *qemu_plugin* functions. The types used to describe -instructions and events are opaque to the plugins themselves. - -Usage -===== - -The QEMU binary needs to be compiled for plugin support: - -:: - configure --enable-plugins - -Once built a program can be run with multiple plugins loaded each with -their own arguments: - -:: - $QEMU $OTHER_QEMU_ARGS \ - -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ - -plugin tests/plugin/libhotblocks.so - -Arguments are plugin specific and can be used to modify their -behaviour. In this case the howvec plugin is being asked to use inline -ops to count and break down the hint instructions by type. - -Plugin Life cycle -================= - -First the plugin is loaded and the public qemu_plugin_install function -is called. The plugin will then register callbacks for various plugin -events. Generally plugins will register a handler for the *atexit* -if they want to dump a summary of collected information once the -program/system has finished running. - -When a registered event occurs the plugin callback is invoked. The -callbacks may provide additional information. In the case of a -translation event the plugin has an option to enumerate the -instructions in a block of instructions and optionally register -callbacks to some or all instructions when they are executed. - -There is also a facility to add an inline event where code to -increment a counter can be directly inlined with the translation. -Currently only a simple increment is supported. This is not atomic so -can miss counts. If you want absolute precision you should use a -callback which can then ensure atomicity itself. - -Finally when QEMU exits all the registered *atexit* callbacks are -invoked. - -Internals -========= - -Locking -------- - -We have to ensure we cannot deadlock, particularly under MTTCG. For -this we acquire a lock when called from plugin code. We also keep the -list of callbacks under RCU so that we do not have to hold the lock -when calling the callbacks. This is also for performance, since some -callbacks (e.g. memory access callbacks) might be called very -frequently. - - * A consequence of this is that we keep our own list of CPUs, so that - we do not have to worry about locking order wrt cpu_list_lock. - * Use a recursive lock, since we can get registration calls from - callbacks. - -As a result registering/unregistering callbacks is "slow", since it -takes a lock. But this is very infrequent; we want performance when -calling (or not calling) callbacks, not when registering them. Using -RCU is great for this. - -We support the uninstallation of a plugin at any time (e.g. from -plugin callbacks). This allows plugins to remove themselves if they no -longer want to instrument the code. This operation is asynchronous -which means callbacks may still occur after the uninstall operation is -requested. The plugin isn't completely uninstalled until the safe work -has executed while all vCPUs are quiescent. diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst new file mode 100644 index 0000000000..b18fb6729e --- /dev/null +++ b/docs/devel/tcg-plugins.rst @@ -0,0 +1,112 @@ +.. + Copyright (C) 2017, Emilio G. Cota + Copyright (c) 2019, Linaro Limited + Written by Emilio Cota and Alex Bennée + +================ +QEMU TCG Plugins +================ + +QEMU TCG plugins provide a way for users to run experiments taking +advantage of the total system control emulation can have over a guest. +It provides a mechanism for plugins to subscribe to events during +translation and execution and optionally callback into the plugin +during these events. TCG plugins are unable to change the system state +only monitor it passively. However they can do this down to an +individual instruction granularity including potentially subscribing +to all load and store operations. + +API Stability +============= + +This is a new feature for QEMU and it does allow people to develop +out-of-tree plugins that can be dynamically linked into a running QEMU +process. However the project reserves the right to change or break the +API should it need to do so. The best way to avoid this is to submit +your plugin upstream so they can be updated if/when the API changes. + + +Exposure of QEMU internals +-------------------------- + +The plugin architecture actively avoids leaking implementation details +about how QEMU's translation works to the plugins. While there are +conceptions such as translation time and translation blocks the +details are opaque to plugins. The plugin is able to query select +details of instructions and system configuration only through the +exported *qemu_plugin* functions. The types used to describe +instructions and events are opaque to the plugins themselves. + +Usage +===== + +The QEMU binary needs to be compiled for plugin support: + +:: + configure --enable-plugins + +Once built a program can be run with multiple plugins loaded each with +their own arguments: + +:: + $QEMU $OTHER_QEMU_ARGS \ + -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \ + -plugin tests/plugin/libhotblocks.so + +Arguments are plugin specific and can be used to modify their +behaviour. In this case the howvec plugin is being asked to use inline +ops to count and break down the hint instructions by type. + +Plugin Life cycle +================= + +First the plugin is loaded and the public qemu_plugin_install function +is called. The plugin will then register callbacks for various plugin +events. Generally plugins will register a handler for the *atexit* +if they want to dump a summary of collected information once the +program/system has finished running. + +When a registered event occurs the plugin callback is invoked. The +callbacks may provide additional information. In the case of a +translation event the plugin has an option to enumerate the +instructions in a block of instructions and optionally register +callbacks to some or all instructions when they are executed. + +There is also a facility to add an inline event where code to +increment a counter can be directly inlined with the translation. +Currently only a simple increment is supported. This is not atomic so +can miss counts. If you want absolute precision you should use a +callback which can then ensure atomicity itself. + +Finally when QEMU exits all the registered *atexit* callbacks are +invoked. + +Internals +========= + +Locking +------- + +We have to ensure we cannot deadlock, particularly under MTTCG. For +this we acquire a lock when called from plugin code. We also keep the +list of callbacks under RCU so that we do not have to hold the lock +when calling the callbacks. This is also for performance, since some +callbacks (e.g. memory access callbacks) might be called very +frequently. + + * A consequence of this is that we keep our own list of CPUs, so that + we do not have to worry about locking order wrt cpu_list_lock. + * Use a recursive lock, since we can get registration calls from + callbacks. + +As a result registering/unregistering callbacks is "slow", since it +takes a lock. But this is very infrequent; we want performance when +calling (or not calling) callbacks, not when registering them. Using +RCU is great for this. + +We support the uninstallation of a plugin at any time (e.g. from +plugin callbacks). This allows plugins to remove themselves if they no +longer want to instrument the code. This operation is asynchronous +which means callbacks may still occur after the uninstall operation is +requested. The plugin isn't completely uninstalled until the safe work +has executed while all vCPUs are quiescent.