[PATCH 0/3] A few doc fixes

[PATCH 0/3] A few doc fixes

[Markus Armbruster]

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(-)

-- 
2.26.2

[PATCH 1/3] docs/interop/qmp-spec: Point to the QEMU QMP reference manual

[Markus Armbruster]

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.

Cc: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/interop/qmp-spec.txt | 9 ++++++---
 1 file changed, 6 insertions(+), 3 deletions(-)

diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt
index adcf86754d..cdf5842555 100644
--- a/docs/interop/qmp-spec.txt
+++ b/docs/interop/qmp-spec.txt
@@ -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

Re: [PATCH 1/3] docs/interop/qmp-spec: Point to the QEMU QMP reference manual

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 2067 bytes --]

On Thu, Aug 6, 2020 at 12:12 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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.
>
> Cc: Marc-André Lureau <marcandre.lureau@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  docs/interop/qmp-spec.txt | 9 ++++++---
>  1 file changed, 6 insertions(+), 3 deletions(-)
>
>
sure,
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


diff --git a/docs/interop/qmp-spec.txt b/docs/interop/qmp-spec.txt
> index adcf86754d..cdf5842555 100644
> --- a/docs/interop/qmp-spec.txt
> +++ b/docs/interop/qmp-spec.txt
> @@ -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
>
>
>

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 3002 bytes --]

[PATCH 2/3] qapi: Document event VSERPORT_CHANGE is rate-limited

[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 <marcandre.lureau@redhat.com>
Cc: Eric Blake <eblake@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 qapi/char.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/qapi/char.json b/qapi/char.json
index 8aeedf96b2..b4d66ec90b 100644
--- a/qapi/char.json
+++ b/qapi/char.json
@@ -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

Re: [PATCH 2/3] qapi: Document event VSERPORT_CHANGE is rate-limited

[Marc-André Lureau]

[-- Attachment #1: Type: text/plain, Size: 904 bytes --]

Hi

On Thu, Aug 6, 2020 at 12:13 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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 <marcandre.lureau@redhat.com>
> Cc: Eric Blake <eblake@redhat.com>
> Signed-off-by: Markus Armbruster <armbru@redhat.com>
> ---
>  qapi/char.json | 2 ++
>  1 file changed, 2 insertions(+)
>

Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>


> diff --git a/qapi/char.json b/qapi/char.json
> index 8aeedf96b2..b4d66ec90b 100644
> --- a/qapi/char.json
> +++ b/qapi/char.json
> @@ -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
>
>
>

-- 
Marc-André Lureau

[-- Attachment #2: Type: text/html, Size: 1768 bytes --]

[PATCH 3/3] docs/qdev-device-use: Don't suggest -drive and -net can do USB

[Markus Armbruster]

Commit 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.

Cc: Thomas Huth <thuth@redhat.com>
Cc: Gerd Hoffmann <kraxel@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
---
 docs/qdev-device-use.txt | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/docs/qdev-device-use.txt b/docs/qdev-device-use.txt
index f8d0d2fe29..8532ba5224 100644
--- a/docs/qdev-device-use.txt
+++ b/docs/qdev-device-use.txt
@@ -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
 
-- 
2.26.2