[RFC,1/4] docs/tcg-plugins: describe QPP API

Describe how multiple TCG plugins can interact using the QEMU
Plugin-to-Plugin API (QPP) with both callbacks and direct
function calls.

Signed-off-by: Andrew Fasano <fasano@mit.edu>
---
 docs/devel/tcg-plugins.rst | 76 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 76 insertions(+)

Andrew Fasano <fasano@mit.edu> writes:

> Describe how multiple TCG plugins can interact using the QEMU
> Plugin-to-Plugin API (QPP) with both callbacks and direct
> function calls.

Looks ok at first glance. I suspect it is quickly coming to the point we
need to split the examples and the API apart in the docs to stop things
getting too messy.

>
> Signed-off-by: Andrew Fasano <fasano@mit.edu>
> ---
>  docs/devel/tcg-plugins.rst | 76 ++++++++++++++++++++++++++++++++++++++
>  1 file changed, 76 insertions(+)
>
> diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst
> index a7cc44aa20..7985572027 100644
> --- a/docs/devel/tcg-plugins.rst
> +++ b/docs/devel/tcg-plugins.rst
> @@ -441,3 +441,79 @@ The plugin has a number of arguments, all of them are optional:
>    associativity of the L2 cache, respectively. Setting any of the L2
>    configuration arguments implies ``l2=on``.
>    (default: N = 2097152 (2MB), B = 64, A = 16)
> +
> +Plugin-to-Plugin Interactions
> +-----------------------------
> +
> +Plugins may interact with other plugins through the QEMU Plugin-to-Plugin
> +("QPP") API by including ``qemu/plugin-qpp.h``. This API supports direct
> +function calls between plugins as well as an inter-plugin callback system.
> +This API allows for composition of plugins: plugins can make use of logic in
> +other plugins without the need for code duplication.
> +
> +Plugin names
> +~~~~~~~~~~~~
> +Plugins are automatically given a name by removing the suffix from their
> +filename.  These plugin names will be used during QPP interactions as
> +described below.  A plugin can access its own name through the preprocessor
> +variable ``CURRENT_PLUGIN``.
> +
> +QPP function calls
> +~~~~~~~~~~~~~~~~~~
> +When a plugin (e.g. ``plugin_a``) wishes to make some of its functions (e.g.
> +``func_1``) available to other plugins, it must:
> +
> +1. Mark the function definition with the ``QEMU_PLUGIN_EXPORT`` macro. For
> +example : ``QEMU_PLUGIN_EXPORT int func_1(int x) {...}``.
> +2. Provide prototypes for exported functions in a header file (e.g.
> +``plugin_a.h``) using the macro ``QPP_FUN_PROTOTYPE`` with arguments of the
> +plugin's name, the function's return type, the function's name, and any
> +arguments the function takes. For example:
> +``QPP_FUN_PROTOTYPE(plugin_a, int, func_1, int);``.
> +3. Import this header from the plugin.
> +
> +When other plugins wish to use the functions exported by ``plugin_a``, they
> +must:
> +
> +1. Import the header file (e.g. ``plugin_a.h``) with the function prototype(s).
> +2. Call the function when desired by combining the target plugin name, an
> +   underscore, and the target function name, e.g. ``plugin_a_func_1()``.
> +
> +QPP callbacks
> +~~~~~~~~~~~~~
> +
> +The QPP API also allows a plugin to define callback events and for other plugins
> +to request to be notified whenever these events happens. The plugin that defines
> +the callback is responsible for triggering the callback when it so wishes. Other
> +plugins that wish to be notified on these events must define a function of an
> +appropriate type and register it to run on this event.
> +
> +When a plugin (e.g. ``plugin_a``) wishes to define a callback (an event that
> +other plugins can request to be notified about), it must:
> +
> +1. Define the callback using the ``QPP_CREATE_CB`` macro with a single argument
> +   of the callback's name. For example: ``QPP_CREATE_CB(on_some_event);``.
> +2. In a header file (e.g. ``plugin_a.h``) create a prototype for the callback
> +   type with ``QPP_CB_PROTOTYPE`` with arguments of the callback's return type
> +   (only ``void`` is currently supported), the name of the callback, and any
> +   arguments the callback function will be called with. For example with a
> +   callback named ``on_some_event`` that returns a void and takes an int and
> +   a bool as an argument, you would use: ``QPP_CB_PROTOTYPE(void,
> +   on_some_event, int, bool)``.
> +3. Import this header from the plugin.
> +4. When the plugin wishes to run any registered callback functions, it should
> +   use the macro ``QPP_RUN_CB`` with the first argument set to the callback
> +   name followed by the arguments as specified in the header. For example:
> +   ``QPP_RUN_CB(on_some_event, 2, true);``.
> +
> +When other plugins wish to register a function to run on such an event, they
> +must:
> +
> +1. Import the header file with the callback prototype(s) (e.g. ``plugin_a.h``)
> +2. Define a function that matches the callback signature. For example:
> +   ``void plugin_b_callback(int, bool) {...}``.
> +3. Register this function to be run on the callback using the ``QPP_REG_CB``
> +   macro with the first argument being the name of the plugin that provides the
> +   callback (as a string), the second being the callback name, and the third as
> +   the function that should be run. For example: ``QPP_REG_CB("plugin_a",
> +   on_some_event, plugin_b_callback);``