From a937b6aa739f65f2cae2ad9a7eb65a309ad2a359 Mon Sep 17 00:00:00 2001 From: Markus Armbruster Date: Fri, 28 Apr 2023 12:54:29 +0200 Subject: qapi: Reformat doc comments to conform to current conventions Change # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. to # @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua. See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale. Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences. To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there. Signed-off-by: Markus Armbruster Message-Id: <20230428105429.1687850-18-armbru@redhat.com> Reviewed-by: Juan Quintela Acked-by: Lukas Straub [Straightforward conflicts in qapi/audio.json qapi/misc-target.json qapi/run-state.json resolved] --- qapi/run-state.json | 227 +++++++++++++++++++++++++++------------------------- 1 file changed, 118 insertions(+), 109 deletions(-) (limited to 'qapi/run-state.json') diff --git a/qapi/run-state.json b/qapi/run-state.json index db3cf52c62..f216ba54ec 100644 --- a/qapi/run-state.json +++ b/qapi/run-state.json @@ -16,16 +16,16 @@ # @finish-migrate: guest is paused to finish the migration process # # @inmigrate: guest is paused waiting for an incoming migration. Note -# that this state does not tell whether the machine will start at the -# end of the migration. This depends on the command-line -S option and -# any invocation of 'stop' or 'cont' that has happened since QEMU was -# started. +# that this state does not tell whether the machine will start at +# the end of the migration. This depends on the command-line -S +# option and any invocation of 'stop' or 'cont' that has happened +# since QEMU was started. # -# @internal-error: An internal error that prevents further guest execution -# has occurred +# @internal-error: An internal error that prevents further guest +# execution has occurred # -# @io-error: the last IOP has failed and the device is configured to pause -# on I/O errors +# @io-error: the last IOP has failed and the device is configured to +# pause on I/O errors # # @paused: guest has been paused via the 'stop' command # @@ -43,13 +43,15 @@ # # @suspended: guest is suspended (ACPI S3) # -# @watchdog: the watchdog action is configured to pause and has been triggered +# @watchdog: the watchdog action is configured to pause and has been +# triggered # -# @guest-panicked: guest has been panicked as a result of guest OS panic +# @guest-panicked: guest has been panicked as a result of guest OS +# panic # -# @colo: guest is paused to save/restore VM state under colo checkpoint, -# VM can not get into this state unless colo capability is enabled -# for migration. (since 2.8) +# @colo: guest is paused to save/restore VM state under colo +# checkpoint, VM can not get into this state unless colo +# capability is enabled for migration. (since 2.8) ## { 'enum': 'RunState', 'data': [ 'debug', 'inmigrate', 'internal-error', 'io-error', 'paused', @@ -75,21 +77,21 @@ # @host-ui: Reaction to a UI event, like window close # # @guest-shutdown: Guest shutdown/suspend request, via ACPI or other -# hardware-specific means +# hardware-specific means # # @guest-reset: Guest reset request, and command line turns that into -# a shutdown +# a shutdown # -# @guest-panic: Guest panicked, and command line turns that into a shutdown +# @guest-panic: Guest panicked, and command line turns that into a +# shutdown # -# @subsystem-reset: Partial guest reset that does not trigger QMP events and -# ignores --no-reboot. This is useful for sanitizing -# hypercalls on s390 that are used during kexec/kdump/boot +# @subsystem-reset: Partial guest reset that does not trigger QMP +# events and ignores --no-reboot. This is useful for sanitizing +# hypercalls on s390 that are used during kexec/kdump/boot # # @snapshot-load: A snapshot is being loaded by the record & replay -# subsystem. This value is used only within QEMU. It -# doesn't occur in QMP. (since 7.2) -# +# subsystem. This value is used only within QEMU. It doesn't +# occur in QMP. (since 7.2) ## { 'enum': 'ShutdownCause', # Beware, shutdown_caused_by_guest() depends on enumeration order @@ -104,19 +106,21 @@ # # @running: true if all VCPUs are runnable, false if not runnable # -# @singlestep: true if using TCG with one guest instruction -# per translation block +# @singlestep: true if using TCG with one guest instruction per +# translation block # # @status: the virtual machine @RunState # # Features: -# @deprecated: Member 'singlestep' is deprecated (with no replacement). +# +# @deprecated: Member 'singlestep' is deprecated (with no +# replacement). # # Since: 0.14 # -# Notes: @singlestep is enabled on the command line with -# '-accel tcg,one-insn-per-tb=on', or with the HMP -# 'one-insn-per-tb' command. +# Notes: @singlestep is enabled on the command line with '-accel +# tcg,one-insn-per-tb=on', or with the HMP 'one-insn-per-tb' +# command. ## { 'struct': 'StatusInfo', 'data': {'running': 'bool', @@ -138,7 +142,6 @@ # <- { "return": { "running": true, # "singlestep": false, # "status": "running" } } -# ## { 'command': 'query-status', 'returns': 'StatusInfo', 'allow-preconfig': true } @@ -146,17 +149,20 @@ ## # @SHUTDOWN: # -# Emitted when the virtual machine has shut down, indicating that qemu is -# about to exit. +# Emitted when the virtual machine has shut down, indicating that qemu +# is about to exit. # -# @guest: If true, the shutdown was triggered by a guest request (such as -# a guest-initiated ACPI shutdown request or other hardware-specific action) -# rather than a host request (such as sending qemu a SIGINT). (since 2.10) +# @guest: If true, the shutdown was triggered by a guest request (such +# as a guest-initiated ACPI shutdown request or other +# hardware-specific action) rather than a host request (such as +# sending qemu a SIGINT). (since 2.10) # -# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since 4.0) +# @reason: The @ShutdownCause which resulted in the SHUTDOWN. (since +# 4.0) # -# Note: If the command-line option "-no-shutdown" has been specified, qemu will -# not exit, and a STOP event will eventually follow the SHUTDOWN event +# Note: If the command-line option "-no-shutdown" has been specified, +# qemu will not exit, and a STOP event will eventually follow the +# SHUTDOWN event # # Since: 0.12 # @@ -165,15 +171,14 @@ # <- { "event": "SHUTDOWN", # "data": { "guest": true, "reason": "guest-shutdown" }, # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } -# ## { 'event': 'SHUTDOWN', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } ## # @POWERDOWN: # -# Emitted when the virtual machine is powered down through the power control -# system, such as via ACPI. +# Emitted when the virtual machine is powered down through the power +# control system, such as via ACPI. # # Since: 0.12 # @@ -181,7 +186,6 @@ # # <- { "event": "POWERDOWN", # "timestamp": { "seconds": 1267040730, "microseconds": 682951 } } -# ## { 'event': 'POWERDOWN' } @@ -191,9 +195,9 @@ # Emitted when the virtual machine is reset # # @guest: If true, the reset was triggered by a guest request (such as -# a guest-initiated ACPI reboot request or other hardware-specific action) -# rather than a host request (such as the QMP command system_reset). -# (since 2.10) +# a guest-initiated ACPI reboot request or other hardware-specific +# action) rather than a host request (such as the QMP command +# system_reset). (since 2.10) # # @reason: The @ShutdownCause of the RESET. (since 4.0) # @@ -204,7 +208,6 @@ # <- { "event": "RESET", # "data": { "guest": false, "reason": "guest-reset" }, # "timestamp": { "seconds": 1267041653, "microseconds": 9518 } } -# ## { 'event': 'RESET', 'data': { 'guest': 'bool', 'reason': 'ShutdownCause' } } @@ -219,7 +222,6 @@ # # <- { "event": "STOP", # "timestamp": { "seconds": 1267041730, "microseconds": 281295 } } -# ## { 'event': 'STOP' } @@ -234,15 +236,14 @@ # # <- { "event": "RESUME", # "timestamp": { "seconds": 1271770767, "microseconds": 582542 } } -# ## { 'event': 'RESUME' } ## # @SUSPEND: # -# Emitted when guest enters a hardware suspension state, for example, S3 state, -# which is sometimes called standby state +# Emitted when guest enters a hardware suspension state, for example, +# S3 state, which is sometimes called standby state # # Since: 1.1 # @@ -250,17 +251,18 @@ # # <- { "event": "SUSPEND", # "timestamp": { "seconds": 1344456160, "microseconds": 309119 } } -# ## { 'event': 'SUSPEND' } ## # @SUSPEND_DISK: # -# Emitted when guest enters a hardware suspension state with data saved on -# disk, for example, S4 state, which is sometimes called hibernate state +# Emitted when guest enters a hardware suspension state with data +# saved on disk, for example, S4 state, which is sometimes called +# hibernate state # -# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering this state +# Note: QEMU shuts down (similar to event @SHUTDOWN) when entering +# this state # # Since: 1.2 # @@ -274,7 +276,8 @@ ## # @WAKEUP: # -# Emitted when the guest has woken up from suspend state and is running +# Emitted when the guest has woken up from suspend state and is +# running # # Since: 1.1 # @@ -282,7 +285,6 @@ # # <- { "event": "WAKEUP", # "timestamp": { "seconds": 1344522075, "microseconds": 745528 } } -# ## { 'event': 'WAKEUP' } @@ -293,8 +295,9 @@ # # @action: action that has been taken # -# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is -# followed respectively by the RESET, SHUTDOWN, or STOP events +# Note: If action is "reset", "shutdown", or "pause" the WATCHDOG +# event is followed respectively by the RESET, SHUTDOWN, or STOP +# events # # Note: This event is rate-limited. # @@ -305,7 +308,6 @@ # <- { "event": "WATCHDOG", # "data": { "action": "reset" }, # "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } -# ## { 'event': 'WATCHDOG', 'data': { 'action': 'WatchdogAction' } } @@ -313,13 +315,13 @@ ## # @WatchdogAction: # -# An enumeration of the actions taken when the watchdog device's timer is -# expired +# An enumeration of the actions taken when the watchdog device's timer +# is expired # # @reset: system resets # -# @shutdown: system shutdown, note that it is similar to @powerdown, which -# tries to set to system status and notify guest +# @shutdown: system shutdown, note that it is similar to @powerdown, +# which tries to set to system status and notify guest # # @poweroff: system poweroff, the emulator program exits # @@ -329,8 +331,8 @@ # # @none: nothing is done # -# @inject-nmi: a non-maskable interrupt is injected into the first VCPU (all -# VCPUS on x86) (since 2.4) +# @inject-nmi: a non-maskable interrupt is injected into the first +# VCPU (all VCPUS on x86) (since 2.4) # # Since: 2.1 ## @@ -345,7 +347,8 @@ # # @reset: Reset the VM # -# @shutdown: Shutdown the VM and exit, according to the shutdown action +# @shutdown: Shutdown the VM and exit, according to the shutdown +# action # # Since: 6.0 ## @@ -373,10 +376,11 @@ # # @pause: Pause the VM # -# @shutdown: Shutdown the VM and exit, according to the shutdown action +# @shutdown: Shutdown the VM and exit, according to the shutdown +# action # -# @exit-failure: Shutdown the VM and exit with nonzero status -# (since 7.1) +# @exit-failure: Shutdown the VM and exit with nonzero status (since +# 7.1) # # Since: 6.0 ## @@ -395,8 +399,8 @@ ## # @set-action: # -# Set the actions that will be taken by the emulator in response to guest -# events. +# Set the actions that will be taken by the emulator in response to +# guest events. # # @reboot: @RebootAction action taken on guest reboot. # @@ -404,7 +408,8 @@ # # @panic: @PanicAction action taken on guest panic. # -# @watchdog: @WatchdogAction action taken when watchdog timer expires . +# @watchdog: @WatchdogAction action taken when watchdog timer expires +# . # # Returns: Nothing on success. # @@ -442,7 +447,6 @@ # <- { "event": "GUEST_PANICKED", # "data": { "action": "pause" }, # "timestamp": { "seconds": 1648245231, "microseconds": 900001 } } -# ## { 'event': 'GUEST_PANICKED', 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } @@ -463,7 +467,6 @@ # <- { "event": "GUEST_CRASHLOADED", # "data": { "action": "run" }, # "timestamp": { "seconds": 1648245259, "microseconds": 893771 } } -# ## { 'event': 'GUEST_CRASHLOADED', 'data': { 'action': 'GuestPanicAction', '*info': 'GuestPanicInformation' } } @@ -510,8 +513,8 @@ {'union': 'GuestPanicInformation', 'base': {'type': 'GuestPanicInformationType'}, 'discriminator': 'type', - 'data': { 'hyper-v': 'GuestPanicInformationHyperV', - 's390': 'GuestPanicInformationS390' } } + 'data': {'hyper-v': 'GuestPanicInformationHyperV', + 's390': 'GuestPanicInformationS390'}} ## # @GuestPanicInformationHyperV: @@ -521,11 +524,11 @@ # Since: 2.9 ## {'struct': 'GuestPanicInformationHyperV', - 'data': { 'arg1': 'uint64', - 'arg2': 'uint64', - 'arg3': 'uint64', - 'arg4': 'uint64', - 'arg5': 'uint64' } } + 'data': {'arg1': 'uint64', + 'arg2': 'uint64', + 'arg3': 'uint64', + 'arg4': 'uint64', + 'arg5': 'uint64'}} ## # @S390CrashReason: @@ -536,13 +539,13 @@ # # @disabled-wait: the CPU has entered a disabled wait state # -# @extint-loop: clock comparator or cpu timer interrupt with new PSW enabled -# for external interrupts +# @extint-loop: clock comparator or cpu timer interrupt with new PSW +# enabled for external interrupts # # @pgmint-loop: program interrupt with BAD new PSW # -# @opint-loop: operation exception interrupt with invalid code at the program -# interrupt new PSW +# @opint-loop: operation exception interrupt with invalid code at the +# program interrupt new PSW # # Since: 2.12 ## @@ -559,17 +562,20 @@ # S390 specific guest panic information (PSW) # # @core: core id of the CPU that crashed +# # @psw-mask: control fields of guest PSW +# # @psw-addr: guest instruction address +# # @reason: guest crash reason # # Since: 2.12 ## {'struct': 'GuestPanicInformationS390', - 'data': { 'core': 'uint32', - 'psw-mask': 'uint64', - 'psw-addr': 'uint64', - 'reason': 'S390CrashReason' } } + 'data': {'core': 'uint32', + 'psw-mask': 'uint64', + 'psw-addr': 'uint64', + 'reason': 'S390CrashReason'}} ## # @MEMORY_FAILURE: @@ -578,9 +584,11 @@ # # @recipient: recipient is defined as @MemoryFailureRecipient. # -# @action: action that has been taken. action is defined as @MemoryFailureAction. +# @action: action that has been taken. action is defined as +# @MemoryFailureAction. # -# @flags: flags for MemoryFailureAction. action is defined as @MemoryFailureFlags. +# @flags: flags for MemoryFailureAction. action is defined as +# @MemoryFailureFlags. # # Since: 5.2 # @@ -592,7 +600,6 @@ # "flags": { "action-required": false, # "recursive": false } }, # "timestamp": { "seconds": 1267061043, "microseconds": 959568 } } -# ## { 'event': 'MEMORY_FAILURE', 'data': { 'recipient': 'MemoryFailureRecipient', @@ -604,8 +611,8 @@ # # Hardware memory failure occurs, handled by recipient. # -# @hypervisor: memory failure at QEMU process address space. -# (none guest memory, but used by QEMU itself). +# @hypervisor: memory failure at QEMU process address space. (none +# guest memory, but used by QEMU itself). # # @guest: memory failure at guest memory, # @@ -620,19 +627,20 @@ # # Actions taken by QEMU in response to a hardware memory failure. # -# @ignore: the memory failure could be ignored. This will only be the case -# for action-optional failures. +# @ignore: the memory failure could be ignored. This will only be the +# case for action-optional failures. # -# @inject: memory failure occurred in guest memory, the guest enabled MCE -# handling mechanism, and QEMU could inject the MCE into the guest -# successfully. +# @inject: memory failure occurred in guest memory, the guest enabled +# MCE handling mechanism, and QEMU could inject the MCE into the +# guest successfully. # -# @fatal: the failure is unrecoverable. This occurs for action-required -# failures if the recipient is the hypervisor; QEMU will exit. +# @fatal: the failure is unrecoverable. This occurs for +# action-required failures if the recipient is the hypervisor; +# QEMU will exit. # -# @reset: the failure is unrecoverable but confined to the guest. This -# occurs if the recipient is a guest guest which is not ready -# to handle memory failures. +# @reset: the failure is unrecoverable but confined to the guest. +# This occurs if the recipient is a guest guest which is not ready +# to handle memory failures. # # Since: 5.2 ## @@ -648,10 +656,10 @@ # Additional information on memory failures. # # @action-required: whether a memory failure event is action-required -# or action-optional (e.g. a failure during memory scrub). +# or action-optional (e.g. a failure during memory scrub). # -# @recursive: whether the failure occurred while the previous -# failure was still in progress. +# @recursive: whether the failure occurred while the previous failure +# was still in progress. # # Since: 5.2 ## @@ -664,10 +672,11 @@ # # An enumeration of the options specified when enabling notify VM exit # -# @run: enable the feature, do nothing and continue if the notify VM exit happens. +# @run: enable the feature, do nothing and continue if the notify VM +# exit happens. # -# @internal-error: enable the feature, raise a internal error if the notify -# VM exit happens. +# @internal-error: enable the feature, raise a internal error if the +# notify VM exit happens. # # @disable: disable the feature. # -- cgit v1.2.3