[PATCH v1 0/2] TCG plugin doc updates

[PATCH v1 0/2] TCG plugin doc updates

[Alex Bennée]

Hi,

A few minor tweaks to the TCG plugin documentation.

Alex Bennée (2):
  docs/devel: rename plugins.rst to tcg-plugins.rst
  docs/devel: update tcg-plugins.rst with API versioning details

 MAINTAINERS                                 |  1 +
 docs/devel/{plugins.rst => tcg-plugins.rst} | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)
 rename docs/devel/{plugins.rst => tcg-plugins.rst} (87%)

-- 
2.20.1

[PATCH v1 1/2] docs/devel: rename plugins.rst to tcg-plugins.rst

[Alex Bennée]

This makes it a bit clearer what this is about.

Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
---
 MAINTAINERS                                 | 1 +
 docs/devel/{plugins.rst => tcg-plugins.rst} | 0
 2 files changed, 1 insertion(+)
 rename docs/devel/{plugins.rst => tcg-plugins.rst} (100%)

diff --git a/MAINTAINERS b/MAINTAINERS
index ff8d0d29f4b..b160d817208 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -2369,6 +2369,7 @@ F: tcg/
 TCG Plugins
 M: Alex Bennée <alex.bennee@linaro.org>
 S: Maintained
+F: docs/devel/tcg-plugins.rst
 F: plugins/
 F: tests/plugin
 
diff --git a/docs/devel/plugins.rst b/docs/devel/tcg-plugins.rst
similarity index 100%
rename from docs/devel/plugins.rst
rename to docs/devel/tcg-plugins.rst
-- 
2.20.1

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

[Alex Bennée]

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

Re: [PATCH v1 1/2] docs/devel: rename plugins.rst to tcg-plugins.rst

[Peter Maydell]

On Tue, 12 Nov 2019 at 16:42, Alex Bennée <alex.bennee@linaro.org> wrote:
>
> This makes it a bit clearer what this is about.
>
> Signed-off-by: Alex Bennée <alex.bennee@linaro.org>
> ---
>  MAINTAINERS                                 | 1 +
>  docs/devel/{plugins.rst => tcg-plugins.rst} | 0
>  2 files changed, 1 insertion(+)
>  rename docs/devel/{plugins.rst => tcg-plugins.rst} (100%)
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index ff8d0d29f4b..b160d817208 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -2369,6 +2369,7 @@ F: tcg/
>  TCG Plugins
>  M: Alex Bennée <alex.bennee@linaro.org>
>  S: Maintained
> +F: docs/devel/tcg-plugins.rst
>  F: plugins/
>  F: tests/plugin
>
> diff --git a/docs/devel/plugins.rst b/docs/devel/tcg-plugins.rst
> similarity index 100%
> rename from docs/devel/plugins.rst
> rename to docs/devel/tcg-plugins.rst
> -

Don't you also need to update the reference
to 'plugins' in docs/devel/index.rst ?

thanks
-- PMM

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

[Peter Maydell]

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

Re: [PATCH v1 0/2] TCG plugin doc updates

[no-reply]

Patchew URL: https://patchew.org/QEMU/20191112164051.16404-1-alex.bennee@linaro.org/



Hi,

This series failed the docker-mingw@fedora build test. Please find the testing commands and
their output below. If you have Docker installed, you can probably reproduce it
locally.

=== TEST SCRIPT BEGIN ===
#! /bin/bash
export ARCH=x86_64
make docker-image-fedora V=1 NETWORK=1
time make docker-test-mingw@fedora J=14 NETWORK=1
=== TEST SCRIPT END ===

  CC      util/thread-pool.o
  CC      util/qemu-timer.o

Warning, treated as error:
/tmp/qemu-test/src/docs/devel/index.rst:13:toctree contains reference to nonexisting document 'plugins'
  CC      util/main-loop.o
  CC      util/aio-win32.o
---
  CC      util/error.o
  CC      util/qemu-error.o
  CC      util/qemu-print.o
make: *** [Makefile:1018: docs/devel/index.html] Error 2
make: *** Waiting for unfinished jobs....
Traceback (most recent call last):
  File "./tests/docker/docker.py", line 662, in <module>
---
    raise CalledProcessError(retcode, cmd)
subprocess.CalledProcessError: Command '['sudo', '-n', 'docker', 'run', '--label', 'com.qemu.instance.uuid=56318e0bd4904ba6866c9fbf90a5f3b3', '-u', '1001', '--security-opt', 'seccomp=unconfined', '--rm', '-e', 'TARGET_LIST=', '-e', 'EXTRA_CONFIGURE_OPTS=', '-e', 'V=', '-e', 'J=14', '-e', 'DEBUG=', '-e', 'SHOW_ENV=', '-e', 'CCACHE_DIR=/var/tmp/ccache', '-v', '/home/patchew/.cache/qemu-docker-ccache:/var/tmp/ccache:z', '-v', '/var/tmp/patchew-tester-tmp-gd8azaub/src/docker-src.2019-11-13-02.05.56.22302:/var/tmp/qemu:z,ro', 'qemu:fedora', '/var/tmp/qemu/run', 'test-mingw']' returned non-zero exit status 2.
filter=--filter=label=com.qemu.instance.uuid=56318e0bd4904ba6866c9fbf90a5f3b3
make[1]: *** [docker-run] Error 1
make[1]: Leaving directory `/var/tmp/patchew-tester-tmp-gd8azaub/src'
make: *** [docker-run-test-mingw@fedora] Error 2

real    1m52.187s
user    0m8.358s


The full log is available at
http://patchew.org/logs/20191112164051.16404-1-alex.bennee@linaro.org/testing.docker-mingw@fedora/?type=message.
---
Email generated automatically by Patchew [https://patchew.org/].
Please send your feedback to patchew-devel@redhat.com