On Wed, Oct 20, 2021 at 11:30:34AM +0300, Dmitrii Shcherbakov wrote: > Describes the format of the newly added VPD capability and gives and > example for a real-world device. > > Signed-off-by: Dmitrii Shcherbakov <dmitrii.shcherbakov@xxxxxxxxxxxxx> > --- > docs/drvnodedev.html.in | 69 +++++++++++++++++++++++++++++++++++++++++ > docs/formatnode.html.in | 63 ++++++++++++++++++++++++++++++++++++- > 2 files changed, 131 insertions(+), 1 deletion(-) > 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 > <a href="#MDEVTypesCap">mdev_types capability</a>. > - </dd> > + </dd> > + <dt><code><a id="VPDCapPCI">vpd</a></code></dt> > + <dd> > + This device exposes a VPD PCI/PCIe capability. > + The sub-elements are summarized in > + <a href="#VPDCap">vpd capability</a>. > + </dd> > </dl> > </dd> > > @@ -592,5 +598,60 @@ > </device> > </pre> > > + <h3><a id="VPDCap">vpd capability</a></h3> > + > + <p> > + <a href="#VPDCapPCI">PCI</a> devices can expose a VPD capability which > + is optional per PCI Local Bus 2.2+ and PCIe 4.0+ specifications. If > + the VPD capability is present, then the parent <code>capability</code> > + element with the <code>vpd</code> type will contain a <code>name</code> > + element (containing a manufacturer-provided device name) and optionally > + one or two <code>fields</code> elements with an <code>access</code> > + attribute set to <code>readonly</code> or <code>readwrite</code>. > + </p> > + <p> > + The read-only <code>fields</code> element may contain the following elements: > + <dl> > + <dt><code>change_level</code></dt> > + <dd>An engineering change level for this add-in card.</dd> > + <dt><code>manufacture_id</code></dt> > + <dd>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 PCI device.</dd> > + <dt><code>part_number</code></dt> > + <dd>An extension to the Device ID (or Subsystem ID) in the Configuration > + Space header specifying a part number of an add-in card.</dd> > + <dt><code>serial_number</code></dt> > + <dd>A unique add-in card Serial Number.</dd> > + <dt><code>vendor_field</code></dt> > + <dd>Zero or many of those elements with an <code>index</code> attribute > + (since-character upper-case ASCII alphanumeric indexes). Contents will vary > + depending on a vendor.</dd> > + </dl> > + All fields are optional and are not guaranteed to be present for a generic PCI device. > + </p> > + <p> > + The read-write <code>fields</code> element may contain the following elements: > + <dl> > + <dt><code>asset_tag</code></dt> > + <dd>A system asset identifier provided by the system owner.</dd> > + <dt><code>vendor_field</code></dt> > + <dd>Zero or many of those elements with an <code>index</code> attribute > + (since-character upper-case ASCII alphanumeric indexes). Contents will vary depending > + on a vendor.</dd> > + <dt><code>system_field</code></dt> > + <dd>Zero or many of those elements with an <code>index</code> attribute (since-character > + upper-case ASCII alphanumeric indexes, except for letter 'A'). May store system-specific > + data related to a PCI device.</dd> > + </dl> > + All fields are optional and are not guaranteed to be present for a generic 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 means external to Libvirt. > + </p> > + <p> > + The device name and all fields may contain only the following characters: > + <code>[0-9a-zA-F -_,.:;=]</code>. > + The device name may be as large as 65535 bytes while fields are limited with 255 bytes. > + </p> This chunk of text is accidentally after the "Example" heading. Regards, Daniel -- |: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
