From eskultet at redhat.com Wed Nov 11 04:35:00 2020
Content-Type: multipart/mixed; boundary="===============7425452514121282204=="
MIME-Version: 1.0
From: Erik Skultety <eskultet at redhat.com>
To: devel at lists.libvirt.org
Subject: Re: [PATCH v2 1/2] docs: refactor mdev_types into new paragraph
Date: Wed, 11 Nov 2020 10:34:51 +0100
Message-ID: <20201111093451.GA857537@nautilus>
In-Reply-To: 20201110180906.38759-2-fiuczy@linux.ibm.com

--===============7425452514121282204==
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: quoted-printable

On Tue, Nov 10, 2020 at 07:09:05PM +0100, Boris Fiuczynski wrote:
> To prevent copying the mdev_types description multiple times
> it is refactored into a new paragraph for easy reuse.
> =

> Signed-off-by: Boris Fiuczynski <fiuczy(a)linux.ibm.com>
> ---
>  docs/formatnode.html.in | 70 ++++++++++++++++++++++++-----------------
>  1 file changed, 41 insertions(+), 29 deletions(-)
> =

> diff --git a/docs/formatnode.html.in b/docs/formatnode.html.in
> index 6928bdd69c..bd3112c5a8 100644
> --- a/docs/formatnode.html.in
> +++ b/docs/formatnode.html.in
> @@ -159,35 +159,10 @@
>                    </dd>
>                    <dt><code><a id=3D"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</co=
de>
> -                    elements, which list all mdev types supported on the
> -                    physical device. <span class=3D"since">Since 3.4.0</=
span>
> -                    Each <code>type</code> element has a single <code>id=
</code>
> -                    attribute that holds an official vendor-supplied ide=
ntifier
> -                    for the type. It supports the following sub-elements:
> -                      <dl>
> -                        <dt><code>name</code></dt>
> -                        <dd>
> -                          The <code>name</code> element holds a vendor-s=
upplied
> -                          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 insta=
nce 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 resour=
ce
> -                        allocation. In other words, how many instances o=
f the
> -                        given type can still be successfully created on =
the
> -                        physical device.
> -                    </dd>
> -                  </dl>
> -                </dd>
> +                    This device is capable of creating mediated devices.
> +                    The sub-elements are summarized in
> +                    <a href=3D"#MDevTypesCap">mdev_types capability</a>.
> +                 </dd>
>                  </dl>
>                </dd>
>  =

> @@ -445,6 +420,43 @@
>        </dd>
>      </dl>
>  =

> +    <h3><a id=3D"MDevTypesCap">mdev_types capability</a></h3>
> +
> +    <p>
> +      <a href=3D"#MDEVCap">PCI</a> devices can be capable of
> +      creating mediated devices.
> +      If they are capable the attribute <code>type</code> of the
> +      element <code>capability</code> is <code>mdev_types</code>.

I'd slightly adjust the wording because the first I read it I got confused,
not just the rewrite, also by the original (probably mine) text.
How about:

"If the indeed are capable, then the parent <code>capability</code> element
for <code>mdev_types</code> type will contain a list of ...."

Reviewed-by: Erik Skultety <eskultet(a)redhat.com>

> +      This capability will contain a list of <code>type</code>
> +      elements, which list all mdev types supported on the
> +      physical device. <span class=3D"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>
> +    </p>
> +
> +
>      <h2><a id=3D"nodeExample">Examples</a></h2>
>  =

>      <p>The following are some example node device XML outputs:</p>
> -- =

> 2.26.2
> =



--===============7425452514121282204==--