Re: [PATCH v3 6/6] docs: Document the mediated devices within the nodedev driver

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



On Wed, Apr 26, 2017 at 04:55:33PM +0200, Erik Skultety wrote:
> Signed-off-by: Erik Skultety <eskultet@xxxxxxxxxx>
> ---
>  docs/drvnodedev.html.in | 164 +++++++++++++++++++++++++++++++++++++++++++++++-
>  1 file changed, 163 insertions(+), 1 deletion(-)

s/3.3.0/3.4.0/ for the whole patch.

Please add the "mdev" capability into the list of valid capability
types for virsh nodedev-list command.

> 
> diff --git a/docs/drvnodedev.html.in b/docs/drvnodedev.html.in
> index 0a3870343..8f820cca1 100644
> --- a/docs/drvnodedev.html.in
> +++ b/docs/drvnodedev.html.in
> @@ -9,7 +9,7 @@
>        (historically also referred to as node devices) like USB, PCI, SCSI, and
>        network devices. This also includes various virtualization capabilities
>        which the aforementioned devices provide for utilization, for example
> -      SR-IOV, NPIV, DRM, etc.
> +      SR-IOV, NPIV, MDEV, DRM, etc.
>      </p>
>  
>      <p>
> @@ -75,6 +75,7 @@
>            <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.3.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.
> @@ -185,5 +186,166 @@
>  ...
>  &lt;device&gt;</pre>
>  
> +    <h3><a name="MDEVCap">MDEV capability</a></h3>
> +    <p>
> +      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:
> +    </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.3.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.3.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.3.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.3.0</span>
> +      </dd>
> +    </dl>
> +
> +    <p>
> +      For a more info about mediated devices, refer to the
> +      <a href="#MDEV">paragraph below</a>.
> +    </p>
> +
> +<pre>
> +&lt;device&gt;
> +...
> +  &lt;driver&gt;
> +    &lt;name&gt;nvidia&lt;/name&gt;
> +  &lt;/driver&gt;
> +  &lt;capability type='pci'&gt;
> +...
> +    &lt;capability type='mdev_types'&gt;
> +      &lt;type id='nvidia-11'&gt;
> +        &lt;name&gt;GRID M60-0B&lt;/name&gt;
> +        &lt;deviceAPI&gt;vfio-pci&lt;/deviceAPI&gt;
> +        &lt;availableInstances&gt;16&lt;/availableInstances&gt;
> +      &lt;/type&gt;
> +      &lt;!-- Here would come the rest of the available mdev types --&gt;
> +    &lt;/capability&gt;
> +...
> +  &lt;/capability&gt;
> +&lt;/device&gt;</pre>
> +
> +    <h2><a name="MDEV">Mediated devices (MDEVs)</a></h2>
> +    <p>
> +      Mediated devices (<span class="since">Since 3.3.0</span>) are software
> +      devices defining resource allocation on the backing physical device which
> +      in turn allows the parent physical device's resources to be divided into
> +      several mediated devices, thus sharing the physical device's performance
> +      among multiple guests. Unlike SR-IOV however, where a PCIe device appears
> +      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.<br/>

Replace the <br/> by </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.3.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.3.0</span>
> +      </dd>
> +    </dl>
> +
> +    <h3>Example of a mediated device</h3>
> +    <pre>
> +&lt;device&gt;
> +  &lt;name&gt;mdev_4b20d080_1b54_4048_85b3_a6a62d165c01&lt;/name&gt;
> +  &lt;path&gt;/sys/devices/pci0000:00/0000:00:02.0/4b20d080-1b54-4048-85b3-a6a62d165c01&lt;/path&gt;
> +  &lt;parent&gt;pci_0000_06_00_0&lt;/parent&gt;
> +  &lt;driver&gt;
> +    &lt;name&gt;vfio_mdev&lt;/name&gt;
> +  &lt;/driver&gt;
> +  &lt;capability type='mdev'&gt;
> +    &lt;type id='nvidia-11'/&gt;
> +    &lt;iommuGroup number='12'/&gt;
> +  &lt;capability/&gt;
> +&lt;device/&gt;</pre>
> +
> +    <p>
> +      The support of mediated device's framework in libvirt's node device driver
> +      covers the following features:
> +    </p>
> +
> +    <ul>
> +      <li>
> +        list available mediated devices on the host
> +        (<span class="since">Since 3.3.0</span>)
> +      </li>
> +      <li>
> +        display device details
> +        (<span class="since">Since 3.3.0</span>)
> +      </li>
> +    </ul>
> +
> +    <p>
> +      Because mediated devices are instantiated from vendor specific templates,
> +      simply called 'types', information describing these types is contained
> +      within the parent device's capabilities
> +      (see the example in <a href="#PCI">PCI host devices</a>).<br/><br/>

Replace the <br/> by </p><p>.

> +
> +      To see the supported mediated device types on a specific physical device
> +      use the following:
> +    </p>
> +
> +    <pre>
> +$ ls /sys/class/mdev_bus/&lt;device&gt;/mdev_supported_types</pre>
> +
> +    <p>
> +      To manually instantiate a mediated device, use one of the following as a
> +      reference:
> +    </p>
> +
> +    <pre>
> +$ uuidgen &gt; /sys/class/mdev_bus/&lt;device&gt;/mdev_supported_types/&lt;type&gt;/create
> +...
> +$ echo &lt;UUID&gt; &gt; /sys/class/mdev_bus/&lt;device&gt;/mdev_supported_types/&lt;type&gt;/create</pre>
> +
> +    <p>
> +      Manual removal of a mediated device is then performed as follows:
> +    </p>
> +
> +    <pre>
> +$ echo 1 &gt; /sys/bus/mdev/devices/&lt;uuid&gt;/remove</pre>
> +
>    </body>
>  </html>
> -- 
> 2.12.2
> 
> --
> libvir-list mailing list
> libvir-list@xxxxxxxxxx
> https://www.redhat.com/mailman/listinfo/libvir-list

Attachment: signature.asc
Description: Digital signature

--
libvir-list mailing list
libvir-list@xxxxxxxxxx
https://www.redhat.com/mailman/listinfo/libvir-list

[Index of Archives]     [Virt Tools]     [Libvirt Users]     [Lib OS Info]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Big List of Linux Books]     [Yosemite News]     [KDE Users]     [Fedora Tools]
  Powered by Linux