[PATCH 0/2] usb: docs update

[PATCH 0/2] usb: docs update

[Gerd Hoffmann]

Gerd Hoffmann (2):
  usb: document guest-reset and guest-reset-all
  usb: document pcap (aka usb traffic capture)

 docs/system/devices/usb.rst | 41 +++++++++++++++++++++++++++++++++++++
 1 file changed, 41 insertions(+)

-- 
2.36.1

[PATCH 1/2] usb: document guest-reset and guest-reset-all

[Gerd Hoffmann]

Suggested-by: Michal Prívozník <mprivozn@redhat.com>
Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 docs/system/devices/usb.rst | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst
index 872d9167589b..18e7c8b4d716 100644
--- a/docs/system/devices/usb.rst
+++ b/docs/system/devices/usb.rst
@@ -353,3 +353,32 @@ and also assign it to the correct USB bus in QEMU like this:
         -device usb-ehci,id=ehci                             \\
         -device usb-host,bus=usb-bus.0,hostbus=3,hostport=1  \\
         -device usb-host,bus=ehci.0,hostbus=1,hostport=1
+
+``usb-host`` properties for reset behavior
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``guest-reset`` and ``guest-reset-all`` properties control
+whenever the guest is allowed to reset the physical usb device on the
+host.  There are three cases:
+
+``guest-reset=false``
+  The guest is not allowed to reset the (physical) usb device.
+
+``guest-reset=true,guest-resets-all=false``
+  The guest is allowed to reset the device when it is not yet
+  initialized (aka no usb bus address assigned).  Usually this results
+  in one guest reset being allowed.  This is the default behavior.
+
+``guest-reset=true,guest-resets-all=true``
+  The guest is allowed to reset the device as it pleases.
+
+The reason for this existing are broken usb devices.  In theory one
+should be able to reset (and re-initialize) usb devices at any time.
+In practice that may result in shitty usb device firmware crashing and
+the device not responding any more until you power-cycle (aka un-plug
+and re-plug) it.
+
+What works best pretty much depends on the behavior of the specific
+usb device at hand, so it's a trial-and-error game.  If the default
+doesn't work, try another option and see whenever the situation
+improves.
-- 
2.36.1

Re: [PATCH 1/2] usb: document guest-reset and guest-reset-all

[Michal Prívozník]

On 7/11/22 11:44, Gerd Hoffmann wrote:
> Suggested-by: Michal Prívozník <mprivozn@redhat.com>
> Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
> ---
>  docs/system/devices/usb.rst | 29 +++++++++++++++++++++++++++++
>  1 file changed, 29 insertions(+)

Thank you!

Reviewed-by: Michal Privoznik <mprivozn@redhat.com>

Michal

[PATCH 2/2] usb: document pcap (aka usb traffic capture)

[Gerd Hoffmann]

Signed-off-by: Gerd Hoffmann <kraxel@redhat.com>
---
 docs/system/devices/usb.rst | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/docs/system/devices/usb.rst b/docs/system/devices/usb.rst
index 18e7c8b4d716..f39a88f080ff 100644
--- a/docs/system/devices/usb.rst
+++ b/docs/system/devices/usb.rst
@@ -382,3 +382,15 @@ What works best pretty much depends on the behavior of the specific
 usb device at hand, so it's a trial-and-error game.  If the default
 doesn't work, try another option and see whenever the situation
 improves.
+
+record usb transfers
+^^^^^^^^^^^^^^^^^^^^
+
+All usb devices have support for recording the usb traffic.  This can
+be enabled using the ``pcap=<file>`` property, for example:
+
+``-device usb-mouse,pcap=mouse.pcap``
+
+The pcap files are compatible with the linux kernels usbmon.  Many
+tools, including ``wireshark``, can decode and inspect these trace
+files.
-- 
2.36.1