Re: FW: [PATCH v1 3/5] docs/devel: update tcg-plugins.rst with API versioning details

[Robert Foley]

On Wed, 13 Nov 2019 at 07:00, Alex Bennée <address@hidden> wrote:
>
> While we are at it fix up the quoted code sections with the inline ::
> approach.
>
> Signed-off-by: Alex Bennée <address@hidden>
>
> ---
> v2
>   - fix grammar
>   - mention we also will fail to load outside the range
>   - clean-up code sections
> ---
>  docs/devel/tcg-plugins.rst | 27 +++++++++++++++++++++------
>  1 file changed, 21 insertions(+), 6 deletions(-)
>
> diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst
> index b18fb6729e3..718eef00f22 100644
> --- a/docs/devel/tcg-plugins.rst
> +++ b/docs/devel/tcg-plugins.rst
> @@ -25,6 +25,23 @@ 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.
>
> +API versioning
> +--------------
> +
> +All plugins need to declare a symbol which exports the plugin API
> +version they were built against. This can be done simply by::
> +
> +  QEMU_PLUGIN_EXPORT int qemu_plugin_version = QEMU_PLUGIN_VERSION;
> +
> +The core code will refuse to load a plugin that doesn't export a
> +`qemu_plugin_version` symbol or if plugin version is outside of QEMU's
> +supported range of API versions.
> +
> +Additionally the `qemu_info_t` structure which is passed to the
> +`qemu_plugin_install` method of a plugin will detail the minimum and
> +current API versions supported by QEMU. The API version will be
> +incremented if new APIs are added. The minimum API version will be
> +incremented if existing APIs are changed or removed.
>
>  Exposure of QEMU internals
>  --------------------------
> @@ -40,16 +57,14 @@ instructions and events are opaque to the plugins 
> themselves.
>  Usage
>  =====
>
> -The QEMU binary needs to be compiled for plugin support:
> +The QEMU binary needs to be compiled for plugin support::
>
> -::
> -    configure --enable-plugins
> +  configure --enable-plugins
>
>  Once built a program can be run with multiple plugins loaded each with
> -their own arguments:
> +their own arguments::
>
> -::
> -    $QEMU $OTHER_QEMU_ARGS \
> +  $QEMU $OTHER_QEMU_ARGS \
>        -plugin tests/plugin/libhowvec.so,arg=inline,arg=hint \
>        -plugin tests/plugin/libhotblocks.so
>
> --
> 2.20.1
>
>
Reviewed-by: Robert Foley <address@hidden>