Re: [PATCH v2 04/20] qapi: Introduce MCD schema

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> Mario Fleischmann <mario.fleischmann@lauterbach.com> writes:
>
>> The MCD implementation follows a remote procedure call approach:
>> Each function from mcd_api.h will correspond to one command in mcd.json.
>>
>> Signed-off-by: Mario Fleischmann <mario.fleischmann@lauterbach.com>
>> ---
>>  MAINTAINERS          |  1 +
>>  docs/interop/mcd.rst | 13 +++++++++++++
>>  mcd/meson.build      | 27 +++++++++++++++++++++++++++
>>  qapi/mcd.json        |  6 ++++++
>>  4 files changed, 47 insertions(+)
>>  create mode 100644 qapi/mcd.json
>>
>> diff --git a/MAINTAINERS b/MAINTAINERS
>> index 327d3c5..7c085dc 100644
>> --- a/MAINTAINERS
>> +++ b/MAINTAINERS
>> @@ -3125,6 +3125,7 @@ M: Mario Fleischmann <mario.fleischmann@lauterbach.com>
>>  S: Maintained
>>  F: mcd/*
>>  F: docs/interop/mcd.rst
>> +F: qapi/mcd.json
>>  
>>  Memory API
>>  M: Paolo Bonzini <pbonzini@redhat.com>
>> diff --git a/docs/interop/mcd.rst b/docs/interop/mcd.rst
>> index 2b21303..13e81df 100644
>> --- a/docs/interop/mcd.rst
>> +++ b/docs/interop/mcd.rst
>> @@ -44,6 +44,19 @@ To configure the build for MCD support:
>>  
>>    ./configure --enable-mcd
>>  
>> +Debugging via QAPI
>> +------------------
>> +
>> +Since the MCD API does not define a communication protocol, a QAPI schema
>> +has been added to implement a remote procedure call mechanism.
>> +Each function within the API corresponds to one QAPI command, ensuring a
>> +one-to-one mapping between the API's functions and the QAPI commands.
>> +
>> +QAPI Reference
>> +--------------
>> +
>> +.. qapi-doc:: qapi/mcd.json
>
> You also need
>
>       :transmogrify:
>
> because we haven't completed the transition to John Snow's new doc
> generator ("transmogrifier"), and
>
>       :namespace: MCD
>
> for a properly separate namespace (see docs/devel/qapi-domain.rst).
>
> I'd expect this to generate its own index, but it doesn't.  John, can
> you have a look?

John has since reminded me of the need to add it to docs/conf.py.
Together, this generates docs/manual/qapi-mcd-index.html.  You need to
link to it manually.  Sketch appended for you convenience.

>> +
>>  API Reference
>>  -------------
>>  
>> diff --git a/mcd/meson.build b/mcd/meson.build
>> index 3e4e67a..d62a625 100644
>> --- a/mcd/meson.build
>> +++ b/mcd/meson.build
>> @@ -1,5 +1,32 @@
>> +mcd_qapi_outputs = [
>> +  'mcd-qapi-commands.c',
>> +  'mcd-qapi-commands.h',
>> +  'mcd-qapi-emit-events.c',
>> +  'mcd-qapi-emit-events.h',
>> +  'mcd-qapi-events.c',
>> +  'mcd-qapi-events.h',
>> +  'mcd-qapi-features.c',
>> +  'mcd-qapi-features.h',
>> +  'mcd-qapi-init-commands.c',
>> +  'mcd-qapi-init-commands.h',
>> +  'mcd-qapi-introspect.c',
>> +  'mcd-qapi-introspect.h',
>> +  'mcd-qapi-types.c',
>> +  'mcd-qapi-types.h',
>> +  'mcd-qapi-visit.c',
>> +  'mcd-qapi-visit.h',
>> +]
>> +
>> +mcd_qapi_files = custom_target('MCD QAPI files',
>> +                               output: mcd_qapi_outputs,
>> +                               input: '../qapi/mcd.json',
>> +                               command: [ qapi_gen, '-p', 'mcd-', '-o', 'mcd',
>> +                                          '--suppress-tracing','@INPUT0@'],
>> +                               depend_files: qapi_gen_depends)
>> +
>>  mcd_ss = ss.source_set()
>>  
>> +mcd_ss.add(mcd_qapi_files.to_list())
>>  mcd_ss.add(files(
>>    'mcd_server.c'))
>>  
>> diff --git a/qapi/mcd.json b/qapi/mcd.json
>> new file mode 100644
>> index 0000000..701fd03
>> --- /dev/null
>> +++ b/qapi/mcd.json
>
> Let's use mcd/qapi-schema.json, similar to the other independent QAPI
> schemas, such as qga/qapi-schema.json.
>
>> @@ -0,0 +1,6 @@
>> +# -*- Mode: Python -*-
>> +# vim: filetype=python
>> +
>> +##
>> +# = Multi-Core Debug (MCD) API
>> +##

diff --git a/docs/conf.py b/docs/conf.py
index f892a6e1da..9b57fb2ee6 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -201,6 +201,7 @@
 # Due to a limitation in Sphinx, we need to know which indices to
 # generate in advance. Adding a namespace here allows that generation.
 qapi_namespaces = {
+    "MCD",
     "QGA",
     "QMP",
     "QSD",
diff --git a/docs/interop/mcd.rst b/docs/interop/mcd.rst
index 860fa8d20f..eb02839e19 100644
--- a/docs/interop/mcd.rst
+++ b/docs/interop/mcd.rst
@@ -58,6 +58,8 @@ QAPI Reference
 --------------
 
 .. qapi-doc:: qapi/mcd.json
+   :transmogrify:
+   :namespace: MCD
 
 API Reference
 -------------
diff --git a/qapi/mcd.json b/qapi/mcd.json
index b90cdfab03..4f0d36c8f1 100644
--- a/qapi/mcd.json
+++ b/qapi/mcd.json
@@ -3,6 +3,8 @@
 
 ##
 # = Multi-Core Debug (MCD) API
+#
+# For locating a particular item, please see the `qapi-mcd-index`.
 ##