* [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag @ 2020-02-27 13:40 Philippe Mathieu-Daudé 2020-02-27 14:52 ` Markus Armbruster 0 siblings, 1 reply; 8+ messages in thread From: Philippe Mathieu-Daudé @ 2020-02-27 13:40 UTC (permalink / raw) To: qemu-devel Cc: Eduardo Habkost, Markus Armbruster, Philippe Mathieu-Daudé This fixes when adding a 'Since' tag: In file included from qapi/qapi-schema.json:105: qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section Reviewed-by: Liam Merwick <liam.merwick@oracle.com> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> --- v2: Fix another occurrence in CpuInstanceProperties (Liam Merwick) --- qapi/machine.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/qapi/machine.json b/qapi/machine.json index 6c11e3cf3a..3d8b5324f3 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -16,11 +16,11 @@ # individual target constants are not documented here, for the time # being. # +# Since: 3.0 +# # Notes: The resulting QMP strings can be appended to the "qemu-system-" # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". -# -# Since: 3.0 ## { 'enum' : 'SysEmuTarget', 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', @@ -820,13 +820,13 @@ # @die-id: die number within node/board the CPU belongs to (Since 4.1) # @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to # +# Since: 2.7 +# # Note: currently there are 5 properties that could be present # but management should be prepared to pass through other # properties with device_add command to allow for future # interface extension. This also requires the filed names to be kept in # sync with the properties passed to -device/device_add. -# -# Since: 2.7 ## { 'struct': 'CpuInstanceProperties', 'data': { '*node-id': 'int', -- 2.21.1 ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-27 13:40 [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag Philippe Mathieu-Daudé @ 2020-02-27 14:52 ` Markus Armbruster 2020-02-27 14:55 ` Philippe Mathieu-Daudé 0 siblings, 1 reply; 8+ messages in thread From: Markus Armbruster @ 2020-02-27 14:52 UTC (permalink / raw) To: Philippe Mathieu-Daudé; +Cc: qemu-devel, Eduardo Habkost Philippe Mathieu-Daudé <philmd@redhat.com> writes: > This fixes when adding a 'Since' tag: > > In file included from qapi/qapi-schema.json:105: > qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section I'm confused. This error is detected in scripts/qapi/parser.py, and it is fatal. Is the build broken for you? It isn't for me. Moreover, where is @arch? I can't see it anywhere close to the two spots the patch patches. > > Reviewed-by: Liam Merwick <liam.merwick@oracle.com> > Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> > --- > v2: Fix another occurrence in CpuInstanceProperties (Liam Merwick) > --- > qapi/machine.json | 8 ++++---- > 1 file changed, 4 insertions(+), 4 deletions(-) > > diff --git a/qapi/machine.json b/qapi/machine.json > index 6c11e3cf3a..3d8b5324f3 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -16,11 +16,11 @@ > # individual target constants are not documented here, for the time > # being. > # > +# Since: 3.0 > +# > # Notes: The resulting QMP strings can be appended to the "qemu-system-" > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > -# > -# Since: 3.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > @@ -820,13 +820,13 @@ > # @die-id: die number within node/board the CPU belongs to (Since 4.1) > # @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to > # > +# Since: 2.7 > +# > # Note: currently there are 5 properties that could be present > # but management should be prepared to pass through other > # properties with device_add command to allow for future > # interface extension. This also requires the filed names to be kept in > # sync with the properties passed to -device/device_add. > -# > -# Since: 2.7 > ## > { 'struct': 'CpuInstanceProperties', > 'data': { '*node-id': 'int', ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-27 14:52 ` Markus Armbruster @ 2020-02-27 14:55 ` Philippe Mathieu-Daudé 2020-02-27 15:21 ` Philippe Mathieu-Daudé 0 siblings, 1 reply; 8+ messages in thread From: Philippe Mathieu-Daudé @ 2020-02-27 14:55 UTC (permalink / raw) To: Markus Armbruster; +Cc: qemu-devel, Eduardo Habkost On 2/27/20 3:52 PM, Markus Armbruster wrote: > Philippe Mathieu-Daudé <philmd@redhat.com> writes: > >> This fixes when adding a 'Since' tag: >> >> In file included from qapi/qapi-schema.json:105: >> qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section > > I'm confused. This error is detected in scripts/qapi/parser.py, and it > is fatal. Is the build broken for you? It isn't for me. Moreover, > where is @arch? I can't see it anywhere close to the two spots the > patch patches. I get the error after trying to fix what Eric commented here: https://www.mail-archive.com/qemu-devel@nongnu.org/msg682344.html > >> >> Reviewed-by: Liam Merwick <liam.merwick@oracle.com> >> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> >> --- >> v2: Fix another occurrence in CpuInstanceProperties (Liam Merwick) >> --- >> qapi/machine.json | 8 ++++---- >> 1 file changed, 4 insertions(+), 4 deletions(-) >> >> diff --git a/qapi/machine.json b/qapi/machine.json >> index 6c11e3cf3a..3d8b5324f3 100644 >> --- a/qapi/machine.json >> +++ b/qapi/machine.json >> @@ -16,11 +16,11 @@ >> # individual target constants are not documented here, for the time >> # being. >> # >> +# Since: 3.0 >> +# >> # Notes: The resulting QMP strings can be appended to the "qemu-system-" >> # prefix to produce the corresponding QEMU executable name. This >> # is true even for "qemu-system-x86_64". >> -# >> -# Since: 3.0 >> ## >> { 'enum' : 'SysEmuTarget', >> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >> @@ -820,13 +820,13 @@ >> # @die-id: die number within node/board the CPU belongs to (Since 4.1) >> # @core-id: core number within die the CPU belongs to# @thread-id: thread number within core the CPU belongs to >> # >> +# Since: 2.7 >> +# >> # Note: currently there are 5 properties that could be present >> # but management should be prepared to pass through other >> # properties with device_add command to allow for future >> # interface extension. This also requires the filed names to be kept in >> # sync with the properties passed to -device/device_add. >> -# >> -# Since: 2.7 >> ## >> { 'struct': 'CpuInstanceProperties', >> 'data': { '*node-id': 'int', > ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-27 14:55 ` Philippe Mathieu-Daudé @ 2020-02-27 15:21 ` Philippe Mathieu-Daudé 2020-02-27 20:14 ` Eduardo Habkost 2020-02-28 6:56 ` Markus Armbruster 0 siblings, 2 replies; 8+ messages in thread From: Philippe Mathieu-Daudé @ 2020-02-27 15:21 UTC (permalink / raw) To: Markus Armbruster; +Cc: qemu-devel, Eduardo Habkost On 2/27/20 3:55 PM, Philippe Mathieu-Daudé wrote: > On 2/27/20 3:52 PM, Markus Armbruster wrote: >> Philippe Mathieu-Daudé <philmd@redhat.com> writes: >> >>> This fixes when adding a 'Since' tag: >>> >>> In file included from qapi/qapi-schema.json:105: >>> qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section >> >> I'm confused. This error is detected in scripts/qapi/parser.py, and it >> is fatal. Is the build broken for you? It isn't for me. Moreover, >> where is @arch? I can't see it anywhere close to the two spots the >> patch patches. > > I get the error after trying to fix what Eric commented here: > https://www.mail-archive.com/qemu-devel@nongnu.org/msg682344.html Using: --- diff --git a/qapi/machine.json b/qapi/machine.json index 6c11e3cf3a..40a36d6276 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -20,13 +20,15 @@ # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". # +# @rx: since 5.0 +# # Since: 3.0 ## { 'enum' : 'SysEmuTarget', 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', 'x86_64', 'xtensa', 'xtensaeb' ] } --- or --- diff --git a/qapi/machine.json b/qapi/machine.json index 6c11e3cf3a..4b59e87b6f 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -21,12 +21,14 @@ # is true even for "qemu-system-x86_64". # # Since: 3.0 +# +# @rx: since 5.0 ## { 'enum' : 'SysEmuTarget', 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', 'x86_64', 'xtensa', 'xtensaeb' ] } --- I get: GEN qapi-gen GEN rx-softmmu/config-devices.mak In file included from qapi/qapi-schema.json:105: qapi/machine.json:23:1: '@rx:' can't follow 'Notes' section make: *** [Makefile:645: qapi-gen-timestamp] Error 1 This works however: --- ## # @SysEmuTarget: # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and # look for the *-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. # +# @rx: since 5.0 +# # Notes: The resulting QMP strings can be appended to the "qemu-system-" # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". # # Since: 3.0 ## { 'enum' : 'SysEmuTarget', 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', 'x86_64', 'xtensa', 'xtensaeb' ] } --- > >> >>> >>> Reviewed-by: Liam Merwick <liam.merwick@oracle.com> >>> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> >>> --- >>> v2: Fix another occurrence in CpuInstanceProperties (Liam Merwick) >>> --- >>> qapi/machine.json | 8 ++++---- >>> 1 file changed, 4 insertions(+), 4 deletions(-) >>> >>> diff --git a/qapi/machine.json b/qapi/machine.json >>> index 6c11e3cf3a..3d8b5324f3 100644 >>> --- a/qapi/machine.json >>> +++ b/qapi/machine.json >>> @@ -16,11 +16,11 @@ >>> # individual target constants are not documented here, for the time >>> # being. >>> # >>> +# Since: 3.0 >>> +# >>> # Notes: The resulting QMP strings can be appended to the >>> "qemu-system-" >>> # prefix to produce the corresponding QEMU executable name. >>> This >>> # is true even for "qemu-system-x86_64". >>> -# >>> -# Since: 3.0 >>> ## >>> { 'enum' : 'SysEmuTarget', >>> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', >>> 'lm32', >>> @@ -820,13 +820,13 @@ >>> # @die-id: die number within node/board the CPU belongs to (Since 4.1) >>> # @core-id: core number within die the CPU belongs to# @thread-id: >>> thread number within core the CPU belongs to >>> # >>> +# Since: 2.7 >>> +# >>> # Note: currently there are 5 properties that could be present >>> # but management should be prepared to pass through other >>> # properties with device_add command to allow for future >>> # interface extension. This also requires the filed names to >>> be kept in >>> # sync with the properties passed to -device/device_add. >>> -# >>> -# Since: 2.7 >>> ## >>> { 'struct': 'CpuInstanceProperties', >>> 'data': { '*node-id': 'int', >> ^ permalink raw reply related [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-27 15:21 ` Philippe Mathieu-Daudé @ 2020-02-27 20:14 ` Eduardo Habkost 2020-02-28 6:56 ` Markus Armbruster 1 sibling, 0 replies; 8+ messages in thread From: Eduardo Habkost @ 2020-02-27 20:14 UTC (permalink / raw) To: Philippe Mathieu-Daudé; +Cc: Markus Armbruster, qemu-devel On Thu, Feb 27, 2020 at 04:21:56PM +0100, Philippe Mathieu-Daudé wrote: > On 2/27/20 3:55 PM, Philippe Mathieu-Daudé wrote: > > On 2/27/20 3:52 PM, Markus Armbruster wrote: > > > Philippe Mathieu-Daudé <philmd@redhat.com> writes: > > > > > > > This fixes when adding a 'Since' tag: > > > > > > > > In file included from qapi/qapi-schema.json:105: > > > > qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section > > > > > > I'm confused. This error is detected in scripts/qapi/parser.py, and it > > > is fatal. Is the build broken for you? It isn't for me. Moreover, > > > where is @arch? I can't see it anywhere close to the two spots the > > > patch patches. > > > > I get the error after trying to fix what Eric commented here: > > https://www.mail-archive.com/qemu-devel@nongnu.org/msg682344.html > > Using: > --- > diff --git a/qapi/machine.json b/qapi/machine.json > index 6c11e3cf3a..40a36d6276 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -20,13 +20,15 @@ > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > # > +# @rx: since 5.0 > +# > # Since: 3.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', > 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', > - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', > + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', > 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', > 'x86_64', 'xtensa', 'xtensaeb' ] } > --- > > or > > --- > diff --git a/qapi/machine.json b/qapi/machine.json > index 6c11e3cf3a..4b59e87b6f 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -21,12 +21,14 @@ > # is true even for "qemu-system-x86_64". > # > # Since: 3.0 > +# > +# @rx: since 5.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', > 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', > - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', > + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', > 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', > 'x86_64', 'xtensa', 'xtensaeb' ] } > --- > > I get: > > GEN qapi-gen > GEN rx-softmmu/config-devices.mak > In file included from qapi/qapi-schema.json:105: > qapi/machine.json:23:1: '@rx:' can't follow 'Notes' section > make: *** [Makefile:645: qapi-gen-timestamp] Error 1 > > This works however: > > --- > ## > # @SysEmuTarget: > # > # The comprehensive enumeration of QEMU system emulation ("softmmu") > # targets. Run "./configure --help" in the project root directory, and > # look for the *-softmmu targets near the "--target-list" option. The > # individual target constants are not documented here, for the time > # being. > # > +# @rx: since 5.0 > +# > # Notes: The resulting QMP strings can be appended to the "qemu-system-" > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > # > # Since: 3.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', > 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', > - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', > + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', > 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', > 'x86_64', 'xtensa', 'xtensaeb' ] } If this works, what exactly is the problem this patch is trying to fix? -- Eduardo ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-27 15:21 ` Philippe Mathieu-Daudé 2020-02-27 20:14 ` Eduardo Habkost @ 2020-02-28 6:56 ` Markus Armbruster 2020-02-28 10:17 ` Philippe Mathieu-Daudé 1 sibling, 1 reply; 8+ messages in thread From: Markus Armbruster @ 2020-02-28 6:56 UTC (permalink / raw) To: Philippe Mathieu-Daudé; +Cc: qemu-devel, Eduardo Habkost Philippe Mathieu-Daudé <philmd@redhat.com> writes: > On 2/27/20 3:55 PM, Philippe Mathieu-Daudé wrote: >> On 2/27/20 3:52 PM, Markus Armbruster wrote: >>> Philippe Mathieu-Daudé <philmd@redhat.com> writes: >>> >>>> This fixes when adding a 'Since' tag: >>>> >>>> In file included from qapi/qapi-schema.json:105: >>>> qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section >>> >>> I'm confused. This error is detected in scripts/qapi/parser.py, and it >>> is fatal. Is the build broken for you? It isn't for me. Moreover, >>> where is @arch? I can't see it anywhere close to the two spots the >>> patch patches. >> >> I get the error after trying to fix what Eric commented here: >> https://www.mail-archive.com/qemu-devel@nongnu.org/msg682344.html > > Using: > --- > diff --git a/qapi/machine.json b/qapi/machine.json > index 6c11e3cf3a..40a36d6276 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -20,13 +20,15 @@ > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > # > +# @rx: since 5.0 > +# > # Since: 3.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', > 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', > - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', > + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', > 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', > 'x86_64', 'xtensa', 'xtensaeb' ] } > --- > > or > > --- > diff --git a/qapi/machine.json b/qapi/machine.json > index 6c11e3cf3a..4b59e87b6f 100644 > --- a/qapi/machine.json > +++ b/qapi/machine.json > @@ -21,12 +21,14 @@ > # is true even for "qemu-system-x86_64". > # > # Since: 3.0 > +# > +# @rx: since 5.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', > 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', > - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', > + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', > 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', > 'x86_64', 'xtensa', 'xtensaeb' ] } > --- > > I get: > > GEN qapi-gen > GEN rx-softmmu/config-devices.mak > In file included from qapi/qapi-schema.json:105: > qapi/machine.json:23:1: '@rx:' can't follow 'Notes' section > make: *** [Makefile:645: qapi-gen-timestamp] Error 1 > > This works however: > > --- > ## > # @SysEmuTarget: > # > # The comprehensive enumeration of QEMU system emulation ("softmmu") > # targets. Run "./configure --help" in the project root directory, and > # look for the *-softmmu targets near the "--target-list" option. The > # individual target constants are not documented here, for the time > # being. > # > +# @rx: since 5.0 > +# > # Notes: The resulting QMP strings can be appended to the "qemu-system-" > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > # > # Since: 3.0 > ## > { 'enum' : 'SysEmuTarget', > 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', > 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', > 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', > - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', > + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', > 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', > 'x86_64', 'xtensa', 'xtensaeb' ] } > --- This one adds it to the correct spot. qapi-code-gen.txt: Definition documentation starts with a line naming the definition, followed by an optional overview, a description of each argument (for commands and events), member (for structs and unions), branch (for alternates), or value (for enums), and finally optional tagged sections. Let's apply this to SysEmuTarget's doc comment: ## # @SysEmuTarget: Line naming the definition # # The comprehensive enumeration of QEMU system emulation ("softmmu") # targets. Run "./configure --help" in the project root directory, and # look for the *-softmmu targets near the "--target-list" option. The # individual target constants are not documented here, for the time # being. Optional overview. Missing here: a description of each value. We should enforce such descriptions. We don't, mostly because we have a number of exceptions where documentation would be bothersome, such as enum QKeyCode. # # Notes: The resulting QMP strings can be appended to the "qemu-system-" # prefix to produce the corresponding QEMU executable name. This # is true even for "qemu-system-x86_64". A tagged section. # # Since: 3.0 Another tagged section. ## Note that qapi-code-gen.txt prescribes no order for the tagged sections. They actually occur in pretty much any order: $ awk '/^##/ { if (on) { if (length(t) > 1) print t; t="" } on=!on } on && /^# (Returns|Since|Notes?|Examples?|TODO):/ { t=t substr($2, 1, 1) }' qapi/*json | sort | uniq -c 1 ENS 2 ES 1 NES 1 NETS 1 NNSE 1 NRS 2 NRSE 14 NS 11 NSE 1 RE 6 RES 4 RNS 6 RNSE 23 RS 78 RSE 1 RSEEEE 3 RSEN 12 RSNE 55 SE 4 SN 2 SNE 2 SRNE 1 TRSE 1 TS 1 TSRE If you think tightening their order would improve the documentation, we should talk. ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-28 6:56 ` Markus Armbruster @ 2020-02-28 10:17 ` Philippe Mathieu-Daudé 2020-02-28 17:34 ` Markus Armbruster 0 siblings, 1 reply; 8+ messages in thread From: Philippe Mathieu-Daudé @ 2020-02-28 10:17 UTC (permalink / raw) To: Markus Armbruster; +Cc: qemu-devel, Eduardo Habkost On 2/28/20 7:56 AM, Markus Armbruster wrote: > Philippe Mathieu-Daudé <philmd@redhat.com> writes: >> On 2/27/20 3:55 PM, Philippe Mathieu-Daudé wrote: >>> On 2/27/20 3:52 PM, Markus Armbruster wrote: >>>> Philippe Mathieu-Daudé <philmd@redhat.com> writes: >>>> >>>>> This fixes when adding a 'Since' tag: >>>>> >>>>> In file included from qapi/qapi-schema.json:105: >>>>> qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section >>>> >>>> I'm confused. This error is detected in scripts/qapi/parser.py, and it >>>> is fatal. Is the build broken for you? It isn't for me. Moreover, >>>> where is @arch? I can't see it anywhere close to the two spots the >>>> patch patches. >>> >>> I get the error after trying to fix what Eric commented here: >>> https://www.mail-archive.com/qemu-devel@nongnu.org/msg682344.html >> >> Using: >> --- >> diff --git a/qapi/machine.json b/qapi/machine.json >> index 6c11e3cf3a..40a36d6276 100644 >> --- a/qapi/machine.json >> +++ b/qapi/machine.json >> @@ -20,13 +20,15 @@ >> # prefix to produce the corresponding QEMU executable name. This >> # is true even for "qemu-system-x86_64". >> # >> +# @rx: since 5.0 >> +# >> # Since: 3.0 >> ## >> { 'enum' : 'SysEmuTarget', >> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >> 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', >> 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', >> - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', >> + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', >> 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', >> 'x86_64', 'xtensa', 'xtensaeb' ] } >> --- >> >> or >> >> --- >> diff --git a/qapi/machine.json b/qapi/machine.json >> index 6c11e3cf3a..4b59e87b6f 100644 >> --- a/qapi/machine.json >> +++ b/qapi/machine.json >> @@ -21,12 +21,14 @@ >> # is true even for "qemu-system-x86_64". >> # >> # Since: 3.0 >> +# >> +# @rx: since 5.0 >> ## >> { 'enum' : 'SysEmuTarget', >> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >> 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', >> 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', >> - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', >> + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', >> 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', >> 'x86_64', 'xtensa', 'xtensaeb' ] } >> --- >> >> I get: >> >> GEN qapi-gen >> GEN rx-softmmu/config-devices.mak >> In file included from qapi/qapi-schema.json:105: >> qapi/machine.json:23:1: '@rx:' can't follow 'Notes' section >> make: *** [Makefile:645: qapi-gen-timestamp] Error 1 >> >> This works however: >> >> --- >> ## >> # @SysEmuTarget: >> # >> # The comprehensive enumeration of QEMU system emulation ("softmmu") >> # targets. Run "./configure --help" in the project root directory, and >> # look for the *-softmmu targets near the "--target-list" option. The >> # individual target constants are not documented here, for the time >> # being. >> # >> +# @rx: since 5.0 >> +# >> # Notes: The resulting QMP strings can be appended to the "qemu-system-" >> # prefix to produce the corresponding QEMU executable name. This >> # is true even for "qemu-system-x86_64". >> # >> # Since: 3.0 >> ## >> { 'enum' : 'SysEmuTarget', >> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >> 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', >> 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', >> - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', >> + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', >> 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', >> 'x86_64', 'xtensa', 'xtensaeb' ] } >> --- > > This one adds it to the correct spot. OK I'll use that then. > > qapi-code-gen.txt: > > Definition documentation starts with a line naming the definition, > followed by an optional overview, a description of each argument (for > commands and events), member (for structs and unions), branch (for > alternates), or value (for enums), and finally optional tagged > sections. I was confused because I understood "@rx: since 5.0" as a tagged section, not as an "Optional overview". > > Let's apply this to SysEmuTarget's doc comment: > > ## > # @SysEmuTarget: > > Line naming the definition > > # > # The comprehensive enumeration of QEMU system emulation ("softmmu") > # targets. Run "./configure --help" in the project root directory, and > # look for the *-softmmu targets near the "--target-list" option. The > # individual target constants are not documented here, for the time > # being. > > Optional overview. > > Missing here: a description of each value. We should enforce such > descriptions. We don't, mostly because we have a number of exceptions > where documentation would be bothersome, such as enum QKeyCode. > > # > # Notes: The resulting QMP strings can be appended to the "qemu-system-" > # prefix to produce the corresponding QEMU executable name. This > # is true even for "qemu-system-x86_64". > > A tagged section. > > # > # Since: 3.0 > > Another tagged section. > > ## > > Note that qapi-code-gen.txt prescribes no order for the tagged > sections. They actually occur in pretty much any order: > > $ awk '/^##/ { if (on) { if (length(t) > 1) print t; t="" } on=!on } on && /^# (Returns|Since|Notes?|Examples?|TODO):/ { t=t substr($2, 1, 1) }' qapi/*json | sort | uniq -c > 1 ENS > 2 ES > 1 NES > 1 NETS > 1 NNSE > 1 NRS > 2 NRSE > 14 NS > 11 NSE > 1 RE > 6 RES > 4 RNS > 6 RNSE > 23 RS > 78 RSE > 1 RSEEEE > 3 RSEN > 12 RSNE > 55 SE > 4 SN > 2 SNE > 2 SRNE > 1 TRSE > 1 TS > 1 TSRE > > If you think tightening their order would improve the documentation, we > should talk. No thanks :) ^ permalink raw reply [flat|nested] 8+ messages in thread
* Re: [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag 2020-02-28 10:17 ` Philippe Mathieu-Daudé @ 2020-02-28 17:34 ` Markus Armbruster 0 siblings, 0 replies; 8+ messages in thread From: Markus Armbruster @ 2020-02-28 17:34 UTC (permalink / raw) To: Philippe Mathieu-Daudé Cc: Markus Armbruster, Eduardo Habkost, qemu-devel Philippe Mathieu-Daudé <philmd@redhat.com> writes: > On 2/28/20 7:56 AM, Markus Armbruster wrote: >> Philippe Mathieu-Daudé <philmd@redhat.com> writes: >>> On 2/27/20 3:55 PM, Philippe Mathieu-Daudé wrote: >>>> On 2/27/20 3:52 PM, Markus Armbruster wrote: >>>>> Philippe Mathieu-Daudé <philmd@redhat.com> writes: >>>>> >>>>>> This fixes when adding a 'Since' tag: >>>>>> >>>>>> In file included from qapi/qapi-schema.json:105: >>>>>> qapi/machine.json:25:1: '@arch:' can't follow 'Notes' section >>>>> >>>>> I'm confused. This error is detected in scripts/qapi/parser.py, and it >>>>> is fatal. Is the build broken for you? It isn't for me. Moreover, >>>>> where is @arch? I can't see it anywhere close to the two spots the >>>>> patch patches. >>>> >>>> I get the error after trying to fix what Eric commented here: >>>> https://www.mail-archive.com/qemu-devel@nongnu.org/msg682344.html >>> >>> Using: >>> --- >>> diff --git a/qapi/machine.json b/qapi/machine.json >>> index 6c11e3cf3a..40a36d6276 100644 >>> --- a/qapi/machine.json >>> +++ b/qapi/machine.json >>> @@ -20,13 +20,15 @@ >>> # prefix to produce the corresponding QEMU executable name. This >>> # is true even for "qemu-system-x86_64". >>> # >>> +# @rx: since 5.0 >>> +# >>> # Since: 3.0 >>> ## >>> { 'enum' : 'SysEmuTarget', >>> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >>> 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', >>> 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', >>> - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', >>> + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', >>> 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', >>> 'x86_64', 'xtensa', 'xtensaeb' ] } >>> --- >>> >>> or >>> >>> --- >>> diff --git a/qapi/machine.json b/qapi/machine.json >>> index 6c11e3cf3a..4b59e87b6f 100644 >>> --- a/qapi/machine.json >>> +++ b/qapi/machine.json >>> @@ -21,12 +21,14 @@ >>> # is true even for "qemu-system-x86_64". >>> # >>> # Since: 3.0 >>> +# >>> +# @rx: since 5.0 >>> ## >>> { 'enum' : 'SysEmuTarget', >>> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >>> 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', >>> 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', >>> - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', >>> + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', >>> 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', >>> 'x86_64', 'xtensa', 'xtensaeb' ] } >>> --- >>> >>> I get: >>> >>> GEN qapi-gen >>> GEN rx-softmmu/config-devices.mak >>> In file included from qapi/qapi-schema.json:105: >>> qapi/machine.json:23:1: '@rx:' can't follow 'Notes' section >>> make: *** [Makefile:645: qapi-gen-timestamp] Error 1 >>> >>> This works however: >>> >>> --- >>> ## >>> # @SysEmuTarget: >>> # >>> # The comprehensive enumeration of QEMU system emulation ("softmmu") >>> # targets. Run "./configure --help" in the project root directory, and >>> # look for the *-softmmu targets near the "--target-list" option. The >>> # individual target constants are not documented here, for the time >>> # being. >>> # >>> +# @rx: since 5.0 >>> +# >>> # Notes: The resulting QMP strings can be appended to the "qemu-system-" >>> # prefix to produce the corresponding QEMU executable name. This >>> # is true even for "qemu-system-x86_64". >>> # >>> # Since: 3.0 >>> ## >>> { 'enum' : 'SysEmuTarget', >>> 'data' : [ 'aarch64', 'alpha', 'arm', 'cris', 'hppa', 'i386', 'lm32', >>> 'm68k', 'microblaze', 'microblazeel', 'mips', 'mips64', >>> 'mips64el', 'mipsel', 'moxie', 'nios2', 'or1k', 'ppc', >>> - 'ppc64', 'riscv32', 'riscv64', 's390x', 'sh4', >>> + 'ppc64', 'riscv32', 'riscv64', 'rx', 's390x', 'sh4', >>> 'sh4eb', 'sparc', 'sparc64', 'tricore', 'unicore32', >>> 'x86_64', 'xtensa', 'xtensaeb' ] } >>> --- >> >> This one adds it to the correct spot. > > OK I'll use that then. > >> >> qapi-code-gen.txt: >> >> Definition documentation starts with a line naming the definition, >> followed by an optional overview, a description of each argument (for >> commands and events), member (for structs and unions), branch (for >> alternates), or value (for enums), and finally optional tagged >> sections. > > I was confused because I understood "@rx: since 5.0" as a tagged > section, not as an "Optional overview". It's actually "a description of a value", not "optional overview". [...] ^ permalink raw reply [flat|nested] 8+ messages in thread
end of thread, other threads:[~2020-02-28 17:38 UTC | newest] Thread overview: 8+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-02-27 13:40 [PATCH v2] qapi/machine: Place the 'Notes' tag after the 'Since' tag Philippe Mathieu-Daudé 2020-02-27 14:52 ` Markus Armbruster 2020-02-27 14:55 ` Philippe Mathieu-Daudé 2020-02-27 15:21 ` Philippe Mathieu-Daudé 2020-02-27 20:14 ` Eduardo Habkost 2020-02-28 6:56 ` Markus Armbruster 2020-02-28 10:17 ` Philippe Mathieu-Daudé 2020-02-28 17:34 ` Markus Armbruster
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).