From nobody Tue Feb 10 12:39:42 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.com: domain of redhat.com designates 216.205.24.124 as permitted sender) client-ip=216.205.24.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 216.205.24.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 [216.205.24.124]) by mx.zohomail.com with SMTPS id 1632771096370760.7646025547318; Mon, 27 Sep 2021 12:31:36 -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-299-HTpmku5HOlqMggukKJtIGQ-1; Mon, 27 Sep 2021 15:31:33 -0400 Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id 55CC3802ECF; Mon, 27 Sep 2021 19:31:28 +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 2AED35FCB5; Mon, 27 Sep 2021 19:31:28 +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 E49154EA37; Mon, 27 Sep 2021 19:31:27 +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 18RJVAsK014454 for ; Mon, 27 Sep 2021 15:31:10 -0400 Received: by smtp.corp.redhat.com (Postfix) id E2BBF202F317; Mon, 27 Sep 2021 19:31:09 +0000 (UTC) Received: from mimecast-mx02.redhat.com (mimecast05.extmail.prod.ext.rdu2.redhat.com [10.11.55.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id D5BBB202F32E for ; Mon, 27 Sep 2021 19:31:02 +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 2339780B91C for ; Mon, 27 Sep 2021 19:31:02 +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-279-jZCCN9jJOnKnrM4OQQAa1Q-1; Mon, 27 Sep 2021 15:31:00 -0400 Received: from mail-lf1-f69.google.com (mail-lf1-f69.google.com [209.85.167.69]) (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 8E8BE40816 for ; Mon, 27 Sep 2021 19:30:58 +0000 (UTC) Received: by mail-lf1-f69.google.com with SMTP id i40-20020a0565123e2800b003f53da59009so16812760lfv.16 for ; Mon, 27 Sep 2021 12:30:58 -0700 (PDT) Received: from ws.lan.d-node.is ([95.165.29.203]) by smtp.gmail.com with ESMTPSA id a8sm1688090lfr.256.2021.09.27.12.30.57 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 27 Sep 2021 12:30:57 -0700 (PDT) X-MC-Unique: HTpmku5HOlqMggukKJtIGQ-1 X-MC-Unique: jZCCN9jJOnKnrM4OQQAa1Q-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:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=q7jXkr2Lxl6EgX0xgbzn4xtMOGD4tWM3fsfROxdvRL0=; b=vObcE+cEuX9Gx18hEAhC+h6sraSGgAxGR8uEB37gybqiX0n2jcPDNtsUm+GNhUylX9 gVBZyUM78ZWHzF4ZIdeqg1V2DNkl1vQJkFL2KJGifa+Ce8Men41GBDaHRTu/IeFumB9i nPp3ilgS4GSMBMmTSK+wTq5lMbRvgjkP5w0lmnwNQFUOYyjSMzv3x7uO7nk1VBdfGGZH IRgHfLiZBVyKaPhMxjTK6/yyN+UPfABdUDenuxaeqeeE50/+fyeQia6pKpbtpZfPpLmn 8+jAjUN30s+UBEGVVRmwXevV98BBXMiQXa2yMW5j/XyhRTOjigKmYYGq7PFXP1EgkCQm y4rA== X-Gm-Message-State: AOAM531BqBM4NRNi+0gy7pzj5ymvTadqsPnXoOXdq+7sukQjwvOc5Njf ICMyRmdgbi0wmDED6ed4XznRnLe0BV3YHXaib/PIQxUJskYXuunYJGBwASnm9HKz9pbYV2XsIrj AiUm7WjQuSviYJ6NzRSmiNlnGnBDb063Igw== X-Received: by 2002:a2e:2201:: with SMTP id i1mr1483335lji.483.1632771057988; Mon, 27 Sep 2021 12:30:57 -0700 (PDT) X-Google-Smtp-Source: ABdhPJzWKapp2WeI5zZnMHMTg6oT5cZHo9V9b7WCTXpP12V+QJ6JUFAykprK0TIFvgABwld4mGu5kw== X-Received: by 2002:a2e:2201:: with SMTP id i1mr1483315lji.483.1632771057759; Mon, 27 Sep 2021 12:30:57 -0700 (PDT) From: Dmitrii Shcherbakov To: libvir-list@redhat.com, dmitrii.shcherbakov@canonical.com Subject: [libvirt PATCH v5 7/7] Add PCI VPD Capability Documentation Date: Mon, 27 Sep 2021 22:30:53 +0300 Message-Id: <20210927193053.109029-8-dmitrii.shcherbakov@canonical.com> In-Reply-To: <20210927193053.109029-1-dmitrii.shcherbakov@canonical.com> References: <20210927193053.109029-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 18RJVAsK014454 X-loop: libvir-list@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.12 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: 1632771097512100001 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 | 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