From nobody Wed Feb 11 03:26:04 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) client-ip=170.10.129.124; envelope-from=libvir-list-bounces@redhat.com; helo=us-smtp-delivery-124.mimecast.com; Authentication-Results: mx.zohomail.com; spf=pass (zohomail.com: domain of redhat.com designates 170.10.129.124 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com; dmarc=fail(p=none dis=none) header.from=canonical.com Return-Path: Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by mx.zohomail.com with SMTPS id 1633961170466570.6945689789812; Mon, 11 Oct 2021 07:06:10 -0700 (PDT) Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-27-qP42KtwvPomFc45CmmVsDA-1; Mon, 11 Oct 2021 10:06:05 -0400 Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.phx2.redhat.com [10.5.11.13]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 5EB241019627; Mon, 11 Oct 2021 14:05:20 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D01DD60871; Mon, 11 Oct 2021 14:05:18 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id C4CCE4E58F; Mon, 11 Oct 2021 14:05:15 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx04.intmail.prod.int.rdu2.redhat.com [10.11.54.4]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 19BE5Bu6030331 for ; Mon, 11 Oct 2021 10:05:11 -0400 Received: by smtp.corp.redhat.com (Postfix) id 6DBE32026D46; Mon, 11 Oct 2021 14:05:11 +0000 (UTC) Received: from mimecast-mx02.redhat.com (mimecast04.extmail.prod.ext.rdu2.redhat.com [10.11.55.20]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 67B782026D67 for ; Mon, 11 Oct 2021 14:05:08 +0000 (UTC) Received: from us-smtp-1.mimecast.com (us-smtp-delivery-1.mimecast.com [205.139.110.120]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mimecast-mx02.redhat.com (Postfix) with ESMTPS id 4C9DD10AF953 for ; Mon, 11 Oct 2021 14:05:08 +0000 (UTC) Received: from smtp-relay-internal-0.canonical.com (smtp-relay-internal-0.canonical.com [185.125.188.122]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-276-aUki6p7KM-28GPsjtzHzbA-1; Mon, 11 Oct 2021 10:05:05 -0400 Received: from mail-lf1-f71.google.com (mail-lf1-f71.google.com [209.85.167.71]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by smtp-relay-internal-0.canonical.com (Postfix) with ESMTPS id DBFF24001A for ; Mon, 11 Oct 2021 14:05:03 +0000 (UTC) Received: by mail-lf1-f71.google.com with SMTP id i6-20020a056512318600b003fd8c8c2677so2617038lfe.1 for ; Mon, 11 Oct 2021 07:05:03 -0700 (PDT) Received: from ws.lan.d-node.is ([95.165.29.203]) by smtp.gmail.com with ESMTPSA id o12sm741144lft.254.2021.10.11.07.05.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 11 Oct 2021 07:05:02 -0700 (PDT) X-MC-Unique: qP42KtwvPomFc45CmmVsDA-1 X-MC-Unique: aUki6p7KM-28GPsjtzHzbA-1 X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=h3q00/snmdSwiLfIh20jzFRfEuKTqtcMhFldueLHKgA=; b=swJUA1bop3EpuhmNtc2+uPrfYZ2+na6NTjE3nQAz6qqF2n0KxSrXIFIun8E7YSm5Kq 7bt/phZDRJrxCEYwPOuIUyuYvKvkx8HkWdZkdb+szbTHdUqH/rzXkGsuCDYcXQEzbM7u OIrxci0B6Uj7nxmB+17w7pTKU0lLlqhviZHCVKVb+ZNHd8wYOOo9nrmm44Qivuvby52e kxkhZbSmnh2oex51/9n8rvZmWQxirBmsByQvWRqJRebitFL3YmxeHXtAvmztwbtYExG4 qz+eGb03WeEzzj11xO3fOq5ifuxn1Jgz0Qm8FJfygE5gXdoZLjEZr1zy+OpWJZoEU5e8 1yCA== X-Gm-Message-State: AOAM533/gnXvg5V49Sk/ju5LoM2ln3x7JrpgfzmiPwAi5QUAwoo2HkFc dvN8dA0ZIkh+KfXOpb1t3MxNccqCfWXRyvu7/Ft4vTo2bpsIMzPK8oJWL/29eSyHIShgaLm0jMu 1UjoknfZjur82LAL7unkg1T9L2P2sIyoytw== X-Received: by 2002:ac2:5fee:: with SMTP id s14mr26897638lfg.537.1633961103272; Mon, 11 Oct 2021 07:05:03 -0700 (PDT) X-Google-Smtp-Source: ABdhPJyDaiQa9e1wGpq7a/hoQ/3oIDHtov5XzOQiTbDRBzF7SFYdBkqroUOEH7gGxf+4ASxqsIHUWQ== X-Received: by 2002:ac2:5fee:: with SMTP id s14mr26897580lfg.537.1633961102686; Mon, 11 Oct 2021 07:05:02 -0700 (PDT) From: Dmitrii Shcherbakov To: dmitrii.shcherbakov@canonical.com, libvir-list@redhat.com Subject: [libvirt PATCH v6 4/5] Add PCI VPD Capability Documentation Date: Mon, 11 Oct 2021 17:04:45 +0300 Message-Id: <20211011140446.220390-5-dmitrii.shcherbakov@canonical.com> In-Reply-To: <20211011140446.220390-1-dmitrii.shcherbakov@canonical.com> References: <20211011140446.220390-1-dmitrii.shcherbakov@canonical.com> MIME-Version: 1.0 X-Mimecast-Impersonation-Protect: Policy=CLT - Impersonation Protection Definition; Similar Internal Domain=false; Similar Monitored External Domain=false; Custom External Domain=false; Mimecast External Domain=false; Newly Observed Domain=false; Internal User Name=false; Custom Display Name List=false; Reply-to Address Mismatch=false; Targeted Threat Dictionary=false; Mimecast Threat Dictionary=false; Custom Threat Dictionary=false X-Scanned-By: MIMEDefang 2.78 on 10.11.54.4 X-MIME-Autoconverted: from quoted-printable to 8bit by lists01.pubmisc.prod.ext.phx2.redhat.com id 19BE5Bu6030331 X-loop: libvir-list@redhat.com Cc: laine@redhat.com X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.13 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=libvir-list-bounces@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable X-ZM-MESSAGEID: 1633961235956100001 Content-Type: text/plain; charset="utf-8" Describes the format of the newly added VPD capability and gives and example for a real-world device. Signed-off-by: Dmitrii Shcherbakov --- docs/drvnodedev.html.in | 69 +++++++++++++++++++++++++++++++++++++++++ docs/formatnode.html.in | 63 ++++++++++++++++++++++++++++++++++++- 2 files changed, 131 insertions(+), 1 deletion(-) diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index 70f7e6717d..ee75eeb25c 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -185,6 +185,75 @@ </capability> </device> =20 +

VPD capability

+

+ A device that exposes a PCI/PCIe VPD capability will include a nested + capability vpd which presents data stored in the Vital = Product + Data (VPD). VPD provides a device name and a number of other standar= d-defined + read-only fields (change level, manufacture id, part number, serial = number) and + vendor-specific read-only fields. Additionally, if a device supports= it, + read-write fields (asset tag, vendor-specific fields or system field= s) may + also be present. The VPD capability is optional for PCI/PCIe devices= and the + set of exposed fields may vary depending on a device. The XML format= follows + the binary format described in "I.3. VPD Definitions" in PCI Local B= us (2.2+) + and the identical format in PCIe 4.0+. At the time of writing, the s= upport for + exposing this capability is only present on Linux-based systems (ker= nel version + v2.6.26 is the first one to expose VPD via sysfs which Libvirt relie= s on). + Reading the VPD contents requires root privileges, therefore, + virsh nodedev-dumpxml must be executed accordingly. + A description of the XML format for the vpd capability = can + be found here. +

+

+ The following example shows a VPD representation for a device that e= xposes the + VPD capability with read-only and read-write fields. Among other thi= ngs, + the VPD of this particular device includes a unique board serial num= ber. +

+
+<device>
+  <name>pci_0000_42_00_0</name>
+  <capability type=3D'pci'>
+    <class>0x020000</class>
+    <domain>0</domain>
+    <bus>66</bus>
+    <slot>0</slot>
+    <function>0</function>
+    <product id=3D'0xa2d6'>MT42822 BlueField-2 integrated =
ConnectX-6 Dx network controller</product>
+    <vendor id=3D'0x15b3'>Mellanox Technologies</vendor=
>
+    <capability type=3D'virt_functions' maxCount=3D'16&a=
pos;/>
+    <capability type=3D'vpd'>
+      <name>BlueField-2 DPU 25GbE Dual-Port SFP56, Crypto Enabled, 1=
6GB on-board DDR, 1GbE OOB management, Tall Bracket</name>
+      <fields access=3D'readonly'>
+        <change_level>B1</change_level>
+        <manufacture_id>foobar</manufacture_id>
+        <part_number>MBF2H332A-AEEOT</part_number>
+        <serial_number>MT2113X00000</serial_number>
+        <vendor_field index=3D'0'>PCIeGen4 x8</vendor_f=
ield>
+        <vendor_field index=3D'2'>MBF2H332A-AEEOT</vend=
or_field>
+        <vendor_field index=3D'3'>3c53d07eec484d8aab34dabd=
24fe575aa</vendor_field>
+        <vendor_field index=3D'A'>MLX:MN=3DMLNX:CSKU=3DV2:=
UUID=3DV3:PCI=3DV0:MODL=3DBF2H332A</vendor_field>
+      </fields>
+      <fields access=3D'readwrite'>
+        <asset_tag>fooasset</asset_tag>
+        <vendor_field index=3D'0'>vendorfield0</vendor_=
field>
+        <vendor_field index=3D'2'>vendorfield2</vendor_=
field>
+        <vendor_field index=3D'A'>vendorfieldA</vendor_=
field>
+        <system_field index=3D'B'>systemfieldB</system_=
field>
+        <system_field index=3D'0'>systemfield0</system_=
field>
+      </fields>
+    </capability>
+    <iommuGroup number=3D'65'>
+      <address domain=3D'0x0000' bus=3D'0x42' slot=
=3D'0x00' function=3D'0x0'/>
+    </iommuGroup>
+    <numa node=3D'0'/>
+    <pci-express>
+      <link validity=3D'cap' port=3D'0' speed=3D&ap=
os;16' width=3D'8'/>
+      <link validity=3D'sta' speed=3D'8' width=3D&a=
pos;8'/>
+    </pci-express>
+  </capability>
+</device>
+
+

Mediated devices (MDEVs)

Mediated devices (Since 3.2.0) are soft= ware diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in index 3b3c3105d4..fb2f356396 100644 --- a/docs/formatnode.html.in +++ b/docs/formatnode.html.in @@ -162,7 +162,13 @@ This device is capable of creating mediated devices. The sub-elements are summarized in mdev_types capability. - + +

vpd
+
+ This device exposes a VPD PCI/PCIe capability. + The sub-elements are summarized in + vpd capability. +
=20 @@ -592,5 +598,60 @@ </device> =20 +

vpd capability

+ +

+ PCI devices can expose a VPD capability w= hich + is optional per PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If + the VPD capability is present, then the parent capability + element with the vpd type will contain a name + element (containing a manufacturer-provided device name) and optiona= lly + one or two fields elements with an access + attribute set to readonly or readwrite. +

+

+ The read-only fields element may contain the following = elements: +

+
change_level
+
An engineering change level for this add-in card.
+
manufacture_id
+
An extension to the Vendor ID (or Subsystem Vendor ID) in the + Configuration Space header which allows vendors the flexibility = to identify + an additional level of detail pertaining to the sourcing of a PC= I device.
+
part_number
+
An extension to the Device ID (or Subsystem ID) in the Configu= ration + Space header specifying a part number of an add-in card.
+
serial_number
+
A unique add-in card Serial Number.
+
vendor_field
+
Zero or many of those elements with an index attr= ibute + (since-character upper-case ASCII alphanumeric indexes). Content= s will vary + depending on a vendor.
+
+ All fields are optional and are not guaranteed to be present for a g= eneric PCI device. +

+

+ The read-write fields element may contain the following= elements: +

+
asset_tag
+
A system asset identifier provided by the system owner.
+
vendor_field
+
Zero or many of those elements with an index attr= ibute + (since-character upper-case ASCII alphanumeric indexes). Content= s will vary depending + on a vendor.
+
system_field
+
Zero or many of those elements with an index attr= ibute (since-character + upper-case ASCII alphanumeric indexes, except for letter 'A'). M= ay store system-specific + data related to a PCI device.
+
+ All fields are optional and are not guaranteed to be present for a g= eneric PCI device. + Read-write fields are not possible to alter via Libvirt at the time = of writing but their + content is refreshed on each invocation in case this is done by mean= s external to Libvirt. +

+

+ The device name and all fields may contain only the following charac= ters: + [0-9a-zA-F -_,.:;=3D]. + The device name may be as large as 65535 bytes while fields are limi= ted with 255 bytes. +

--=20 2.30.2