docs: add description for USB port matching

Adds documentation for the new USB bus/port addressing.
The new "port" attribute is explained.
Resolves: https://gitlab.com/libvirt/libvirt/-/issues/513

Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Maximilian Martin <maximilian_martin@gmx.de>

diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst
index 87644ad42ae39bdfc731c19e6dcc64454d6a6169..f9f8719f1cb110f0781dd3ea8af3a6015f999700 100644 (file)
--- a/docs/formatdomain.rst
+++ b/docs/formatdomain.rst
@@ -4885,19 +4885,22 @@ or:
    tweak the loading process further using the ``bar`` or ``file`` attributes
    will be rejected. :since:`Since 4.3.0 (QEMU and KVM only)`.
 ``address``
-   The ``address`` element for USB devices has a ``bus`` and ``device``
-   attribute to specify the USB bus and device number the device appears at on
-   the host. The values of these attributes can be given in decimal, hexadecimal
-   (starting with 0x) or octal (starting with 0) form. For PCI devices the
-   element carries 4 attributes allowing to designate the device as can be found
-   with the ``lspci`` or with ``virsh nodedev-list``. For SCSI devices a 'drive'
-   address type must be used. For mediated devices, which are software-only
-   devices defining an allocation of resources on the physical parent device,
-   the address type used must conform to the ``model`` attribute of element
-   ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` device API
-   or any address type other than CCW for ``vfio-ccw`` device API will result in
-   an error. See the `Device Addresses`_ section for more details on the address
-   element.
+   The ``address`` element for USB devices has a ``bus`` attribute to specify
+   the USB bus. In addition, either a ``device`` attribute or a ``port``
+   attribute is required to identify the device on the host. While the device
+   number is assigned upon connection of the device, the port number is a
+   stable identifier of the physical host port. Bus and device number can be
+   given in decimal, hexadecimal (starting with 0x) or octal (starting with 0)
+   form. The port number is a dotted path (examples: ``2``, ``1.2.5``). For PCI
+   devices the element carries 4 attributes allowing to designate the device as
+   can be found with the ``lspci`` or with ``virsh nodedev-list``. For SCSI
+   devices a 'drive' address type must be used. For mediated devices, which are
+   software-only devices defining an allocation of resources on the physical
+   parent device, the address type used must conform to the ``model`` attribute
+   of element ``hostdev``, e.g. any address type other than PCI for ``vfio-pci``
+   device API or any address type other than CCW for ``vfio-ccw`` device API
+   will result in an error. See the `Device Addresses`_ section for more details
+   on the address element.
 ``driver``
    PCI hostdev devices can have an optional ``driver`` subelement that
    specifies which host driver to bind to the device when preparing it