Zhao Liu <zhao1.liu@xxxxxxxxx> writes:
>> Let's ignore how to place it for now, and focus on where we would *like*
>> to place it.
>>
>> Is it related to anything other than ObjectType / ObjectOptions in the
>> QMP reference manual?
>
> Yes!
Now I'm confused :)
It is related to ObjectType / ObjectType.
Is it related to anything else in the QMP reference manual, and if yes,
to what exactly is it related?
>> I guess qapi/kvm.json is for KVM-specific stuff in general, not just the
>> KVM PMU filter. Should we have a section for accelerator-specific
>> stuff, with subsections for the various accelerators?
>>
>> [...]
>
> If we consider the accelerator from a top-down perspective, I understand
> that we need to add accelerator.json, kvm.json, and kvm-pmu-filter.json.
>
> The first two files are just to include subsections without any additional
> content. Is this overkill? Could we just add a single kvm-pmu-filter.json
> (I also considered this name, thinking that kvm might need to add more
> things in the future)?
>
> Of course, I lack experience with the file organization here. If you think
> the three-level sections (accelerator.json, kvm.json, and kvm-pmu-filter.json)
> is necessary, I am happy to try this way. :-)
We don't have to create files just to get a desired section structure.
I'll show you how in a jiffie, but before I do that, let me stress: we
should figure out what we want *first*, and only then how to get it.
So, what section structure would make the most sense for the QMP
reference manual?
A few hints on how...
Consider how qapi/block.json includes qapi/block-core.json:
##
# = Block devices
##
{ 'include': 'block-core.json' }
##
# == Additional block stuff (VM related)
##
block-core.json starts with
##
# == Block core (VM unrelated)
##
Together, this produces this section structure
= Block devices
==
##
Together, this produces this section structure
= Block devices
== Block core (VM unrelated)
== Additional block stuff (VM related)
Note that qapi/block-core.json isn't included anywhere else.
qapi/qapi-schema.json advises:
# Documentation generated with qapi-gen.py is in source order, with
# included sub-schemas inserted at the first include directive
# (subsequent include directives have no effect). To get a sane and
# stable order, it's best to include each sub-schema just once, or
# include it first right here.
