[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PATCH v4 11/54] docs/devel: add plugins.rst design documen
From: |
Alex Bennée |
Subject: |
[Qemu-devel] [PATCH v4 11/54] docs/devel: add plugins.rst design document |
Date: |
Wed, 31 Jul 2019 17:06:36 +0100 |
This is mostly extracted from Emilio's more verbose commit comments
with some additional verbiage from me.
Signed-off-by: Alex Bennée <address@hidden>
---
v4
- some rewording and tweaks
- made non-atomicity of inline ops more explicit
- expanded description of plugin unload
---
docs/devel/index.rst | 1 +
docs/devel/plugins.rst | 107 +++++++++++++++++++++++++++++++++++++++++
2 files changed, 108 insertions(+)
create mode 100644 docs/devel/plugins.rst
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 1ec61fcfed9..2ff058bae38 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -22,3 +22,4 @@ Contents:
decodetree
secure-coding-practices
tcg
+ plugins
diff --git a/docs/devel/plugins.rst b/docs/devel/plugins.rst
new file mode 100644
index 00000000000..0a31227b613
--- /dev/null
+++ b/docs/devel/plugins.rst
@@ -0,0 +1,107 @@
+..
+ Copyright (C) 2017, Emilio G. Cota <address@hidden>
+ 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.
+
+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.
+
+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.
--
2.20.1
- [Qemu-devel] [PATCH v4 03/54] target/arm: handle A-profile A32 semihosting at translate time, (continued)
- [Qemu-devel] [PATCH v4 03/54] target/arm: handle A-profile A32 semihosting at translate time, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 06/54] trace: expand mem_info:size_shift to 4 bits, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 04/54] target/arm: remove run time semihosting checks, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 15/54] plugin: add implementation of the api, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 10/54] translate-all: use cpu_in_exclusive_work_context() in tb_flush, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 05/54] includes: remove stale [smp|max]_cpus externs, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 08/54] tcg/README: fix typo s/afterwise/afterwards/, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 12/54] configure: add --enable-plugins (MOVE TO END), Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 13/54] plugin: add user-facing API, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 09/54] cpu: introduce cpu_in_exclusive_context(), Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 11/54] docs/devel: add plugins.rst design document,
Alex Bennée <=
- [Qemu-devel] [PATCH v4 29/54] plugin-gen: add plugin_insn_append, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 14/54] plugin: add core code, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 07/54] trace: add mmu_index to mem_info, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 45/54] linux-user: support -plugin option, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 53/54] include/exec: wrap cpu_ldst.h in CONFIG_TCG, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 33/54] target/sh4: fetch code with translator_ld, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 42/54] translator: inject instrumentation from plugins, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 19/54] tcg: add tcg_gen_st_ptr, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 54/54] include/exec/cpu-defs.h: fix typo, Alex Bennée, 2019/07/31
- [Qemu-devel] [PATCH v4 40/54] target/xtensa: fetch code with translator_ld, Alex Bennée, 2019/07/31