Re: linux-next: build warning after merge of the vfio tree

[Alex Williamson <alex.williamson@redhat.com>]

On Wed, 12 Apr 2023 14:32:29 +1000
Stephen Rothwell <sfr@canb.auug.org.au> wrote:

> Hi all,
> 
> After merging the vfio tree, today's linux-next build (htmldocs) produced
> this warning:
> 
> Documentation/virt/kvm/devices/vfio.rst:45: WARNING: Literal block expected; none found.
> 
> Introduced by commit
> 
>   25e1b301a946 ("docs: kvm: vfio: Suggest KVM_DEV_VFIO_GROUP_ADD vs VFIO_GROUP_GET_DEVICE_FD ordering")
> 

Thanks, Stephen!

Hi Yi,

Clearly this comes from:

diff --git a/Documentation/virt/kvm/devices/vfio.rst b/Documentation/virt/kvm/devices/vfio.rst
index 2d20dc561069..79b6811bb4f3 100644
--- a/Documentation/virt/kvm/devices/vfio.rst
+++ b/Documentation/virt/kvm/devices/vfio.rst
@@ -39,3 +39,10 @@ KVM_DEV_VFIO_GROUP attributes:
        - @groupfd is a file descriptor for a VFIO group;
        - @tablefd is a file descriptor for a TCE table allocated via
          KVM_CREATE_SPAPR_TCE.
+
+::
+
+The GROUP_ADD operation above should be invoked prior to accessing the
+device file descriptor via VFIO_GROUP_GET_DEVICE_FD in order to support
+drivers which require a kvm pointer to be set in their .open_device()
+callback.

Were you looking for this paragraph to be formatted like an
implementation note in a similar way to a block quote, for example:

https://docs.kernel.org/process/2.Process.html#getting-started-with-kernel-development

We need tabs preceding each line to get that effect.

If there's no objection, I'll just fix the original commit with that
change given how little is currently in my next branch.  Thanks,

Alex