[dpdk-dev,2/2] doc: update programmers guide for uio_pci_generic
Commit Message
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(-)
Comments
> -----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.rst
> @@ -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?
> + modprobe uio_pci_generic
> + python tools/dpdk_nic_bind.py -b uio_pci_generic
> + 0000:09:00:00.0
>
> In this case, 0000:09:00.0 is the PCI address for the NIC controller.
>
> diff --git a/doc/guides/prog_guide/kernel_nic_interface.rst
> b/doc/guides/prog_guide/kernel_nic_interface.rst
> index 0276019..9ed7688 100644
> --- a/doc/guides/prog_guide/kernel_nic_interface.rst
> +++ b/doc/guides/prog_guide/kernel_nic_interface.rst
> @@ -224,7 +224,7 @@ Otherwise, by default, KNI will not enable its backend support capability.
>
> Of course, as a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen before compiling
> the kernel.
>
> -#. Compile the DPDK and insert igb_uio as normal.
> +#. Compile the DPDK and insert uio_pci_generic/igb_uio kernel modules as normal.
>
> #. Insert the KNI kernel module:
>
> diff --git a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> b/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> index 86f4f60..b0a6250 100644
> --- a/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> +++ b/doc/guides/prog_guide/poll_mode_drv_emulated_virtio_nic.rst
> @@ -113,7 +113,7 @@ Host2VM communication example
>
> insmod rte_kni.ko
>
> - Other basic DPDK preparations like hugepage enabling, igb_uio port binding are not listed here.
> + Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
> Please refer to the *DPDK Getting Started Guide* for detailed instructions.
>
> #. Launch the kni user application:
> @@ -154,7 +154,7 @@ Host2VM communication example
> In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns
> corresponds to a physical port,
> which means received packets come from vEth0, and transmitted packets is sent to vEth0.
>
> -#. In the guest, bind the virtio device to the igb_uio kernel module and start the forwarding
> application.
> +#. In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding
> application.
> When the virtio port in guest bursts rx, it is getting packets from the raw socket's receive queue.
> When the virtio port bursts tx, it is sending packet to the tx_q.
>
> @@ -162,8 +162,8 @@ Host2VM communication example
>
> modprobe uio
> echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
> - insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
> - python tools/dpdk_nic_bind.py -b igb_uio 00:03.0
Should the information about igb_uio be retained alongside the new information about uio_pci_generic?
> + modprobe uio_pci_generic
> + python tools/dpdk_nic_bind.py -b uio_pci_generic 00:03.0
>
> We use testpmd as the forwarding application in this example.
>
> diff --git a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> b/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> index e48bc13..769723e 100644
> --- a/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> +++ b/doc/guides/prog_guide/poll_mode_drv_paravirtual_vmxnets_nic.rst
> @@ -150,7 +150,7 @@ This section describes an example setup for Phy-vSwitch-VM-Phy
> communication.
>
> .. note::
>
> - Other instructions on preparing to use DPDK such as, hugepage enabling, igb_uio port binding are
> not listed here.
> + Other instructions on preparing to use DPDK such as, hugepage enabling, uio port binding are not
> listed here.
> Please refer to *DPDK Getting Started Guide and DPDK Sample Application's User Guide* for
> detailed instructions.
>
> The packet reception and transmission flow path is:
> --
> 2.1.0
Regards,
Bernard.
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.rst
> > @@ -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
> -----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.
Regards,
Bernard.
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
On Wed, Feb 25, 2015 at 01:20:43PM +0000, Bruce Richardson wrote:
> 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
From further testing, it appears that uio_pci_generic does not work with VF
devices due to the fact that it doesn't allow MSI/MSI-X interrupts and requires
than any device has a (legacy) interrupt available to it. Therefore, I'll do
a suitable update to the docs to reflect this (perhaps a partial rollback of this
patch). Investigation is continuing...
Regards,
/Bruce
@@ -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
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -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
+ modprobe uio_pci_generic
+ python tools/dpdk_nic_bind.py -b uio_pci_generic 0000:09:00:00.0
In this case, 0000:09:00.0 is the PCI address for the NIC controller.
@@ -224,7 +224,7 @@ Otherwise, by default, KNI will not enable its backend support capability.
Of course, as a prerequisite, the vhost/vhost-net kernel CONFIG should be chosen before compiling the kernel.
-#. Compile the DPDK and insert igb_uio as normal.
+#. Compile the DPDK and insert uio_pci_generic/igb_uio kernel modules as normal.
#. Insert the KNI kernel module:
@@ -113,7 +113,7 @@ Host2VM communication example
insmod rte_kni.ko
- Other basic DPDK preparations like hugepage enabling, igb_uio port binding are not listed here.
+ Other basic DPDK preparations like hugepage enabling, uio port binding are not listed here.
Please refer to the *DPDK Getting Started Guide* for detailed instructions.
#. Launch the kni user application:
@@ -154,7 +154,7 @@ Host2VM communication example
In the above example, virtio port 0 in the guest VM will be associated with vEth0, which in turns corresponds to a physical port,
which means received packets come from vEth0, and transmitted packets is sent to vEth0.
-#. In the guest, bind the virtio device to the igb_uio kernel module and start the forwarding application.
+#. In the guest, bind the virtio device to the uio_pci_generic kernel module and start the forwarding application.
When the virtio port in guest bursts rx, it is getting packets from the raw socket's receive queue.
When the virtio port bursts tx, it is sending packet to the tx_q.
@@ -162,8 +162,8 @@ Host2VM communication example
modprobe uio
echo 512 > /sys/devices/system/node/node0/hugepages/hugepages-2048kB/nr_hugepages
- insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko
- python tools/dpdk_nic_bind.py -b igb_uio 00:03.0
+ modprobe uio_pci_generic
+ python tools/dpdk_nic_bind.py -b uio_pci_generic 00:03.0
We use testpmd as the forwarding application in this example.
@@ -150,7 +150,7 @@ This section describes an example setup for Phy-vSwitch-VM-Phy communication.
.. note::
- Other instructions on preparing to use DPDK such as, hugepage enabling, igb_uio port binding are not listed here.
+ Other instructions on preparing to use DPDK such as, hugepage enabling, uio port binding are not listed here.
Please refer to *DPDK Getting Started Guide and DPDK Sample Application's User Guide* for detailed instructions.
The packet reception and transmission flow path is: