From: "Alex Bennée" <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: "Alex Bennée" <alex.bennee@linaro.org>
Subject: [Qemu-devel] [PATCH v3 05/50] docs/devel: add plugins.rst design document
Date: Fri, 14 Jun 2019 18:11:15 +0100 [thread overview]
Message-ID: <20190614171200.21078-6-alex.bennee@linaro.org> (raw)
In-Reply-To: <20190614171200.21078-1-alex.bennee@linaro.org>
This is mostly extracted from Emilio's more verbose commit comments
with some additional verbiage from me.
Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
docs/devel/index.rst | 1 +
docs/devel/plugins.rst | 99 ++++++++++++++++++++++++++++++++++++++++++
2 files changed, 100 insertions(+)
create mode 100644 docs/devel/plugins.rst
diff --git a/docs/devel/index.rst b/docs/devel/index.rst
index 2a4ddf40ad..7e6d20c970 100644
--- a/docs/devel/index.rst
+++ b/docs/devel/index.rst
@@ -21,3 +21,4 @@ Contents:
testing
decodetree
secure-coding-practices
+ plugins
diff --git a/docs/devel/plugins.rst b/docs/devel/plugins.rst
new file mode 100644
index 0000000000..b0c30375ef
--- /dev/null
+++ b/docs/devel/plugins.rst
@@ -0,0 +1,99 @@
+..
+ Copyright (C) 2017, Emilio G. Cota <cota@braap.org>
+ 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 than 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
+
+Plugin Life cycle
+=================
+
+First the plugin is loaded and the public qemu_plugin_install function
+is called. The plugin with then register callbacks for various plugin
+events. Generally at least the atexit_cb is registered so the plugin
+can dump its information at the end of a run.
+
+When a registered event occurs the plugin callback is called. 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
+the plugin must either keep it's counters separated and indexed by CPU
+or use a callback which can ensure atomicity.
+
+Finally when QEMU exits all the registered atexit callbacks are called
+
+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 means some callbacks might still be called after the uninstall
+function returns. The plugin isn't completely uninstalled until the
+safe work has executed while all vCPUs are quiescent.
--
2.20.1
next prev parent reply other threads:[~2019-06-14 17:22 UTC|newest]
Thread overview: 117+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-06-14 17:11 [Qemu-devel] [PATCH v3 00/50] tcg plugin support Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 01/50] trace: expand mem_info:size_shift to 3 bits Alex Bennée
2019-06-17 2:12 ` Richard Henderson
2019-06-17 8:22 ` Alex Bennée
2019-06-17 23:29 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 02/50] tcg/README: fix typo s/afterwise/afterwards/ Alex Bennée
2019-06-17 2:13 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 03/50] cpu: introduce cpu_in_exclusive_work_context() Alex Bennée
2019-06-17 2:15 ` Richard Henderson
2019-06-20 9:50 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 04/50] translate-all: use cpu_in_exclusive_work_context() in tb_flush Alex Bennée
2019-06-14 17:11 ` Alex Bennée [this message]
2019-06-19 3:34 ` [Qemu-devel] [PATCH v3 05/50] docs/devel: add plugins.rst design document Pranith Kumar
2019-06-20 13:38 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 06/50] configure: add --enable-plugins (MOVE TO END) Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 07/50] plugin: add user-facing API Alex Bennée
2019-06-19 3:34 ` Pranith Kumar
2019-06-19 11:32 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 08/50] plugin: add core code Alex Bennée
[not found] ` <CADYwmhGiU_1GrBrR_tzBx+Lw+Hs3=Hi3AoPxRwkEj2pv9awqUg@mail.gmail.com>
2019-06-19 11:46 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 09/50] plugin: add implementation of the api Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 10/50] queue: add QTAILQ_REMOVE_SEVERAL Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 11/50] cputlb: document get_page_addr_code Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 12/50] cputlb: introduce get_page_addr_code_hostp Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 13/50] plugin-gen: add module for TCG-related code Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 14/50] tcg: add tcg_gen_st_ptr Alex Bennée
2019-06-17 20:19 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 15/50] tcg: add MO_HADDR to TCGMemOp Alex Bennée
2019-06-17 20:43 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 16/50] atomic_template: fix indentation in GEN_ATOMIC_HELPER Alex Bennée
2019-06-17 20:43 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 17/50] atomic_template: add inline trace/plugin helpers Alex Bennée
2019-06-17 20:47 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 18/50] cpu_ldst_useronly_template: remove redundant #ifndef CODE_ACCESS Alex Bennée
2019-06-17 20:47 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 19/50] tcg: let plugins instrument memory accesses Alex Bennée
2019-06-17 20:51 ` Richard Henderson
2019-06-28 15:30 ` Aaron Lindsay OS via Qemu-devel
2019-06-28 17:11 ` Alex Bennée
2019-06-28 17:58 ` Aaron Lindsay OS via Qemu-devel
2019-06-28 20:52 ` Alex Bennée
2019-07-01 14:40 ` Aaron Lindsay OS via Qemu-devel
2019-07-01 15:00 ` Alex Bennée
2019-07-02 14:07 ` Aaron Lindsay OS via Qemu-devel
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 20/50] translate-all: notify plugin code of tb_flush Alex Bennée
2019-06-17 20:54 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 21/50] *-user: notify plugin of exit Alex Bennée
2019-06-17 20:54 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 22/50] *-user: plugin syscalls Alex Bennée
2019-06-17 20:56 ` Richard Henderson
2019-06-19 3:35 ` Pranith Kumar
2019-07-01 14:20 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 23/50] cpu: hook plugin vcpu events Alex Bennée
2019-06-17 21:00 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 24/50] plugin-gen: add plugin_insn_append Alex Bennée
2019-06-17 21:03 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 25/50] translator: add translator_ld{ub, sw, uw, l, q} Alex Bennée
2019-06-17 21:06 ` Richard Henderson
2019-07-30 12:41 ` Alex Bennée
2019-07-30 13:23 ` Richard Henderson
2019-07-30 14:08 ` Alex Bennée
2019-07-30 17:04 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 26/50] target/arm: call qemu_plugin_insn_append Alex Bennée
2019-06-17 22:28 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 27/50] target/ppc: fetch code with translator_ld Alex Bennée
2019-06-17 22:30 ` Richard Henderson
2019-06-19 9:39 ` David Gibson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 28/50] target/sh4: " Alex Bennée
2019-06-17 22:33 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 29/50] target/i386: " Alex Bennée
2019-06-17 22:33 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 30/50] target/hppa: " Alex Bennée
2019-06-17 22:34 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 31/50] target/m68k: " Alex Bennée
2019-06-17 22:35 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 32/50] target/alpha: " Alex Bennée
2019-06-17 22:35 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 33/50] target/riscv: " Alex Bennée
2019-06-17 22:38 ` Richard Henderson
2019-06-19 10:49 ` Palmer Dabbelt
2019-09-27 21:47 ` Alistair Francis
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 34/50] target/sparc: " Alex Bennée
2019-06-17 22:39 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 35/50] target/xtensa: " Alex Bennée
2019-06-17 22:41 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 36/50] target/openrisc: " Alex Bennée
2019-06-17 22:41 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 37/50] translator: inject instrumentation from plugins Alex Bennée
2019-06-17 22:44 ` Richard Henderson
2019-06-20 16:51 ` Alex Bennée
2019-07-01 16:01 ` Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 38/50] plugin: add API symbols to qemu-plugins.symbols Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 39/50] vl: support -plugin option Alex Bennée
2019-06-17 22:53 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 40/50] linux-user: " Alex Bennée
2019-06-17 22:54 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 41/50] tests/plugin: add sample plugins Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 42/50] tests/tcg: enable plugin testing Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 43/50] tests/plugin: add a hotblocks plugin Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 44/50] plugin: add qemu_plugin_insn_disas helper Alex Bennée
2019-06-17 23:09 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 45/50] tests/plugin: add instruction execution breakdown Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 46/50] tests/plugin: add hotpages plugin to breakdown memory access patterns Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 47/50] accel/stubs: reduce headers from tcg-stub Alex Bennée
2019-06-17 23:22 ` Richard Henderson
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 48/50] include/exec: wrap cpu_ldst.h in CONFIG_TCG Alex Bennée
2019-06-14 17:11 ` [Qemu-devel] [PATCH v3 49/50] include/exec/cpu-defs.h: fix typo Alex Bennée
2019-06-17 23:23 ` Richard Henderson
2019-06-14 17:12 ` [Qemu-devel] [PATCH v3 50/50] TODO: API changes to make? Alex Bennée
2019-06-14 17:41 ` [Qemu-devel] [PATCH v3 00/50] tcg plugin support Aleksandar Markovic
2019-06-14 18:39 ` Alex Bennée
2019-06-14 19:47 ` no-reply
2019-06-14 19:48 ` no-reply
2019-06-20 13:53 ` Pranith Kumar
2019-06-21 8:21 ` Alex Bennée
2019-06-21 17:36 ` Pranith Kumar
2019-07-01 16:51 ` Alex Bennée
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20190614171200.21078-6-alex.bennee@linaro.org \
--to=alex.bennee@linaro.org \
--cc=qemu-devel@nongnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).