From mboxrd@z Thu Jan 1 00:00:00 1970 From: John McNamara Subject: =?utf-8?q?=5BPATCH=5D_doc=3A_improve_linux_guide_layou?= =?utf-8?q?t?= Date: Tue, 15 Dec 2015 13:34:08 +0000 Message-ID: <1450186448-4508-1-git-send-email-john.mcnamara@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev@dpdk.org Return-path: Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id D71E1FE5 for ; Tue, 15 Dec 2015 14:35:29 +0100 (CET) List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Fixed Linux Getting Started Guide rst layout to improve rendering in PDF. Signed-off-by: John McNamara --- doc/guides/linux_gsg/build_dpdk.rst | 88 +++++++++--------- doc/guides/linux_gsg/build_sample_apps.rst | 141 +++++++++++++++++------= ------ doc/guides/linux_gsg/enable_func.rst | 95 ++++++++++--------- doc/guides/linux_gsg/intro.rst | 8 +- doc/guides/linux_gsg/quick_start.rst | 25 ++--- doc/guides/linux_gsg/sys_reqs.rst | 114 ++++++++--------------- 6 files changed, 234 insertions(+), 237 deletions(-) diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/b= uild_dpdk.rst index c4d1e08..1f4c1f7 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -28,14 +28,13 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. =20 -.. _linux_gsg_compiling_dpdk: - Compiling the DPDK Target from Source =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 .. note:: =20 - Parts of this process can also be done using the setup script descri= bed in Chapter 6 of this document. + Parts of this process can also be done using the setup script descri= bed in + the :ref:`linux_setup_script` section of this document. =20 Install the DPDK and Browse Sources ----------------------------------- @@ -44,10 +43,12 @@ First, uncompress the archive and move to the uncompr= essed DPDK source directory =20 .. code-block:: console =20 - user@host:~$ unzip DPDK-.zip - user@host:~$ cd DPDK- - user@host:~/DPDK-$ ls - app/ config/ drivers/ examples/ lib/ LICENSE.GPL LICENSE.= LGPL Makefile mk/ scripts/ tools/ + unzip DPDK-.zip + cd DPDK- + + ls + app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Makefile + mk/ scripts/ tools/ =20 The DPDK is composed of several directories: =20 @@ -64,19 +65,19 @@ The DPDK is composed of several directories: Installation of DPDK Target Environments ---------------------------------------- =20 -The format of a DPDK target is: +The format of a DPDK target is:: =20 ARCH-MACHINE-EXECENV-TOOLCHAIN =20 where: =20 -* ARCH can be: i686, x86_64, ppc_64 +* ``ARCH`` can be: ``i686``, ``x86_64``, ``ppc_64`` =20 -* MACHINE can be: native, ivshmem, power8 +* ``MACHINE`` can be: ``native``, ``ivshmem``, ``power8`` =20 -* EXECENV can be: linuxapp, bsdapp +* ``EXECENV`` can be: ``linuxapp``, ``bsdapp`` =20 -* TOOLCHAIN can be: gcc, icc +* ``TOOLCHAIN`` can be: ``gcc``, ``icc`` =20 The targets to be installed depend on the 32-bit and/or 64-bit packages = and compilers installed on the host. Available targets can be found in the DPDK/config directory. @@ -84,13 +85,13 @@ The defconfig\_ prefix should not be used. =20 .. note:: =20 - Configuration files are provided with the RTE_MACHINE optimization l= evel set. - Within the configuration files, the RTE_MACHINE configuration value = is set to native, + Configuration files are provided with the ``RTE_MACHINE`` optimizati= on level set. + Within the configuration files, the ``RTE_MACHINE`` configuration va= lue is set to native, which means that the compiled software is tuned for the platform on = which it is built. For more information on this setting, and its possible values, see t= he *DPDK Programmers Guide*. =20 When using the Intel=C2=AE C++ Compiler (icc), one of the following comm= ands should be invoked for 64-bit or 32-bit use respectively. -Notice that the shell scripts update the $PATH variable and therefore sh= ould not be performed in the same session. +Notice that the shell scripts update the ``$PATH`` variable and therefor= e should not be performed in the same session. Also, verify the compiler's installation directory since the path may be= different: =20 .. code-block:: console @@ -98,7 +99,7 @@ Also, verify the compiler's installation directory sinc= e the path may be differe source /opt/intel/bin/iccvars.sh intel64 source /opt/intel/bin/iccvars.sh ia32 =20 -To install and make targets, use the make install T=3D command i= n the top-level DPDK directory. +To install and make targets, use the ``make install T=3D`` comma= nd in the top-level DPDK directory. =20 For example, to compile a 64-bit target using icc, run: =20 @@ -113,7 +114,7 @@ To compile a 32-bit build using gcc, the make command= should be: make install T=3Di686-native-linuxapp-gcc =20 To prepare a target without building it, for example, if the configurati= on changes need to be made before compilation, -use the make config T=3D command: +use the ``make config T=3D`` command: =20 .. code-block:: console =20 @@ -121,10 +122,10 @@ use the make config T=3D command: =20 .. warning:: =20 - Any kernel modules to be used, e.g. igb_uio, kni, must be compiled w= ith the + Any kernel modules to be used, e.g. ``igb_uio``, ``kni``, must be co= mpiled with the same kernel as the one running on the target. If the DPDK is not being built on the target machine, - the RTE_KERNELDIR environment variable should be used to point the c= ompilation at a copy of the kernel version to be used on the target machi= ne. + the ``RTE_KERNELDIR`` environment variable should be used to point t= he compilation at a copy of the kernel version to be used on the target m= achine. =20 Once the target environment is created, the user may move to the target = environment directory and continue to make code changes and re-compile. The user may also make modifications to the compile-time DPDK configurat= ion by editing the .config file in the build directory. @@ -147,21 +148,22 @@ A kmod directory is also present that contains ker= nel modules which may be load =20 .. code-block:: console =20 - $ ls x86_64-native-linuxapp-gcc + ls x86_64-native-linuxapp-gcc + app build hostapp include kmod lib Makefile =20 Loading Modules to Enable Userspace IO for DPDK ----------------------------------------------- =20 To run any DPDK application, a suitable uio module can be loaded into th= e running kernel. -In many cases, the standard uio_pci_generic module included in the Linux= kernel +In many cases, the standard ``uio_pci_generic`` module included in the L= inux kernel can provide the uio capability. This module can be loaded using the comm= and =20 .. code-block:: console =20 sudo modprobe uio_pci_generic =20 -As an alternative to the uio_pci_generic, the DPDK also includes the igb= _uio +As an alternative to the ``uio_pci_generic``, the DPDK also includes the= igb_uio module which can be found in the kmod subdirectory referred to above. It= can be loaded as shown below: =20 @@ -173,7 +175,7 @@ be loaded as shown below: .. note:: =20 For some devices which lack support for legacy interrupts, e.g. virt= ual function - (VF) devices, the igb_uio module may be needed in place of uio_pci_g= eneric. + (VF) devices, the ``igb_uio`` module may be needed in place of ``uio= _pci_generic``. =20 Since DPDK release 1.7 onward provides VFIO support, use of UIO is optio= nal for platforms that support using VFIO. @@ -181,7 +183,7 @@ for platforms that support using VFIO. Loading VFIO Module ------------------- =20 -To run an DPDK application and make use of VFIO, the vfio-pci module mus= t be loaded: +To run an DPDK application and make use of VFIO, the ``vfio-pci`` module= must be loaded: =20 .. code-block:: console =20 @@ -196,29 +198,31 @@ Also, to use VFIO, both kernel and BIOS must suppor= t and be configured to use IO For proper operation of VFIO when running DPDK applications as a non-pri= vileged user, correct permissions should also be set up. This can be done by using the DPDK setup script (called setup.sh and loc= ated in the tools directory). =20 +.. _linux_gsg_binding_kernel: + Binding and Unbinding Network Ports to/from the Kernel Modules ----------------------------------------------------------------------- +-------------------------------------------------------------- =20 As of release 1.4, DPDK applications no longer automatically unbind all = supported network ports from the kernel driver in use. Instead, all ports that are to be used by an DPDK application must be bo= und to the -uio_pci_generic, igb_uio or vfio-pci module before the application is ru= n. +``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` module before the appli= cation is run. Any network ports under Linux* control will be ignored by the DPDK poll-= mode drivers and cannot be used by the application. =20 .. warning:: =20 The DPDK will, by default, no longer automatically unbind network po= rts from the kernel driver at startup. Any ports to be used by an DPDK application must be unbound from Lin= ux* control and - bound to the uio_pci_generic, igb_uio or vfio-pci module before the = application is run. + bound to the ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` module= before the application is run. =20 -To bind ports to the uio_pci_generic, igb_uio or vfio-pci module for DPD= K use, +To bind ports to the ``uio_pci_generic``, ``igb_uio`` or ``vfio-pci`` mo= dule for DPDK use, and then subsequently return ports to Linux* control, a utility script called dpdk_nic _bind.py is provided in the tools subdi= rectory. This utility can be used to provide a view of the current state of the n= etwork ports on the system, and to bind and unbind those ports from the different kernel modules, in= cluding the uio and vfio modules. The following are some examples of how the script can be used. -A full description of the script and its parameters can be obtained by c= alling the script with the --help or --usage options. +A full description of the script and its parameters can be obtained by c= alling the script with the ``--help`` or ``--usage`` options. Note that the uio or vfio kernel modules to be used, should be loaded in= to the kernel before -running the dpdk_nic_bind.py script. +running the ``dpdk_nic_bind.py`` script. =20 .. warning:: =20 @@ -239,38 +243,38 @@ To see the status of all network ports on the syste= m: =20 .. code-block:: console =20 - root@host:DPDK# ./tools/dpdk_nic_bind.py --status + ./tools/dpdk_nic_bind.py --status =20 Network devices using DPDK-compatible driver =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - 0000:82:00.0 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=3D= uio_pci_generic unused=3Dixgbe - 0000:82:00.1 '82599EB 10-Gigabit SFI/SFP+ Network Connection' drv=3D= uio_pci_generic unused=3Dixgbe + 0000:82:00.0 '82599EB 10-GbE NIC' drv=3Duio_pci_generic unused=3Dixg= be + 0000:82:00.1 '82599EB 10-GbE NIC' drv=3Duio_pci_generic unused=3Dixg= be =20 Network devices using kernel driver =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D - 0000:04:00.0 'I350 Gigabit Network Connection' if=3Dem0 drv=3Digb un= used=3Duio_pci_generic *Active* - 0000:04:00.1 'I350 Gigabit Network Connection' if=3Deth1 drv=3Digb u= nused=3Duio_pci_generic - 0000:04:00.2 'I350 Gigabit Network Connection' if=3Deth2 drv=3Digb u= nused=3Duio_pci_generic - 0000:04:00.3 'I350 Gigabit Network Connection' if=3Deth3 drv=3Digb u= nused=3Duio_pci_generic + 0000:04:00.0 'I350 1-GbE NIC' if=3Dem0 drv=3Digb unused=3Duio_pci_g= eneric *Active* + 0000:04:00.1 'I350 1-GbE NIC' if=3Deth1 drv=3Digb unused=3Duio_pci_g= eneric + 0000:04:00.2 'I350 1-GbE NIC' if=3Deth2 drv=3Digb unused=3Duio_pci_g= eneric + 0000:04:00.3 'I350 1-GbE NIC' if=3Deth3 drv=3Digb unused=3Duio_pci_g= eneric =20 Other network devices =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -To bind device eth1, 04:00.1, to the uio_pci_generic driver: +To bind device ``eth1``,``04:00.1``, to the ``uio_pci_generic`` driver: =20 .. code-block:: console =20 - root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=3Duio_pci_generic 04= :00.1 + ./tools/dpdk_nic_bind.py --bind=3Duio_pci_generic 04:00.1 =20 or, alternatively, =20 .. code-block:: console =20 - root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=3Duio_pci_generic et= h1 + ./tools/dpdk_nic_bind.py --bind=3Duio_pci_generic eth1 =20 -To restore device 82:00.0 to its original kernel binding: +To restore device ``82:00.0`` to its original kernel binding: =20 .. code-block:: console =20 - root@host:DPDK# ./tools/dpdk_nic_bind.py --bind=3Dixgbe 82:00.0 + ./tools/dpdk_nic_bind.py --bind=3Dixgbe 82:00.0 diff --git a/doc/guides/linux_gsg/build_sample_apps.rst b/doc/guides/linu= x_gsg/build_sample_apps.rst index 07d84df..e53bd51 100644 --- a/doc/guides/linux_gsg/build_sample_apps.rst +++ b/doc/guides/linux_gsg/build_sample_apps.rst @@ -36,59 +36,62 @@ It also provides a pointer to where sample applicatio= ns are stored. =20 .. note:: =20 - Parts of this process can also be done using the setup script descri= bed in **Chapter 6** of this document. + Parts of this process can also be done using the setup script descri= bed the + :ref:`linux_setup_script` section of this document. =20 Compiling a Sample Application ------------------------------ =20 -Once an DPDK target environment directory has been created (such as x86_= 64-native-linuxapp-gcc), +Once an DPDK target environment directory has been created (such as ``x8= 6_64-native-linuxapp-gcc``), it contains all libraries and header files required to build an applicat= ion. =20 When compiling an application in the Linux* environment on the DPDK, the= following variables must be exported: =20 -* RTE_SDK - Points to the DPDK installation directory. +* ``RTE_SDK`` - Points to the DPDK installation directory. =20 -* RTE_TARGET - Points to the DPDK target environment directory. +* ``RTE_TARGET`` - Points to the DPDK target environment directory. =20 -The following is an example of creating the helloworld application, whic= h runs in the DPDK Linux environment. -This example may be found in the ${RTE_SDK}/examples directory. +The following is an example of creating the ``helloworld`` application, = which runs in the DPDK Linux environment. +This example may be found in the ``${RTE_SDK}/examples`` directory. =20 -The directory contains the main.c file. This file, when combined with th= e libraries in the DPDK target environment, +The directory contains the ``main.c`` file. This file, when combined wit= h the libraries in the DPDK target environment, calls the various functions to initialize the DPDK environment, then launches an entry point (dispatch application) for each core to be = utilized. By default, the binary is generated in the build directory. =20 .. code-block:: console =20 - user@host:~/DPDK$ cd examples/helloworld/ - user@host:~/DPDK/examples/helloworld$ export RTE_SDK=3D$HOME/DPDK - user@host:~/DPDK/examples/helloworld$ export RTE_TARGET=3Dx86_64-nat= ive-linuxapp-gcc - user@host:~/DPDK/examples/helloworld$ make + cd examples/helloworld/ + export RTE_SDK=3D$HOME/DPDK + export RTE_TARGET=3Dx86_64-native-linuxapp-gcc + + make CC main.o LD helloworld INSTALL-APP helloworld INSTALL-MAP helloworld.map =20 - user@host:~/DPDK/examples/helloworld$ ls build/app + ls build/app helloworld helloworld.map =20 .. note:: =20 - In the above example, helloworld was in the directory structure of t= he DPDK. + In the above example, ``helloworld`` was in the directory structure = of the DPDK. However, it could have been located outside the directory structure = to keep the DPDK structure intact. - In the following case, the helloworld application is copied to a new= directory as a new starting point. + In the following case, the ``helloworld`` application is copied to a= new directory as a new starting point. =20 .. code-block:: console =20 - user@host:~$ export RTE_SDK=3D/home/user/DPDK - user@host:~$ cp -r $(RTE_SDK)/examples/helloworld my_rte_app - user@host:~$ cd my_rte_app/ - user@host:~$ export RTE_TARGET=3Dx86_64-native-linuxapp-gcc - user@host:~/my_rte_app$ make - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map + export RTE_SDK=3D/home/user/DPDK + cp -r $(RTE_SDK)/examples/helloworld my_rte_app + cd my_rte_app/ + export RTE_TARGET=3Dx86_64-native-linuxapp-gcc + + make + CC main.o + LD helloworld + INSTALL-APP helloworld + INSTALL-MAP helloworld.map =20 Running a Sample Application ---------------------------- @@ -100,7 +103,7 @@ Running a Sample Application .. warning:: =20 Any ports to be used by the application must be already bound to an = appropriate kernel - module, as described in Section 3.5, prior to running the applicatio= n. + module, as described in :ref:`linux_gsg_binding_kernel`, prior to ru= nning the application. =20 The application is linked with the DPDK target environment's Environment= al Abstraction Layer (EAL) library, which provides some options that are generic to every DPDK application. @@ -109,55 +112,75 @@ The following is the list of options that can be gi= ven to the EAL: =20 .. code-block:: console =20 - ./rte-app -n NUM [-c COREMASK] [-b ] [--socke= t-mem=3DMB,...] [-m MB] [-r NUM] [-v] [--file-prefix] [--proc-type ] [-- xen-dom0] + ./rte-app -c COREMASK [-n NUM] [-b ] \ + [--socket-mem=3DMB,...] [-m MB] [-r NUM] [-v] [--file-pref= ix] \ + [--proc-type ] [-- xen-dom0] =20 The EAL options are as follows: =20 -* -c COREMASK: An hexadecimal bit mask of the cores to run on. Note th= at core numbering can change between platforms and should be determined b= eforehand. +* ``-c COREMASK``: + An hexadecimal bit mask of the cores to run on. Note that core numberi= ng can + change between platforms and should be determined beforehand. =20 -* -n NUM: Number of memory channels per processor socket +* ``-n NUM``: + Number of memory channels per processor socket. =20 -* -b : blacklisting of ports; prevent EAL from = using specified PCI device (multiple -b options are allowed) +* ``-b ``: + Blacklisting of ports; prevent EAL from using specified PCI device + (multiple ``-b`` options are allowed). =20 -* --use-device: use the specified Ethernet device(s) only. Use comma-s= eparate <[domain:]bus:devid.func> values. Cannot be used with -b option +* ``--use-device``: + use the specified Ethernet device(s) only. Use comma-separate + ``[domain:]bus:devid.func`` values. Cannot be used with ``-b`` option. =20 -* --socket-mem: Memory to allocate from hugepages on specific sockets +* ``--socket-mem``: + Memory to allocate from hugepages on specific sockets. =20 -* -m MB: Memory to allocate from hugepages, regardless of processor so= cket. It is recommended that --socket-mem be used instead of this option. +* ``-m MB``: + Memory to allocate from hugepages, regardless of processor socket. It = is + recommended that ``--socket-mem`` be used instead of this option. =20 -* -r NUM: Number of memory ranks +* ``-r NUM``: + Number of memory ranks. =20 -* -v: Display version information on startup +* ``-v``: + Display version information on startup. =20 -* --huge-dir: The directory where hugetlbfs is mounted +* ``--huge-dir``: + The directory where hugetlbfs is mounted. =20 -* --file-prefix: The prefix text used for hugepage filenames +* ``--file-prefix``: + The prefix text used for hugepage filenames. =20 -* --proc-type: The type of process instance +* ``--proc-type``: + The type of process instance. =20 -* --xen-dom0: Support application running on Xen Domain0 without huget= lbfs +* ``--xen-dom0``: + Support application running on Xen Domain0 without hugetlbfs. =20 -* --vmware-tsc-map: use VMware TSC map instead of native RDTSC +* ``--vmware-tsc-map``: + Use VMware TSC map instead of native RDTSC. =20 -* --base-virtaddr: specify base virtual address +* ``--base-virtaddr``: + Specify base virtual address. =20 -* --vfio-intr: specify interrupt type to be used by VFIO (has no effec= t if VFIO is not used) +* ``--vfio-intr``: + Specify interrupt type to be used by VFIO (has no effect if VFIO is no= t used). =20 -The -c and the -n options are mandatory; the others are optional. +The ``-c`` and option is mandatory; the others are optional. =20 Copy the DPDK application binary to your target, then run the applicatio= n as follows (assuming the platform has four memory channels per processor socket, -and that cores 0-3 are present and are to be used for running the applic= ation): - -.. code-block:: console +and that cores 0-3 are present and are to be used for running the applic= ation):: =20 - user@target:~$ ./helloworld -c f -n 4 + ./helloworld -c f -n 4 =20 .. note:: =20 - The --proc-type and --file-prefix EAL options are used for running = multiple DPDK processes. - See the =E2=80=9CMulti-process Sample Application=E2=80=9D chapter i= n the *DPDK Sample Applications User Guide* and - the *DPDK Programmers Guide* for more details. + The ``--proc-type`` and ``--file-prefix`` EAL options are used for r= unning + multiple DPDK processes. See the "Multi-process Sample Application" + chapter in the *DPDK Sample Applications User Guide* and the *DPDK + Programmers Guide* for more details. =20 Logical Core Use by Applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -168,16 +191,14 @@ Since these logical core numbers, and their mapping= to specific cores on specifi it is recommended that the core layout for each platform be considered w= hen choosing the coremask to use in each case. =20 On initialization of the EAL layer by an DPDK application, the logical c= ores to be used and their socket location are displayed. -This information can also be determined for all cores on the system by e= xamining the /proc/cpuinfo file, for example, by running cat /proc/cpuinf= o. +This information can also be determined for all cores on the system by e= xamining the ``/proc/cpuinfo`` file, for example, by running cat ``/proc/= cpuinfo``. The physical id attribute listed for each processor indicates the CPU so= cket to which it belongs. This can be useful when using other processors to understand the mapping= of the logical cores to the sockets. =20 .. note:: =20 - A more graphical view of the logical core layout may be obtained usi= ng the lstopo Linux utility. - On Fedora* Linux, this may be installed and run using the following = command: - -.. code-block:: console + A more graphical view of the logical core layout may be obtained usi= ng the ``lstopo`` Linux utility. + On Fedora Linux, this may be installed and run using the following c= ommand:: =20 sudo yum install hwloc ./lstopo @@ -191,25 +212,25 @@ Hugepage Memory Use by Applications =20 When running an application, it is recommended to use the same amount of= memory as that allocated for hugepages. This is done automatically by the DPDK application at startup, -if no -m or --socket-mem parameter is passed to it when run. +if no ``-m`` or ``--socket-mem`` parameter is passed to it when run. =20 -If more memory is requested by explicitly passing a -m or --socket-mem v= alue, the application fails. -However, the application itself can also fail if the user requests less = memory than the reserved amount of hugepage-memory, particularly if using= the -m option. +If more memory is requested by explicitly passing a ``-m`` or ``--socket= -mem`` value, the application fails. +However, the application itself can also fail if the user requests less = memory than the reserved amount of hugepage-memory, particularly if using= the ``-m`` option. The reason is as follows. Suppose the system has 1024 reserved 2 MB pages in socket 0 and 1024 in = socket 1. If the user requests 128 MB of memory, the 64 pages may not match the co= nstraints: =20 * The hugepage memory by be given to the application by the kernel in = socket 1 only. In this case, if the application attempts to create an object, such = as a ring or memory pool in socket 0, it fails. - To avoid this issue, it is recommended that the -- socket-mem option= be used instead of the -m option. + To avoid this issue, it is recommended that the ``--socket-mem`` opt= ion be used instead of the ``-m`` option. =20 * These pages can be located anywhere in physical memory, and, althoug= h the DPDK EAL will attempt to allocate memory in contiguous blocks, it is possible that the pages will not be contiguous. In this case, = the application is not able to allocate big memory pools. =20 The socket-mem option can be used to request specific amounts of memory = for specific sockets. -This is accomplished by supplying the --socket-mem flag followed by amou= nts of memory requested on each socket, -for example, supply --socket-mem=3D0,512 to try and reserve 512 MB for s= ocket 1 only. -Similarly, on a four socket system, to allocate 1 GB memory on each of s= ockets 0 and 2 only, the parameter --socket-mem=3D1024,0,1024 can be used= . +This is accomplished by supplying the ``--socket-mem`` flag followed by = amounts of memory requested on each socket, +for example, supply ``--socket-mem=3D0,512`` to try and reserve 512 MB f= or socket 1 only. +Similarly, on a four socket system, to allocate 1 GB memory on each of s= ockets 0 and 2 only, the parameter ``--socket-mem=3D1024,0,1024`` can be = used. No memory will be reserved on any CPU socket that is not explicitly refe= renced, for example, socket 3 in this case. If the DPDK cannot allocate enough memory on each socket, the EAL initia= lization fails. =20 diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/= enable_func.rst index 0105a82..c3fa6d3 100644 --- a/doc/guides/linux_gsg/enable_func.rst +++ b/doc/guides/linux_gsg/enable_func.rst @@ -47,11 +47,9 @@ The BIOS is typically accessed by pressing F2 while th= e platform is starting up. The user can then navigate to the HPET option. On the Crystal Forest pla= tform BIOS, the path is: **Advanced -> PCH-IO Configuration -> High Precision Timer ->** (Change = from Disabled to Enabled if necessary). =20 -On a system that has already booted, the following command can be issued= to check if HPET is enabled: +On a system that has already booted, the following command can be issued= to check if HPET is enabled:: =20 -.. code-block:: console - - # grep hpet /proc/timer_list + grep hpet /proc/timer_list =20 If no entries are returned, HPET must be enabled in the BIOS (as per the= instructions above) and the system rebooted. =20 @@ -59,75 +57,84 @@ Linux Kernel Support ~~~~~~~~~~~~~~~~~~~~ =20 The DPDK makes use of the platform HPET timer by mapping the timer count= er into the process address space, and as such, -requires that the HPET_MMAP kernel configuration option be enabled. +requires that the ``HPET_MMAP`` kernel configuration option be enabled. =20 .. warning:: =20 - On Fedora*, and other common distributions such as Ubuntu*, the HPET= _MMAP kernel option is not enabled by default. + On Fedora, and other common distributions such as Ubuntu, the ``HPET= _MMAP`` kernel option is not enabled by default. To recompile the Linux kernel with this option enabled, please consu= lt the distributions documentation for the relevant instructions. =20 Enabling HPET in the DPDK ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 By default, HPET support is disabled in the DPDK build configuration fil= es. -To use HPET, the CONFIG_RTE_LIBEAL_USE_HPET setting should be changed to= =E2=80=9Cy=E2=80=9D, which will enable the HPET settings at compile time= . +To use HPET, the ``CONFIG_RTE_LIBEAL_USE_HPET`` setting should be change= d to ``y``, which will enable the HPET settings at compile time. =20 -For an application to use the rte_get_hpet_cycles() and rte_get_hpet_hz(= ) API calls, +For an application to use the ``rte_get_hpet_cycles()`` and ``rte_get_hp= et_hz()`` API calls, and optionally to make the HPET the default time source for the rte_time= r library, -the new rte_eal_hpet_init() API call should be called at application ini= tialization. +the new ``rte_eal_hpet_init()`` API call should be called at application= initialization. This API call will ensure that the HPET is accessible, returning an erro= r to the application if it is not, -for example, if HPET_MMAP is not enabled in the kernel. +for example, if ``HPET_MMAP`` is not enabled in the kernel. The application can then determine what action to take, if any, if the H= PET is not available at run-time. =20 .. note:: =20 For applications that require timing APIs, but not the HPET timer sp= ecifically, - it is recommended that the rte_get_timer_cycles() and rte_get_timer_= hz() API calls be used instead of the HPET-specific APIs. - These generic APIs can work with either TSC or HPET time sources, de= pending on what is requested by an application call to rte_eal_hpet_init(= ), + it is recommended that the ``rte_get_timer_cycles()`` and ``rte_get_= timer_hz()`` API calls be used instead of the HPET-specific APIs. + These generic APIs can work with either TSC or HPET time sources, de= pending on what is requested by an application call to ``rte_eal_hpet_ini= t()``, if any, and on what is available on the system at runtime. =20 Running DPDK Applications Without Root Privileges -------------------------------------------------------- =20 Although applications using the DPDK use network ports and other hardwar= e resources directly, -with a number of small permission adjustments it is possible to run thes= e applications as a user other than =E2=80=9Croot=E2=80=9D. +with a number of small permission adjustments it is possible to run thes= e applications as a user other than "root". To do so, the ownership, or permissions, on the following Linux file sys= tem objects should be adjusted to ensure that the Linux user account being used to run the DPDK application has access= to them: =20 -* All directories which serve as hugepage mount points, for example, = /mnt/huge +* All directories which serve as hugepage mount points, for example, = ``/mnt/huge`` + +* The userspace-io device files in ``/dev``, for example, ``/dev/uio= 0``, ``/dev/uio1``, and so on =20 -* The userspace-io device files in /dev, for example, /dev/uio0, /de= v/uio1, and so on +* The userspace-io sysfs config and resource files, for example for ``= uio0``:: =20 -* The userspace-io sysfs config and resource files, for example for ui= o0: /sys/class/uio/uio0/device/config /sys/class/uio/uio0/device/resource= * + /sys/class/uio/uio0/device/config + /sys/class/uio/uio0/device/resource* =20 -* If the HPET is to be used, /dev/hpet +* If the HPET is to be used, ``/dev/hpet`` =20 .. note:: =20 - On some Linux installations, /dev/hugepages is also a hugepage moun= t point created by default. + On some Linux installations, ``/dev/hugepages`` is also a hugepage = mount point created by default. =20 Power Management and Power Saving Functionality ----------------------------------------------- =20 Enhanced Intel SpeedStep=C2=AE Technology must be enabled in the platfor= m BIOS if the power management feature of DPDK is to be used. -Otherwise, the sys file folder /sys/devices/system/cpu/cpu0/cpufreq will= not exist, and the CPU frequency- based power management cannot be used. +Otherwise, the sys file folder ``/sys/devices/system/cpu/cpu0/cpufreq`` = will not exist, and the CPU frequency- based power management cannot be u= sed. Consult the relevant BIOS documentation to determine how these settings = can be accessed. =20 -For example, on some Intel reference platform BIOS variants, the path to= Enhanced Intel SpeedStep=C2=AE Technology is: +For example, on some Intel reference platform BIOS variants, the path to= Enhanced Intel SpeedStep=C2=AE Technology is:: =20 -**Advanced->Processor Configuration->Enhanced Intel SpeedStep=C2=AE Tech= ** + Advanced + -> Processor Configuration + -> Enhanced Intel SpeedStep=C2=AE Tech =20 -In addition, C3 and C6 should be enabled as well for power management. T= he path of C3 and C6 on the same platform BIOS is: +In addition, C3 and C6 should be enabled as well for power management. T= he path of C3 and C6 on the same platform BIOS is:: =20 -**Advanced->Processor Configuration->Processor C3 Advanced->Processor Co= nfiguration-> Processor C6** + Advanced + -> Processor Configuration + -> Processor C3 Advanced + -> Processor Configuration + -> Processor C6 =20 -Using Linux* Core Isolation to Reduce Context Switches ------------------------------------------------------- +Using Linux Core Isolation to Reduce Context Switches +----------------------------------------------------- =20 While the threads used by an DPDK application are pinned to logical core= s on the system, it is possible for the Linux scheduler to run other tasks on those cores= also. To help prevent additional workloads from running on those cores, -it is possible to use the isolcpus Linux* kernel parameter to isolate th= em from the general Linux scheduler. +it is possible to use the ``isolcpus`` Linux kernel parameter to isolate= them from the general Linux scheduler. =20 For example, if DPDK applications are to run on logical cores 2, 4 and 6= , the following should be added to the kernel parameter list: @@ -137,38 +144,38 @@ the following should be added to the kernel paramet= er list: isolcpus=3D2,4,6 =20 Loading the DPDK KNI Kernel Module ------------------------------------------ +---------------------------------- =20 To run the DPDK Kernel NIC Interface (KNI) sample application, an extra = kernel module (the kni module) must be loaded into the running kernel. The module is found in the kmod sub-directory of the DPDK target directo= ry. -Similar to the loading of the igb_uio module, this module should be load= ed using the insmod command as shown below +Similar to the loading of the ``igb_uio`` module, this module should be = loaded using the insmod command as shown below (assuming that the current directory is the DPDK target directory): =20 .. code-block:: console =20 - #insmod kmod/rte_kni.ko + insmod kmod/rte_kni.ko =20 .. note:: =20 - See the =E2=80=9CKernel NIC Interface Sample Application=E2=80=9D ch= apter in the *DPDK Sample Applications User Guide* for more details. + See the "Kernel NIC Interface Sample Application" chapter in the *DPD= K Sample Applications User Guide* for more details. =20 Using Linux IOMMU Pass-Through to Run DPDK with Intel=C2=AE VT-d ----------------------------------------------------------- =20 To enable Intel=C2=AE VT-d in a Linux kernel, a number of kernel configu= ration options must be set. These include: =20 -* IOMMU_SUPPORT +* ``IOMMU_SUPPORT`` =20 -* IOMMU_API +* ``IOMMU_API`` =20 -* INTEL_IOMMU +* ``INTEL_IOMMU`` =20 -In addition, to run the DPDK with Intel=C2=AE VT-d, the iommu=3Dpt kerne= l parameter must be used when using igb_uio driver. +In addition, to run the DPDK with Intel=C2=AE VT-d, the ``iommu=3Dpt`` k= ernel parameter must be used when using ``igb_uio`` driver. This results in pass-through of the DMAR (DMA Remapping) lookup in the h= ost. -Also, if INTEL_IOMMU_DEFAULT_ON is not set in the kernel, the intel_iomm= u=3Don kernel parameter must be used too. +Also, if ``INTEL_IOMMU_DEFAULT_ON`` is not set in the kernel, the ``inte= l_iommu=3Don`` kernel parameter must be used too. This ensures that the Intel IOMMU is being initialized as expected. =20 -Please note that while using iommu=3Dpt is compulsory for igb_uio driver= , the vfio-pci driver can actually work with both iommu=3Dpt and iommu=3D= on. +Please note that while using ``iommu=3Dpt`` is compulsory for ``igb_uio = driver``, the ``vfio-pci`` driver can actually work with both ``iommu=3Dp= t`` and ``iommu=3Don``. =20 High Performance of Small Packets on 40G NIC -------------------------------------------- @@ -182,12 +189,12 @@ DPDK release, so currently the validated firmware v= ersion is 4.2.6. Enabling Extended Tag and Setting Max Read Request Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -PCI configurations of extended_tag and max _read_requ st_size have big i= mpacts on performance of small packets on 40G NIC. -Enabling extended_tag and setting max _read_requ st_size to small size s= uch as 128 bytes provide great helps to high performance of small packets= . +PCI configurations of ``extended_tag`` and max _read_requ st_size have b= ig impacts on performance of small packets on 40G NIC. +Enabling extended_tag and setting ``max_read_request_size`` to small siz= e such as 128 bytes provide great helps to high performance of small pack= ets. =20 * These can be done in some BIOS implementations. =20 -* For other BIOS implementations, PCI configurations can be changed by= using command of setpci, or special configurations in DPDK config file o= f common_linux. +* For other BIOS implementations, PCI configurations can be changed by= using command of ``setpci``, or special configurations in DPDK config fi= le of ``common_linux``. =20 * Bits 7:5 at address of 0xA8 of each PCI device is used for setti= ng the max_read_request_size, and bit 8 of 0xA8 of each PCI device is used for enabling/disabl= ing the extended_tag. @@ -195,24 +202,24 @@ Enabling extended_tag and setting max _read_requ st= _size to small size such as 1 =20 * In config file of common_linux, below three configurations can b= e changed for the same purpose. =20 - CONFIG_RTE_PCI_CONFIG + ``CONFIG_RTE_PCI_CONFIG`` =20 - CONFIG_RTE_PCI_EXTENDED_TAG + ``CONFIG_RTE_PCI_EXTENDED_TAG`` =20 - CONFIG_RTE_PCI_MAX_READ_REQUEST_SIZE + ``CONFIG_RTE_PCI_MAX_READ_REQUEST_SIZE`` =20 Use 16 Bytes RX Descriptor Size ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 As i40e PMD supports both 16 and 32 bytes RX descriptor sizes, and 16 by= tes size can provide helps to high performance of small packets. -Configuration of CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC in config files c= an be changed to use 16 bytes size RX descriptors. +Configuration of ``CONFIG_RTE_LIBRTE_I40E_16BYTE_RX_DESC`` in config fil= es can be changed to use 16 bytes size RX descriptors. =20 High Performance and per Packet Latency Tradeoff ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 Due to the hardware design, the interrupt signal inside NIC is needed fo= r per packet descriptor write-back. The minimum interval of interrupts could b= e set -at compile time by CONFIG_RTE_LIBRTE_I40E_ITR_INTERVAL in configuration = files. +at compile time by ``CONFIG_RTE_LIBRTE_I40E_ITR_INTERVAL`` in configurat= ion files. Though there is a default configuration, the interval could be tuned by = the users with that configuration item depends on what the user cares about = more, performance or per packet latency. diff --git a/doc/guides/linux_gsg/intro.rst b/doc/guides/linux_gsg/intro.= rst index a6ee188..eef7e83 100644 --- a/doc/guides/linux_gsg/intro.rst +++ b/doc/guides/linux_gsg/intro.rst @@ -33,7 +33,7 @@ Introduction =20 This document contains instructions for installing and configuring the I= ntel=C2=AE Data Plane Development Kit (DPDK) software. It is designed to get customers up and running quickly. -The document describes how to compile and run a DPDK application in a Li= nux* application (linuxapp) environment, +The document describes how to compile and run a DPDK application in a Li= nux application (linuxapp) environment, without going deeply into detail. =20 Documentation Roadmap @@ -48,7 +48,7 @@ The following is a list of DPDK documents in the sugges= ted reading order: =20 * Programmer's Guide: Describes: =20 - * The software architecture and how to use it (through examples), = specifically in a Linux* application (linuxapp) environment + * The software architecture and how to use it (through examples), = specifically in a Linux application (linuxapp) environment =20 * The content of the DPDK, the build system (including the command= s that can be used in the root DPDK Makefile to build the development kit= and an application) and guidelines for porting an application @@ -61,7 +61,3 @@ The following is a list of DPDK documents in the sugges= ted reading order: =20 * Sample Applications User Guide: Describes a set of sample applicatio= ns. Each chapter describes a sample application that showcases specific = functionality and provides instructions on how to compile, run and use th= e sample application. - -.. note:: - - These documents are available for download as a separate documentati= on package at the same location as the DPDK code package. diff --git a/doc/guides/linux_gsg/quick_start.rst b/doc/guides/linux_gsg/= quick_start.rst index b07fc87..1e0f8ff 100644 --- a/doc/guides/linux_gsg/quick_start.rst +++ b/doc/guides/linux_gsg/quick_start.rst @@ -28,6 +28,8 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. =20 +.. _linux_setup_script: + Quick Start Setup Script =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -51,7 +53,7 @@ The setup.sh script, found in the tools subdirectory, a= llows the user to perform =20 * Look at hugepages in the meminfo =20 -* List hugepages in /mnt/huge +* List hugepages in ``/mnt/huge`` =20 * Remove built DPDK libraries =20 @@ -106,7 +108,7 @@ Some options in the script prompt the user for furthe= r data before proceeding. =20 .. code-block:: console =20 - user@host:~/rte$ source tools/setup.sh + source tools/setup.sh =20 --------------------------------------------------------------------= ---- =20 @@ -202,7 +204,7 @@ Some options in the script prompt the user for furthe= r data before proceeding. =20 Option: =20 -The following selection demonstrates the creation of the x86_64-native-l= inuxapp-gcc DPDK library. +The following selection demonstrates the creation of the ``x86_64-native= -linuxapp-gcc`` DPDK library. =20 .. code-block:: console =20 @@ -214,7 +216,7 @@ The following selection demonstrates the creation of = the x86_64-native-linuxapp- =3D=3D Build lib ... Build complete - RTE_TARGET exported as x86_64-native -linuxapp-gcc + RTE_TARGET exported as x86_64-native-linuxapp-gcc =20 The following selection demonstrates the starting of the DPDK UIO driver= . =20 @@ -277,15 +279,16 @@ the logical core layout of the platform should be d= etermined when selecting a co =20 .. code-block:: console =20 - rte@rte-desktop:~/rte/examples$ cd helloworld/ - rte@rte-desktop:~/rte/examples/helloworld$ make - CC main.o - LD helloworld - INSTALL-APP helloworld - INSTALL-MAP helloworld.map + cd helloworld/ + make + CC main.o + LD helloworld + INSTALL-APP helloworld + INSTALL-MAP helloworld.map =20 - rte@rte-desktop:~/rte/examples/helloworld$ sudo ./build/app/hellowor= ld -c 0xf -n 3 + sudo ./build/app/helloworld -c 0xf -n 3 [sudo] password for rte: + EAL: coremask set to f EAL: Detected lcore 0 as core 0 on socket 0 EAL: Detected lcore 1 as core 0 on socket 1 diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys= _reqs.rst index ef01944..a20a407 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -28,7 +28,6 @@ (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE US= E OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. =20 - System Requirements =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 @@ -37,7 +36,7 @@ This chapter describes the packages required to compile= the DPDK. .. note:: =20 If the DPDK is being used on an Intel=C2=AE Communications Chipset 8= 9xx Series platform, - please consult the *Intel=C2=AE Communications Chipset 89xx Series S= oftware for Linux* Getting Started Guide*. + please consult the *Intel=C2=AE Communications Chipset 89xx Series S= oftware for Linux Getting Started Guide*. =20 BIOS Setting Prerequisite on x86 -------------------------------- @@ -45,7 +44,7 @@ BIOS Setting Prerequisite on x86 For the majority of platforms, no special BIOS settings are needed to us= e basic DPDK functionality. However, for additional HPET timer and power management functionality, and high performance of small packets on 40G NIC, BIOS setting changes m= ay be needed. -Consult :ref:`Chapter 5. Enabling Additional Functionality ` +Consult the section on :ref:`Enabling Additional Functionality ` for more information on the required changes. =20 Compilation of the DPDK @@ -55,17 +54,17 @@ Compilation of the DPDK =20 .. note:: =20 - Testing has been performed using Fedora* 18. The setup commands and = installed packages needed on other systems may be different. + Testing has been performed using Fedora 18. The setup commands and i= nstalled packages needed on other systems may be different. For details on other Linux distributions and the versions tested, pl= ease consult the DPDK Release Notes. =20 -* GNU make +* GNU ``make``. =20 -* coreutils: cmp, sed, grep, arch +* coreutils: ``cmp``, ``sed``, ``grep``, ``arch``, etc. =20 -* gcc: versions 4.5.x or later is recommended for i686/x86_64. version= s 4.8.x or later is recommended - for ppc_64 and x86_x32 ABI. On some distributions, some specific com= piler flags and linker flags are enabled by - default and affect performance (- fstack-protector, for example). Pl= ease refer to the documentation - of your distribution and to gcc -dumpspecs. +* gcc: versions 4.5.x or later is recommended for ``i686/x86_64``. Ver= sions 4.8.x or later is recommended + for ``ppc_64`` and ``x86_x32`` ABI. On some distributions, some spec= ific compiler flags and linker flags are enabled by + default and affect performance (``-fstack-protector``, for example).= Please refer to the documentation + of your distribution and to ``gcc -dumpspecs``. =20 * libc headers (glibc-devel.i686 / libc6-dev-i386; glibc-devel.x86_64 = for 64-bit compilation on Intel architecture; glibc-devel.ppc64 for 64 bit IBM Power architecture;) @@ -75,9 +74,9 @@ Compilation of the DPDK =20 * Additional packages required for 32-bit compilation on 64-bit system= s are: =20 - glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for Int= el i686/x86_64; + * glibc.i686, libgcc.i686, libstdc++.i686 and glibc-devel.i686 for I= ntel i686/x86_64; =20 - glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for= IBM ppc_64; + * glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 f= or IBM ppc_64; =20 .. note:: =20 @@ -86,21 +85,20 @@ Compilation of the DPDK =20 .. note:: =20 - Python, version 2.6 or 2.7, to use various helper scripts included i= n the DPDK package + Python, version 2.6 or 2.7, to use various helper scripts included i= n the DPDK package. =20 =20 **Optional Tools:** =20 -* Intel=C2=AE C++ Compiler (icc). For installation, additional librar= ies may be required. +* Intel=C2=AE C++ Compiler (icc). For installation, additional librari= es may be required. See the icc Installation Guide found in the Documentation directory = under the compiler installation. - This release has been tested using version 12.1. =20 * IBM=C2=AE Advance ToolChain for Powerlinux. This is a set of open so= urce development tools and runtime libraries which allows users to take leading edge advantage of IBM's latest PO= WER hardware features on Linux. To install it, see the IBM official installation document. =20 * libpcap headers and libraries (libpcap-devel) to compile and use the= libpcap-based poll-mode driver. - This driver is disabled by default and can be enabled by setting CON= FIG_RTE_LIBRTE_PMD_PCAP=3Dy in the build time config file. + This driver is disabled by default and can be enabled by setting ``C= ONFIG_RTE_LIBRTE_PMD_PCAP=3Dy`` in the build time config file. =20 Running DPDK Applications ------------------------- @@ -114,29 +112,17 @@ System Software =20 * Kernel version >=3D 2.6.34 =20 - The kernel version in use can be checked using the command: - - .. code-block:: console + The kernel version in use can be checked using the command:: =20 uname -r =20 * glibc >=3D 2.7 (for features related to cpuset) =20 - The version can be checked using the ldd --version command. A sample= output is shown below: - - .. code-block:: console - - # ldd --version - - ldd (GNU libc) 2.14.90 - Copyright (C) 2011 Free Software Foundation, Inc. - This is free software; see the source for copying conditions. Th= ere is NO - warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICUL= AR PURPOSE. - Written by Roland McGrath and Ulrich Drepper. + The version can be checked using the ``ldd --version`` command. =20 * Kernel configuration =20 - In the Fedora* OS and other common distributions, such as Ubuntu*, o= r Red Hat Enterprise Linux*, + In the Fedora OS and other common distributions, such as Ubuntu, or = Red Hat Enterprise Linux, the vendor supplied kernel configurations can be used to run most DP= DK applications. =20 For other kernel builds, options which should be enabled for DPDK in= clude: @@ -148,15 +134,15 @@ System Software * PROC_PAGE_MONITOR support =20 * HPET and HPET_MMAP configuration options should also be enabled = if HPET support is required. - See :ref:`Section 5.1 High Precision Event Timer (HPET) Function= ality ` for more details. + See the section on :ref:`High Precision Event Timer (HPET) Funct= ionality ` for more details. =20 .. _linux_gsg_hugepages: =20 -Use of Hugepages in the Linux* Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Use of Hugepages in the Linux Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 Hugepage support is required for the large memory pool allocation used f= or packet buffers -(the HUGETLBFS option must be enabled in the running kernel as indicated= in Section 2.3). +(the HUGETLBFS option must be enabled in the running kernel as indicated= the previous section). By using hugepage allocations, performance is increased since fewer page= s are needed, and therefore less Translation Lookaside Buffers (TLBs, high speed trans= lation caches), which reduce the time it takes to translate a virtual page address to a = physical page address. @@ -167,19 +153,15 @@ Reserving Hugepages for DPDK Use =20 The allocation of hugepages should be done at boot time or as soon as po= ssible after system boot to prevent memory from being fragmented in physical memory. -To reserve hugepages at boot time, a parameter is passed to the Linux* k= ernel on the kernel command line. - -For 2 MB pages, just pass the hugepages option to the kernel. For exampl= e, to reserve 1024 pages of 2 MB, use: +To reserve hugepages at boot time, a parameter is passed to the Linux ke= rnel on the kernel command line. =20 -.. code-block:: console +For 2 MB pages, just pass the hugepages option to the kernel. For exampl= e, to reserve 1024 pages of 2 MB, use:: =20 hugepages=3D1024 =20 For other hugepage sizes, for example 1G pages, the size must be specifi= ed explicitly and can also be optionally set as the default hugepage size for the system. -For example, to reserve 4G of hugepage memory in the form of four 1G pag= es, the following options should be passed to the kernel: - -.. code-block:: console +For example, to reserve 4G of hugepage memory in the form of four 1G pag= es, the following options should be passed to the kernel:: =20 default_hugepagesz=3D1G hugepagesz=3D1G hugepages=3D4 =20 @@ -197,21 +179,17 @@ In the case of a dual-socket NUMA system, the number of hugepages reserved at boot time is generally divided equal= ly between the two sockets (on the assumption that sufficient memory is present on both sockets). =20 -See the Documentation/kernel-parameters.txt file in your Linux* source t= ree for further details of these and other kernel options. +See the Documentation/kernel-parameters.txt file in your Linux source tr= ee for further details of these and other kernel options. =20 **Alternative:** =20 For 2 MB pages, there is also the option of allocating hugepages after t= he system has booted. -This is done by echoing the number of hugepages required to a nr_hugepag= es file in the /sys/devices/ directory. -For a single-node system, the command to use is as follows (assuming tha= t 1024 pages are required): - -.. code-block:: console +This is done by echoing the number of hugepages required to a nr_hugepag= es file in the ``/sys/devices/`` directory. +For a single-node system, the command to use is as follows (assuming tha= t 1024 pages are required):: =20 echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages =20 -On a NUMA machine, pages should be allocated explicitly on separate node= s: - -.. code-block:: console +On a NUMA machine, pages should be allocated explicitly on separate node= s:: =20 echo 1024 > /sys/devices/system/node/node0/hugepages/hugepages-2048k= B/nr_hugepages echo 1024 > /sys/devices/system/node/node1/hugepages/hugepages-2048k= B/nr_hugepages @@ -223,29 +201,23 @@ On a NUMA machine, pages should be allocated explic= itly on separate nodes: Using Hugepages with the DPDK ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -Once the hugepage memory is reserved, to make the memory available for D= PDK use, perform the following steps: - -.. code-block:: console +Once the hugepage memory is reserved, to make the memory available for D= PDK use, perform the following steps:: =20 mkdir /mnt/huge mount -t hugetlbfs nodev /mnt/huge =20 -The mount point can be made permanent across reboots, by adding the foll= owing line to the /etc/fstab file: - -.. code-block:: console +The mount point can be made permanent across reboots, by adding the foll= owing line to the ``/etc/fstab`` file:: =20 nodev /mnt/huge hugetlbfs defaults 0 0 =20 -For 1GB pages, the page size must be specified as a mount option: - -.. code-block:: console +For 1GB pages, the page size must be specified as a mount option:: =20 nodev /mnt/huge_1GB hugetlbfs pagesize=3D1GB 0 0 =20 -Xen Domain0 Support in the Linux* Environment -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Xen Domain0 Support in the Linux Environment +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -The existing memory management implementation is based on the Linux* ker= nel hugepage mechanism. +The existing memory management implementation is based on the Linux kern= el hugepage mechanism. On the Xen hypervisor, hugepage support for DomainU (DomU) Guests means = that DPDK applications work as normal for guests. =20 However, Domain0 (Dom0) does not support hugepages. @@ -263,11 +235,9 @@ Furthermore, the CONFIG_RTE_EAL_ALLOW_INV_SOCKET_ID = setting should also be chang Loading the DPDK rte_dom0_mm Module ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -To run any DPDK application on Xen Dom0, the rte_dom0_mm module must be = loaded into the running kernel with rsv_memsize option. +To run any DPDK application on Xen Dom0, the ``rte_dom0_mm`` module must= be loaded into the running kernel with rsv_memsize option. The module is found in the kmod sub-directory of the DPDK target directo= ry. -This module should be loaded using the insmod command as shown below (as= suming that the current directory is the DPDK target directory): - -.. code-block:: console +This module should be loaded using the insmod command as shown below (as= suming that the current directory is the DPDK target directory):: =20 sudo insmod kmod/rte_dom0_mm.ko rsv_memsize=3DX =20 @@ -278,19 +248,15 @@ Configuring Memory for DPDK Use =20 After the rte_dom0_mm.ko kernel module has been loaded, the user must co= nfigure the memory size for DPDK usage. This is done by echoing the memory size to a memsize file in the /sys/de= vices/ directory. -Use the following command (assuming that 2048 MB is required): - -.. code-block:: console +Use the following command (assuming that 2048 MB is required):: =20 echo 2048 > /sys/kernel/mm/dom0-mm/memsize-mB/memsize =20 -The user can also check how much memory has already been used: - -.. code-block:: console +The user can also check how much memory has already been used:: =20 cat /sys/kernel/mm/dom0-mm/memsize-mB/memsize_rsvd =20 -Xen Domain0 does not support NUMA configuration, as a result the --socke= t-mem command line option is invalid for Xen Domain0. +Xen Domain0 does not support NUMA configuration, as a result the ``--soc= ket-mem`` command line option is invalid for Xen Domain0. =20 .. note:: =20 @@ -299,4 +265,4 @@ Xen Domain0 does not support NUMA configuration, as a= result the --socket-mem co Running the DPDK Application on Xen Domain0 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -To run the DPDK application on Xen Domain0, an extra command line option= --xen-dom0 is required. +To run the DPDK application on Xen Domain0, an extra command line option= ``--xen-dom0`` is required. --=20 2.5.0