[v1,3/5] docs/devel: update tcg-plugins.rst with API versioning details
diff mbox series

Message ID 20191113115952.775-4-alex.bennee@linaro.org
State New
Headers show
Series
  • misc doc and testing fixes
Related show

Commit Message

Alex Bennée Nov. 13, 2019, 11:59 a.m. UTC
While we are at it fix up the quoted code sections with the inline ::
approach.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>

---
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(-)

Comments

Robert Foley Nov. 13, 2019, 2:40 p.m. UTC | #1
On Wed, 13 Nov 2019 at 07:00, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> While we are at it fix up the quoted code sections with the inline ::
> approach.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
>
> ---
> 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 <robert.foley@linaro.org>

Patch
diff mbox series

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