Fix some qapi examples and a TODO section
cover Fix some qapi examples and a TODO section
Hi,
I've being using the examples as unit tests and found a few that doesn't work out-of-the-box, might be inteded in order to be less verbose in the qapi documentation but nevertheless I'm sending this out in case you want to cherry-pick them.
Cheers,
Victor Toso (14):
qapi: BlockExportRemoveMode: move comments to TODO
qapi: fix example of BLOCK_IMAGE_CORRUPTED event
qapi: fix example of BLOCK_IO_ERROR event
qapi: fix example of BLOCK_JOB_PENDING event
qapi: fix example of DUMP_COMPLETED event
qapi: fix example of MEMORY_DEVICE_SIZE_CHANGE event
qapi: fix example of UNPLUG_PRIMARY event
qapi: fix example of FAILOVER_NEGOTIATED event
qapi: run-state examples: add missing member
qapi: run-state examples: add missing timestamp
qapi: fix example of MEMORY_FAILURE
qapi: ui examples: add missing websocket member
qapi: fix example of ACPI_DEVICE_OST event
qapi: fix example of dump-guest-memory
qapi/acpi.json | 5 +++-- qapi/block-core.json | 9 +++++---- qapi/block-export.json | 10 +++++----- qapi/dump.json | 9 +++++---- qapi/machine.json | 3 ++- qapi/migration.json | 4 +++- qapi/net.json | 3 ++- qapi/run-state.json | 16 +++++++++++----- qapi/ui.json | 12 ++++++------ 9 files changed, 42 insertions(+), 29 deletions(-)
Signature · 1 line
2.35.1
PATCH 1/14 qapi: BlockExportRemoveMode: move comments to TODO
@hide and @soft are potential additions which fits the TODO section perfectly.
The main motivation is to avoid this whole block of comment entering the wrong section in the python parser.
--- qapi/block-export.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)
qapi/block-export.json +5 -5
@@ -219,13 +219,13 @@ # # @hard: Drop all connections immediately and remove export. # -# Potential additional modes to be added in the future: +# TODO: Potential additional modes to be added in the future: # -# hide: Just hide export from new clients, leave existing connections as is. -# Remove export after all clients are disconnected. +# hide: Just hide export from new clients, leave existing connections as is. +# Remove export after all clients are disconnected. # -# soft: Hide export from new clients, answer with ESHUTDOWN for all further -# requests from existing clients. +# soft: Hide export from new clients, answer with ESHUTDOWN for all further +# requests from existing clients. # # Since: 2.12 ##
Signature · 1 line
2.35.1
Re: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO
Quoted 36 lines · Victor Toso
@hide and @soft are potential additions which fits the TODO section perfectly.
The main motivation is to avoid this whole block of comment entering the wrong section in the python parser.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-export.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)qapi/block-export.json +5
-6@@ -219,13 +219,13 @@ # # @hard: Drop all connections immediately and remove export. # -# Potential additional modes to be added in the future: +# TODO: Potential additional modes to be added in the future: # -# hide: Just hide export from new clients, leave existing connections as is. -# Remove export after all clients are disconnected. +# hide: Just hide export from new clients, leave existing connections as is. +# Remove export after all clients are disconnected. # -# soft: Hide export from new clients, answer with ESHUTDOWN for all further -# requests from existing clients. +# soft: Hide export from new clients, answer with ESHUTDOWN for all further +# requests from existing clients. # # Since: 2.12 ## --
Quoted 2 lines
2.35.1
Does this help with something in particular? (Got an example for me?)
--js
Re: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO
Hi,
Many thanks for the quick review!
Quoted 33 lines · John Snow
Quoted 32 lines · Victor Toso
@hide and @soft are potential additions which fits the TODO section perfectly.
The main motivation is to avoid this whole block of comment entering the wrong section in the python parser.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-export.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)qapi/block-export.json +5
-5@@ -219,13 +219,13 @@ # # @hard: Drop all connections immediately and remove export. # -# Potential additional modes to be added in the future: +# TODO: Potential additional modes to be added in the future: # -# hide: Just hide export from new clients, leave existing connections as is. -# Remove export after all clients are disconnected. +# hide: Just hide export from new clients, leave existing connections as is. +# Remove export after all clients are disconnected. # -# soft: Hide export from new clients, answer with ESHUTDOWN for all further -# requests from existing clients. +# soft: Hide export from new clients, answer with ESHUTDOWN for all further +# requests from existing clients.
Quoted 8 lines
Quoted 6 lines
qapi/block-export.json +0
-1# # Since: 2.12 ## --2.35.1
Does this help with something in particular? (Got an example for me?)
I'm working on a Golang interface and I'm using the QAPI documentation to document the Go's types of the QAPI spec. For this kind of documentation, documentation related to future development can be excluded. This patch helps me filter it out :)
Example:
$ cd qemu/scripts && python
Quoted 2 lines
Quoted 2 lines
Quoted 2 lines
from qapi.schema import QAPISchema
schema = QAPISchema('../qapi/qapi-schema.json')
# Without this patch, the 'Potential additional modes' doc is
# under no specific named Section.
Quoted 1 line
Quoted 1 line
Quoted 1 line
for s in schema._entity_dict['BlockExportRemoveMode'].doc.sections:
... pprint(vars(s))
...
{'_indent': 0,
'_parser': <qapi.parser.QAPISchemaParser object at 0x7f4fcf854760>, 'name': None,
'text': 'Potential additional modes to be added in the future:\n'
'\n'
'hide: Just hide export from new clients, leave existing connections '
'as is.\n'
'Remove export after all clients are disconnected.\n'
'\n'
'soft: Hide export from new clients, answer with ESHUTDOWN for all '
'further\n'
'requests from existing clients.'} {'_indent': 7,
'_parser': <qapi.parser.QAPISchemaParser object at 0x7f4fcf854760>, 'name': 'Since',
'text': '2.12'}
# With this patch, we can filter out TODO section
Quoted 1 line
Quoted 1 line
Quoted 1 line
pprint(schema._entity_dict['BlockExportRemoveMode'].doc.sections[0]))
{'_indent': 6,
'_parser': <qapi.parser.QAPISchemaParser object at 0x7f228d97e950>, 'name': 'TODO',
'text': 'Potential additional modes to be added in the future:\n'
'\n'
'hide: Just hide export from new clients, leave existing connections '
'as is.\n'
'Remove export after all clients are disconnected.\n'
'\n'
'soft: Hide export from new clients, answer with ESHUTDOWN for all '
'further\n'
'requests from existing clients.'}Cheers,
Victor
Re: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO
In reply to Victor TosoQuoted 24 lines · Victor Toso
@hide and @soft are potential additions which fits the TODO section perfectly.
The main motivation is to avoid this whole block of comment entering the wrong section in the python parser.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-export.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)qapi/block-export.json +1
-3@@ -219,13 +219,13 @@ # # @hard: Drop all connections immediately and remove export. # -# Potential additional modes to be added in the future: +# TODO: Potential additional modes to be added in the future: # -# hide: Just hide export from new clients, leave existing connections as is. -# Remove export after all clients are disconnected.
qapi/block-export.json line 231
Quoted 10 lines
qapi/block-export.json +4
-2+# hide: Just hide export from new clients, leave existing connections as is. +# Remove export after all clients are disconnected. # -# soft: Hide export from new clients, answer with ESHUTDOWN for all further -# requests from existing clients. +# soft: Hide export from new clients, answer with ESHUTDOWN for all further +# requests from existing clients. # # Since: 2.12 ##
Doc comments embed user documentation in the source code. The doc generator extracts it.
TODOs are generally for developers. Should the doc generator suppress TODO sections?
John Snow
Reviewed-byRe: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO
Quoted 41 lines · Markus Armbruster
Quoted 16 lines · Victor Toso
@hide and @soft are potential additions which fits the TODO section perfectly.
The main motivation is to avoid this whole block of comment entering the wrong section in the python parser.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-export.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)qapi/block-export.json +0
-0qapi/block-export.json line 224
Quoted 7 lines
qapi/block-export.json +1
-2@@ -219,13 +219,13 @@ # # @hard: Drop all connections immediately and remove export. # -# Potential additional modes to be added in the future: +# TODO: Potential additional modes to be added in the future: # -# hide: Just hide export from new clients, leave existing connectionsas is.
qapi/block-export.json line 224
Quoted 2 lines
qapi/block-export.json +1
-1-# Remove export after all clients are disconnected. +# hide: Just hide export from new clients, leave existingconnections as is.
qapi/block-export.json
Quoted 3 lines
qapi/block-export.json +1
-1+# Remove export after all clients are disconnected. # -# soft: Hide export from new clients, answer with ESHUTDOWN for allfurther
qapi/block-export.json line 227
Quoted 2 lines
qapi/block-export.json +1
-1-# requests from existing clients. +# soft: Hide export from new clients, answer with ESHUTDOWN forall further
qapi/block-export.json line 231
Quoted 4 lines
qapi/block-export.json +1
-0+# requests from existing clients. # # Since: 2.12 ##
Quoted 8 lines
Reviewed-by Markus Armbruster <[email protected]>Doc comments embed user documentation in the source code. The doc generator extracts it.
TODOs are generally for developers. Should the doc generator suppress TODO sections?
Needs an audit to make sure we're using it consistently with that semantic, but broadly it's probably a good idea to squelch "internal" todos, yes.
Things like "Watch out, were definitely gonna deprecate this soon probably maybe!" can stay outside of the TODO section. (Sometimes heads up are legitimate, even if most won't read them. the faithful and diligent will be rewarded with painless upgrades.)
Anyway, if Markus is happy with this change, I am too, I was just curious to know if there were bigger cleanups to do here and what the impact was.
Anyway:
Quoted 1 line
Re: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO
Hi,
Quoted 38 lines · John Snow
Quoted 36 lines · Markus Armbruster
Quoted 16 lines · Victor Toso
@hide and @soft are potential additions which fits the TODO section perfectly.
The main motivation is to avoid this whole block of comment entering the wrong section in the python parser.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-export.json | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-)qapi/block-export.json +0
-0qapi/block-export.json line 224
Quoted 7 lines
qapi/block-export.json +1
-2@@ -219,13 +219,13 @@ # # @hard: Drop all connections immediately and remove export. # -# Potential additional modes to be added in the future: +# TODO: Potential additional modes to be added in the future: # -# hide: Just hide export from new clients, leave existing connectionsas is.
qapi/block-export.json line 224
Quoted 2 lines
qapi/block-export.json +1
-1-# Remove export after all clients are disconnected. +# hide: Just hide export from new clients, leave existingconnections as is.
qapi/block-export.json
Quoted 3 lines
qapi/block-export.json +1
-1+# Remove export after all clients are disconnected. # -# soft: Hide export from new clients, answer with ESHUTDOWN for allfurther
qapi/block-export.json line 227
Quoted 2 lines
qapi/block-export.json +1
-1-# requests from existing clients. +# soft: Hide export from new clients, answer with ESHUTDOWN forall further
Quoted 6 lines
Quoted 6 lines
qapi/block-export.json line 231
Quoted 4 lines
qapi/block-export.json +1
-0+# requests from existing clients. # # Since: 2.12 ##Reviewed-by Markus Armbruster <[email protected]>
Thanks,
Quoted 10 lines
Quoted 5 lines
Doc comments embed user documentation in the source code. The doc generator extracts it.
TODOs are generally for developers. Should the doc generator suppress TODO sections?
Needs an audit to make sure we're using it consistently with that semantic, but broadly it's probably a good idea to squelch "internal" todos, yes.
Quoted 5 lines
Things like "Watch out, were definitely gonna deprecate this soon probably maybe!" can stay outside of the TODO section. (Sometimes heads up are legitimate, even if most won't read them. the faithful and diligent will be rewarded with painless upgrades.)
There are 5 TODO sections in QAPI (including this patch):
qapi/block-export.json:222:# TODO: Potential additional modes to be added in the future:
qapi/introspect.json:300:# TODO: @success-response (currently irrelevant, because it's QGA, not QMP) qapi/machine.json:913:# TODO: Better documentation; currently there is none. qapi/migration.json:933:# TODO either fuse back into MigrationParameters, or make qapi/qdev.json:70:# TODO: This command effectively bypasses QAPI completely due to its
I think their usage is a bit broad but helpful.
Quoted 3 lines
Anyway, if Markus is happy with this change, I am too, I was just curious to know if there were bigger cleanups to do here and what the impact was.
I'll let you know if I find more :)
Quoted 3 lines
Anyway:
Reviewed-by John Snow <[email protected]>
Thanks! I'll send a v2 later with all suggestions.
Cheers,
Victor
"Future directions" vs. "TODO" in doc comments (was: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO)
Quoted 4 lines · Victor Toso
Hi,
Quoted 1 line · John Snow
On Fri, Mar 25, 2022, 8:33 AM Markus Armbruster <[email protected]> wrote:
[...]
Quoted 10 lines
Quoted 10 lines
Quoted 5 lines
Doc comments embed user documentation in the source code. The doc generator extracts it.
TODOs are generally for developers. Should the doc generator suppress TODO sections?
Needs an audit to make sure we're using it consistently with that semantic, but broadly it's probably a good idea to squelch "internal" todos, yes.
Quoted 5 lines
Quoted 5 lines
Things like "Watch out, were definitely gonna deprecate this soon probably maybe!" can stay outside of the TODO section. (Sometimes heads up are legitimate, even if most won't read them. the faithful and diligent will be rewarded with painless upgrades.)
This is "future directions", not quite the same as "TODO".
Would a section tag "Future directions" make sense?
Quoted 1 line
There are 5 TODO sections in QAPI (including this patch):
Let me try to sort them into "TODO" and "future directions" buckets. The former are of interest for developers only, and thus should be elided from documentation meant for users.
Quoted 1 line
qapi/block-export.json:222:# TODO: Potential additional modes to be added in the future:
Do we believe our thoughts on evolving of this enum are relevant for users of the affected QMP commands (nbd-server-remove and block-export-del)?
If yes, it's "future directions".
Quoted 1 line
qapi/introspect.json:300:# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
As phrased, this is only useful for developers, and even for them, it's rather terse.
If we add introspection to QGA, we'll want to add a @success-response member.
So, if we intend to add introspection to QGA, *and* we think current users of (QMP-only) introspection need to know about a future addition of @success-response, then this should be rephrased as "future directions".
I doubt it.
Quoted 1 line
qapi/machine.json:913:# TODO: Better documentation; currently there is none.
Clearly TODO.
Quoted 1 line
qapi/migration.json:933:# TODO either fuse back into MigrationParameters, or make
Clearly TODO. Note that this one is *not* in a doc comment, and does *not* appear in generated documentation.
Once we have concrete plans on how to address the TODO, these plans may motivate "future directions", namely if they involve user-visible change users need to know about in advance.
Quoted 1 line
qapi/qdev.json:70:# TODO: This command effectively bypasses QAPI completely due to its
Likewise.
I think this shows that we have a few comments just for developers in the middle of user documentation.
We could simply keep these outside doc comments, like the TODO in qapi/migration.json.
This can occasionally be awkward. For instance, TODO @success-response is right where @success-response ought to be. Moving it outside the doc comment would lose that. Not the end of the world, just awkward.
If this annoys us enough, we could provide means to let us have elide parts of doc comments from generated docs. The simplest one is probably eliding certain sections, say the TODO sections.
Thoughts?
[...]
Re: "Future directions" vs. "TODO" in doc comments (was: [PATCH 01/14] qapi: BlockExportRemoveMode: move comments to TODO)
Quoted 26 lines · Markus Armbruster
Quoted 4 lines · Victor Toso
Hi,
Quoted 1 line · John Snow
On Fri, Mar 25, 2022, 8:33 AM Markus Armbruster <[email protected]> wrote:
[...]
Quoted 10 lines
Quoted 10 lines
Quoted 5 lines
Doc comments embed user documentation in the source code. The doc generator extracts it.
TODOs are generally for developers. Should the doc generator suppress TODO sections?
Needs an audit to make sure we're using it consistently with that semantic, but broadly it's probably a good idea to squelch "internal" todos, yes.
Quoted 5 lines
Quoted 5 lines
Things like "Watch out, were definitely gonna deprecate this soon probably maybe!" can stay outside of the TODO section. (Sometimes heads up are legitimate, even if most won't read them. the faithful and diligent will be rewarded with painless upgrades.)
Quoted 4 lines
This is "future directions", not quite the same as "TODO".
Would a section tag "Future directions" make sense?
If we're leaving these kinds of warnings already, sure. I was just speaking generically.
I didn't actually audit all of our docs to see what types of notes we've left so far.
Quoted 6 lines
Quoted 1 line
There are 5 TODO sections in QAPI (including this patch):
Let me try to sort them into "TODO" and "future directions" buckets. The former are of interest for developers only, and thus should be elided from documentation meant for users.
Oh, but it looks like *you* did the audit ;)
Quoted 8 lines
Quoted 1 line
qapi/block-export.json:222:# TODO: Potential additional modes to be added in the future:
Do we believe our thoughts on evolving of this enum are relevant for users of the affected QMP commands (nbd-server-remove and block-export-del)?
If yes, it's "future directions".
Presumably this evolves compatibly like QMP always does, and doesn't necessarily warrant a special note. "future directions" feels reasonable.
Quoted 8 lines
Quoted 1 line
qapi/introspect.json:300:# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
As phrased, this is only useful for developers, and even for them, it's rather terse.
If we add introspection to QGA, we'll want to add a @success-response member.
Quoted 7 lines
So, if we intend to add introspection to QGA, *and* we think current users of (QMP-only) introspection need to know about a future addition of @success-response, then this should be rephrased as "future directions".
I doubt it.
I'll defer to your judgment on this one. The last time I tried to bark into QGA I got more than I bargained for. :')
Quoted 4 lines
Quoted 1 line
qapi/machine.json:913:# TODO: Better documentation; currently there is none.
Clearly TODO.
Yuh
Quoted 23 lines
Quoted 1 line
qapi/migration.json:933:# TODO either fuse back into MigrationParameters, or make
Clearly TODO. Note that this one is *not* in a doc comment, and does *not* appear in generated documentation.
Once we have concrete plans on how to address the TODO, these plans may motivate "future directions", namely if they involve user-visible change users need to know about in advance.
Quoted 1 line
qapi/qdev.json:70:# TODO: This command effectively bypasses QAPI completely due to its
Likewise.
I think this shows that we have a few comments just for developers in the middle of user documentation.
We could simply keep these outside doc comments, like the TODO in
qapi/migration.json.This can occasionally be awkward. For instance, TODO @success-response is right where @success-response ought to be. Moving it outside the doc comment would lose that. Not the end of the world, just awkward.
Quoted 6 lines
If this annoys us enough, we could provide means to let us have elide parts of doc comments from generated docs. The simplest one is probably eliding certain sections, say the TODO sections.
Thoughts?
I'm fine with it, maybe pending the spelling of such a section. Keeping the docs clean and useful on generation sounds like a noble endeavor. I don't think it's urgent, but I'm willing to let Victor tell me which pieces are annoying and getting in his way.
(I still want to redo our docstring handling, but it wound up being a bigger project than I could bite off in a week or two. It's extremely high on my list of things to do, but I am already in debt to you on the typing project I wanted to engage on, so ... I will sit on my hands for right now.)
PATCH 2/14 qapi: fix example of BLOCK_IMAGE_CORRUPTED event
In reply to Victor TosoFatal is not optional.
--- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
qapi/block-core.json +1 -1
@@ -5008,7 +5008,7 @@ # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "ide0-hd0", "node-name": "node0", # "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, +# "size": 65536, "fatal": false }, # "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } # # Since: 1.7
Signature · 1 line
2.35.1
Re: [PATCH 02/14] qapi: fix example of BLOCK_IMAGE_CORRUPTED event
Quoted 20 lines · Victor Toso
Fatal is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qapi/block-core.json +1
-1@@ -5008,7 +5008,7 @@ # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "ide0-hd0", "node-name": "node0", # "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, +# "size": 65536, "fatal": false }, # "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } #
Quoted 4 lines
# Since: 1.7
--
2.35.1
Is this the correct fatality setting for this particular case? Default is implied to be true.
Quoted 1 line
Re: [PATCH 02/14] qapi: fix example of BLOCK_IMAGE_CORRUPTED event
Quoted 22 lines · John Snow
Quoted 18 lines · Victor Toso
Fatal is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qapi/block-core.json +1
-1@@ -5008,7 +5008,7 @@ # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "ide0-hd0", "node-name": "node0", # "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, +# "size": 65536, "fatal": false },
Quoted 8 lines
Quoted 5 lines
qapi/block-core.json +0
-1# "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } # # Since: 1.7 --2.35.1
Is this the correct fatality setting for this particular case? Default is implied to be true.
(1) We don't seem to actually emit this particular message anymore. I don't think it exists in the tree.
(2) The only fatal=False messages I can see is
"Cannot free unaligned cluster %#llx"
(Try grepping for qcow2_signal_corruption)
so maybe we should pick a new example that might really exist. iotest 060 seems to test this, so that can be used as a guide.
--js
Re: [PATCH 02/14] qapi: fix example of BLOCK_IMAGE_CORRUPTED event
Quoted 32 lines · John Snow
Quoted 22 lines · John Snow
Quoted 18 lines · Victor Toso
Fatal is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qapi/block-core.json +1
-1@@ -5008,7 +5008,7 @@ # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "ide0-hd0", "node-name": "node0", # "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, +# "size": 65536, "fatal": false },Quoted 8 lines
Quoted 5 lines
qapi/block-core.json +0
-1# "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } # # Since: 1.7 --2.35.1
Is this the correct fatality setting for this particular case? Default is implied to be true.
Quoted 2 lines
(1) We don't seem to actually emit this particular message anymore. I don't think it exists in the tree.
I doubt we ever emitted it.
Quoted 7 lines
(2) The only fatal=False messages I can see is
"Cannot free unaligned cluster %#llx"(Try grepping for
qcow2_signal_corruption)so maybe we should pick a new example that might really exist. iotest 060 seems to test this, so that can be used as a guide.
Yes, please.
Re: [PATCH 02/14] qapi: fix example of BLOCK_IMAGE_CORRUPTED event
Hi,
Quoted 34 lines · Markus Armbruster
Quoted 32 lines · John Snow
Quoted 30 lines · John Snow
Quoted 22 lines · Victor Toso
Fatal is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qapi/block-core.json +1
-2@@ -5008,7 +5008,7 @@ # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "ide0-hd0", "node-name": "node0", # "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, +# "size": 65536, "fatal": false }, # "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } # # Since: 1.7 --Quoted 1 line
2.35.1
Is this the correct fatality setting for this particular case? Default is implied to be true.
Quoted 4 lines
Quoted 2 lines
(1) We don't seem to actually emit this particular message anymore. I don't think it exists in the tree.
I doubt we ever emitted it.
Out of curiosity, shouldn't we deprecate it then?
Quoted 9 lines
Quoted 7 lines
(2) The only fatal=False messages I can see is
"Cannot free unaligned cluster %#llx"(Try grepping for
qcow2_signal_corruption)so maybe we should pick a new example that might really exist. iotest 060 seems to test this, so that can be used as a guide.
Yes, please.
I'll be changing it on v2
Re: [PATCH 02/14] qapi: fix example of BLOCK_IMAGE_CORRUPTED event
Quoted 38 lines · Victor Toso
Hi,
Quoted 34 lines · Markus Armbruster
Quoted 32 lines · John Snow
Quoted 30 lines · John Snow
Quoted 22 lines · Victor Toso
Fatal is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qapi/block-core.json +1
-2@@ -5008,7 +5008,7 @@ # <- { "event": "BLOCK_IMAGE_CORRUPTED", # "data": { "device": "ide0-hd0", "node-name": "node0", # "msg": "Prevented active L1 table overwrite", "offset": 196608, -# "size": 65536 }, +# "size": 65536, "fatal": false }, # "timestamp": { "seconds": 1378126126, "microseconds": 966463 } } # # Since: 1.7 --Quoted 1 line
2.35.1
Is this the correct fatality setting for this particular case? Default is implied to be true.
Quoted 7 lines
Quoted 4 lines
Quoted 2 lines
(1) We don't seem to actually emit this particular message anymore. I don't think it exists in the tree.
I doubt we ever emitted it.
Out of curiosity, shouldn't we deprecate it then?
He means: we probably never emitted that specific error message. The *event* is in use, see iotest 060.
Quoted 11 lines
Quoted 9 lines
Quoted 7 lines
(2) The only fatal=False messages I can see is
"Cannot free unaligned cluster %#llx"(Try grepping for
qcow2_signal_corruption)so maybe we should pick a new example that might really exist. iotest 060 seems to test this, so that can be used as a guide.
Yes, please.
I'll be changing it on v2
PATCH 3/14 qapi: fix example of BLOCK_IO_ERROR event
In reply to Victor TosoReason is not optional.
--- qapi/block-core.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
qapi/block-core.json +2 -1
@@ -5059,7 +5059,8 @@ # "data": { "device": "ide0-hd1", # "node-name": "#block212", # "operation": "write", -# "action": "stop" }, +# "action": "stop", +# "reason": "Driver requires too large request alignment" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ##
Signature · 1 line
2.35.1
Re: [PATCH 03/14] qapi: fix example of BLOCK_IO_ERROR event
Quoted 23 lines · Victor Toso
Reason is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)qapi/block-core.json +2
-2@@ -5059,7 +5059,8 @@ # "data": { "device": "ide0-hd1", # "node-name": "#block212", # "operation": "write", -# "action": "stop" }, +# "action": "stop", +# "reason": "Driver requires too large request alignment" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## --
Quoted 2 lines
2.35.1
We discourage people using the reason programmatically, but there will indeed be one. Where'd you pull the message out from?
I see this:
static void send_qmp_error_event(BlockBackend *blk,
BlockErrorAction action, bool is_read, int error)
{
IoOperationType optype;
BlockDriverState *bs = blk_bs(blk);
optype = is_read ? IO_OPERATION_TYPE_READ : IO_OPERATION_TYPE_WRITE;
qapi_event_send_block_io_error(blk_name(blk), !!bs,
bs ? bdrv_get_node_name(bs) : NULL, optype,
action, blk_iostatus_is_enabled(blk),
error == ENOSPC, strerror(error));
}so it should be one of the "standard" strerror messages, right?
--js
Re: [PATCH 03/14] qapi: fix example of BLOCK_IO_ERROR event
Hi,
Quoted 22 lines · John Snow
Quoted 21 lines · Victor Toso
Reason is not optional.
Signed-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)qapi/block-core.json +2
-1@@ -5059,7 +5059,8 @@ # "data": { "device": "ide0-hd1", # "node-name": "#block212", # "operation": "write", -# "action": "stop" }, +# "action": "stop", +# "reason": "Driver requires too large request alignment" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } #
Quoted 8 lines
Quoted 4 lines
qapi/block-core.json +0
-1## --2.35.1
We discourage people using the reason programmatically, but there will indeed be one. Where'd you pull the message out from?
I was looking into the block related errors and pick a string. It wasn't a real error that I had.
Quoted 17 lines
I see this:
static void send_qmp_error_event(BlockBackend *blk,
BlockErrorAction action, boolis_read, int error){ IoOperationType optype; BlockDriverState *bs = blk_bs(blk); optype = is_read ? IO_OPERATION_TYPE_READ : IO_OPERATION_TYPE_WRITE; qapi_event_send_block_io_error(blk_name(blk), !!bs, bs ? bdrv_get_node_name(bs) : NULL, optype, action, blk_iostatus_is_enabled(blk), error == ENOSPC, strerror(error)); }
Quoted 1 line
so it should be one of the "standard" strerror messages, right?
Yep. I'll pick that one and use 'No space left on device'
Cheers,
PATCH 4/14 qapi: fix example of BLOCK_JOB_PENDING event
In reply to Victor Toso* Event's name: BLOCK_JOB_WAITING -> BLOCK_JOB_PENDING
* Argument device -> id
--- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)
qapi/block-core.json +2 -2
@@ -5226,8 +5226,8 @@ # # Example: # -# <- { "event": "BLOCK_JOB_WAITING", -# "data": { "device": "drive0", "type": "mirror" }, +# <- { "event": "BLOCK_JOB_PENDING", +# "data": { "type": "mirror", "id": "backup_1" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ##
Signature · 1 line
2.35.1
Re: [PATCH 04/14] qapi: fix example of BLOCK_JOB_PENDING event
Quoted 24 lines · Victor Toso
* Event's name:
BLOCK_JOB_WAITING->BLOCK_JOB_PENDING
* Argument device -> idSigned-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qapi/block-core.json +2
-3@@ -5226,8 +5226,8 @@ # # Example: # -# <- { "event": "BLOCK_JOB_WAITING", -# "data": { "device": "drive0", "type": "mirror" }, +# <- { "event": "BLOCK_JOB_PENDING", +# "data": { "type": "mirror", "id": "backup_1" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## --
Quoted 2 lines
2.35.1
Ow, how'd I get away with this? It was just always wrong and we never noticed?
Cool.
(Whoa, this is from 2018? It feels like it was from way before then.)
Quoted 1 line
Re: [PATCH 04/14] qapi: fix example of BLOCK_JOB_PENDING event
In reply to Victor TosoQuoted 13 lines · Victor Toso
* Event's name:
BLOCK_JOB_WAITING->BLOCK_JOB_PENDING
* Argument device -> idSigned-off-by Victor Toso <[email protected]>--- qapi/block-core.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-)qapi/block-core.json +0
-0
qapi/block-core.json line 5233
Quoted 10 lines
qapi/block-core.json +2
-2@@ -5226,8 +5226,8 @@ # # Example: # -# <- { "event": "BLOCK_JOB_WAITING", -# "data": { "device": "drive0", "type": "mirror" }, +# <- { "event": "BLOCK_JOB_PENDING", +# "data": { "type": "mirror", "id": "backup_1" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ##
PATCH 5/14 qapi: fix example of DUMP_COMPLETED event
In reply to Victor Toso* Timestamp is not optional, let's add for completeness.
* Add '<-' to signalize it is receiving the data
* While at it, add extra space before "result" and "total"
--- qapi/dump.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
qapi/dump.json +4 -3
@@ -161,9 +161,10 @@ # # Example: # -# { "event": "DUMP_COMPLETED", -# "data": {"result": {"total": 1090650112, "status": "completed", -# "completed": 1090650112} } } +# <- { "event": "DUMP_COMPLETED", +# "data": { "result": { "total": 1090650112, "status": "completed", +# "completed": 1090650112} }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'DUMP_COMPLETED' ,
Signature · 1 line
2.35.1
Re: [PATCH 05/14] qapi: fix example of DUMP_COMPLETED event
Quoted 29 lines · Victor Toso
* Timestamp is not optional, let's add for completeness.
* Add '<-' to signalize it is receiving the data
* While at it, add extra space before "result" and "total"Signed-off-by Victor Toso <[email protected]>--- qapi/dump.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)qapi/dump.json +4
-4@@ -161,9 +161,10 @@ # # Example: # -# { "event": "DUMP_COMPLETED", -# "data": {"result": {"total": 1090650112, "status": "completed", -# "completed": 1090650112} } } +# <- { "event": "DUMP_COMPLETED", +# "data": { "result": { "total": 1090650112, "status": "completed", +# "completed": 1090650112} }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'DUMP_COMPLETED' , --
Quoted 2 lines
2.35.1
Other events seem to use the timestamp as well, so go for it. I agree that being able to programmatically verify docstrings is pretty valuable in an API test suite.
(What date did you choose? Does it mean anything to you? :p)
Markus Armbruster
Reviewed-byRe: [PATCH 05/14] qapi: fix example of DUMP_COMPLETED event
Quoted 11 lines · John Snow
Quoted 10 lines · Victor Toso
* Timestamp is not optional, let's add for completeness.
* Add '<-' to signalize it is receiving the data
* While at it, add extra space before "result" and "total"Signed-off-by Victor Toso <[email protected]>--- qapi/dump.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Quoted 14 lines
Quoted 5 lines
qapi/dump.json +0
-0qapi/dump.json line 166
Quoted 9 lines
qapi/dump.json +3
-3@@ -161,9 +161,10 @@ # # Example: # -# { "event": "DUMP_COMPLETED", -# "data": {"result": {"total": 1090650112, "status": "completed", -# "completed": 1090650112} } } +# <- { "event": "DUMP_COMPLETED", +# "data": { "result": { "total": 1090650112, "status": "completed", +# "completed": 1090650112} },
Add a space after 1090650112, too?
Aside: I don't actually like our use of spaces in JSON, but consistently ugly beats inconsistently ugly.
Quoted 8 lines
Quoted 7 lines
qapi/dump.json +1
-1+# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'DUMP_COMPLETED' , --2.35.1
Quoted 5 lines
Other events seem to use the timestamp as well, so go for it. I agree that being able to programmatically verify docstrings is pretty valuable in an API test suite.
(What date did you choose? Does it mean anything to you? :p)
Copied from some other example, I suppose. I'd probably use time of writing, but that's just me.
Quoted 1 line
Reviewed-by John Snow <[email protected]>
Re: [PATCH 05/14] qapi: fix example of DUMP_COMPLETED event
Hi,
Quoted 13 lines · Markus Armbruster
Quoted 11 lines · John Snow
Quoted 10 lines · Victor Toso
* Timestamp is not optional, let's add for completeness.
* Add '<-' to signalize it is receiving the data
* While at it, add extra space before "result" and "total"Signed-off-by Victor Toso <[email protected]>--- qapi/dump.json | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-)
Quoted 16 lines
Quoted 6 lines
Quoted 6 lines
qapi/dump.json +0
-0@@ -161,9 +161,10 @@ #Quoted 8 lines
qapi/dump.json line 166
Quoted 8 lines
qapi/dump.json +3
-3# Example: # -# { "event": "DUMP_COMPLETED", -# "data": {"result": {"total": 1090650112, "status": "completed", -# "completed": 1090650112} } } +# <- { "event": "DUMP_COMPLETED", +# "data": { "result": { "total": 1090650112, "status": "completed", +# "completed": 1090650112} },Add a space after 1090650112, too?
ok!
Quoted 2 lines
Aside: I don't actually like our use of spaces in JSON, but consistently ugly beats inconsistently ugly.
Ideally it would be better use some tool to pretty format/sort it so we don't even bother looking at it too much.
Quoted 8 lines
Quoted 8 lines
Quoted 7 lines
qapi/dump.json +1
-1+# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'DUMP_COMPLETED' , --2.35.1
Quoted 7 lines
Quoted 5 lines
Other events seem to use the timestamp as well, so go for it. I agree that being able to programmatically verify docstrings is pretty valuable in an API test suite.
(What date did you choose? Does it mean anything to you? :p)
Copied from some other example, I suppose.
Yes,
Quoted 1 line
I'd probably use time of writing, but that's just me.
Never thought about it. Why not, I'll change it.
Quoted 3 lines
Quoted 1 line
Reviewed-by John Snow <[email protected]>Reviewed-by Markus Armbruster <[email protected]>
Thanks!
PATCH 6/14 qapi: fix example of MEMORY_DEVICE_SIZE_CHANGE event
In reply to Victor Toso* qom-path is not optional
--- qapi/machine.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
qapi/machine.json +2 -1
@@ -1356,7 +1356,8 @@ # Example: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824}, +# "data": { "id": "vm0", "size": 1073741824, +# "qom-path": "/machine/unattached/device[2]" }, # "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } # ##
Signature · 1 line
2.35.1
Re: [PATCH 06/14] qapi: fix example of MEMORY_DEVICE_SIZE_CHANGE event
Quoted 23 lines · Victor Toso
* qom-path is not optional
Signed-off-by Victor Toso <[email protected]>--- qapi/machine.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)qapi/machine.json +2
-2@@ -1356,7 +1356,8 @@ # Example: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824}, +# "data": { "id": "vm0", "size": 1073741824, +# "qom-path": "/machine/unattached/device[2]" }, # "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } # ## --
Quoted 2 lines
2.35.1
I'll just assume this is a realistic qom-path and not actually try to check 😅
Markus Armbruster
Reviewed-byRe: [PATCH 06/14] qapi: fix example of MEMORY_DEVICE_SIZE_CHANGE event
Quoted 3 lines · John Snow
Quoted 2 lines · Victor Toso
* qom-path is not optional
List of one item. Recommend to scratch '* '. Slightly less terse, like "Event data member @qom-path is not optional" wouldn't hurt.
Quoted 17 lines
Quoted 17 lines
Signed-off-by Victor Toso <[email protected]>--- qapi/machine.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)qapi/machine.json +2
-1@@ -1356,7 +1356,8 @@ # Example: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824}, +# "data": { "id": "vm0", "size": 1073741824, +# "qom-path": "/machine/unattached/device[2]" },
Quoted 8 lines
Quoted 6 lines
qapi/machine.json +0
-1# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } # ## --2.35.1
I'll just assume this is a realistic qom-path and not actually try to check 😅
I suppose a machine could exist where this path leads to a suitable device.
Quoted 1 line
Reviewed-by John Snow <[email protected]>
Re: [PATCH 06/14] qapi: fix example of MEMORY_DEVICE_SIZE_CHANGE event
In reply to John SnowQuoted 20 lines · John Snow
Quoted 19 lines · Victor Toso
* qom-path is not optional
Signed-off-by Victor Toso <[email protected]>--- qapi/machine.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)qapi/machine.json +2
-1@@ -1356,7 +1356,8 @@ # Example: # # <- { "event": "MEMORY_DEVICE_SIZE_CHANGE", -# "data": { "id": "vm0", "size": 1073741824}, +# "data": { "id": "vm0", "size": 1073741824, +# "qom-path": "/machine/unattached/device[2]" },
Quoted 8 lines
Quoted 6 lines
qapi/machine.json +0
-1# "timestamp": { "seconds": 1588168529, "microseconds": 201316 } } # ## --2.35.1
I'll just assume this is a realistic qom-path and not actually try to check 😅
Copied from another example, so blame that one if it doesn't!
Quoted 1 line
Reviewed-by John Snow <[email protected]>
Cheers,
PATCH 7/14 qapi: fix example of UNPLUG_PRIMARY event
In reply to Victor Toso* Timestamp is not optional, let's add for completeness.
* Add '<-' to signalize it is receiving the data
* Break likes like most of examples do
--- qapi/migration.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
qapi/migration.json +3 -1
@@ -1736,7 +1736,9 @@ # Since: 4.2 # # Example: -# {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} } +# <- { "event": "UNPLUG_PRIMARY", +# "data": { "device-id": "hostdev0" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'UNPLUG_PRIMARY',
Signature · 1 line
2.35.1
Re: [PATCH 07/14] qapi: fix example of UNPLUG_PRIMARY event
Quoted 4 lines · Victor Toso
* Timestamp is not optional, let's add for completeness.
* Add '<-' to signalize it is receiving the data
* Break likes like most of examples do
Oh, I think you meant "break lines like". That took a long minute to parse.
Quoted 22 lines
Signed-off-by Victor Toso <[email protected]>--- qapi/migration.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)qapi/migration.json +3
-2@@ -1736,7 +1736,9 @@ # Since: 4.2 # # Example: -# {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} } +# <- { "event": "UNPLUG_PRIMARY", +# "data": { "device-id": "hostdev0" }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'UNPLUG_PRIMARY', --
Quoted 2 lines
2.35.1
With commit message amended:
PATCH 8/14 qapi: fix example of FAILOVER_NEGOTIATED event
In reply to Victor Toso* Data is an object, not a string. It generates a qdict.
* Timestamp is not optional, let's add for completeness.
--- qapi/net.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)
qapi/net.json +2 -1
@@ -691,7 +691,8 @@ # Example: # # <- { "event": "FAILOVER_NEGOTIATED", -# "data": "net1" } +# "data": { "device-id": "net1" }, +# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } # ## { 'event': 'FAILOVER_NEGOTIATED',
Signature · 1 line
2.35.1
Re: [PATCH 08/14] qapi: fix example of FAILOVER_NEGOTIATED event
Quoted 24 lines · Victor Toso
* Data is an object, not a string. It generates a qdict.
* Timestamp is not optional, let's add for completeness.Signed-off-by Victor Toso <[email protected]>--- qapi/net.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-)qapi/net.json +2
-2@@ -691,7 +691,8 @@ # Example: # # <- { "event": "FAILOVER_NEGOTIATED", -# "data": "net1" } +# "data": { "device-id": "net1" }, +# "timestamp": { "seconds": 1368697518, "microseconds": 326866 } } # ## { 'event': 'FAILOVER_NEGOTIATED', --
Quoted 2 lines
2.35.1
Oh, this one is all messed up to hell. We're not documenting the device-id properly, either. Can that be fixed as well?
Your patch ain't wrong, though:
PATCH 9/14 qapi: run-state examples: add missing member
In reply to Victor TosoAs reason member in not optional.
--- qapi/run-state.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
qapi/run-state.json +4 -2
@@ -150,7 +150,8 @@ # # Example: # -# <- { "event": "SHUTDOWN", "data": { "guest": true }, +# <- { "event": "SHUTDOWN", +# "data": { "guest": true, "reason": "guest-shutdown" }, # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } # ##
@@ -188,7 +189,8 @@ # # Example: # -# <- { "event": "RESET", "data": { "guest": false }, +# <- { "event": "RESET", +# "data": { "guest": false, "reason": "guest-reset" }, # "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } # ##
Signature · 1 line
2.35.1
Re: [PATCH 09/14] qapi: run-state examples: add missing member
Quoted 2 lines · Victor Toso
As reason member in not optional.
Suggest:
"The 'reason' member is not optional."
I also like how you included the type/structure name in the other commit messages, can you work "SHUTDOWN" into this one?
Quoted 31 lines
Signed-off-by Victor Toso <[email protected]>--- qapi/run-state.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)qapi/run-state.json +4
-3@@ -150,7 +150,8 @@ # # Example: # -# <- { "event": "SHUTDOWN", "data": { "guest": true }, +# <- { "event": "SHUTDOWN", +# "data": { "guest": true, "reason": "guest-shutdown" }, # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } # ##@@ -188,7 +189,8 @@ # # Example: # -# <- { "event": "RESET", "data": { "guest": false }, +# <- { "event": "RESET", +# "data": { "guest": false, "reason": "guest-reset" }, # "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } # ## --
Quoted 2 lines
2.35.1
With commit tweaks:
PATCH 10/14 qapi: run-state examples: add missing timestamp
In reply to Victor Toso--- qapi/run-state.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)
qapi/run-state.json +4 -2
@@ -426,7 +426,8 @@ # Example: # # <- { "event": "GUEST_PANICKED", -# "data": { "action": "pause" } } +# "data": { "action": "pause" }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # ## { 'event': 'GUEST_PANICKED',
@@ -446,7 +447,8 @@ # Example: # # <- { "event": "GUEST_CRASHLOADED", -# "data": { "action": "run" } } +# "data": { "action": "run" }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # ## { 'event': 'GUEST_CRASHLOADED',
Signature · 1 line
2.35.1
Re: [PATCH 10/14] qapi: run-state examples: add missing timestamp
Quoted 31 lines · Victor Toso
Signed-off-by Victor Toso <[email protected]>--- qapi/run-state.json | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-)qapi/run-state.json +4
-3@@ -426,7 +426,8 @@ # Example: # # <- { "event": "GUEST_PANICKED", -# "data": { "action": "pause" } } +# "data": { "action": "pause" }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # ## { 'event': 'GUEST_PANICKED',@@ -446,7 +447,8 @@ # Example: # # <- { "event": "GUEST_CRASHLOADED", -# "data": { "action": "run" } } +# "data": { "action": "run" }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # ## { 'event': 'GUEST_CRASHLOADED', --
Quoted 2 lines
2.35.1
Someone once reviewed my documentation and noted that the timestamps were correctly chronological.
... I feel like I have been *hurt* somehow.
Anyway:
PATCH 11/14 qapi: fix example of MEMORY_FAILURE
In reply to Victor TosoMinor issues found and fixed with the example:
* The JSON object of EVENT was not closed
* Missing timestamp
* Flags are optional but if defined then all members should be include so we add "recursive" member.
* Changed string from '' to "" in action-required member.
--- qapi/run-state.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)
qapi/run-state.json +3 -1
@@ -571,7 +571,9 @@ # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor", # "action": "fatal", -# "flags": { 'action-required': false } } +# "flags": { "action-required": false, +# "recursive": false } }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # ## { 'event': 'MEMORY_FAILURE',
Signature · 1 line
2.35.1
Re: [PATCH 11/14] qapi: fix example of MEMORY_FAILURE
Quoted 6 lines · Victor Toso
Minor issues found and fixed with the example:
* The JSON object of EVENT was not closed
* Missing timestamp
* Flags are optional but if defined then all members should be include so we add "recursive" member.
Oh, yeah. Good call.
Quoted 23 lines
* Changed string from '' to "" in action-required member.
Signed-off-by Victor Toso <[email protected]>--- qapi/run-state.json | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-)qapi/run-state.json +3
-2@@ -571,7 +571,9 @@ # <- { "event": "MEMORY_FAILURE", # "data": { "recipient": "hypervisor", # "action": "fatal", -# "flags": { 'action-required': false } } +# "flags": { "action-required": false, +# "recursive": false } }, +# "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } # ## { 'event': 'MEMORY_FAILURE', --
Quoted 2 lines
2.35.1
PATCH 12/14 qapi: ui examples: add missing websocket member
In reply to Victor TosoAs the websocket is not optional in VncBasicInfo.
--- qapi/ui.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)
qapi/ui.json +6 -6
@@ -710,10 +710,10 @@ # # <- { "event": "VNC_CONNECTED", # "data": { -# "server": { "auth": "sasl", "family": "ipv4", +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, # "service": "5901", "host": "0.0.0.0" }, # "client": { "family": "ipv4", "service": "58425", -# "host": "127.0.0.1" } }, +# "host": "127.0.0.1", "websocket": false } }, # "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } # ##
@@ -738,9 +738,9 @@ # # <- { "event": "VNC_INITIALIZED", # "data": { -# "server": { "auth": "sasl", "family": "ipv4", +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, # "service": "5901", "host": "0.0.0.0"}, -# "client": { "family": "ipv4", "service": "46089", +# "client": { "family": "ipv4", "service": "46089", "websocket": false, # "host": "127.0.0.1", "sasl_username": "luiz" } }, # "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } #
@@ -765,9 +765,9 @@ # # <- { "event": "VNC_DISCONNECTED", # "data": { -# "server": { "auth": "sasl", "family": "ipv4", +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, # "service": "5901", "host": "0.0.0.0" }, -# "client": { "family": "ipv4", "service": "58425", +# "client": { "family": "ipv4", "service": "58425", "websocket": false, # "host": "127.0.0.1", "sasl_username": "luiz" } }, # "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } #
Signature · 1 line
2.35.1
Re: [PATCH 12/14] qapi: ui examples: add missing websocket member
Quoted 50 lines · Victor Toso
As the websocket is not optional in VncBasicInfo.
Signed-off-by Victor Toso <[email protected]>--- qapi/ui.json | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-)qapi/ui.json +6
-7@@ -710,10 +710,10 @@ # # <- { "event": "VNC_CONNECTED", # "data": { -# "server": { "auth": "sasl", "family": "ipv4", +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, # "service": "5901", "host": "0.0.0.0" }, # "client": { "family": "ipv4", "service": "58425", -# "host": "127.0.0.1" } }, +# "host": "127.0.0.1", "websocket": false } }, # "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } # ##@@ -738,9 +738,9 @@ # # <- { "event": "VNC_INITIALIZED", # "data": { -# "server": { "auth": "sasl", "family": "ipv4", +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, # "service": "5901", "host": "0.0.0.0"}, -# "client": { "family": "ipv4", "service": "46089", +# "client": { "family": "ipv4", "service": "46089", "websocket": false, # "host": "127.0.0.1", "sasl_username": "luiz" } }, # "timestamp": { "seconds": 1263475302, "microseconds": 150772 } } #@@ -765,9 +765,9 @@ # # <- { "event": "VNC_DISCONNECTED", # "data": { -# "server": { "auth": "sasl", "family": "ipv4", +# "server": { "auth": "sasl", "family": "ipv4", "websocket": false, # "service": "5901", "host": "0.0.0.0" }, -# "client": { "family": "ipv4", "service": "58425", +# "client": { "family": "ipv4", "service": "58425", "websocket": false, # "host": "127.0.0.1", "sasl_username": "luiz" } }, # "timestamp": { "seconds": 1262976601, "microseconds": 975795 } } # --
Quoted 2 lines
2.35.1
Okie-dokey.
PATCH 13/14 qapi: fix example of ACPI_DEVICE_OST event
In reply to Victor Toso* Missing the timestamp
* Missing the "info" object in the "data" member
--- qapi/acpi.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)
qapi/acpi.json +3 -2
@@ -133,8 +133,9 @@ # Example: # # <- { "event": "ACPI_DEVICE_OST", -# "data": { "device": "d1", "slot": "0", -# "slot-type": "DIMM", "source": 1, "status": 0 } } +# "data": { "info": { "device": "d1", "slot": "0", +# "slot-type": "DIMM", "source": 1, "status": 0 } }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'ACPI_DEVICE_OST',
Signature · 1 line
2.35.1
Re: [PATCH 13/14] qapi: fix example of ACPI_DEVICE_OST event
Quoted 26 lines · Victor Toso
* Missing the timestamp
* Missing the "info" object in the "data" memberSigned-off-by Victor Toso <[email protected]>--- qapi/acpi.json | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-)qapi/acpi.json +3
-3@@ -133,8 +133,9 @@ # Example: # # <- { "event": "ACPI_DEVICE_OST", -# "data": { "device": "d1", "slot": "0", -# "slot-type": "DIMM", "source": 1, "status": 0 } } +# "data": { "info": { "device": "d1", "slot": "0", +# "slot-type": "DIMM", "source": 1, "status": 0 } }, +# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } # ## { 'event': 'ACPI_DEVICE_OST', --
Quoted 2 lines
2.35.1
Oh, good spot.
PATCH 14/14 qapi: fix example of dump-guest-memory
In reply to Victor TosoThe member "paging" is not optional
--- qapi/dump.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
qapi/dump.json +1 -1
@@ -83,7 +83,7 @@ # Example: # # -> { "execute": "dump-guest-memory", -# "arguments": { "protocol": "fd:dump" } } +# "arguments": { "paging": false, "protocol": "fd:dump" } } # <- { "return": {} } # ##
Signature · 1 line
2.35.1
Re: [PATCH 14/14] qapi: fix example of dump-guest-memory
Quoted 22 lines · Victor Toso
The member "paging" is not optional
Signed-off-by Victor Toso <[email protected]>--- qapi/dump.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)qapi/dump.json +1
-2@@ -83,7 +83,7 @@ # Example: # # -> { "execute": "dump-guest-memory", -# "arguments": { "protocol": "fd:dump" } } +# "arguments": { "paging": false, "protocol": "fd:dump" } } # <- { "return": {} } # ## --
Quoted 2 lines
2.35.1
Assuming this is a feasible example.
Quoted 37 lines · Victor Toso
Hi,
I've being using the examples as unit tests and found a few that doesn't work out-of-the-box, might be inteded in order to be less verbose in the qapi documentation but nevertheless I'm sending this out in case you want to cherry-pick them.
Cheers,
Victor Toso (14):
qapi: BlockExportRemoveMode: move comments to TODO
qapi: fix example ofBLOCK_IMAGE_CORRUPTEDevent
qapi: fix example ofBLOCK_IO_ERRORevent
qapi: fix example ofBLOCK_JOB_PENDINGevent
qapi: fix example ofDUMP_COMPLETEDevent
qapi: fix example ofMEMORY_DEVICE_SIZE_CHANGEevent
qapi: fix example ofUNPLUG_PRIMARYevent
qapi: fix example ofFAILOVER_NEGOTIATEDevent
qapi: run-state examples: add missing member
qapi: run-state examples: add missing timestamp
qapi: fix example ofMEMORY_FAILURE
qapi: ui examples: add missing websocket member
qapi: fix example ofACPI_DEVICE_OSTevent
qapi: fix example of dump-guest-memoryqapi/acpi.json | 5 +++-- qapi/block-core.json | 9 +++++---- qapi/block-export.json | 10 +++++----- qapi/dump.json | 9 +++++---- qapi/machine.json | 3 ++- qapi/migration.json | 4 +++- qapi/net.json | 3 ++- qapi/run-state.json | 16 +++++++++++----- qapi/ui.json | 12 ++++++------ 9 files changed, 42 insertions(+), 29 deletions(-)
Quoted 3 lines
--
2.35.1
Good stuff, IMO. Systematically validating our docs will be a good thing for improving the usability of those docs.
Only the first patch seems like a lateral move, but I assume you had your reasons.
--js