Thomas Weißschuh <thomas.weisssc...@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.weisssc...@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?
