From 433a4fdc42042e3d5a6c3dc741215f78b43b3a2e Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 22 Apr 2022 15:28:07 +0200 Subject: [PATCH 01/11] qapi: Fix malformed "Since:" section tags "Since X.Y" is not recognized as a tagged section, and therefore not formatted as such in generated documentation. Fix by adding the required colon. Signed-off-by: Markus Armbruster Message-Id: <20220422132807.1704411-1-armbru@redhat.com> Reviewed-by: Andrea Bolognani --- qapi/crypto.json | 3 +-- qapi/machine.json | 2 +- qapi/misc.json | 2 +- qga/qapi-schema.json | 2 +- 4 files changed, 4 insertions(+), 5 deletions(-) diff --git a/qapi/crypto.json b/qapi/crypto.json index 1ec54c15ca..8e0b4764e5 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -357,8 +357,7 @@ # password to use to retrieve current master key. # Defaults to the same secret that was used to open the image # -# -# Since 5.1 +# Since: 5.1 ## { 'struct': 'QCryptoBlockAmendOptionsLUKS', 'data': { 'state': 'QCryptoBlockLUKSKeyslotState', diff --git a/qapi/machine.json b/qapi/machine.json index 92480d4044..c9bdae40eb 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -972,7 +972,7 @@ # preconfigure stage to configure numa mapping before initializing # machine. # -# Since 3.0 +# Since: 3.0 ## { 'command': 'set-numa-node', 'boxed': true, 'data': 'NumaOptions', diff --git a/qapi/misc.json b/qapi/misc.json index b83cc39029..f8a9feda30 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -188,7 +188,7 @@ # Features: # @unstable: This command is experimental. # -# Since 3.0 +# Since: 3.0 # # Returns: nothing # diff --git a/qga/qapi-schema.json b/qga/qapi-schema.json index 4d8e506c9e..f989597b0c 100644 --- a/qga/qapi-schema.json +++ b/qga/qapi-schema.json @@ -950,7 +950,7 @@ # by device mapper # @smart: disk smart information (Since 7.1) # -# Since 5.2 +# Since: 5.2 ## { 'struct': 'GuestDiskInfo', 'data': {'name': 'str', 'partition': 'bool', '*dependencies': ['str'], From f39057d58b9edc37fd82e3ea8a034fc7353c46e8 Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:30 +0200 Subject: [PATCH 02/11] qapi: Drop stray trailing symbol Signed-off-by: Andrea Bolognani Reviewed-by: Markus Armbruster Message-Id: <20220503073737.84223-2-abologna@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/run-state.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/qapi/run-state.json b/qapi/run-state.json index 8124220bd9..15d6c9a2ed 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -348,7 +348,7 @@ # # @poweroff: Shutdown the VM and exit # -# @pause: pause the VM# +# @pause: pause the VM # # Since: 6.0 ## From 406dfba614edc8629f60f03eb7c26bf4e426137d Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:31 +0200 Subject: [PATCH 03/11] qapi: Fix comment indentation It should start on the very first column. Signed-off-by: Andrea Bolognani Reviewed-by: Markus Armbruster Message-Id: <20220503073737.84223-3-abologna@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/ui.json | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/qapi/ui.json b/qapi/ui.json index 059302a5ef..43e62efd76 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1250,21 +1250,21 @@ '*p2p': 'bool', '*audiodev': 'str' } } - ## - # @DisplayGLMode: - # - # Display OpenGL mode. - # - # @off: Disable OpenGL (default). - # @on: Use OpenGL, pick context type automatically. - # Would better be named 'auto' but is called 'on' for backward - # compatibility with bool type. - # @core: Use OpenGL with Core (desktop) Context. - # @es: Use OpenGL with ES (embedded systems) Context. - # - # Since: 3.0 - # - ## +## +# @DisplayGLMode: +# +# Display OpenGL mode. +# +# @off: Disable OpenGL (default). +# @on: Use OpenGL, pick context type automatically. +# Would better be named 'auto' but is called 'on' for backward +# compatibility with bool type. +# @core: Use OpenGL with Core (desktop) Context. +# @es: Use OpenGL with ES (embedded systems) Context. +# +# Since: 3.0 +# +## { 'enum' : 'DisplayGLMode', 'data' : [ 'off', 'on', 'core', 'es' ] } From 4ae65a52658c264caebcb3a31effccf582822a6d Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:32 +0200 Subject: [PATCH 04/11] qapi: Add missing separators between sections This only affects readability. The generated documentation doesn't change. Signed-off-by: Andrea Bolognani Reviewed-by: Markus Armbruster Message-Id: <20220503073737.84223-4-abologna@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/block-core.json | 5 +++++ qapi/block.json | 1 + qapi/crypto.json | 7 +++++++ qapi/machine.json | 1 + qapi/migration.json | 4 ++++ 5 files changed, 18 insertions(+) diff --git a/qapi/block-core.json b/qapi/block-core.json index b66494e8c5..34dae298ee 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -1744,6 +1744,7 @@ # Since: 2.3 # # Example: +# # -> { "execute": "blockdev-backup", # "arguments": { "device": "src-id", # "sync": "full", @@ -2008,6 +2009,7 @@ # @on-target-error: the action to take on an error on the target, # default 'report' (no limitations, since this applies to # a different block device than @device). +# # @unmap: Whether to try to unmap target sectors where source has # only zero. If true, and target unallocated sectors will read as zero, # target image sectors will be unmapped; otherwise, zeroes will be @@ -2029,6 +2031,7 @@ # When true, this job will automatically disappear from the query # list without user intervention. # Defaults to true. (Since 3.1) +# # Since: 1.3 ## { 'struct': 'DriveMirror', @@ -2342,6 +2345,7 @@ # When true, this job will automatically disappear from the query # list without user intervention. # Defaults to true. (Since 3.1) +# # Returns: nothing on success. # # Since: 2.6 @@ -4139,6 +4143,7 @@ # @throttle-group: the name of the throttle-group object to use. It # must already exist. # @file: reference to or definition of the data source block device +# # Since: 2.11 ## { 'struct': 'BlockdevOptionsThrottle', diff --git a/qapi/block.json b/qapi/block.json index 3f100d4887..e0f7898ed1 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -105,6 +105,7 @@ # # Returns: - Nothing on success # - If @device is not a valid block device, DeviceNotFound +# # Notes: Ejecting a device with no media results in success # # Since: 0.14 diff --git a/qapi/crypto.json b/qapi/crypto.json index 8e0b4764e5..21c670eefa 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -32,6 +32,7 @@ # # @raw: raw bytes. When encoded in JSON only valid UTF-8 sequences can be used # @base64: arbitrary base64 encoded binary data +# # Since: 2.6 ## { 'enum': 'QCryptoSecretFormat', @@ -51,6 +52,7 @@ # @sha384: SHA-384. (since 2.7) # @sha512: SHA-512. (since 2.7) # @ripemd160: RIPEMD-160. (since 2.7) +# # Since: 2.6 ## { 'enum': 'QCryptoHashAlgorithm', @@ -75,6 +77,7 @@ # @twofish-128: Twofish with 128 bit / 16 byte keys # @twofish-192: Twofish with 192 bit / 24 byte keys # @twofish-256: Twofish with 256 bit / 32 byte keys +# # Since: 2.6 ## { 'enum': 'QCryptoCipherAlgorithm', @@ -95,6 +98,7 @@ # @cbc: Cipher Block Chaining # @xts: XEX with tweaked code book and ciphertext stealing # @ctr: Counter (Since 2.8) +# # Since: 2.6 ## { 'enum': 'QCryptoCipherMode', @@ -114,6 +118,7 @@ # @plain: 64-bit sector number truncated to 32-bits # @plain64: 64-bit sector number # @essiv: 64-bit sector number encrypted with a hash of the encryption key +# # Since: 2.6 ## { 'enum': 'QCryptoIVGenAlgorithm', @@ -170,6 +175,7 @@ # @key-secret: the ID of a QCryptoSecret object providing the # decryption key. Mandatory except when probing image for # metadata only. +# # Since: 2.6 ## { 'struct': 'QCryptoBlockOptionsLUKS', @@ -194,6 +200,7 @@ # @iter-time: number of milliseconds to spend in # PBKDF passphrase processing. Currently defaults # to 2000. (since 2.8) +# # Since: 2.6 ## { 'struct': 'QCryptoBlockCreateOptionsLUKS', diff --git a/qapi/machine.json b/qapi/machine.json index c9bdae40eb..79901e1c09 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -299,6 +299,7 @@ # returning does not indicate that a guest has accepted the request or # that it has shut down. Many guests will respond to this command by # prompting the user in some way. +# # Example: # # -> { "execute": "system_powerdown" } diff --git a/qapi/migration.json b/qapi/migration.json index 409eb086a2..fc1c157d3f 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1422,7 +1422,9 @@ # @state: The state the migration is currently expected to be in # # Returns: nothing on success +# # Since: 2.11 +# # Example: # # -> { "execute": "migrate-continue" , "arguments": @@ -1736,6 +1738,7 @@ # Since: 4.2 # # Example: +# # <- { "event": "UNPLUG_PRIMARY", # "data": { "device-id": "hostdev0" }, # "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } @@ -1845,6 +1848,7 @@ # Since: 5.2 # # Example: +# # {"execute": "calc-dirty-rate", "arguments": {"calc-time": 1, # 'sample-pages': 512} } # From c6487a88871ed299f78641f81f2c0aaff9b6c8bb Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:33 +0200 Subject: [PATCH 05/11] qapi: Drop unnecessary empty lines in comments Signed-off-by: Andrea Bolognani Reviewed-by: Markus Armbruster Message-Id: <20220503073737.84223-5-abologna@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/block-core.json | 4 ---- qapi/block.json | 1 - qapi/char.json | 1 - qapi/common.json | 2 -- qapi/control.json | 2 -- qapi/machine.json | 2 -- qapi/migration.json | 7 ------- qapi/misc-target.json | 3 --- qapi/replay.json | 1 - qapi/run-state.json | 3 --- qapi/ui.json | 22 ---------------------- 11 files changed, 48 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 34dae298ee..27832a1244 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -237,7 +237,6 @@ # information (since 1.7) # # Since: 1.3 -# ## { 'struct': 'ImageInfo', 'data': {'filename': 'str', 'format': 'str', '*dirty-flag': 'bool', @@ -288,7 +287,6 @@ # supports it # # Since: 1.4 -# ## { 'struct': 'ImageCheck', 'data': {'filename': 'str', 'format': 'str', 'check-errors': 'int', @@ -328,7 +326,6 @@ # @filename: filename that is referred to by @offset # # Since: 2.6 -# ## { 'struct': 'MapEntry', 'data': {'start': 'int', 'length': 'int', 'data': 'bool', @@ -445,7 +442,6 @@ # has one or more dirty bitmaps) (Since 4.2) # # Since: 0.14 -# ## { 'struct': 'BlockDeviceInfo', 'data': { 'file': 'str', '*node-name': 'str', 'ro': 'bool', 'drv': 'str', diff --git a/qapi/block.json b/qapi/block.json index e0f7898ed1..5de15c6070 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -300,7 +300,6 @@ # @read-write: Makes the device writable # # Since: 2.3 -# ## { 'enum': 'BlockdevChangeReadOnlyMode', 'data': ['retain', 'read-only', 'read-write'] } diff --git a/qapi/char.json b/qapi/char.json index 7b42151575..f0fd0d1c9f 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -413,7 +413,6 @@ # @clipboard: enable/disable clipboard, default is disabled. # # Since: 6.1 -# ## { 'struct': 'ChardevQemuVDAgent', 'data': { '*mouse': 'bool', diff --git a/qapi/common.json b/qapi/common.json index 412cc4f5ae..356db3f670 100644 --- a/qapi/common.json +++ b/qapi/common.json @@ -192,7 +192,6 @@ # Keys to toggle input-linux between host and guest. # # Since: 4.0 -# ## { 'enum': 'GrabToggleKeys', 'data': [ 'ctrl-ctrl', 'alt-alt', 'shift-shift','meta-meta', 'scrolllock', @@ -204,7 +203,6 @@ # @human-readable-text: Formatted output intended for humans. # # Since: 6.2 -# ## { 'struct': 'HumanReadableText', 'data': { 'human-readable-text': 'str' } } diff --git a/qapi/control.json b/qapi/control.json index 71a838d49e..8c9122ef7a 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -33,7 +33,6 @@ # all the QMP capabilities will be turned off by default. # # Since: 0.13 -# ## { 'command': 'qmp_capabilities', 'data': { '*enable': [ 'QMPCapability' ] }, @@ -49,7 +48,6 @@ # (Please refer to qmp-spec.txt for more information on OOB) # # Since: 2.12 -# ## { 'enum': 'QMPCapability', 'data': [ 'oob' ] } diff --git a/qapi/machine.json b/qapi/machine.json index 79901e1c09..c8f07c43cd 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -77,7 +77,6 @@ # additional fields will be listed (since 3.0) # # Since: 2.12 -# ## { 'union' : 'CpuInfoFast', 'base' : { 'cpu-index' : 'int', @@ -1022,7 +1021,6 @@ # Formula used: logical_vm_size = vm_ram_size - balloon_size # # Since: 0.14 -# ## { 'struct': 'BalloonInfo', 'data': {'actual': 'int' } } diff --git a/qapi/migration.json b/qapi/migration.json index fc1c157d3f..dd4dde6361 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -151,7 +151,6 @@ # (since 4.2) # # Since: 2.3 -# ## { 'enum': 'MigrationStatus', 'data': [ 'none', 'setup', 'cancelling', 'cancelled', @@ -166,7 +165,6 @@ # @transferred: amount of bytes transferred to the target VM by VFIO devices # # Since: 5.2 -# ## { 'struct': 'VfioStats', 'data': {'transferred': 'int' } } @@ -546,7 +544,6 @@ # @zstd: use zstd compression method. # # Since: 5.0 -# ## { 'enum': 'MultiFDCompression', 'data': [ 'none', 'zlib', @@ -1757,7 +1754,6 @@ # @dirty-rate: dirty rate. # # Since: 6.2 -# ## { 'struct': 'DirtyRateVcpu', 'data': { 'id': 'int', 'dirty-rate': 'int64' } } @@ -1774,7 +1770,6 @@ # @measured: the dirtyrate thread has measured and results are available. # # Since: 5.2 -# ## { 'enum': 'DirtyRateStatus', 'data': [ 'unstarted', 'measuring', 'measured'] } @@ -1791,7 +1786,6 @@ # @dirty-bitmap: calculate dirtyrate by dirty bitmap. # # Since: 6.2 -# ## { 'enum': 'DirtyRateMeasureMode', 'data': ['page-sampling', 'dirty-ring', 'dirty-bitmap'] } @@ -1821,7 +1815,6 @@ # mode specified (Since 6.2) # # Since: 5.2 -# ## { 'struct': 'DirtyRateInfo', 'data': {'*dirty-rate': 'int64', diff --git a/qapi/misc-target.json b/qapi/misc-target.json index ed4a468aab..ae2c483a68 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -110,7 +110,6 @@ # @data: the measurement value encoded in base64 # # Since: 2.12 -# ## { 'struct': 'SevLaunchMeasureInfo', 'data': {'data': 'str'}, 'if': 'TARGET_I386' } @@ -194,7 +193,6 @@ # @gpa: the guest physical address where secret will be injected. # # Since: 6.0 -# ## { 'command': 'sev-inject-launch-secret', 'data': { 'packet-header': 'str', 'secret': 'str', '*gpa': 'uint64' }, @@ -208,7 +206,6 @@ # # @data: guest attestation report (base64 encoded) # -# # Since: 6.1 ## { 'struct': 'SevAttestationReport', diff --git a/qapi/replay.json b/qapi/replay.json index 351898f60d..729470300d 100644 --- a/qapi/replay.json +++ b/qapi/replay.json @@ -40,7 +40,6 @@ # @icount: current number of executed instructions. # # Since: 5.2 -# ## { 'struct': 'ReplayInfo', 'data': { 'mode': 'ReplayMode', '*filename': 'str', 'icount': 'int' } } diff --git a/qapi/run-state.json b/qapi/run-state.json index 15d6c9a2ed..a5d2db3b91 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -592,7 +592,6 @@ # @guest: memory failure at guest memory, # # Since: 5.2 -# ## { 'enum': 'MemoryFailureRecipient', 'data': [ 'hypervisor', @@ -619,7 +618,6 @@ # to handle memory failures. # # Since: 5.2 -# ## { 'enum': 'MemoryFailureAction', 'data': [ 'ignore', @@ -639,7 +637,6 @@ # failure was still in progress. # # Since: 5.2 -# ## { 'struct': 'MemoryFailureFlags', 'data': { 'action-required': 'bool', diff --git a/qapi/ui.json b/qapi/ui.json index 43e62efd76..0e903340fc 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -15,7 +15,6 @@ # Display protocols which support changing password options. # # Since: 7.0 -# ## { 'enum': 'DisplayProtocol', 'data': [ 'vnc', 'spice' ] } @@ -32,7 +31,6 @@ # @disconnect: disconnect existing clients # # Since: 7.0 -# ## { 'enum': 'SetPasswordAction', 'data': [ 'keep', 'fail', 'disconnect' ] } @@ -52,7 +50,6 @@ # For VNC, only 'keep' is currently implemented. # # Since: 7.0 -# ## { 'union': 'SetPasswordOptions', 'base': { 'protocol': 'DisplayProtocol', @@ -70,7 +67,6 @@ # Defaults to the first. # # Since: 7.0 -# ## { 'struct': 'SetPasswordOptionsVnc', 'data': { '*display': 'str' } } @@ -115,7 +111,6 @@ # sure you are on the same machine as the QEMU instance. # # Since: 7.0 -# ## { 'union': 'ExpirePasswordOptions', 'base': { 'protocol': 'DisplayProtocol', @@ -132,7 +127,6 @@ # Defaults to the first. # # Since: 7.0 -# ## { 'struct': 'ExpirePasswordOptionsVnc', @@ -167,7 +161,6 @@ # @ppm: PPM format # # Since: 7.1 -# ## { 'enum': 'ImageFormat', 'data': ['ppm', 'png'] } @@ -902,7 +895,6 @@ # are effectively synonyms. # # Since: 1.3 -# ## { 'enum': 'QKeyCode', 'data': [ 'unmapped', @@ -1206,7 +1198,6 @@ # Since 3.1 # # Since: 2.12 -# ## { 'struct' : 'DisplayGTK', 'data' : { '*grab-on-hover' : 'bool', @@ -1221,7 +1212,6 @@ # available node on the host. # # Since: 3.1 -# ## { 'struct' : 'DisplayEGLHeadless', 'data' : { '*rendernode' : 'str' } } @@ -1242,7 +1232,6 @@ # @audiodev: Use the specified DBus audiodev to export audio. # # Since: 7.0 -# ## { 'struct' : 'DisplayDBus', 'data' : { '*rendernode' : 'str', @@ -1263,7 +1252,6 @@ # @es: Use OpenGL with ES (embedded systems) Context. # # Since: 3.0 -# ## { 'enum' : 'DisplayGLMode', 'data' : [ 'off', 'on', 'core', 'es' ] } @@ -1276,7 +1264,6 @@ # @charset: Font charset used by guest (default: CP437). # # Since: 4.0 -# ## { 'struct' : 'DisplayCurses', 'data' : { '*charset' : 'str' } } @@ -1346,7 +1333,6 @@ # @dbus: Start a D-Bus service for the display. (Since 7.0) # # Since: 2.12 -# ## { 'enum' : 'DisplayType', 'data' : [ @@ -1376,7 +1362,6 @@ # @gl: Enable OpenGL support (default: off). # # Since: 2.12 -# ## { 'union' : 'DisplayOptions', 'base' : { 'type' : 'DisplayType', @@ -1403,7 +1388,6 @@ # Returns: @DisplayOptions # # Since: 3.1 -# ## { 'command': 'query-display-options', 'returns': 'DisplayOptions' } @@ -1416,7 +1400,6 @@ # @vnc: VNC display # # Since: 6.0 -# ## { 'enum': 'DisplayReloadType', 'data': ['vnc'] } @@ -1429,7 +1412,6 @@ # @tls-certs: reload tls certs or not. # # Since: 6.0 -# ## { 'struct': 'DisplayReloadOptionsVNC', 'data': { '*tls-certs': 'bool' } } @@ -1442,7 +1424,6 @@ # @type: Specify the display type. # # Since: 6.0 -# ## { 'union': 'DisplayReloadOptions', 'base': {'type': 'DisplayReloadType'}, @@ -1477,7 +1458,6 @@ # @vnc: VNC display # # Since: 7.1 -# ## { 'enum': 'DisplayUpdateType', 'data': ['vnc'] } @@ -1492,7 +1472,6 @@ # for websockets are not touched. # # Since: 7.1 -# ## { 'struct': 'DisplayUpdateOptionsVNC', 'data': { '*addresses': ['SocketAddress'] } } @@ -1505,7 +1484,6 @@ # @type: Specify the display type. # # Since: 7.1 -# ## { 'union': 'DisplayUpdateOptions', 'base': {'type': 'DisplayUpdateType'}, From 15cc783cfbd8949c5477c134f66f1fdc599a129e Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:34 +0200 Subject: [PATCH 06/11] qapi: Drop unnecessary empty lines outside of comments Signed-off-by: Andrea Bolognani Reviewed-by: Markus Armbruster Message-Id: <20220503073737.84223-6-abologna@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/audio.json | 1 - qapi/block-core.json | 11 ----------- qapi/block.json | 3 --- qapi/char.json | 1 - qapi/control.json | 1 - qapi/crypto.json | 12 ------------ qapi/job.json | 1 - qapi/machine-target.json | 1 - qapi/machine.json | 1 - qapi/misc-target.json | 4 ---- qapi/run-state.json | 1 - qapi/ui.json | 1 - 12 files changed, 38 deletions(-) diff --git a/qapi/audio.json b/qapi/audio.json index 0785e70a50..8099e3d7f1 100644 --- a/qapi/audio.json +++ b/qapi/audio.json @@ -352,7 +352,6 @@ '*out': 'AudiodevPerDirectionOptions', '*path': 'str' } } - ## # @AudioFormat: # diff --git a/qapi/block-core.json b/qapi/block-core.json index 27832a1244..2bce5bb0ae 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -739,7 +739,6 @@ ## { 'command': 'query-block', 'returns': ['BlockInfo'] } - ## # @BlockDeviceTimedStats: # @@ -1512,7 +1511,6 @@ { 'command': 'blockdev-snapshot-sync', 'data': 'BlockdevSnapshotSync' } - ## # @blockdev-snapshot: # @@ -1751,7 +1749,6 @@ { 'command': 'blockdev-backup', 'boxed': true, 'data': 'BlockdevBackup' } - ## # @query-named-block-nodes: # @@ -3067,7 +3064,6 @@ 'base': 'BlockdevOptionsGenericFormat', 'data': { '*key-secret': 'str' } } - ## # @BlockdevOptionsGenericCOWFormat: # @@ -3182,8 +3178,6 @@ 'base': 'BlockdevOptionsGenericCOWFormat', 'data': { '*encrypt': 'BlockdevQcowEncryption' } } - - ## # @BlockdevQcow2EncryptionFormat: # @@ -3357,7 +3351,6 @@ '*user': 'str', '*host-key-check': 'SshHostKeyCheck' } } - ## # @BlkdebugEvent: # @@ -3721,7 +3714,6 @@ '*header-digest': 'IscsiHeaderDigest', '*timeout': 'int' } } - ## # @RbdAuthMode: # @@ -4564,7 +4556,6 @@ { 'enum': 'BlockdevQcow2Version', 'data': [ 'v2', 'v3' ] } - ## # @Qcow2CompressionType: # @@ -4738,7 +4729,6 @@ '*toolsversion': 'str', '*zeroed-grain': 'bool' } } - ## # @BlockdevCreateOptionsSsh: # @@ -4973,7 +4963,6 @@ { 'enum': 'BlockErrorAction', 'data': [ 'ignore', 'report', 'stop' ] } - ## # @BLOCK_IMAGE_CORRUPTED: # diff --git a/qapi/block.json b/qapi/block.json index 5de15c6070..41b73c9934 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -286,7 +286,6 @@ 'data': { 'id': 'str', 'node-name': 'str'} } - ## # @BlockdevChangeReadOnlyMode: # @@ -304,7 +303,6 @@ { 'enum': 'BlockdevChangeReadOnlyMode', 'data': ['retain', 'read-only', 'read-write'] } - ## # @blockdev-change-medium: # @@ -375,7 +373,6 @@ '*force': 'bool', '*read-only-mode': 'BlockdevChangeReadOnlyMode' } } - ## # @DEVICE_TRAY_MOVED: # diff --git a/qapi/char.json b/qapi/char.json index f0fd0d1c9f..8414ef2bc2 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -329,7 +329,6 @@ 'data': { '*signal': 'bool' }, 'base': 'ChardevCommon' } - ## # @ChardevSpiceChannel: # diff --git a/qapi/control.json b/qapi/control.json index 8c9122ef7a..53461cec05 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -68,7 +68,6 @@ { 'struct': 'VersionTriple', 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} } - ## # @VersionInfo: # diff --git a/qapi/crypto.json b/qapi/crypto.json index 21c670eefa..9ec0aca1c6 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -24,7 +24,6 @@ 'prefix': 'QCRYPTO_TLS_CREDS_ENDPOINT', 'data': ['client', 'server']} - ## # @QCryptoSecretFormat: # @@ -39,7 +38,6 @@ 'prefix': 'QCRYPTO_SECRET_FORMAT', 'data': ['raw', 'base64']} - ## # @QCryptoHashAlgorithm: # @@ -59,7 +57,6 @@ 'prefix': 'QCRYPTO_HASH_ALG', 'data': ['md5', 'sha1', 'sha224', 'sha256', 'sha384', 'sha512', 'ripemd160']} - ## # @QCryptoCipherAlgorithm: # @@ -88,7 +85,6 @@ 'serpent-128', 'serpent-192', 'serpent-256', 'twofish-128', 'twofish-192', 'twofish-256']} - ## # @QCryptoCipherMode: # @@ -105,7 +101,6 @@ 'prefix': 'QCRYPTO_CIPHER_MODE', 'data': ['ecb', 'cbc', 'xts', 'ctr']} - ## # @QCryptoIVGenAlgorithm: # @@ -181,7 +176,6 @@ { 'struct': 'QCryptoBlockOptionsLUKS', 'data': { '*key-secret': 'str' }} - ## # @QCryptoBlockCreateOptionsLUKS: # @@ -212,7 +206,6 @@ '*hash-alg': 'QCryptoHashAlgorithm', '*iter-time': 'int'}} - ## # @QCryptoBlockOpenOptions: # @@ -227,7 +220,6 @@ 'data': { 'qcow': 'QCryptoBlockOptionsQCow', 'luks': 'QCryptoBlockOptionsLUKS' } } - ## # @QCryptoBlockCreateOptions: # @@ -242,7 +234,6 @@ 'data': { 'qcow': 'QCryptoBlockOptionsQCow', 'luks': 'QCryptoBlockCreateOptionsLUKS' } } - ## # @QCryptoBlockInfoBase: # @@ -256,7 +247,6 @@ { 'struct': 'QCryptoBlockInfoBase', 'data': { 'format': 'QCryptoBlockFormat' }} - ## # @QCryptoBlockInfoLUKSSlot: # @@ -276,7 +266,6 @@ '*stripes': 'int', 'key-offset': 'int' } } - ## # @QCryptoBlockInfoLUKS: # @@ -330,7 +319,6 @@ { 'enum': 'QCryptoBlockLUKSKeyslotState', 'data': [ 'active', 'inactive' ] } - ## # @QCryptoBlockAmendOptionsLUKS: # diff --git a/qapi/job.json b/qapi/job.json index 1a6ef03451..d5f84e9615 100644 --- a/qapi/job.json +++ b/qapi/job.json @@ -173,7 +173,6 @@ ## { 'command': 'job-cancel', 'data': { 'id': 'str' } } - ## # @job-complete: # diff --git a/qapi/machine-target.json b/qapi/machine-target.json index f5ec4bc172..06b0d2ca61 100644 --- a/qapi/machine-target.json +++ b/qapi/machine-target.json @@ -54,7 +54,6 @@ { 'enum': 'CpuModelExpansionType', 'data': [ 'static', 'full' ] } - ## # @CpuModelCompareResult: # diff --git a/qapi/machine.json b/qapi/machine.json index c8f07c43cd..3fe977e903 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -1365,7 +1365,6 @@ { 'event': 'MEMORY_DEVICE_SIZE_CHANGE', 'data': { '*id': 'str', 'size': 'size', 'qom-path' : 'str'} } - ## # @MEM_UNPLUG_ERROR: # diff --git a/qapi/misc-target.json b/qapi/misc-target.json index ae2c483a68..2fa68a6796 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -21,7 +21,6 @@ { 'command': 'rtc-reset-reinjection', 'if': 'TARGET_I386' } - ## # @SevState: # @@ -101,7 +100,6 @@ { 'command': 'query-sev', 'returns': 'SevInfo', 'if': 'TARGET_I386' } - ## # @SevLaunchMeasureInfo: # @@ -132,7 +130,6 @@ { 'command': 'query-sev-launch-measure', 'returns': 'SevLaunchMeasureInfo', 'if': 'TARGET_I386' } - ## # @SevCapability: # @@ -304,7 +301,6 @@ { 'command': 'query-gic-capabilities', 'returns': ['GICCapability'], 'if': 'TARGET_ARM' } - ## # @SGXEPCSection: # diff --git a/qapi/run-state.json b/qapi/run-state.json index a5d2db3b91..30a2f5231d 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -597,7 +597,6 @@ 'data': [ 'hypervisor', 'guest' ] } - ## # @MemoryFailureAction: # diff --git a/qapi/ui.json b/qapi/ui.json index 0e903340fc..9f19beea6d 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -128,7 +128,6 @@ # # Since: 7.0 ## - { 'struct': 'ExpirePasswordOptionsVnc', 'data': { '*display': 'str' } } From 23e46452589d8c62d69ae993d16e6d15fd15f526 Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:35 +0200 Subject: [PATCH 07/11] qapi: Drop unnecessary whitespace in comments The only instances that get changed are those in which the additional whitespace was not (or couldn't possibly be) used for alignment purposes. Signed-off-by: Andrea Bolognani Message-Id: <20220503073737.84223-7-abologna@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster --- qapi/block-core.json | 24 ++++++++++++------------ qapi/block-export.json | 2 +- qapi/block.json | 2 +- qapi/char.json | 2 +- qapi/dump.json | 4 ++-- qapi/machine.json | 8 ++++---- qapi/misc-target.json | 6 +++--- qapi/misc.json | 6 +++--- qapi/run-state.json | 4 ++-- qapi/sockets.json | 2 +- qapi/ui.json | 2 +- 11 files changed, 31 insertions(+), 31 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index 2bce5bb0ae..e110af2f1d 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -604,7 +604,7 @@ # @inserted: @BlockDeviceInfo describing the device if media is # present # -# Since: 0.14 +# Since: 0.14 ## { 'struct': 'BlockInfo', 'data': {'device': 'str', '*qdev': 'str', 'type': 'str', 'removable': 'bool', @@ -795,9 +795,9 @@ # # Statistics of a virtual block device or a block backing device. # -# @rd_bytes: The number of bytes read by the device. +# @rd_bytes: The number of bytes read by the device. # -# @wr_bytes: The number of bytes written by the device. +# @wr_bytes: The number of bytes written by the device. # # @unmap_bytes: The number of bytes unmapped by the device (Since 4.2) # @@ -970,7 +970,7 @@ # @qdev: The qdev ID, or if no ID is assigned, the QOM path of the block # device. (since 3.0) # -# @stats: A @BlockDeviceStats for the device. +# @stats: A @BlockDeviceStats for the device. # # @driver-specific: Optional driver-specific stats. (Since 4.2) # @@ -1275,7 +1275,7 @@ # # @node-name: graph node name to get the image resized (Since 2.0) # -# @size: new image size in bytes +# @size: new image size in bytes # # Returns: - nothing on success # - If @device is not a valid block device, DeviceNotFound @@ -1960,8 +1960,8 @@ # @job-id: identifier for the newly-created block job. If # omitted, the device name will be used. (Since 2.7) # -# @device: the device name or node-name of a root node whose writes should be -# mirrored. +# @device: the device name or node-name of a root node whose writes should be +# mirrored. # # @target: the target of the new image. If the file exists, or if it # is a device, the existing file/device will be used as the new @@ -1981,7 +1981,7 @@ # @mode: whether and how QEMU should create a new image, default is # 'absolute-paths'. # -# @speed: the maximum speed, in bytes per second +# @speed: the maximum speed, in bytes per second # # @sync: what parts of the disk image should be copied to the destination # (all the disk, only the sectors allocated in the topmost image, or @@ -2296,7 +2296,7 @@ # broken Quorum files. By default, @device is replaced, although # implicitly created filters on it are kept. # -# @speed: the maximum speed, in bytes per second +# @speed: the maximum speed, in bytes per second # # @sync: what parts of the disk image should be copied to the destination # (all the disk, only the sectors allocated in the topmost image, or @@ -4548,8 +4548,8 @@ ## # @BlockdevQcow2Version: # -# @v2: The original QCOW2 format as introduced in qemu 0.10 (version 2) -# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) +# @v2: The original QCOW2 format as introduced in qemu 0.10 (version 2) +# @v3: The extended QCOW2 format as introduced in qemu 1.1 (version 3) # # Since: 2.12 ## @@ -4905,7 +4905,7 @@ # # Options for amending an image format # -# @driver: Block driver of the node to amend. +# @driver: Block driver of the node to amend. # # Since: 5.1 ## diff --git a/qapi/block-export.json b/qapi/block-export.json index 7776248435..0685cb8b9a 100644 --- a/qapi/block-export.json +++ b/qapi/block-export.json @@ -391,7 +391,7 @@ # block-export-del command, but before the shutdown has # completed) # -# Since: 5.2 +# Since: 5.2 ## { 'struct': 'BlockExportInfo', 'data': { 'id': 'str', diff --git a/qapi/block.json b/qapi/block.json index 41b73c9934..96f557b3bb 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -106,7 +106,7 @@ # Returns: - Nothing on success # - If @device is not a valid block device, DeviceNotFound # -# Notes: Ejecting a device with no media results in success +# Notes: Ejecting a device with no media results in success # # Since: 0.14 # diff --git a/qapi/char.json b/qapi/char.json index 8414ef2bc2..a40fe4b7bd 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -216,7 +216,7 @@ # # Configuration info for file chardevs. # -# @in: The name of the input file +# @in: The name of the input file # @out: The name of the output file # @append: Open the file in append mode (default false to # truncate) (Since 2.6) diff --git a/qapi/dump.json b/qapi/dump.json index 29441af9d8..90859c5483 100644 --- a/qapi/dump.json +++ b/qapi/dump.json @@ -186,8 +186,8 @@ # # Returns the available formats for dump-guest-memory # -# Returns: A @DumpGuestMemoryCapability object listing available formats for -# dump-guest-memory +# Returns: A @DumpGuestMemoryCapability object listing available formats for +# dump-guest-memory # # Since: 2.0 # diff --git a/qapi/machine.json b/qapi/machine.json index 3fe977e903..1e5bf02480 100644 --- a/qapi/machine.json +++ b/qapi/machine.json @@ -315,9 +315,9 @@ # query-current-machine), wake-up guest from suspend if the guest is # in SUSPENDED state. Return an error otherwise. # -# Since: 1.1 +# Since: 1.1 # -# Returns: nothing. +# Returns: nothing. # # Note: prior to 4.0, this command does nothing in case the guest # isn't suspended. @@ -368,9 +368,9 @@ # Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64). # The command fails when the guest doesn't support injecting. # -# Returns: If successful, nothing +# Returns: If successful, nothing # -# Since: 0.14 +# Since: 0.14 # # Note: prior to 2.1, this command was only supported for x86 and s390 VMs # diff --git a/qapi/misc-target.json b/qapi/misc-target.json index 2fa68a6796..4944c0528f 100644 --- a/qapi/misc-target.json +++ b/qapi/misc-target.json @@ -136,9 +136,9 @@ # The struct describes capability for a Secure Encrypted Virtualization # feature. # -# @pdh: Platform Diffie-Hellman key (base64 encoded) +# @pdh: Platform Diffie-Hellman key (base64 encoded) # -# @cert-chain: PDH certificate chain (base64 encoded) +# @cert-chain: PDH certificate chain (base64 encoded) # # @cpu0-id: Unique ID of CPU0 (base64 encoded) (since 7.1) # @@ -201,7 +201,7 @@ # The struct describes attestation report for a Secure Encrypted # Virtualization feature. # -# @data: guest attestation report (base64 encoded) +# @data: guest attestation report (base64 encoded) # # Since: 6.1 ## diff --git a/qapi/misc.json b/qapi/misc.json index f8a9feda30..45344483cd 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -136,7 +136,7 @@ # # Stop all guest VCPU execution. # -# Since: 0.14 +# Since: 0.14 # # Notes: This function will succeed even if the guest is already in the stopped # state. In "inmigrate" state, it will ensure that the guest @@ -156,9 +156,9 @@ # # Resume guest VCPU execution. # -# Since: 0.14 +# Since: 0.14 # -# Returns: If successful, nothing +# Returns: If successful, nothing # # Notes: This command will succeed if the guest is currently running. It # will also succeed if the guest is in the "inmigrate" state; in diff --git a/qapi/run-state.json b/qapi/run-state.json index 30a2f5231d..6e2162d7b3 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -104,7 +104,7 @@ # # @status: the virtual machine @RunState # -# Since: 0.14 +# Since: 0.14 # # Notes: @singlestep is enabled through the GDB stub ## @@ -118,7 +118,7 @@ # # Returns: @StatusInfo reflecting all VCPUs # -# Since: 0.14 +# Since: 0.14 # # Example: # diff --git a/qapi/sockets.json b/qapi/sockets.json index fccc38584b..b4f84d3334 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -189,7 +189,7 @@ # Captures the address of a socket, which could also be a named file # descriptor # -# @type: Transport type +# @type: Transport type # # Since: 2.9 ## diff --git a/qapi/ui.json b/qapi/ui.json index 9f19beea6d..c844237434 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1260,7 +1260,7 @@ # # Curses display options. # -# @charset: Font charset used by guest (default: CP437). +# @charset: Font charset used by guest (default: CP437). # # Since: 4.0 ## From c0ac533b6f97fe978a9d9b33078ee36dd54cedb2 Mon Sep 17 00:00:00 2001 From: Andrea Bolognani Date: Tue, 3 May 2022 09:37:36 +0200 Subject: [PATCH 08/11] qapi: Stop using whitespace for alignment in comments Perfectly aligned things look pretty, but keeping them that way as the schema evolves requires churn, and in some cases newly-added lines are not aligned properly. Overall, trying to align things is just not worth the trouble. Signed-off-by: Andrea Bolognani Message-Id: <20220503073737.84223-8-abologna@redhat.com> Message-Id: <20220503073737.84223-9-abologna@redhat.com> Reviewed-by: Eric Blake Reviewed-by: Markus Armbruster [Two patches squashed together] Signed-off-by: Markus Armbruster --- qapi/block-core.json | 53 ++++++++++++++++++++++---------------------- qapi/block.json | 6 ++--- qapi/char.json | 6 ++--- qapi/control.json | 10 ++++----- qapi/crypto.json | 42 +++++++++++++++++------------------ qapi/migration.json | 8 +++---- qapi/sockets.json | 4 ++-- qapi/ui.json | 17 +++++++------- 8 files changed, 72 insertions(+), 74 deletions(-) diff --git a/qapi/block-core.json b/qapi/block-core.json index e110af2f1d..f0383c7925 100644 --- a/qapi/block-core.json +++ b/qapi/block-core.json @@ -337,9 +337,9 @@ # # Cache mode information for a block device # -# @writeback: true if writeback mode is enabled -# @direct: true if the host page cache is bypassed (O_DIRECT) -# @no-flush: true if flush requests are ignored for the device +# @writeback: true if writeback mode is enabled +# @direct: true if the host page cache is bypassed (O_DIRECT) +# @no-flush: true if flush requests are ignored for the device # # Since: 2.3 ## @@ -3333,15 +3333,14 @@ ## # @BlockdevOptionsSsh: # -# @server: host address +# @server: host address # -# @path: path to the image on the host +# @path: path to the image on the host # -# @user: user as which to connect, defaults to current -# local user name +# @user: user as which to connect, defaults to current local user name # -# @host-key-check: Defines how and what to check the host key against -# (default: known_hosts) +# @host-key-check: Defines how and what to check the host key against +# (default: known_hosts) # # Since: 2.9 ## @@ -4662,18 +4661,18 @@ # # Subformat options for VMDK images # -# @monolithicSparse: Single file image with sparse cluster allocation +# @monolithicSparse: Single file image with sparse cluster allocation # -# @monolithicFlat: Single flat data image and a descriptor file +# @monolithicFlat: Single flat data image and a descriptor file # # @twoGbMaxExtentSparse: Data is split into 2GB (per virtual LBA) sparse extent # files, in addition to a descriptor file # -# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat extent -# files, in addition to a descriptor file +# @twoGbMaxExtentFlat: Data is split into 2GB (per virtual LBA) flat extent +# files, in addition to a descriptor file # -# @streamOptimized: Single file image sparse cluster allocation, optimized -# for streaming over network. +# @streamOptimized: Single file image sparse cluster allocation, optimized +# for streaming over network. # # Since: 4.0 ## @@ -4764,7 +4763,7 @@ # @BlockdevVhdxSubformat: # # @dynamic: Growing image file -# @fixed: Preallocated fixed-size image file +# @fixed: Preallocated fixed-size image file # # Since: 2.12 ## @@ -4802,7 +4801,7 @@ # @BlockdevVpcSubformat: # # @dynamic: Growing image file -# @fixed: Preallocated fixed-size image file +# @fixed: Preallocated fixed-size image file # # Since: 2.12 ## @@ -4865,9 +4864,9 @@ # Starts a job to create an image format on a given node. The job is # automatically finalized, but a manual job-dismiss is required. # -# @job-id: Identifier for the newly created job. +# @job-id: Identifier for the newly created job. # -# @options: Options for the image creation. +# @options: Options for the image creation. # # Since: 3.0 ## @@ -4923,17 +4922,17 @@ # Starts a job to amend format specific options of an existing open block device # The job is automatically finalized, but a manual job-dismiss is required. # -# @job-id: Identifier for the newly created job. +# @job-id: Identifier for the newly created job. # -# @node-name: Name of the block node to work on +# @node-name: Name of the block node to work on # -# @options: Options (driver specific) +# @options: Options (driver specific) # -# @force: Allow unsafe operations, format specific -# For luks that allows erase of the last active keyslot -# (permanent loss of data), -# and replacement of an active keyslot -# (possible loss of data if IO error happens) +# @force: Allow unsafe operations, format specific +# For luks that allows erase of the last active keyslot +# (permanent loss of data), +# and replacement of an active keyslot +# (possible loss of data if IO error happens) # # Features: # @unstable: This command is experimental. diff --git a/qapi/block.json b/qapi/block.json index 96f557b3bb..19326641ac 100644 --- a/qapi/block.json +++ b/qapi/block.json @@ -50,9 +50,9 @@ # # Type of Floppy drive to be emulated by the Floppy Disk Controller. # -# @144: 1.44MB 3.5" drive -# @288: 2.88MB 3.5" drive -# @120: 1.2MB 5.25" drive +# @144: 1.44MB 3.5" drive +# @288: 2.88MB 3.5" drive +# @120: 1.2MB 5.25" drive # @none: No drive connected # @auto: Automatically determined by inserted media at boot # diff --git a/qapi/char.json b/qapi/char.json index a40fe4b7bd..923dc5056d 100644 --- a/qapi/char.json +++ b/qapi/char.json @@ -376,10 +376,10 @@ # # Configuration info for virtual console chardevs. # -# @width: console width, in pixels +# @width: console width, in pixels # @height: console height, in pixels -# @cols: console width, in chars -# @rows: console height, in chars +# @cols: console width, in chars +# @rows: console height, in chars # # Since: 1.5 ## diff --git a/qapi/control.json b/qapi/control.json index 53461cec05..afca2043af 100644 --- a/qapi/control.json +++ b/qapi/control.json @@ -192,14 +192,14 @@ # # Options to be used for adding a new monitor. # -# @id: Name of the monitor +# @id: Name of the monitor # -# @mode: Selects the monitor mode (default: readline in the system -# emulator, control in qemu-storage-daemon) +# @mode: Selects the monitor mode (default: readline in the system +# emulator, control in qemu-storage-daemon) # -# @pretty: Enables pretty printing (QMP only) +# @pretty: Enables pretty printing (QMP only) # -# @chardev: Name of a character device to expose the monitor on +# @chardev: Name of a character device to expose the monitor on # # Since: 5.0 ## diff --git a/qapi/crypto.json b/qapi/crypto.json index 9ec0aca1c6..15c24f0078 100644 --- a/qapi/crypto.json +++ b/qapi/crypto.json @@ -311,8 +311,8 @@ # # Defines state of keyslots that are affected by the update # -# @active: The slots contain the given password and marked as active -# @inactive: The slots are erased (contain garbage) and marked as inactive +# @active: The slots contain the given password and marked as active +# @inactive: The slots are erased (contain garbage) and marked as inactive # # Since: 5.1 ## @@ -327,30 +327,30 @@ # # @state: the desired state of the keyslots # -# @new-secret: The ID of a QCryptoSecret object providing the password to be -# written into added active keyslots +# @new-secret: The ID of a QCryptoSecret object providing the password to be +# written into added active keyslots # -# @old-secret: Optional (for deactivation only) -# If given will deactivate all keyslots that -# match password located in QCryptoSecret with this ID +# @old-secret: Optional (for deactivation only) +# If given will deactivate all keyslots that +# match password located in QCryptoSecret with this ID # -# @iter-time: Optional (for activation only) -# Number of milliseconds to spend in -# PBKDF passphrase processing for the newly activated keyslot. -# Currently defaults to 2000. +# @iter-time: Optional (for activation only) +# Number of milliseconds to spend in +# PBKDF passphrase processing for the newly activated keyslot. +# Currently defaults to 2000. # -# @keyslot: Optional. ID of the keyslot to activate/deactivate. -# For keyslot activation, keyslot should not be active already -# (this is unsafe to update an active keyslot), -# but possible if 'force' parameter is given. -# If keyslot is not given, first free keyslot will be written. +# @keyslot: Optional. ID of the keyslot to activate/deactivate. +# For keyslot activation, keyslot should not be active already +# (this is unsafe to update an active keyslot), +# but possible if 'force' parameter is given. +# If keyslot is not given, first free keyslot will be written. # -# For keyslot deactivation, this parameter specifies the exact -# keyslot to deactivate +# For keyslot deactivation, this parameter specifies the exact +# keyslot to deactivate # -# @secret: Optional. The ID of a QCryptoSecret object providing the -# password to use to retrieve current master key. -# Defaults to the same secret that was used to open the image +# @secret: Optional. The ID of a QCryptoSecret object providing the +# password to use to retrieve current master key. +# Defaults to the same secret that was used to open the image # # Since: 5.1 ## diff --git a/qapi/migration.json b/qapi/migration.json index dd4dde6361..1ff4d7eaff 100644 --- a/qapi/migration.json +++ b/qapi/migration.json @@ -1191,10 +1191,10 @@ # ask the client to automatically reconnect using the new parameters # once migration finished successfully. Only implemented for SPICE. # -# @protocol: must be "spice" -# @hostname: migration target hostname -# @port: spice tcp port for plaintext channels -# @tls-port: spice tcp port for tls-secured channels +# @protocol: must be "spice" +# @hostname: migration target hostname +# @port: spice tcp port for plaintext channels +# @tls-port: spice tcp port for tls-secured channels # @cert-subject: server certificate subject # # Since: 0.14 diff --git a/qapi/sockets.json b/qapi/sockets.json index b4f84d3334..bad74e34d3 100644 --- a/qapi/sockets.json +++ b/qapi/sockets.json @@ -167,9 +167,9 @@ # # Available SocketAddress types # -# @inet: Internet address +# @inet: Internet address # -# @unix: Unix domain socket +# @unix: Unix domain socket # # @vsock: VMCI address # diff --git a/qapi/ui.json b/qapi/ui.json index c844237434..11a827d10f 100644 --- a/qapi/ui.json +++ b/qapi/ui.json @@ -1018,8 +1018,8 @@ # # Keyboard input event. # -# @key: Which key this event is for. -# @down: True for key-down and false for key-up events. +# @key: Which key this event is for. +# @down: True for key-down and false for key-up events. # # Since: 2.0 ## @@ -1033,7 +1033,7 @@ # Pointer button input event. # # @button: Which button this event is for. -# @down: True for key-down and false for key-up events. +# @down: True for key-down and false for key-up events. # # Since: 2.0 ## @@ -1353,12 +1353,11 @@ # # Display (user interface) options. # -# @type: Which DisplayType qemu should use. -# @full-screen: Start user interface in fullscreen mode (default: off). -# @window-close: Allow to quit qemu with window close button (default: on). -# @show-cursor: Force showing the mouse cursor (default: off). -# (since: 5.0) -# @gl: Enable OpenGL support (default: off). +# @type: Which DisplayType qemu should use. +# @full-screen: Start user interface in fullscreen mode (default: off). +# @window-close: Allow to quit qemu with window close button (default: on). +# @show-cursor: Force showing the mouse cursor (default: off). (since: 5.0) +# @gl: Enable OpenGL support (default: off). # # Since: 2.12 ## From 9e191d33688125c0cadff96b389126664054046f Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 10 May 2022 08:16:44 +0200 Subject: [PATCH 09/11] qapi/expr: Enforce feature naming rules again Commit e42648dccd "qapi/expr.py: Remove single-letter variable" accidentally removed the check for "only lower case letters and hyphens". Restore it. Fixes: e42648dccdd1defe8f35f247966cd7283f865cd6 Signed-off-by: Markus Armbruster Message-Id: <20220510061645.3209195-2-armbru@redhat.com> --- scripts/qapi/expr.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/qapi/expr.py b/scripts/qapi/expr.py index 48578e1698..5a1782b57e 100644 --- a/scripts/qapi/expr.py +++ b/scripts/qapi/expr.py @@ -443,7 +443,7 @@ def check_features(features: Optional[object], check_keys(feat, info, source, ['name'], ['if']) check_name_is_str(feat['name'], info, source) source = "%s '%s'" % (source, feat['name']) - check_name_str(feat['name'], info, source) + check_name_lower(feat['name'], info, source) check_if(feat, info, source) From 1524559f58b1fe14e9b1c9b5be09a82696867eb1 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 10 May 2022 08:16:45 +0200 Subject: [PATCH 10/11] docs/devel/qapi-code-gen: Belatedly document feature naming rules Signed-off-by: Markus Armbruster Message-Id: <20220510061645.3209195-3-armbru@redhat.com> --- docs/devel/qapi-code-gen.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst index 7b968433a6..cd9b544376 100644 --- a/docs/devel/qapi-code-gen.rst +++ b/docs/devel/qapi-code-gen.rst @@ -739,10 +739,11 @@ Type names ending with ``Kind`` or ``List`` are reserved for the generator, which uses them for implicit union enums and array types, respectively. -Command names, and member names within a type, should be all lower -case with words separated by a hyphen. However, some existing older -commands and complex types use underscore; when extending them, -consistency is preferred over blindly avoiding underscore. +Command names, member names within a type, and feature names should be +all lower case with words separated by a hyphen. However, some +existing older commands and complex types use underscore; when +extending them, consistency is preferred over blindly avoiding +underscore. Event names should be ALL_CAPS with words separated by underscore. From dd8f0f332f34a2466d855d1067386b04ff2eb6d9 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Tue, 10 May 2022 10:14:33 +0200 Subject: [PATCH 11/11] qapi/pragma: Tidy up comments Commit 05ebf841ef "qapi: Enforce command naming rules" inserted new code between a comment and the code it applies to. Move the comment back to its code, and add one for the new code. Signed-off-by: Markus Armbruster Message-Id: <20220510081433.3289762-1-armbru@redhat.com> --- qapi/pragma.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/qapi/pragma.json b/qapi/pragma.json index e6a021c19c..7f810b0e97 100644 --- a/qapi/pragma.json +++ b/qapi/pragma.json @@ -6,7 +6,7 @@ # Whitelists to permit QAPI rule violations; think twice before you # add to them! { 'pragma': { - # Commands allowed to return a non-dictionary: + # Command names containing '_' 'command-name-exceptions': [ 'add_client', 'block_resize', @@ -24,6 +24,7 @@ 'system_powerdown', 'system_reset', 'system_wakeup' ], + # Commands allowed to return a non-dictionary 'command-returns-exceptions': [ 'human-monitor-command', 'qom-get',