Skip to content

L
libvirt

openeuler / libvirt

通知 3
Star 0
Fork 0
L
libvirt
提交 88cab64f 编写于 作者: J Jonathon Jongsma 提交者： Erik Skultety
浏览文件
操作

docs: Document full node device xml in formatnode.html.in 

Some of the node device xml schema was documented in drvnodedev.html.in
rather than in formatnode.html.in. Move all of the schema documentation
to formatnode.html.in and provide reference links from the
drvnodedev.html.in page.
Signed-off-by: NJonathon Jongsma <jjongsma@redhat.com>
Reviewed-by: NErik Skultety <eskultet@redhat.com>
上级 e68c290f
隐藏空白更改
内联 并排
Showing with 82 addition and 116 deletion
docs/drvnodedev.html.in
浏览文件 @ 88cab64f
......@@ -28,60 +28,12 @@
</p>
<p>
The generic format of a host device XML can be seen below.
To identify a device both within the host and the device tree hierarchy,
the following elements are used:
Details of the XML format of a host device can be found <a
href="formatnode.html">here</a>. Of particular interest is the
<code>capability</code> element, which describes features supported by
the device. Some specific device types are addressed in more detail
below.
</p>
<dl>
<dt><code>name</code></dt>
<dd>
The device's name will be generated by libvirt using the subsystem,
like pci and the device's sysfs basename.
</dd>
<dt><code>path</code></dt>
<dd>
Fully qualified sysfs path to the device.
</dd>
<dt><code>parent</code></dt>
<dd>
This element identifies the parent node in the device hierarchy. The
value of the element will correspond with the device parent's
<code>name</code> element or <code>computer</code> if the device does
not have any parent.
</dd>
<dt><code>driver</code></dt>
<dd>
This elements reports the driver in use for this device. The presence
of this element in the output XML depends on whether the underlying
device manager (most likely udev) exposes information about the
driver.
</dd>
<dt><code>capability</code></dt>
<dd>
Describes the device in terms of feature support. The element has one
mandatory attribute <code>type</code> the value of which determines
the type of the device. Currently recognized values for the attribute
are:
<code>system</code>,
<code>pci</code>,
<code>usb</code>,
<code>usb_device</code>,
<code>net</code>,
<code>scsi</code>,
<code>scsi_host</code> (<span class="since">Since 0.4.7</span>),
<code>fc_host</code>,
<code>vports</code>,
<code>scsi_target</code> (<span class="since">Since 0.7.3</span>),
<code>storage</code> (<span class="since">Since 1.0.4</span>),
<code>scsi_generic</code> (<span class="since">Since 1.0.7</span>),
<code>drm</code> (<span class="since">Since 3.1.0</span>), and
<code>mdev</code> (<span class="since">Since 3.4.0</span>).
This element can be nested in which case it further specifies a
device's capability. Refer to specific device types to see more values
for the <code>type</code> attribute which are exclusive.
</dd>
</dl>
<h2>Basic structure of a node device</h2>
<pre>
&lt;device&gt;
......@@ -191,45 +143,14 @@
A PCI device capable of creating mediated devices will include a nested
capability <code>mdev_types</code> which enumerates all supported mdev
types on the physical device, along with the type attributes available
through sysfs:
through sysfs. A detailed description of the XML format for the
<code>mdev_types</code> capability can be found
<a href="formatnode.html#MDEVCap">here</a>.
</p>
<dl>
<dt><code>type</code></dt>
<dd>
This element describes a mediated device type which acts as an
abstract template defining a resource allocation for instances of this
device type. The element has one attribute <code>id</code> which holds
an official vendor-supplied identifier for the type.
<span class="since">Since 3.4.0</span>
</dd>
<dt><code>name</code></dt>
<dd>
The <code>name</code> element holds a vendor-supplied code name for
the given mediated device type. This is an optional element.
<span class="since">Since 3.4.0</span>
</dd>
<dt><code>deviceAPI</code></dt>
<dd>
The value of this element describes how an instance of the given type
will be presented to the guest by the VFIO framework.
<span class="since">Since 3.4.0</span>
</dd>
<dt><code>availableInstances</code></dt>
<dd>
This element reports the current state of resource allocation. In other
words, how many instances of the given type can still be successfully
created on the physical device.
<span class="since">Since 3.4.0</span>
</dd>
</dl>
<p>
For a more info about mediated devices, refer to the
<a href="#MDEV">paragraph below</a>.
The following example shows how we might represent an NVIDIA GPU device
that supports mediated devices. See below for <a href="#MDEV">more
information about mediated devices</a>.
</p>
<pre>
......@@ -262,32 +183,11 @@
as multiple separate PCIe devices on the host's PCI bus, mediated devices
only appear on the mdev virtual bus. Therefore, no detach/reattach
procedure from/to the host driver procedure is involved even though
mediated devices are used in a direct device assignment manner.
mediated devices are used in a direct device assignment manner. A
detailed description of the XML format for the <code>mdev</code>
capability can be found <a href="formatnode.html#mdev">here</a>.
</p>
<p>
The following sub-elements and attributes are exposed within the
<code>capability</code> element:
</p>
<dl>
<dt><code>type</code></dt>
<dd>
This element describes a mediated device type which acts as an
abstract template defining a resource allocation for instances of this
device type. The element has one attribute <code>id</code> which holds
an official vendor-supplied identifier for the type.
<span class="since">Since 3.4.0</span>
</dd>
<dt><code>iommuGroup</code></dt>
<dd>
This element supports a single attribute <code>number</code> which holds
the IOMMU group number the mediated device belongs to.
<span class="since">Since 3.4.0</span>
</dd>
</dl>
<h3>Example of a mediated device</h3>
<pre>
&lt;device&gt;
......
docs/formatnode.html.in
浏览文件 @ 88cab64f
......@@ -33,9 +33,23 @@
to provide more specific names, such as
"net_eth1_00_27_13_6a_fe_00".
</dd>
<dt><code>path</code></dt>
<dd>
Fully qualified sysfs path to the device.
</dd>
<dt><code>parent</code></dt>
<dd>If this element is present, it names the parent device (that
is, a controller to which this node belongs).
<dd>
This element identifies the parent node in the device hierarchy. The
value of the element will correspond with the device parent's
<code>name</code> element or <code>computer</code> if the device does
not have any parent.
</dd>
<dt><code>driver</code></dt>
<dd>
This elements reports the driver in use for this device. The presence
of this element in the output XML depends on whether the underlying
device manager (most likely udev) exposes information about the
driver.
</dd>
<dt><code>devnode</code></dt>
<dd>This node appears for each associated <code>/dev</code>
......@@ -138,8 +152,40 @@
means such device cannot be used for PCI passthrough.
<span class="since">Since 1.3.3</span>
</dd>
<dt><code><a id="MDEVCap">mdev_types</a></code></dt>
<dd>
This device is capable of creating mediated devices, and
the capability will contain a list of <code>type</code>
elements, which list all mdev types supported on the
physical device. <span class="since">Since 3.4.0</span>
Each <code>type</code> element has a single <code>id</code>
attribute that holds an official vendor-supplied identifier
for the type. It supports the following sub-elements:
<dl>
<dt><code>name</code></dt>
<dd>
The <code>name</code> element holds a vendor-supplied
code name for the given mediated device type. This is
an optional element.
</dd>
<dt><code>deviceAPI</code></dt>
<dd>
The value of this element describes how an instance of
the given type will be presented to the guest by the
VFIO framework.
</dd>
<dt><code>availableInstances</code></dt>
<dd>
This element reports the current state of resource
allocation. In other words, how many instances of the
given type can still be successfully created on the
physical device.
</dd>
</dl>
</dd>
</dl>
</dd>
<dt><code>numa</code></dt>
<dd>
This optional element contains information on the PCI device
......@@ -329,6 +375,26 @@
<code>render</code>.</dd>
</dl>
</dd>
<dt><a id="mdev"><code>mdev</code></a></dt>
<dd>Describes a mediated device. <span class="since">Since
3.4.0</span> Sub-elements include:
<dl>
<dt><code>type</code></dt>
<dd>
Describes a mediated device type which acts as an abstract
template defining a resource allocation for instances
of this device type. The element has one attribute
<code>id</code> which holds an official vendor-supplied
identifier for the type.
</dd>
<dt><code>iommuGroup</code></dt>
<dd>
This element supports a single attribute <code>number</code>
which holds the IOMMU group number the mediated device belongs
to.
</dd>
</dl>
</dd>
<dt><code>ccw</code></dt>
<dd>Describes a Command Channel Word (CCW) device commonly found on
the S390 architecture. Sub-elements include:
......
Markdown is supported
0% 或 .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑！
想要评论请 注册 或