Re: [PATCH v2 1/2] docs: refactor mdev_types into new paragraph

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&gt; > --- > 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="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> > + This device is capable of creating mediated devices. > + The sub-elements are summarized in > + <a href="#MDevTypesCap">mdev_types capability</a>. > + </dd> > </dl> > </dd> > > @@ -445,6 +420,43 @@ > </dd> > </dl> > > + <h3><a id="MDevTypesCap">mdev_types capability</a></h3> > + > + <p> > + <a href="#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&gt;

> + This 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> > + </p> > + > + > <h2><a id="nodeExample">Examples</a></h2> > > <p>The following are some example node device XML outputs:</p> > -- > 2.26.2 >