[libvirt] [PATCH v4 14/14] docs: Document the new hostdev and address type 'mdev'

[Laine Stump]

On 03/22/2017 11:27 AM, Erik Skultety wrote:
> Signed-off-by: Erik Skultety <eskultet at redhat.com>
> ---
>  docs/formatdomain.html.in | 46 ++++++++++++++++++++++++++++++++++++++++------
>  1 file changed, 40 insertions(+), 6 deletions(-)

I always like to put the docs changes in the same patch that modifies
the schema and XML parsing functions, but that's not a hard rule, so I'm
fine with this.

> 
> diff --git a/docs/formatdomain.html.in b/docs/formatdomain.html.in
> index 4a3123e989..1eb6c44b6f 100644
> --- a/docs/formatdomain.html.in
> +++ b/docs/formatdomain.html.in
> @@ -3886,6 +3886,19 @@
>    </devices>
>    ...</pre>
>  
> +    <p>or:</p>
> +
> +<pre>
> +  ...
> +  <devices>
> +    <hostdev mode='subsystem' type='mdev' model='vfio-pci'>
> +    <source>
> +      <address uuid='c2177883-f1bb-47f0-914d-32a22e3a8804'>
> +    </source>
> +    </hostdev>
> +  </devices>
> +  ...</pre>
> +
>      <dl>
>        <dt><code>hostdev</code></dt>
>        <dd>The <code>hostdev</code> element is the main container for describing
> @@ -3930,12 +3943,22 @@
>              <code>type</code> passes all LUNs presented by a single HBA to
>              the guest.
>            </dd>
> +          <dt><code>mdev</code></dt>
> +          <dd>For mediated devices (<span class="since">Since 3.2.0</span>)
> +          the <code>model</code> attribute specifies the device API which
> +          determines how the host's vfio driver will expose the device to the
> +          guest. Currently, only <code>vfio-pci</code> model is supported.


either "only the vfio-pci model is supported" or "only model='vfio-pci'
is supported".


> +          There are also some implications on the usage of guest's address type
> +          depending on the <code>model</code> attribute, see the
> +          <code>address</code> element below.</dd>

I'm not really comfortable with this - it means that the code that
parses <address> has to have information from a higher level rather than
being self contained. Remind me why you decided to remove "type='mdev'"
(or whatever it was) from the <address> syntax?


>          </dl>
>          <p>
> -          Note: The <code>managed</code> attribute is only used with PCI devices

s/PCI/type='pci'/

> -          and is ignored by all the other device types, thus setting
> -          <code>managed</code> explicitly with other than PCI device has the same
> -          effect as omitting it.
> +          Note: The <code>managed</code> attribute is only used with PCI and is
> +          ignored by all the other device types, thus setting
> +          <code>managed</code> explicitly with other than a PCI device has the
> +          same effect as omitting it. Similarly, <code>model</code> attribute is
> +          only supported by mediated devices and ignored by all other device
> +          types.

Do we want to ignore it, or log an error if someone specifies it when
they shouldn't? Doing the latter would prevent someone from thinking
they've done "A" when actually they've done "B".


>          </p>
>        </dd>
>        <dt><code>source</code></dt>
> @@ -4000,6 +4023,12 @@
>              is the vhost_scsi wwpn (16 hexadecimal digits with a prefix of
>              "naa.") established in the host configfs.
>            </dd>
> +          <dt><code>mdev</code></dt>
> +          <dd>Mediated devices (<span class="since">Since 3.2.0</span>) are
> +            described by the <code>address</code> element. The
> +            <code>address</code> element contains so far a single mandatory


s/so far//


> +            attribute <code>uuid</code>.
> +          </dd>
>          </dl>
>        </dd>
>        <dt><code>vendor</code>, <code>product</code></dt>
> @@ -4043,8 +4072,13 @@
>        For PCI devices the element carries 4 attributes allowing to designate
>        the device as can be found with the <code>lspci</code> or
>        with <code>virsh nodedev-list</code>. For SCSI devices a 'drive'
> -      address type must be used. <a href="#elementsAddress">See above</a> for
> -      more details on the address element.</dd>
> +      address type must be used. For mediated devices, which are only software

s/only software/software-only/

> +      devices defining an allocation of resources on the physical parent device,
> +      the address type used must conform to the <code>model</code> attribute
> +      of element <code>hostdev</code>, e.g. any address type other than PCI for
> +      <code>vfio-pci</code> device API will result in an error.
> +      <a href="#elementsAddress">See above</a> for more details on the address
> +      element.</dd>
>        <dt><code>driver</code></dt>
>        <dd>
>          PCI devices can have an optional <code>driver</code>
> 

I'm still unsure about having no type specifier in <address>. I know
that's already the case for PCI addresses in <source>, but I actually
think that was an incorrect decision - it's cleaner if we can
parse/format <address> without reaching up into higher levels. Maybe I
can be convinced though :-)

In the meantime, I think it would be better to get this all in and get
some solid testing outside of the few people directly involved, so ACK
to this patch too (which makes the entire series ACKed (with a few small
changes requested), and we can have one last debate about <address>
during the next couple days.