jcs.org / qemu
qemu with hax to log dma reads & writes jcs.org/2018/11/12/vfio
fork atom

qapi: Use explicit bulleted lists

A JSON block comment like this:
Returns: nothing on success
If @node is not a valid block device, DeviceNotFound
If @name is not found, GenericError with an explanation

renders like this:

Returns: nothing on success If node is not a valid block device,
DeviceNotFound If name is not found, GenericError with an explanation

because whitespace is not significant.

Use an actual bulleted list, so that the formatting is correct.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-14-peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-15-peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-16-peter.maydell@linaro.org>
[Three commits squashed into one]
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>

authored by

Peter Maydell and committed by
Markus Armbruster e050e426 449be9df

+119 -125
+54 -54
qapi/block-core.json
··· 1326 1326 # 1327 1327 # @size: new image size in bytes 1328 1328 # 1329 - # Returns: nothing on success 1330 - # If @device is not a valid block device, DeviceNotFound 1329 + # Returns: - nothing on success 1330 + # - If @device is not a valid block device, DeviceNotFound 1331 1331 # 1332 1332 # Since: 0.14.0 1333 1333 # ··· 1510 1510 # 1511 1511 # For the arguments, see the documentation of BlockdevSnapshotSync. 1512 1512 # 1513 - # Returns: nothing on success 1514 - # If @device is not a valid block device, DeviceNotFound 1513 + # Returns: - nothing on success 1514 + # - If @device is not a valid block device, DeviceNotFound 1515 1515 # 1516 1516 # Since: 0.14.0 1517 1517 # ··· 1586 1586 # when specifying the string or the image chain may 1587 1587 # not be able to be reopened again. 1588 1588 # 1589 - # Returns: Nothing on success 1590 - # 1591 - # If "device" does not exist or cannot be determined, DeviceNotFound 1589 + # Returns: - Nothing on success 1590 + # - If "device" does not exist or cannot be determined, DeviceNotFound 1592 1591 # 1593 1592 # Since: 2.1 1594 1593 ## ··· 1674 1673 # list without user intervention. 1675 1674 # Defaults to true. (Since 3.1) 1676 1675 # 1677 - # Returns: Nothing on success 1678 - # If @device does not exist, DeviceNotFound 1679 - # Any other error returns a GenericError. 1676 + # Returns: - Nothing on success 1677 + # - If @device does not exist, DeviceNotFound 1678 + # - Any other error returns a GenericError. 1680 1679 # 1681 1680 # Since: 1.3 1682 1681 # ··· 1704 1703 # The operation can be stopped before it has completed using the 1705 1704 # block-job-cancel command. 1706 1705 # 1707 - # Returns: nothing on success 1708 - # If @device is not a valid block device, GenericError 1706 + # Returns: - nothing on success 1707 + # - If @device is not a valid block device, GenericError 1709 1708 # 1710 1709 # Since: 1.6 1711 1710 # ··· 1730 1729 # The operation can be stopped before it has completed using the 1731 1730 # block-job-cancel command. 1732 1731 # 1733 - # Returns: nothing on success 1734 - # If @device is not a valid block device, DeviceNotFound 1732 + # Returns: - nothing on success 1733 + # - If @device is not a valid block device, DeviceNotFound 1735 1734 # 1736 1735 # Since: 2.3 1737 1736 # ··· 1925 1924 # format of the mirror image, default is to probe if mode='existing', 1926 1925 # else the format of the source. 1927 1926 # 1928 - # Returns: nothing on success 1929 - # If @device is not a valid block device, GenericError 1927 + # Returns: - nothing on success 1928 + # - If @device is not a valid block device, GenericError 1930 1929 # 1931 1930 # Since: 1.3 1932 1931 # ··· 2097 2096 # 2098 2097 # Create a dirty bitmap with a name on the node, and start tracking the writes. 2099 2098 # 2100 - # Returns: nothing on success 2101 - # If @node is not a valid block device or node, DeviceNotFound 2102 - # If @name is already taken, GenericError with an explanation 2099 + # Returns: - nothing on success 2100 + # - If @node is not a valid block device or node, DeviceNotFound 2101 + # - If @name is already taken, GenericError with an explanation 2103 2102 # 2104 2103 # Since: 2.4 2105 2104 # ··· 2120 2119 # with block-dirty-bitmap-add. If the bitmap is persistent, remove it from its 2121 2120 # storage too. 2122 2121 # 2123 - # Returns: nothing on success 2124 - # If @node is not a valid block device or node, DeviceNotFound 2125 - # If @name is not found, GenericError with an explanation 2126 - # if @name is frozen by an operation, GenericError 2122 + # Returns: - nothing on success 2123 + # - If @node is not a valid block device or node, DeviceNotFound 2124 + # - If @name is not found, GenericError with an explanation 2125 + # - if @name is frozen by an operation, GenericError 2127 2126 # 2128 2127 # Since: 2.4 2129 2128 # ··· 2144 2143 # backup from this point in time forward will only backup clusters 2145 2144 # modified after this clear operation. 2146 2145 # 2147 - # Returns: nothing on success 2148 - # If @node is not a valid block device, DeviceNotFound 2149 - # If @name is not found, GenericError with an explanation 2146 + # Returns: - nothing on success 2147 + # - If @node is not a valid block device, DeviceNotFound 2148 + # - If @name is not found, GenericError with an explanation 2150 2149 # 2151 2150 # Since: 2.4 2152 2151 # ··· 2165 2164 # 2166 2165 # Enables a dirty bitmap so that it will begin tracking disk changes. 2167 2166 # 2168 - # Returns: nothing on success 2169 - # If @node is not a valid block device, DeviceNotFound 2170 - # If @name is not found, GenericError with an explanation 2167 + # Returns: - nothing on success 2168 + # - If @node is not a valid block device, DeviceNotFound 2169 + # - If @name is not found, GenericError with an explanation 2171 2170 # 2172 2171 # Since: 4.0 2173 2172 # ··· 2186 2185 # 2187 2186 # Disables a dirty bitmap so that it will stop tracking disk changes. 2188 2187 # 2189 - # Returns: nothing on success 2190 - # If @node is not a valid block device, DeviceNotFound 2191 - # If @name is not found, GenericError with an explanation 2188 + # Returns: - nothing on success 2189 + # - If @node is not a valid block device, DeviceNotFound 2190 + # - If @name is not found, GenericError with an explanation 2192 2191 # 2193 2192 # Since: 4.0 2194 2193 # ··· 2215 2214 # of the source bitmaps. This can be used to achieve backup checkpoints, or in 2216 2215 # simpler usages, to copy bitmaps. 2217 2216 # 2218 - # Returns: nothing on success 2219 - # If @node is not a valid block device, DeviceNotFound 2220 - # If any bitmap in @bitmaps or @target is not found, GenericError 2221 - # If any of the bitmaps have different sizes or granularities, 2222 - # GenericError 2217 + # Returns: - nothing on success 2218 + # - If @node is not a valid block device, DeviceNotFound 2219 + # - If any bitmap in @bitmaps or @target is not found, GenericError 2220 + # - If any of the bitmaps have different sizes or granularities, 2221 + # GenericError 2223 2222 # 2224 2223 # Since: 4.0 2225 2224 # ··· 2251 2250 # 2252 2251 # Get bitmap SHA256. 2253 2252 # 2254 - # Returns: BlockDirtyBitmapSha256 on success 2255 - # If @node is not a valid block device, DeviceNotFound 2256 - # If @name is not found or if hashing has failed, GenericError with an 2257 - # explanation 2253 + # Returns: - BlockDirtyBitmapSha256 on success 2254 + # - If @node is not a valid block device, DeviceNotFound 2255 + # - If @name is not found or if hashing has failed, GenericError with an 2256 + # explanation 2258 2257 # 2259 2258 # Since: 2.10 2260 2259 ## ··· 2371 2370 # the device will be removed from its group and the rest of its 2372 2371 # members will not be affected. The 'group' parameter is ignored. 2373 2372 # 2374 - # Returns: Nothing on success 2375 - # If @device is not a valid block device, DeviceNotFound 2373 + # Returns: - Nothing on success 2374 + # - If @device is not a valid block device, DeviceNotFound 2376 2375 # 2377 2376 # Since: 1.1 2378 2377 # ··· 2622 2621 # list without user intervention. 2623 2622 # Defaults to true. (Since 3.1) 2624 2623 # 2625 - # Returns: Nothing on success. If @device does not exist, DeviceNotFound. 2624 + # Returns: - Nothing on success. 2625 + # - If @device does not exist, DeviceNotFound. 2626 2626 # 2627 2627 # Since: 1.1 2628 2628 # ··· 2656 2656 # @speed: the maximum speed, in bytes per second, or 0 for unlimited. 2657 2657 # Defaults to 0. 2658 2658 # 2659 - # Returns: Nothing on success 2660 - # If no background operation is active on this device, DeviceNotActive 2659 + # Returns: - Nothing on success 2660 + # - If no background operation is active on this device, DeviceNotActive 2661 2661 # 2662 2662 # Since: 1.1 2663 2663 ## ··· 2696 2696 # abandon the job immediately (even if it is paused) instead of waiting 2697 2697 # for the destination to complete its final synchronization (since 1.3) 2698 2698 # 2699 - # Returns: Nothing on success 2700 - # If no background operation is active on this device, DeviceNotActive 2699 + # Returns: - Nothing on success 2700 + # - If no background operation is active on this device, DeviceNotActive 2701 2701 # 2702 2702 # Since: 1.1 2703 2703 ## ··· 2720 2720 # the name of the parameter), but since QEMU 2.7 it can have 2721 2721 # other values. 2722 2722 # 2723 - # Returns: Nothing on success 2724 - # If no background operation is active on this device, DeviceNotActive 2723 + # Returns: - Nothing on success 2724 + # - If no background operation is active on this device, DeviceNotActive 2725 2725 # 2726 2726 # Since: 1.3 2727 2727 ## ··· 2742 2742 # the name of the parameter), but since QEMU 2.7 it can have 2743 2743 # other values. 2744 2744 # 2745 - # Returns: Nothing on success 2746 - # If no background operation is active on this device, DeviceNotActive 2745 + # Returns: - Nothing on success 2746 + # - If no background operation is active on this device, DeviceNotActive 2747 2747 # 2748 2748 # Since: 1.3 2749 2749 ## ··· 2770 2770 # the name of the parameter), but since QEMU 2.7 it can have 2771 2771 # other values. 2772 2772 # 2773 - # Returns: Nothing on success 2774 - # If no background operation is active on this device, DeviceNotActive 2773 + # Returns: - Nothing on success 2774 + # - If no background operation is active on this device, DeviceNotActive 2775 2775 # 2776 2776 # Since: 1.3 2777 2777 ##
+14 -19
qapi/block.json
··· 115 115 # 116 116 # For the arguments, see the documentation of BlockdevSnapshotInternal. 117 117 # 118 - # Returns: nothing on success 119 - # 120 - # If @device is not a valid block device, GenericError 121 - # 122 - # If any snapshot matching @name exists, or @name is empty, 123 - # GenericError 124 - # 125 - # If the format of the image used does not support it, 126 - # BlockFormatFeatureNotSupported 118 + # Returns: - nothing on success 119 + # - If @device is not a valid block device, GenericError 120 + # - If any snapshot matching @name exists, or @name is empty, 121 + # GenericError 122 + # - If the format of the image used does not support it, 123 + # BlockFormatFeatureNotSupported 127 124 # 128 125 # Since: 1.7 129 126 # ··· 154 151 # 155 152 # @name: optional the snapshot's name to be deleted 156 153 # 157 - # Returns: SnapshotInfo on success 158 - # If @device is not a valid block device, GenericError 159 - # If snapshot not found, GenericError 160 - # If the format of the image used does not support it, 161 - # BlockFormatFeatureNotSupported 162 - # If @id and @name are both not specified, GenericError 154 + # Returns: - SnapshotInfo on success 155 + # - If @device is not a valid block device, GenericError 156 + # - If snapshot not found, GenericError 157 + # - If the format of the image used does not support it, 158 + # BlockFormatFeatureNotSupported 159 + # - If @id and @name are both not specified, GenericError 163 160 # 164 161 # Since: 1.7 165 162 # ··· 197 194 # @force: If true, eject regardless of whether the drive is locked. 198 195 # If not specified, the default value is false. 199 196 # 200 - # Returns: Nothing on success 201 - # 202 - # If @device is not a valid block device, DeviceNotFound 203 - # 197 + # Returns: - Nothing on success 198 + # - If @device is not a valid block device, DeviceNotFound 204 199 # Notes: Ejecting a device with no media results in success 205 200 # 206 201 # Since: 0.14.0
+16 -20
qapi/misc.json
··· 430 430 # 431 431 # Return information about the balloon device. 432 432 # 433 - # Returns: @BalloonInfo on success 434 - # 435 - # If the balloon driver is enabled but not functional because the KVM 436 - # kernel module cannot support it, KvmMissingCap 437 - # 438 - # If no balloon device is present, DeviceNotActive 433 + # Returns: - @BalloonInfo on success 434 + # - If the balloon driver is enabled but not functional because the KVM 435 + # kernel module cannot support it, KvmMissingCap 436 + # - If no balloon device is present, DeviceNotActive 439 437 # 440 438 # Since: 0.14.0 441 439 # ··· 492 490 # 493 491 # @bar: the index of the Base Address Register for this region 494 492 # 495 - # @type: 'io' if the region is a PIO region 496 - # 'memory' if the region is a MMIO region 493 + # @type: - 'io' if the region is a PIO region 494 + # - 'memory' if the region is a MMIO region 497 495 # 498 496 # @size: memory size 499 497 # ··· 1004 1002 # 1005 1003 # @value: the target size of the balloon in bytes 1006 1004 # 1007 - # Returns: Nothing on success 1008 - # If the balloon driver is enabled but not functional because the KVM 1005 + # Returns: - Nothing on success 1006 + # - If the balloon driver is enabled but not functional because the KVM 1009 1007 # kernel module cannot support it, KvmMissingCap 1010 - # If no balloon device is present, DeviceNotActive 1008 + # - If no balloon device is present, DeviceNotActive 1011 1009 # 1012 1010 # Notes: This command just issues a request to the guest. When it returns, 1013 1011 # the balloon size may not have changed. A guest can change the balloon ··· 1086 1084 # If @device is 'vnc' and @target is 'password', this is the new VNC 1087 1085 # password to set. See change-vnc-password for additional notes. 1088 1086 # 1089 - # Returns: Nothing on success. 1090 - # If @device is not a valid block device, DeviceNotFound 1087 + # Returns: - Nothing on success. 1088 + # - If @device is not a valid block device, DeviceNotFound 1091 1089 # 1092 1090 # Notes: This interface is deprecated, and it is strongly recommended that you 1093 1091 # avoid using it. For changing block devices, use ··· 1237 1235 # 1238 1236 # @opaque: A free-form string that can be used to describe the fd. 1239 1237 # 1240 - # Returns: @AddfdInfo on success 1241 - # 1242 - # If file descriptor was not received, FdNotSupplied 1243 - # 1244 - # If @fdset-id is a negative value, InvalidParameterValue 1238 + # Returns: - @AddfdInfo on success 1239 + # - If file descriptor was not received, FdNotSupplied 1240 + # - If @fdset-id is a negative value, InvalidParameterValue 1245 1241 # 1246 1242 # Notes: The list of fd sets is shared by all monitor connections. 1247 1243 # ··· 1269 1265 # 1270 1266 # @fd: The file descriptor that is to be removed. 1271 1267 # 1272 - # Returns: Nothing on success 1273 - # If @fdset-id or @fd is not found, FdNotFound 1268 + # Returns: - Nothing on success 1269 + # - If @fdset-id or @fd is not found, FdNotFound 1274 1270 # 1275 1271 # Since: 1.2.0 1276 1272 #
+2 -2
qapi/tpm.json
··· 96 96 # 97 97 # A union referencing different TPM backend types' configuration options 98 98 # 99 - # @type: 'passthrough' The configuration options for the TPM passthrough type 100 - # 'emulator' The configuration options for TPM emulator backend type 99 + # @type: - 'passthrough' The configuration options for the TPM passthrough type 100 + # - 'emulator' The configuration options for TPM emulator backend type 101 101 # 102 102 # Since: 1.5 103 103 ##
+33 -30
qapi/ui.json
··· 12 12 # 13 13 # Sets the password of a remote display session. 14 14 # 15 - # @protocol: 'vnc' to modify the VNC server password 16 - # 'spice' to modify the Spice server password 15 + # @protocol: - 'vnc' to modify the VNC server password 16 + # - 'spice' to modify the Spice server password 17 17 # 18 18 # @password: the new password 19 19 # ··· 23 23 # 'disconnect' to disconnect existing clients 24 24 # 'keep' to maintain existing clients 25 25 # 26 - # Returns: Nothing on success 27 - # If Spice is not enabled, DeviceNotFound 26 + # Returns: - Nothing on success 27 + # - If Spice is not enabled, DeviceNotFound 28 28 # 29 29 # Since: 0.14.0 30 30 # ··· 46 46 # @protocol: the name of the remote display protocol 'vnc' or 'spice' 47 47 # 48 48 # @time: when to expire the password. 49 - # 'now' to expire the password immediately 50 - # 'never' to cancel password expiration 51 - # '+INT' where INT is the number of seconds from now (integer) 52 - # 'INT' where INT is the absolute time in seconds 49 + # 50 + # - 'now' to expire the password immediately 51 + # - 'never' to cancel password expiration 52 + # - '+INT' where INT is the number of seconds from now (integer) 53 + # - 'INT' where INT is the absolute time in seconds 53 54 # 54 - # Returns: Nothing on success 55 - # If @protocol is 'spice' and Spice is not active, DeviceNotFound 55 + # Returns: - Nothing on success 56 + # - If @protocol is 'spice' and Spice is not active, DeviceNotFound 56 57 # 57 58 # Since: 0.14.0 58 59 # ··· 201 202 # @tls-port: The SPICE server's TLS port number. 202 203 # 203 204 # @auth: the current authentication type used by the server 204 - # 'none' if no authentication is being used 205 - # 'spice' uses SASL or direct TLS authentication, depending on command 206 - # line options 205 + # 206 + # - 'none' if no authentication is being used 207 + # - 'spice' uses SASL or direct TLS authentication, depending on command 208 + # line options 207 209 # 208 210 # @mouse-mode: The mode in which the mouse cursor is displayed currently. Can 209 211 # be determined by the client or the server, or unknown if spice ··· 433 435 # @host: The hostname the VNC server is bound to. This depends on 434 436 # the name resolution on the host and may be an IP address. 435 437 # 436 - # @family: 'ipv6' if the host is listening for IPv6 connections 437 - # 'ipv4' if the host is listening for IPv4 connections 438 - # 'unix' if the host is listening on a unix domain socket 439 - # 'unknown' otherwise 438 + # @family: - 'ipv6' if the host is listening for IPv6 connections 439 + # - 'ipv4' if the host is listening for IPv4 connections 440 + # - 'unix' if the host is listening on a unix domain socket 441 + # - 'unknown' otherwise 440 442 # 441 443 # @service: The service name of the server's port. This may depends 442 444 # on the host system's service database so symbolic names should not 443 445 # be relied on. 444 446 # 445 447 # @auth: the current authentication type used by the server 446 - # 'none' if no authentication is being used 447 - # 'vnc' if VNC authentication is being used 448 - # 'vencrypt+plain' if VEncrypt is used with plain text authentication 449 - # 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication 450 - # 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication 451 - # 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth 452 - # 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth 453 - # 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth 454 - # 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth 455 - # 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth 456 - # 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth 448 + # 449 + # - 'none' if no authentication is being used 450 + # - 'vnc' if VNC authentication is being used 451 + # - 'vencrypt+plain' if VEncrypt is used with plain text authentication 452 + # - 'vencrypt+tls+none' if VEncrypt is used with TLS and no authentication 453 + # - 'vencrypt+tls+vnc' if VEncrypt is used with TLS and VNC authentication 454 + # - 'vencrypt+tls+plain' if VEncrypt is used with TLS and plain text auth 455 + # - 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth 456 + # - 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth 457 + # - 'vencrypt+x509+plain' if VEncrypt is used with x509 and plain text auth 458 + # - 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth 459 + # - 'vencrypt+x509+sasl' if VEncrypt is used with x509 and SASL auth 457 460 # 458 461 # @clients: a list of @VncClientInfo of all currently connected clients 459 462 # ··· 840 843 # @hold-time: time to delay key up events, milliseconds. Defaults 841 844 # to 100 842 845 # 843 - # Returns: Nothing on success 844 - # If key is unknown or redundant, InvalidParameter 846 + # Returns: - Nothing on success 847 + # - If key is unknown or redundant, InvalidParameter 845 848 # 846 849 # Since: 1.3.0 847 850 #