Markus Armbruster <arm...@redhat.com> writes:
> Mario Fleischmann <mario.fleischm...@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.fleischm...@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.fleischm...@lauterbach.com>
>> S: Maintained
>> F: mcd/*
>> F: docs/interop/mcd.rst
>> +F: qapi/mcd.json
>>
>> Memory API
>> M: Paolo Bonzini <pbonz...@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`.
##
