Re: [PATCH 3/4] docs/interop/firmware.json: Use full include paths

[Markus Armbruster <armbru@redhat.com>]

Thomas Weißschuh <thomas.weissschuh@linutronix.de> writes:

> The included files are part of the toplevel QAPI directory and need to
> be included from there.
>
> Signed-off-by: Thomas Weißschuh <thomas.weissschuh@linutronix.de>
> ---
>  docs/interop/firmware.json | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
>
> diff --git a/docs/interop/firmware.json b/docs/interop/firmware.json
> index 54a1fc6c1041..4ac840e2b413 100644
> --- a/docs/interop/firmware.json
> +++ b/docs/interop/firmware.json
> @@ -14,8 +14,8 @@
>  # = Firmware
>  ##
>  
> -{ 'include' : 'machine.json' }
> -{ 'include' : 'block-core.json' }
> +{ 'include' : '../../qapi/machine.json' }
> +{ 'include' : '../../qapi/block-core.json' }
>  
>  ##
>  # @FirmwareOSInterface:

The coupling with the main QAPI schema is unfortunate.

The purpose of docs/interop/firmware.json is to serve as schema for
firmware descriptions: a firmware description is a JSON object that
conforms to this schema's struct Firmware.

Such a description should be installed along with each firmware binary.

QAPI tooling can be used to check conformance: parse the firmware
description JSON object, feed it to the generated visit_type_Firmware().
Success implies conformance.

If you find more uses for the C struct Firmware created by
visit_type_Firmware(), more power to you.

firmware.json needs machine.json for SysEmuTarget, and block-core.json
for BlockdevDriver.  The largest and the third-largest QAPI module just
for two enums.  Almost a quarter Mebibyte of code.

qapi-gen.py generates more than 12kSLOC.  Without the include (and with
the enums dumbed down to 'str' to enable that), it generates less than
800.

We could use Sphinx to generate a manual from firmware.json's document.
Except that manual would be useless, because of its 11,000 lines of
HTML, less than 800 are for firmware.json.

Options:

* Live with the mess.

* Refactor QAPI modules so firmware.json can include just the enums.

  Drawback: we spread the mess into qapi/.  Ugh.

* Copy the enums to firmware.json.

  Drawback: we risk them going stale.

* Dumb down to 'str'.

  Drawback: the conformance check no longer enforces the value of
  FirmwareTarget member @architecture and FirmwareFlashFile member
  @format is valid.

Thoughts?