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

[Peter Maydell <peter.maydell@linaro.org>]

On Tue, 12 Nov 2019 at 16:41, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  docs/devel/tcg-plugins.rst | 16 ++++++++++++++++
>  1 file changed, 16 insertions(+)
>
> diff --git a/docs/devel/tcg-plugins.rst b/docs/devel/tcg-plugins.rst
> index b18fb6729e3..8d619fd44ef 100644
> --- a/docs/devel/tcg-plugins.rst
> +++ b/docs/devel/tcg-plugins.rst
> @@ -25,6 +25,22 @@ 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 is can be done simply by:

either "is" or "can be", but not both :-)

> +
> +::
> +    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.

It also refuses to load a plugin which exports a qemu_plugin_version
specifying a version which the core code doesn't support, right?

> 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.
> +
>

thanks
-- PMM