Re: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic

[Bruce Richardson <bruce.richardson@intel.com>]

On Wed, Feb 25, 2015 at 01:12:43PM +0000, Iremonger, Bernard wrote:
> 
> 
> > -----Original Message-----
> > From: Richardson, Bruce
> > Sent: Wednesday, February 25, 2015 12:28 PM
> > To: Iremonger, Bernard
> > Cc: dev@dpdk.org
> > Subject: Re: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for uio_pci_generic
> > 
> > On Wed, Feb 25, 2015 at 12:19:10PM +0000, Iremonger, Bernard wrote:
> > >
> > >
> > > > -----Original Message-----
> > > > From: dev [mailto:dev-bounces@dpdk.org] On Behalf Of Bruce
> > > > Richardson
> > > > Sent: Tuesday, February 24, 2015 4:28 PM
> > > > To: dev@dpdk.org
> > > > Subject: [dpdk-dev] [PATCH 2/2] doc: update programmers guide for
> > > > uio_pci_generic
> > > >
> > > > Since DPDK now has support for the in-tree uio_pci_generic driver,
> > > > update the programmers guide document to reference this module, and
> > > > to use it in preference to the igb_uio driver, which is DPDK- specific.
> > > >
> > > > Signed-off-by: Bruce Richardson <bruce.richardson@intel.com>
> > > > ---
> > > >  doc/guides/prog_guide/env_abstraction_layer.rst                  | 8 ++++----
> > > >  doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst | 6 +++---
> > > >  doc/guides/prog_guide/kernel_nic_interface.rst                   | 2 +-
> > > >  doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst      | 8 ++++----
> > > >  doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst  |
> > > > 2 +-
> > > >  5 files changed, 13 insertions(+), 13 deletions(-)
> > > >
> > > > diff --git a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > index 231e266..b5321c3 100644
> > > > --- a/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > +++ b/doc/guides/prog_guide/env_abstraction_layer.rst
> > > > @@ -66,7 +66,7 @@ EAL in a Linux-userland Execution Environment
> > > >  ---------------------------------------------
> > > >
> > > >  In a Linux user space environment, the DPDK application runs as a
> > > > user-space application using the pthread library.
> > > > -PCI information about devices and address space is discovered
> > > > through the /sys kernel interface and through a module called igb_uio.
> > > > +PCI information about devices and address space is discovered
> > > > +through the /sys kernel interface and
> > > > through kernel modules such as uio_pci_generic, or igb_uio.
> > > >  Refer to the UIO: User-space drivers documentation in the Linux
> > > > kernel. This memory is mmap'd in the application.
> > > >
> > > >  The EAL performs physical memory allocation using mmap() in
> > > > hugetlbfs (using huge page sizes to increase performance).
> > > > @@ -134,10 +134,10 @@ PCI Access
> > > >  ~~~~~~~~~~
> > > >
> > > >  The EAL uses the /sys/bus/pci utilities provided by the kernel to scan the content on the PCI bus.
> > > > -
> > > > -To access PCI memory, a kernel module called igb_uio provides a
> > > > /dev/uioX device file
> > > > +To access PCI memory, a kernel module called uio_pci_generic
> > > > +provides a /dev/uioX device file and resource files in /sys
> > > >  that can be mmap'd to obtain access to PCI address space from the application.
> > > > -It uses the uio kernel feature (userland driver).
> > > > +The DPDK-specific igb_uio module can also be used for this. Both
> > > > +drivers use the uio kernel feature
> > > > (userland driver).
> > > >
> > > >  Per-lcore and Shared Variables
> > > >  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> > > > diff --git
> > > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > index 1f1e04f..a0dd959 100644
> > > > ---
> > > > a/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.rst
> > > > +++ b/doc/guides/prog_guide/intel_dpdk_xen_based_packet_switch_sol.r
> > > > +++ st
> > > > @@ -306,12 +306,12 @@ Building and Running the Switching Backend
> > > >          Refer to the *DPDK Getting Started Guide* for more
> > > > information on memory management in the DPDK.
> > > >          In the above command, 4 GB memory is reserved (2048 of 2 MB pages) for DPDK.
> > > >
> > > > -#.  Load igb_uio and bind one Intel NIC controller to igb_uio:
> > > > +#.  Load uio_pci_generic and bind one Intel NIC controller to it:
> > > >
> > > >      .. code-block:: console
> > > >
> > > > -        insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> > > > -        python tools/dpdk_nic_bind.py -b igb_uio 0000:09:00:00.0
> > >
> > >
> > > Hi Bruce,
> > >
> > > Should the information about igb_uio be retained alongside the new information about
> > uio_pci_generic?
> > >
> > While the answer may not be as clear-cut as with the GSG, why would be bother covering both here.
> > We already ignore VFIO in these examples.
> > 
> > /Bruce
> 
> Hi Bruce,
> 
> The method of loading is different for both modules, igb_uio uses insmod and uio_pci_generic uses modprobe.
> It would be useful to retain this igb_uio information. Maybe vfio information should be added too.
> This comment also applies to the GSG,  the differences need to be documented.
>
Yes, the differences between the different modules needs to be documented, 
including limitations of each one and when and why you might choose one over
the other. This probably belongs as a section in programmers guide. However, IMHO
it definitely does not belong in the GSG guide, except as a reference to the
programmers guide section. [I think section 3.1 is the best place for such
documentation].

Regards,
/Bruce