From nobody Mon Sep 8 17:07:21 2025 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=1755528130; cv=none; d=zohomail.com; s=zohoarc; b=dJA1ujvgPdzcS9r2skP6N+Wuhu2f3r67jjLmpTXDwb7Ngf0sY3K5rgc5oMUZQB+Tl1iTdGY2FPoW+nTHUbuzk+v/8K74QM6Ah4XzXos5/s2TtOAmrlgYlDIotqixROXTp9PGicq2AC5fHyfHK1h31+wkfT55GZ3dYJD9T9Klz0c= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1755528130; 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=bZ6myFujSz1kSMQoQJxPkacuQGqaOxo/T27t7fpoMkQ=; b=Es+lZqJw5Uc6ZBiTbHkqm360DhxgVAvVWC6auKePzwhaka29gZvaPWkyaN+SDJ8sKcFl9HuoTCg12ZfH4Qkr9oUhqp2vh4BtbteqAy4efPCCfETKtnPztFq5z16FvdRLyWcsZwyQAiyiLicFzZAnn1pElaENJKh19UpAKOQEpLc= 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 175552813045274.46400643450295; Mon, 18 Aug 2025 07:42:10 -0700 (PDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 7093CAEB; Mon, 18 Aug 2025 10:42:09 -0400 (EDT) Received: from lists.libvirt.org (localhost [IPv6:::1]) by lists.libvirt.org (Postfix) with ESMTP id 8B127D3D; Mon, 18 Aug 2025 10:39:40 -0400 (EDT) Received: by lists.libvirt.org (Postfix, from userid 996) id 5B32AA79; Mon, 18 Aug 2025 10:39:36 -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 730DDA79 for ; Mon, 18 Aug 2025 10:39:30 -0400 (EDT) Received: from cu-host.fritz.box ([185.17.205.244]) by mail.gmx.net (mrgmx004 [212.227.17.190]) with ESMTPSA (Nemesis) id 1Mi2Nv-1uJ3m93uqn-00fKE8; Mon, 18 Aug 2025 16:34:20 +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_MSPIKE_H4, RCVD_IN_MSPIKE_WL,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=1755527969; x=1756132769; i=maximilian_martin@gmx.de; bh=bZ6myFujSz1kSMQoQJxPkacuQGqaOxo/T27t7fpoMkQ=; 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=AGFhD810/egZMaUG08ERX/mF9PI8vcHqTDil8+g4zDe/kDC3MaBECwRTq333g4UV tF5iL0hgqNTkGlhMBtVGvPd+6wd6b0JyNv1Y0o3DZDWnBZlV/tY/tx5beLYf9dhEA xVUoXdSZ6GUseUrJfRjheLZrffHceOi3FgafgzrrlW0kZSCGsWzzrRmKh6pW/WxY6 rsv7y8sl60wHt35iOBe1wrPBFweOxs0olhhJ9tVVnwjKGVtE+EUrZ8j5fide/q/8q y5Had+QtJoKGHLDHN1C/Q+bylWoLCDfIdfLaFjDRVkGpfMJ/iVICsCRvWyniNZLmE /keLYlRRB+Laf1F4Bw== X-UI-Sender-Class: 724b4f7f-cbec-4199-ad4e-598c01a50d3a To: devel@lists.libvirt.org Subject: [PATCH v3 7/7] docs: add description for USB port matching Date: Mon, 18 Aug 2025 16:34:17 +0200 Message-Id: <20250818143417.765-8-maximilian_martin@gmx.de> X-Mailer: git-send-email 2.39.5 In-Reply-To: <20250818143417.765-1-maximilian_martin@gmx.de> References: <20250818143417.765-1-maximilian_martin@gmx.de> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:HQ9yk6mA1nHpBJ6iToVgx40MfCS2SQze/AGKLy8j17cCRziriuz 2iIOuMC6FF++dfYjNPm2Gj8ubZwmi3Iqng4sbdaQOJjwT42tO81BKHNVvtvyKdYBoNGPAJU 8ETBmL1DCbTBLd7NZ1ataGspfqRe98kAZOROYxhugk3Wa9BQHMjxd+SWvtFGESHJOAYJom9 dKXq9zUNFD2KMZZLObSQw== UI-OutboundReport: notjunk:1;M01:P0:BGcaK+ovvhQ=;IE/U1wKlLgVNztSNnNf/hugqfON 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 Message-ID-Hash: K3M6PE2HN7SVEO3QPP2UF6RCFCATQLQ7 X-Message-ID-Hash: K3M6PE2HN7SVEO3QPP2UF6RCFCATQLQ7 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: 1755528133081116600 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. Resolves: https://gitlab.com/libvirt/libvirt/-/issues/513 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 9f7311b6d5..687d00c56b 100644 --- a/docs/formatdomain.rst +++ b/docs/formatdomain.rst @@ -4837,19 +4837,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