A few doc fixes
cover A few doc fixes
If we need -rc4 for some other reason, throwing these in would be nice.
Markus Armbruster (3):
docs/interop/qmp-spec: Point to the QEMU QMP reference manual
qapi: Document event VSERPORT_CHANGE is rate-limited docs/qdev-device-use: Don't suggest -drive and -net can do USB
docs/interop/qmp-spec.txt | 9 ++++++--- docs/qdev-device-use.txt | 34 ++++++++++++++++++++++++++++++++-- qapi/char.json | 2 ++ 3 files changed, 40 insertions(+), 5 deletions(-)
Signature · 1 line
2.26.2
PATCH 1/3 docs/interop/qmp-spec: Point to the QEMU QMP reference manual
Commit 4d8bb958fa0..231aaf3a821 integrated the contents of docs/qmp-events.txt into QAPI schema doc comments. It left dangling references to qmp-events.txt behind. Fix to point to the QEMU QMP reference manual generated from the QAPI schema.
Add a similar reference for commands.
--- docs/interop/qmp-spec.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
docs/interop/qmp-spec.txt +6 -3
@@ -110,6 +110,9 @@ or if provided. The "id" member can be any json-value. A json-number incremented for each successive command works fine. +The actual commands are documented in the QEMU QMP reference manual +docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}. + 2.3.1 Out-of-band execution ---------------------------
@@ -207,13 +210,13 @@ The format of asynchronous events is: there is a failure to retrieve host time, both members of the timestamp will be set to -1. -For a listing of supported asynchronous events, please, refer to the -qmp-events.txt file. +The actual asynchronous events are documented in the QEMU QMP +reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}. Some events are rate-limited to at most one per second. If additional "similar" events arrive within one second, all but the last one are dropped, and the last one is delayed. "Similar" normally means same -event type. See qmp-events.txt for details. +event type. 2.6 Forcing the JSON parser into known-good state -------------------------------------------------
Signature · 1 line
2.26.2
Re: [PATCH 1/3] docs/interop/qmp-spec: Point to the QEMU QMP reference manual
Quoted 5 lines · Markus Armbruster
Commit
4d8bb958fa0..231aaf3a821integrated the contents ofdocs/qmp-events.txtinto QAPI schema doc comments. It left dangling references to qmp-events.txt behind. Fix to point to the QEMU QMP reference manual generated from the QAPI schema.
Quoted 9 lines
Add a similar reference for commands.
Cc Marc-André Lureau <[email protected]>Signed-off-by Markus Armbruster <[email protected]>--- docs/interop/qmp-spec.txt | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-)
sure,
docs/interop/qmp-spec.txt +0 -0
Quoted 35 lines
index
adcf86754d..cdf5842555100644docs/interop/qmp-spec.txt +6
-4@@ -110,6 +110,9 @@ or if provided. The "id" member can be any json-value. A json-number incremented for each successive command works fine. +The actual commands are documented in the QEMU QMP reference manual +docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}. + 2.3.1 Out-of-band execution ---------------------------@@ -207,13 +210,13 @@ The format of asynchronous events is: there is a failure to retrieve host time, both members of the timestamp will be set to -1. -For a listing of supported asynchronous events, please, refer to the -qmp-events.txt file. +The actual asynchronous events are documented in the QEMU QMP +reference manual docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt}. Some events are rate-limited to at most one per second. If additional "similar" events arrive within one second, all but the last one are dropped, and the last one is delayed. "Similar" normally means same -event type. See qmp-events.txt for details. +event type. 2.6 Forcing the JSON parser into known-good state ------------------------------------------------- --2.26.2
Signature · 1 line
Marc-André Lureau
PATCH 2/3 qapi: Document event VSERPORT_CHANGE is rate-limited
In reply to Markus ArmbrusterCommit e2ae6159de "virtio-serial: report frontend connection state via monitor" neglected to document the new event is rate-limited. Fix that.
--- qapi/char.json | 2 ++ 1 file changed, 2 insertions(+)
qapi/char.json +2 -0
@@ -562,6 +562,8 @@ # # @open: true if the guest has opened the virtio-serial port # +# Note: This event is rate-limited. +# # Since: 2.1 # # Example:
Signature · 1 line
2.26.2
Re: [PATCH 2/3] qapi: Document event VSERPORT_CHANGE is rate-limited
Hi
Quoted 11 lines · Markus Armbruster
Commit
e2ae6159de"virtio-serial: report frontend connection state via monitor" neglected to document the new event is rate-limited. Fix that.Cc Marc-André Lureau <[email protected]>Cc Eric Blake <[email protected]>Signed-off-by Markus Armbruster <[email protected]>--- qapi/char.json | 2 ++ 1 file changed, 2 insertions(+)
Quoted 18 lines
qapi/char.json +2
-1@@ -562,6 +562,8 @@ # # @open: true if the guest has opened the virtio-serial port # +# Note: This event is rate-limited. +# # Since: 2.1 # # Example: --2.26.2
Signature · 1 line
Marc-André Lureau
PATCH 3/3 docs/qdev-device-use: Don't suggest -drive and -net can do USB
In reply to Markus ArmbrusterCommit 480324ec8d "docs/qdev-device-use: Clean up the sentences related to -usbdevice" deleted the information on syntax that no longer works. Unfortunately, the resulting text suggests you can configure USB block devices with -drive, and USB network devices with -net, which is misleading.
Instead of rephrasing the now misleading text, I'm putting the information back, and just make clear it's about old versions of QEMU.
--- docs/qdev-device-use.txt | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-)
docs/qdev-device-use.txt +32 -2
@@ -125,7 +125,14 @@ The -device argument differs in detail for each type of drive: * if=pflash, if=mtd, if=sd, if=xen are not yet available with -device -For USB storage devices, you can use something like: +For USB devices, the old way was actually different: + + -usbdevice disk:format=FMT:FILENAME + +"Was" because "disk:" is gone since v2.12.0. + +The old way provided much less control than -drive's OPTS... The new +way fixes that: -device usb-storage,drive=DRIVE-ID,removable=RMB
@@ -178,6 +185,9 @@ The appropriate DEVNAME depends on the machine type. For type "pc": -device usb-braille,chardev=braille -chardev braille,id=braille +* -usbdevice serial::chardev is gone since v2.12.0. It became + -device usb-serial,chardev=dev. + LEGACY-CHARDEV translates to -chardev HOST-OPTS... as follows: * null becomes -chardev null
@@ -231,6 +241,12 @@ The old way to define the guest part looks like this: -net nic,netdev=NET-ID,macaddr=MACADDR,model=MODEL,name=ID,addr=STR,vectors=V +Except for USB it looked like this: + + -usbdevice net:netdev=NET-ID,macaddr=MACADDR,name=ID + +"Looked" because "net:" is gone since v2.12.0. + The new way is -device: -device DEVNAME,netdev=NET-ID,mac=MACADDR,DEV-OPTS...
@@ -327,6 +343,13 @@ The new way is -device DEVNAME,DEV-OPTS... Details depend on DRIVER: * wacom-tablet -device usb-wacom-tablet * braille See "Character Devices" +Until v2.12.0, we additionally had + +* host:... See "Host Device Assignment" +* disk:... See "Block Devices" +* serial:... See "Character Devices" +* net:... See "Network Devices" + === Watchdog Devices === Host and guest part of watchdog devices have always been separate.
@@ -342,7 +365,14 @@ and host USB devices. PCI devices can only be assigned with -device: -device vfio-pci,host=ADDR,id=ID -To assign a host USB device use: +The old way to assign a USB host device + + -usbdevice host:auto:BUS.ADDR:VID:PRID + +was removed in v2.12.0. Any of BUS, ADDR, VID, PRID could be the +wildcard *. + +The new way is -device usb-host,hostbus=BUS,hostaddr=ADDR,vendorid=VID,productid=PRID
Signature · 1 line
2.26.2