From nobody Mon Feb 9 19:30:46 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 170.10.133.124 as permitted sender) client-ip=170.10.133.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.133.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.133.124]) by mx.zohomail.com with SMTPS id 1632320681942861.6933862965473; Wed, 22 Sep 2021 07:24:41 -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-480-hiZYiuxPPmGRFOgI2Lk8GA-1; Wed, 22 Sep 2021 10:24:39 -0400 Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 9D4691808302; Wed, 22 Sep 2021 14:24:33 +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 5E064189C4; Wed, 22 Sep 2021 14:24:33 +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 2D8724EA30; Wed, 22 Sep 2021 14:24:33 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx03.intmail.prod.int.rdu2.redhat.com [10.11.54.3]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id 18MEOB6G028624 for ; Wed, 22 Sep 2021 10:24:11 -0400 Received: by smtp.corp.redhat.com (Postfix) id 385711011002; Wed, 22 Sep 2021 14:24: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 2FC111011011 for ; Wed, 22 Sep 2021 14:24:03 +0000 (UTC) Received: from us-smtp-1.mimecast.com (us-smtp-1.mimecast.com [207.211.31.81]) (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 37AF61066566 for ; Wed, 22 Sep 2021 14:24:03 +0000 (UTC) Received: from smtp-relay-internal-1.canonical.com (smtp-relay-internal-1.canonical.com [185.125.188.123]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-101-u2XTGWwEM9yH2WGIbdpmZA-1; Wed, 22 Sep 2021 10:24:01 -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-1.canonical.com (Postfix) with ESMTPS id 21EB140260 for ; Wed, 22 Sep 2021 14:24:00 +0000 (UTC) Received: by mail-lf1-f71.google.com with SMTP id x4-20020a056512078400b003fc8e963f1dso2981333lfr.5 for ; Wed, 22 Sep 2021 07:24:00 -0700 (PDT) Received: from ws.. ([5.8.16.162]) by smtp.gmail.com with ESMTPSA id e3sm273868ljo.2.2021.09.22.07.23.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 22 Sep 2021 07:23:59 -0700 (PDT) X-MC-Unique: hiZYiuxPPmGRFOgI2Lk8GA-1 X-MC-Unique: u2XTGWwEM9yH2WGIbdpmZA-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=oax3v1IQ5e/QWkeYDaBEbXWCRvkUPt4mUduMZ+kU510=; b=oC3Rrn1m7KQ1NHe1eEWA31OSftYjlq/BuOpiswH6i+QInptmctQWGwp/2BpVHH3eQY te5k42KAc9Qb+1mg+4usS/HgUaGe1hYMaihqo/okN2G7mddGOJK4QiVDEAu8IEjIbg8n jX8QWilU7BgM1nLz0gBKiTU6TxvNYtGM/FfrpqL1duvbvUHKlwmc4G6534772iCuqp3w as6YhK0avB7U8xt3M0/gi51+H5aS58nEhQyWkjPKiFPKJHuhx6ZG1N2zRX0RRWwrumWt 4IEMaXFReJGPgakCjm/7gvVFLCleqaHDHSI05gQvVaJVi9x5c9qEZZXwgYrACZlbg3zb oUVA== X-Gm-Message-State: AOAM530WgnoAzyW3pHA++0mlV3qJTOaOxJ0dZZwtuXwWOqalhxlO8ZlP 9IrZAABEEtoqt/pEIIVnZrC637O3IrptjKwtNUzJuXqip08k4GjgjSEdENtb5N0hcenzrzKt9Ax ABQeTn/ui17NZtBe5YGCnf/w3qdXuhw8WDA== X-Received: by 2002:a2e:7008:: with SMTP id l8mr10472023ljc.340.1632320639470; Wed, 22 Sep 2021 07:23:59 -0700 (PDT) X-Google-Smtp-Source: ABdhPJwJWBfg/QkT0dVF4/l8Lypr8rwltXq320yrOZk9+oOQp8B27oAdBpRNgjC/pBi8AefocWZA8A== X-Received: by 2002:a2e:7008:: with SMTP id l8mr10472006ljc.340.1632320639259; Wed, 22 Sep 2021 07:23:59 -0700 (PDT) From: Dmitrii Shcherbakov To: dmitrii.shcherbakov@canonical.com, libvir-list@redhat.com Subject: [libvirt PATCH v4 4/4] Add PCI VPD Capability Documentation Date: Wed, 22 Sep 2021 17:23:53 +0300 Message-Id: <20210922142353.957080-5-dmitrii.shcherbakov@canonical.com> In-Reply-To: <20210922142353.957080-1-dmitrii.shcherbakov@canonical.com> References: <20210922142353.957080-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.3 X-MIME-Autoconverted: from quoted-printable to 8bit by lists01.pubmisc.prod.ext.phx2.redhat.com id 18MEOB6G028624 X-loop: libvir-list@redhat.com Cc: pkrempa@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.11 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: 1632320682272100001 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. --- docs/drvnodedev.html.in | 46 +++++++++++++++++++++++++++++++++++++++++ docs/formatnode.html.in | 24 ++++++++++++++++++++- 2 files changed, 69 insertions(+), 1 deletion(-) diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in index 70f7e6717d..438d20f2dd 100644 --- a/docs/drvnodedev.html.in +++ b/docs/drvnodedev.html.in @@ -185,6 +185,52 @@ </capability> </device> =20 +

VPD capability

+

+ A device that exposes a PCI/PCIe VPD capability will include a nested + capability vpd which presents all resources (string, re= ad-only + and read-write keyword resources) that may be contained in a valid V= PD + entry. The XML format follows the binary format described in + "I.3. VPD Definitions" in PCI Local Bus (2.2+) and the identical for= mat + in PCIe 4.0+. At the time of writing, the support for exposing this = capability + is only present on Linux-based systems (kernel version v2.6.26 is th= e first one + to expose VPD via sysfs which Libvirt relies on). Reading the VPD co= ntents 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 a string resource and a VPD-R resource. Among ot= her things, + the VPD of this particular device includes a unique board serial num= ber in the + "SN" field. +

+
+<device>
+  <!-- ... -->
+  <driver>
+    <name>mlx5_core</name>
+  </driver>
+  <capability type=3D'pci'>
+    <!-- ... -->
+    <capability type=3D'vpd'>
+      <resource type=3D'string'>BlueField-2 DPU 25GbE Dual=
-Port SFP56, 16GB on-board DDR, 1GbE OOB management, Tall Bracket</resou=
rce>
+      <resource type=3D'vpd-r'>
+        <field keyword=3D'SN'>MT2113X00000</field>
+        <field keyword=3D'V3'>d644e35a61d0eb11e000e8cef671=
bf3e</field>
+        <field keyword=3D'VA'>MLX:MN=3DMLNX:CSKU=3DV2:UUID=
=3DV3:PCI=3DV0:MODL=3DBF2H332A</field>
+        <field keyword=3D'PN'>MBF2H332A-AEEOT</field>
+        <field keyword=3D'V2'>MBF2H332A-AEEOT</field>
+        <field keyword=3D'EC'>B1</field>
+        <field keyword=3D'V0'>PCIeGen4 x8</field>
+      </resource>
+    </capability>
+  <!-- ... -->
+  </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..3e8c771398 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,21 @@ </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 list of + resource elements with contents applicable to a + particular resource type (string or keyword resources). The + resource element will either contain a string + resource value or a list of field elements in + the case of keyword resources. field elements + contain a keyword attribute corresponding to the + 2-byte VPD keyword and text as element data representing the + field value. +

--=20 2.30.2