Re: [PATCH v2 3/3] doc: add documentation for uio-hv-generic

[Jani Nikula]

On Mon, 17 Oct 2016, Stephen Hemminger <stephen@xxxxxxxxxxxxxxxxxx> wrote:
> From: Stephen Hemminger <sthemmin@xxxxxxxxxxxxx>
>
> Update UIO documentation to include basic information about
> uio_hv_generic.

How about converting to Sphinx/reStructuredText first...? It's not a big
file...

BR,
Jani.



>
> Signed-off-by: Stephen Hemminger <sthemmin@xxxxxxxxxxxxx>
> ---
>  Documentation/DocBook/uio-howto.tmpl | 62 ++++++++++++++++++++++++++++++++++++
>  1 file changed, 62 insertions(+)
>
> diff --git a/Documentation/DocBook/uio-howto.tmpl b/Documentation/DocBook/uio-howto.tmpl
> index cd0e452..5210f8a 100644
> --- a/Documentation/DocBook/uio-howto.tmpl
> +++ b/Documentation/DocBook/uio-howto.tmpl
> @@ -46,6 +46,13 @@ GPL version 2.
>  
>  <revhistory>
>  	<revision>
> +	<revnumber>0.10</revnumber>
> +	<date>2016-10-17</date>
> +	<authorinitials>sch</authorinitials>
> +	<revremark>Added generic hyperv driver
> +		</revremark>
> +	</revision>
> +	<revision>
>  	<revnumber>0.9</revnumber>
>  	<date>2009-07-16</date>
>  	<authorinitials>mst</authorinitials>
> @@ -1033,6 +1040,61 @@ int main()
>  
>  </chapter>
>  
> +<chapter id="uio_hv_generic" xreflabel="Using Generic driver for Hyper-V VMBUS">
> +<?dbhtml filename="uio_hv_generic.html"?>
> +<title>Generic Hyper-V UIO driver</title>
> +	<para>
> +	The generic driver is a kernel module named uio_hv_generic.
> +	It supports devices on the Hyper-V VMBus similar to uio_pci_generic
> +	on PCI bus.
> +	</para>
> +
> +<sect1 id="uio_hv_generic_binding">
> +<title>Making the driver recognize the device</title>
> +	<para>
> +Since the driver does not declare any device GUID's, it will not get loaded
> +automatically and will not automatically bind to any devices, you must load it
> +and allocate id to the driver yourself. For example, to use the network device
> +GUID:
> +	<programlisting>
> + modprobe uio_hv_generic
> + echo &quot;f8615163-df3e-46c5-913f-f2d2f965ed0e&quot; &gt; /sys/bus/vmbus/drivers/uio_hv_generic/new_id
> +	</programlisting>
> +	</para>
> +	<para>
> +If there already is a hardware specific kernel driver for the device, the
> +generic driver still won't bind to it, in this case if you want to use the
> +generic driver (why would you?) you'll have to manually unbind the hardware
> +specific driver and bind the generic driver, like this:
> +	<programlisting>
> +	  echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 &gt; /sys/bus/vmbus/drivers/hv_netvsc/unbind
> +	  echo -n vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3 &gt; /sys/bus/vmbus/drivers/uio_hv_generic/bind
> +	</programlisting>
> +	</para>
> +	<para>
> +You can verify that the device has been bound to the driver
> +by looking for it in sysfs, for example like the following:
> +	<programlisting>
> +    ls -l /sys/bus/vmbus/devices/vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver
> +	</programlisting>
> +Which if successful should print
> +	<programlisting>
> +  .../vmbus-ed963694-e847-4b2a-85af-bc9cfc11d6f3/driver -&gt; ../../../bus/vmbus/drivers/uio_hv_generic
> +	</programlisting>
> +	</para>
> +</sect1>
> +
> +<sect1 id="uio_hv_generic_internals">
> +<title>Things to know about uio_hv_generic</title>
> +	<para>
> +On each interrupt, uio_hv_generic sets the Interrupt Disable bit.
> +This prevents the device from generating further interrupts
> +until the bit is cleared. The userspace driver should clear this
> +bit before blocking and waiting for more interrupts.
> +	</para>
> +</sect1>
> +</chapter>
> +
>  <appendix id="app1">
>  <title>Further information</title>
>  <itemizedlist>

-- 
Jani Nikula, Intel Open Source Technology Center