From nobody Tue May 5 09:33:50 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) client-ip=8.43.85.245; envelope-from=devel-bounces@lists.libvirt.org; helo=lists.libvirt.org; Authentication-Results: mx.zohomail.com; dkim=fail header.i=maximilian_martin@gmx.de; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=pass(p=reject dis=none) header.from=lists.libvirt.org ARC-Seal: i=1; a=rsa-sha256; t=1745264538; cv=none; d=zohomail.com; s=zohoarc; b=I5FVAOU5iZmAGHPfNm+hwV71WDYqA35Merm87El3PukLrIll/BTaehP62K7jUMDb3UO81avL8WMf6c93s1TFY7d+RnVOBXfDqkm5cEWX0E76c9uYTii1p6ndvpCMhiJUXurzjy6ZabTLp0KQxWl6io+Kzmg0znR+VsmoWKcxsFU= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1745264538; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:Reply-To:Reply-To:References:Subject:Subject:To:To:Message-Id; bh=QOR4o/PDBh2tGXp1SOadH+BLLl+Kp3nPWs5VXq6ed5o=; b=ikrCs3BZyvRQmKJoYTui/OJctSQMqP+GQhoLgDICGRAXPZNSDSEcAACkJSFtoFUQHsD3a00IzVc4JydTORzXE/p5yxX6xIj9ZJsauF+lRfFVqXI1Ctbdvd/CdQKYRZO4CnQJD+kaNTHrBUdN3DPnw8yQyOUaln0vIeuI+xaaVnE= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=fail header.i=maximilian_martin@gmx.de; spf=pass (zohomail.com: domain of lists.libvirt.org designates 8.43.85.245 as permitted sender) smtp.mailfrom=devel-bounces@lists.libvirt.org; dmarc=pass header.from= (p=reject dis=none) Return-Path: Received: from lists.libvirt.org (lists.libvirt.org [8.43.85.245]) by mx.zohomail.com with SMTPS id 174526453790472.28326053426838; Mon, 21 Apr 2025 12:42:17 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id D2482A77; Mon, 21 Apr 2025 15:42:16 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id A225711E2; Mon, 21 Apr 2025 15:39:15 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 475A4CAA; Mon, 21 Apr 2025 15:39:09 -0400 (EDT) Received: from mout.gmx.net (mout.gmx.net [212.227.15.18]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by lists.libvirt.org (Postfix) with ESMTPS id 653DF1182 for ; Mon, 21 Apr 2025 15:38:55 -0400 (EDT) Received: from cu-host.fritz.box ([185.17.205.183]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1MeCtZ-1ued6V2S0d-00qWRJ; Mon, 21 Apr 2025 21:38:48 +0200 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on lists.libvirt.org X-Spam-Level: X-Spam-Status: No, score=-1.5 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, MAILING_LIST_MULTI,RCVD_IN_DNSWL_LOW,RCVD_IN_VALIDITY_RPBL_BLOCKED, RCVD_IN_VALIDITY_SAFE_BLOCKED,SPF_HELO_NONE autolearn=unavailable autolearn_force=no version=3.4.4 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmx.de; s=s31663417; t=1745264328; x=1745869128; i=maximilian_martin@gmx.de; bh=QOR4o/PDBh2tGXp1SOadH+BLLl+Kp3nPWs5VXq6ed5o=; h=X-UI-Sender-Class:From:To:Cc:Subject:Date:Message-Id:In-Reply-To: References:MIME-Version:Content-Transfer-Encoding:cc: content-transfer-encoding:content-type:date:from:message-id: mime-version:reply-to:subject:to; b=MqNVvffeHUagWbKv+N/OvE+SaK6mF1ag2LYlwulYzIT5KLzfWA4cENvYyaxR11U7 SGL1R6nhWcTf7HLNzz72E8PY9A9hIXuw6ua3QZjdrUiuKE2Fum1cKBGN3qeb2IFWm tvy2Eh5lQVqU6qoX38R7axdSL/w8uH+dkmA9XyNUWjSmAxUKSkqHpJ6a9fuJBz6H0 lfOJrg/Cn0IBiU6gRSaipvpvLD0SoHAIDdj/wbQh7XURUO6JK1kWW1myr5tmRMpx4 7QhA6S2pRm8xe01G43SHVYwmqM2Pvh+nT/Clnyc/gU0yLNLgdzXvHPsgbik3AMrLf er6ipQqbqAk7tkxznw== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a To: devel@lists.libvirt.org Subject: [PATCH 4/4] docs: add description for USB port matching Date: Mon, 21 Apr 2025 21:38:38 +0200 Message-Id: <20250421193838.1934-5-maximilian_martin@gmx.de> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20250421193838.1934-1-maximilian_martin@gmx.de> References: <20250421193838.1934-1-maximilian_martin@gmx.de> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:Sb45b9yFc1M/pV+udvugUXccdOhqcWDpx9ZkFKu+KEP3H+SZ0ml AStlwd2tJV0wUGcwV1HRe/3UrDFmlzCkyqNW8Xcoznf6rTNDtHcuVcbXnSG87OOxaDyypmy a8pY9i0EnKzVpzp58lWIkM2mlbTZKeru8cbU9yh6tJGp7KK1XAerduQcRTTroj5KsE7Nuix omEIm7Zd9+SFcZxDSmMYw== UI-OutboundReport: notjunk:1;M01:P0:vuHa6qec2kM=;p2DzfTGpXtGBrd7sQVvodOg2UFx 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 A== Message-ID-Hash: AJMP2QDWQ6LFAZU4S45XIO7JO4KQAZIE X-Message-ID-Hash: AJMP2QDWQ6LFAZU4S45XIO7JO4KQAZIE X-MailFrom: maximilian_martin@gmx.de X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; header-match-config-1; header-match-config-2; header-match-config-3; header-match-devel.lists.libvirt.org-0; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; suspicious-header CC: Maximilian Martin X-Mailman-Version: 3.2.2 Precedence: list List-Id: Development discussions about the libvirt library & tools Archived-At: List-Archive: List-Help: List-Post: List-Subscribe: List-Unsubscribe: From: Maximilian Martin via Devel Reply-To: Maximilian Martin X-ZohoMail-DKIM: fail (Header signature does not verify) X-ZM-MESSAGEID: 1745264540266019100 Content-Type: text/plain; charset="utf-8" From: Maximilian Martin Adds documentation for the new USB bus/port addressing. The new "port" attribute is explained. Signed-off-by: Maximilian Martin --- docs/formatdomain.rst | 29 ++++++++++++++++------------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/docs/formatdomain.rst b/docs/formatdomain.rst index c7c75ae219..3cc0bb0533 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -4784,19 +4784,22 @@ or: tweak the loading process further using the ``bar`` or ``file`` attribu= tes 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 a= t on - the host. The values of these attributes can be given in decimal, hexad= ecimal - (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 devi= ce, - the address type used must conform to the ``model`` attribute of element - ``hostdev``, e.g. any address type other than PCI for ``vfio-pci`` devi= ce API - or any address type other than CCW for ``vfio-ccw`` device API will res= ult in - an error. See the `Device Addresses`_ section for more details on the a= ddress - element. + The ``address`` element for USB devices has a ``bus`` attribute to spec= ify + the USB bus. In addition, either a ``device`` attribute or a ``port`` + attribute is required to identify the device on the host. While the dev= ice + 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 wit= h 0) + form. The port number is a dotted path (examples: ``2``, ``1.2.5``). Fo= r PCI + devices the element carries 4 attributes allowing to designate the devi= ce 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, whic= h are + software-only devices defining an allocation of resources on the physic= al + parent device, the address type used must conform to the ``model`` attr= ibute + 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 A= PI + will result in an error. See the `Device Addresses`_ section for more d= etails + 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 --=20 2.39.5