From mboxrd@z Thu Jan 1 00:00:00 1970 From: Pablo de Lara Subject: =?utf-8?q?=5BPATCH_v2_2/3=5D_doc=3A_remove_references_?= =?utf-8?q?to_intel_dpdk_in_linux=5Fgsg?= Date: Fri, 19 Dec 2014 15:08:47 +0000 Message-ID: <1419001728-7878-3-git-send-email-pablo.de.lara.guarch@intel.com> References: <1417563667-16686-1-git-send-email-siobhan.a.butler@intel.com> <1419001728-7878-1-git-send-email-pablo.de.lara.guarch@intel.com> Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable To: dev-VfR2kkLFssw@public.gmane.org Return-path: In-Reply-To: <1419001728-7878-1-git-send-email-pablo.de.lara.guarch-ral2JQCrhuEAvxtiuMwx3w@public.gmane.org> List-Id: patches and discussions about DPDK List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces-VfR2kkLFssw@public.gmane.org Sender: "dev" From: Siobhan Butler Adjusted line lengths and removed references to Intel which are no longer relevant in linux gsg. Signed-off-by: Siobhan Butler --- doc/guides/linux_gsg/build_dpdk.rst | 68 +++++++++++++++---------= ------ doc/guides/linux_gsg/build_sample_apps.rst | 46 ++++++++++---------- doc/guides/linux_gsg/enable_func.rst | 34 +++++++-------- doc/guides/linux_gsg/intro.rst | 14 +++--- doc/guides/linux_gsg/quick_start.rst | 28 ++++++------ doc/guides/linux_gsg/sys_reqs.rst | 66 ++++++++++++++----------= ----- 6 files changed, 128 insertions(+), 128 deletions(-) diff --git a/doc/guides/linux_gsg/build_dpdk.rst b/doc/guides/linux_gsg/b= uild_dpdk.rst index 5bdd6d8..d09c69d 100644 --- a/doc/guides/linux_gsg/build_dpdk.rst +++ b/doc/guides/linux_gsg/build_dpdk.rst @@ -28,17 +28,17 @@ (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 -Compiling the Intel=C2=AE 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=3D=3D=3D=3D=3D=3D=3D +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. =20 -Install the Intel=C2=AE DPDK and Browse Sources ------------------------------------------- +Install the DPDK and Browse Sources +----------------------------------- =20 -First, uncompress the archive and move to the uncompressed Intel=C2=AE D= PDK source directory: +First, uncompress the archive and move to the uncompressed DPDK source d= irectory: =20 .. code-block:: console =20 @@ -47,20 +47,20 @@ First, uncompress the archive and move to the uncompr= essed Intel=C2=AE DPDK source d user@host:~/DPDK-$ ls app/ config/ examples/ lib/ LICENSE.GPL LICENSE.LGPL Make= file mk/ scripts/ tools/ =20 -The Intel=C2=AE DPDK is composed of several directories: +The DPDK is composed of several directories: =20 -* lib: Source code of Intel=C2=AE DPDK libraries +* lib: Source code of DPDK libraries =20 -* app: Source code of Intel=C2=AE DPDK applications (automatic tests) +* app: Source code of DPDK applications (automatic tests) =20 -* examples: Source code of Intel=C2=AE DPDK application examples +* examples: Source code of DPDK application examples =20 * config, tools, scripts, mk: Framework-related makefiles, scripts and= configuration =20 -Installation of Intel=C2=AE DPDK Target Environments ------------------------------------------------ +Installation of DPDK Target Environments +---------------------------------------- =20 -The format of a Intel=C2=AE DPDK target is: +The format of a DPDK target is: =20 ARCH-MACHINE-EXECENV-TOOLCHAIN =20 @@ -83,7 +83,7 @@ The defconfig\_ prefix should not be used. 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, 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 *Intel=C2=AE DPDK Programmers Guide*. + 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. @@ -94,7 +94,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 Intel=C2=AE DPDK directory. +To install and make targets, use the make install T=3D command i= n the top-level DPDK directory. =20 For example, to compile a 64-bit target using icc, run: =20 @@ -134,11 +134,11 @@ use the make config T=3D command: .. warning:: =20 The igb_uio module must be compiled with the same kernel as the one = running on the target. - If the Intel=C2=AE DPDK is not being built on the target machine, + 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. =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 Intel=C2=AE DPD= K configuration by editing the .config file in the build directory. +The user may also make modifications to the compile-time DPDK configurat= ion by editing the .config file in the build directory. (This is a build-local copy of the defconfig file from the top- level co= nfig directory). =20 .. code-block:: console @@ -149,10 +149,10 @@ The user may also make modifications to the compile= -time Intel=C2=AE DPDK configurat =20 In addition, the make clean command can be used to remove any existing c= ompiled files for a subsequent full, clean rebuild of the code. =20 -Browsing the Installed Intel=C2=AE DPDK Environment Target ------------------------------------------------------ +Browsing the Installed DPDK Environment Target +---------------------------------------------- =20 -Once a target is created it contains all libraries and header files for = the Intel=C2=AE DPDK environment that are required to build customer appl= ications. +Once a target is created it contains all libraries and header files for = the DPDK environment that are required to build customer applications. In addition, the test and testpmd applications are built under the build= /app directory, which may be used for testing. In the case of Linux, a kmod directory is also present that contains a = module to install: =20 @@ -161,12 +161,12 @@ In the case of Linux, a kmod directory is also pre= sent that contains a module t $ ls x86_64-native-linuxapp-gcc app build hostapp include kmod lib Makefile =20 -Loading the Intel=C2=AE DPDK igb_uio Module --------------------------------------- +Loading the DPDK igb_uio Module +------------------------------- =20 -To run any Intel=C2=AE DPDK application, the igb_uio module can be loade= d into the running kernel. -The module is found in the kmod sub-directory of the Intel=C2=AE DPDK ta= rget directory. -This module should be loaded using the insmod command as shown below (as= suming that the current directory is the Intel=C2=AE DPDK target director= y). +To run any DPDK application, the igb_uio module can be loaded into the r= unning kernel. +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). In many cases, the uio support in the Linux* kernel is compiled as a mod= ule rather than as part of the kernel, so it is often necessary to load the uio module first: =20 @@ -175,12 +175,12 @@ so it is often necessary to load the uio module fir= st: sudo modprobe uio sudo insmod kmod/igb_uio.ko =20 -Since Intel=C2=AE DPDK release 1.7 provides VFIO support, compilation an= d use of igb_uio module has become optional for platforms that support us= ing VFIO. +Since DPDK release 1.7 provides VFIO support, compilation and use of igb= _uio module has become optional for platforms that support using VFIO. =20 Loading VFIO Module ------------------- =20 -To run an Intel=C2=AE DPDK application and make use of VFIO, the vfio-pc= i module must be loaded: +To run an DPDK application and make use of VFIO, the vfio-pci module mus= t be loaded: =20 .. code-block:: console =20 @@ -192,22 +192,22 @@ however please consult your distributions documenta= tion to make sure that is the =20 Also, to use VFIO, both kernel and BIOS must support and be configured t= o use IO virtualization (such as Intel=C2=AE VT-d). =20 -For proper operation of VFIO when running Intel=C2=AE DPDK applications = as a non-privileged user, correct permissions should also be set up. -This can be done by using the Intel=C2=AE DPDK setup script (called setu= p.sh and located in the tools directory). +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 Binding and Unbinding Network Ports to/from the igb_uioor VFIO Modules ---------------------------------------------------------------------- =20 -As of release 1.4, Intel=C2=AE 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 Intel=C2=AE DPDK applicatio= n must be bound to the igb_uio or vfio-pci module before the application = is run. -Any network ports under Linux* control will be ignored by the Intel=C2=AE= DPDK poll-mode drivers and cannot be used by the application. +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 igb_uio or vfio-pci module before the application 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 Intel=C2=AE DPDK will, by default, no longer automatically unbin= d network ports from the kernel driver at startup. - Any ports to be used by an Intel=C2=AE DPDK application must be unbo= und from Linux* control and bound to the igb_uio or vfio-pci module befor= e the application is run. + 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 igb_uio or vfio-pci module before the applic= ation is run. =20 -To bind ports to the igb_uio or vfio-pci module for Intel=C2=AE DPDK use= , and then subsequently return ports to Linux* control, +To bind ports to the igb_uio or vfio-pci module for DPDK use, and then s= ubsequently 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 igb_uio and vfio-pci. diff --git a/doc/guides/linux_gsg/build_sample_apps.rst b/doc/guides/linu= x_gsg/build_sample_apps.rst index 0eec4b1..40d1eb7 100644 --- a/doc/guides/linux_gsg/build_sample_apps.rst +++ b/doc/guides/linux_gsg/build_sample_apps.rst @@ -31,7 +31,7 @@ Compiling and Running Sample Applications =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 =20 -The chapter describes how to compile and run applications in an Intel=C2= =AE DPDK environment. +The chapter describes how to compile and run applications in an DPDK env= ironment. It also provides a pointer to where sample applications are stored. =20 .. note:: @@ -41,20 +41,20 @@ It also provides a pointer to where sample applicatio= ns are stored. Compiling a Sample Application ------------------------------ =20 -Once an Intel=C2=AE 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 x86_= 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 Intel=C2=AE= DPDK, the following variables must be exported: +When compiling an application in the Linux* environment on the DPDK, the= following variables must be exported: =20 -* RTE_SDK - Points to the Intel=C2=AE DPDK installation directory. +* RTE_SDK - Points to the DPDK installation directory. =20 -* RTE_TARGET - Points to the Intel=C2=AE DPDK target environment directo= ry. +* 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 Intel=C2=AE DPDK Linux environment. +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. =20 -The directory contains the main.c file. This file, when combined with th= e libraries in the Intel=C2=AE DPDK target environment, -calls the various functions to initialize the Intel=C2=AE DPDK environme= nt, +The directory contains the main.c file. This file, when combined with th= e 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 @@ -74,8 +74,8 @@ By default, the binary is generated in the build direct= ory. =20 .. note:: =20 - In the above example, helloworld was in the directory structure of t= he Intel=C2=AE DPDK. - However, it could have been located outside the directory structure = to keep the Intel=C2=AE DPDK structure intact. + In the above example, helloworld was in the directory structure of t= he 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. =20 .. code-block:: console @@ -101,8 +101,8 @@ Running a Sample Application =20 Any ports to be used by the application must be already bound to the= igb_uio module, as described in Section 3.5, prior to running the applic= ation. =20 -The application is linked with the Intel=C2=AE DPDK target environment's= Environmental Abstraction Layer (EAL) library, -which provides some options that are generic to every Intel=C2=AE DPDK a= pplication. +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. =20 The following is the list of options that can be given to the EAL: =20 @@ -144,7 +144,7 @@ The EAL options are as follows: =20 The -c and the -n options are mandatory; the others are optional. =20 -Copy the Intel=C2=AE DPDK application binary to your target, then run th= e application as follows +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): =20 @@ -154,19 +154,19 @@ and that cores 0-3 are present and are to be used f= or running the application): =20 .. note:: =20 - The --proc-type and --file-prefix EAL options are used for running = multiple Intel=C2=AE DPDK processes. - See the =E2=80=9CMulti-process Sample Application=E2=80=9D chapter i= n the *Intel=C2=AE DPDK Sample Applications User Guide* and - the *Intel=C2=AE DPDK Programmers Guide* for more details. + 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. =20 Logical Core Use by Applications ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -The coremask parameter is always mandatory for Intel=C2=AE DPDK applicat= ions. +The coremask parameter is always mandatory for DPDK applications. Each bit of the mask corresponds to the equivalent logical core number a= s reported by Linux. Since these logical core numbers, and their mapping to specific cores on= specific NUMA sockets, can vary from platform to platform, 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 Intel=C2=AE DPDK application, t= he logical cores to be used and their socket location are displayed. +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. 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. @@ -189,7 +189,7 @@ 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 Intel=C2=AE DPDK application at startu= p, +This is done automatically by the DPDK application at startup, 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. @@ -202,7 +202,7 @@ If the user requests 128 MB of memory, the 64 pages m= ay not match the constraint 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. =20 -* These pages can be located anywhere in physical memory, and, althoug= h the Intel=C2=AE DPDK EAL will attempt to allocate memory in contiguous = blocks, +* 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. @@ -210,14 +210,14 @@ This is accomplished by supplying the --socket-mem = flag followed by amounts of m 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= . No memory will be reserved on any CPU socket that is not explicitly refe= renced, for example, socket 3 in this case. -If the Intel=C2=AE DPDK cannot allocate enough memory on each socket, th= e EAL initialization fails. +If the DPDK cannot allocate enough memory on each socket, the EAL initia= lization fails. =20 Additional Sample Applications ------------------------------ =20 Additional sample applications are included in the ${RTE_SDK}/examples d= irectory. These sample applications may be built and run in a manner similar to th= at described in earlier sections in this manual. -In addition, see the *Intel=C2=AE DPDK Sample Applications User Guide* f= or a description of the application, +In addition, see the *DPDK Sample Applications User Guide* for a descrip= tion of the application, specific instructions on compilation and execution and some explanation = of the code. =20 Additional Test Applications @@ -227,7 +227,7 @@ In addition, there are two other applications that ar= e built when the libraries The source files for these are in the DPDK/app directory and are called = test and testpmd. Once the libraries are created, they can be found in the build/app direc= tory. =20 -* The test application provides a variety of specific tests for the va= rious functions in the Intel=C2=AE DPDK. +* The test application provides a variety of specific tests for the va= rious functions in the DPDK. =20 * The testpmd application provides a number of different packet throug= hput tests and examples of features such as how to use the Flow Director found in t= he Intel=C2=AE 82599 10 Gigabit Ethernet Controller. diff --git a/doc/guides/linux_gsg/enable_func.rst b/doc/guides/linux_gsg/= enable_func.rst index 00c6d9e..3590000 100644 --- a/doc/guides/linux_gsg/enable_func.rst +++ b/doc/guides/linux_gsg/enable_func.rst @@ -58,7 +58,7 @@ If no entries are returned, HPET must be enabled in the= BIOS (as per the instruc Linux Kernel Support ~~~~~~~~~~~~~~~~~~~~ =20 -The Intel=C2=AE DPDK makes use of the platform HPET timer by mapping the= timer counter into the process address space, and as such, +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. =20 .. warning:: @@ -66,10 +66,10 @@ requires that the HPET_MMAP kernel configuration opti= on be enabled. 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 Intel=C2=AE DPDK +Enabling HPET in the DPDK ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 -By default, HPET support is disabled in the Intel=C2=AE DPDK build confi= guration files. +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= . =20 For an application to use the rte_get_hpet_cycles() and rte_get_hpet_hz(= ) API calls, @@ -86,13 +86,13 @@ The application can then determine what action to tak= e, if any, if the HPET is n 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(= ), if any, and on what is available on the system at runtime. =20 -Running Intel=C2=AE DPDK Applications Without Root Privileges +Running DPDK Applications Without Root Privileges -------------------------------------------------------- =20 -Although applications using the Intel=C2=AE DPDK use network ports and o= ther hardware resources directly, +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. 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 Intel=C2=AE DPDK applicatio= n has access to them: +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 =20 @@ -107,7 +107,7 @@ the Linux user account being used to run the Intel=C2= =AE DPDK application has access 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 Intel=C2=AE DPDK is to be used. +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. Consult the relevant BIOS documentation to determine how these settings = can be accessed. =20 @@ -122,25 +122,25 @@ In addition, C3 and C6 should be enabled as well fo= r power management. The path Using Linux* Core Isolation to Reduce Context Switches ------------------------------------------------------ =20 -While the threads used by an Intel=C2=AE DPDK application are pinned to = logical cores on the system, +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. =20 -For example, if Intel=C2=AE DPDK applications are to run on logical core= s 2, 4 and 6, +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: =20 .. code-block:: console =20 isolcpus=3D2,4,6 =20 -Loading the Intel=C2=AE DPDK KNI Kernel Module +Loading the DPDK KNI Kernel Module ----------------------------------------- =20 -To run the Intel=C2=AE DPDK Kernel NIC Interface (KNI) sample applicatio= n, an extra kernel module (the kni module) must be loaded into the runnin= g kernel. -The module is found in the kmod sub-directory of the Intel=C2=AE DPDK ta= rget directory. +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 -(assuming that the current directory is the Intel=C2=AE DPDK target dire= ctory): +(assuming that the current directory is the DPDK target directory): =20 .. code-block:: console =20 @@ -148,10 +148,10 @@ Similar to the loading of the igb_uio module, this = module should be loaded using =20 .. note:: =20 - See the =E2=80=9CKernel NIC Interface Sample Application=E2=80=9D ch= apter in the *Intel=C2=AE DPDK Sample Applications User Guide* for more d= etails. + See the =E2=80=9CKernel NIC Interface Sample Application=E2=80=9D ch= apter in the *DPDK Sample Applications User Guide* for more details. =20 -Using Linux IOMMU Pass-Through to Run Intel=C2=AE DPDK with Intel=C2=AE = VT-d ------------------------------------------------------------------- +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 @@ -161,7 +161,7 @@ To enable Intel=C2=AE VT-d in a Linux kernel, a numbe= r of kernel configuration optio =20 * INTEL_IOMMU =20 -In addition, to run the Intel=C2=AE DPDK with Intel=C2=AE VT-d, the iomm= u=3Dpt kernel parameter must be used when using igb_uio driver. +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. 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. This ensures that the Intel IOMMU is being initialized as expected. diff --git a/doc/guides/linux_gsg/intro.rst b/doc/guides/linux_gsg/intro.= rst index 6bcc80b..a6ee188 100644 --- a/doc/guides/linux_gsg/intro.rst +++ b/doc/guides/linux_gsg/intro.rst @@ -31,37 +31,37 @@ Introduction =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -This document contains instructions for installing and configuring the I= ntel=C2=AE Data Plane Development Kit (Intel=C2=AE DPDK) software. +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 an Intel=C2=AE DPDK applic= ation in a Linux* 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 --------------------- =20 -The following is a list of Intel=C2=AE DPDK documents in the suggested r= eading order: +The following is a list of DPDK documents in the suggested reading order= : =20 * Release Notes: Provides release-specific information, including supp= orted features, limitations, fixed issues, known issues and so on. Also, provides the answers to frequently asked questions in FAQ form= at. =20 -* Getting Started Guide (this document): Describes how to install and = configure the Intel=C2=AE DPDK; designed to get users up and running quic= kly with the software. +* Getting Started Guide (this document): Describes how to install and = configure the DPDK; designed to get users up and running quickly with the= software. =20 * Programmer's Guide: Describes: =20 * The software architecture and how to use it (through examples), = specifically in a Linux* application (linuxapp) environment =20 - * The content of the Intel=C2=AE DPDK, the build system (including= the commands that can be used in the root Intel=C2=AE DPDK Makefile to b= uild the development kit and + * 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 =20 * Optimizations used in the software and those that should be cons= idered for new development =20 A glossary of terms is also provided. =20 -* API Reference: Provides detailed information about Intel=C2=AE DPDK = functions, data structures and other programming constructs. +* API Reference: Provides detailed information about DPDK functions, d= ata structures and other programming constructs. =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. =20 .. note:: =20 - These documents are available for download as a separate documentati= on package at the same location as the Intel=C2=AE DPDK code package. + 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 98815dd..d4652df 100644 --- a/doc/guides/linux_gsg/quick_start.rst +++ b/doc/guides/linux_gsg/quick_start.rst @@ -33,17 +33,17 @@ Quick Start Setup Script =20 The setup.sh script, found in the tools subdirectory, allows the user to= perform the following tasks: =20 -* Build the Intel=C2=AE DPDK libraries +* Build the DPDK libraries =20 -* Insert and remove the Intel=C2=AE DPDK IGB_UIO kernel module +* Insert and remove the DPDK IGB_UIO kernel module =20 * Insert and remove VFIO kernel modules =20 -* Insert and remove the Intel=C2=AE DPDK KNI kernel module +* Insert and remove the DPDK KNI kernel module =20 * Create and delete hugepages for NUMA and non-NUMA cases =20 -* View network port status and reserve ports for Intel=C2=AE DPDK appl= ication use +* View network port status and reserve ports for DPDK application use =20 * Set up permissions for using VFIO as a non-privileged user =20 @@ -53,10 +53,10 @@ The setup.sh script, found in the tools subdirectory,= allows the user to perform =20 * List hugepages in /mnt/huge =20 -* Remove built Intel=C2=AE DPDK libraries +* Remove built DPDK libraries =20 Once these steps have been completed for one of the EAL targets, -the user may compile their own application that links in the EAL librari= es to create the Intel=C2=AE DPDK image. +the user may compile their own application that links in the EAL librari= es to create the DPDK image. =20 Script Organization ------------------- @@ -67,22 +67,22 @@ The following is a brief synopsis of each step. =20 **Step 1: Build DPDK Libraries** =20 -Initially, the user must select an Intel=C2=AE DPDK target to choose the= correct target type and compiler options to use when building the librar= ies. +Initially, the user must select a DPDK target to choose the correct targ= et type and compiler options to use when building the libraries. =20 The user must have all libraries, modules, updates and compilers install= ed in the system prior to this, as described in the earlier chapters in this Getting Started Guide. =20 **Step 2: Setup Environment** =20 -The user configures the Linux* environment to support the running of Int= el=C2=AE DPDK applications. +The user configures the Linux* environment to support the running of DPD= K applications. Hugepages can be set up for NUMA or non-NUMA systems. Any existing hugep= ages will be removed. -The Intel=C2=AE DPDK kernel module that is needed can also be inserted i= n this step, -and network ports may be bound to this module for Intel=C2=AE DPDK appli= cation use. +The DPDK kernel module that is needed can also be inserted in this step, +and network ports may be bound to this module for DPDK application use. =20 **Step 3: Run an Application** =20 The user may run the test application once the other steps have been per= formed. -The test application allows the user to run a series of functional tests= for the Intel=C2=AE DPDK. +The test application allows the user to run a series of functional tests= for the DPDK. The testpmd application, which supports the receiving and sending of pac= kets, can also be run. =20 **Step 4: Examining the System** @@ -202,7 +202,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 Intel=C2=AE DPDK library. +The following selection demonstrates the creation of the x86_64-native-l= inuxapp-gcc DPDK library. =20 .. code-block:: console =20 @@ -218,7 +218,7 @@ The following selection demonstrates the creation of = the x86_64-native-linuxapp- Build complete RTE_TARGET exported as x86_64-native -linuxapp-gcc =20 -The following selection demonstrates the starting of the Intel=C2=AE DPD= K UIO driver. +The following selection demonstrates the starting of the DPDK UIO driver= . =20 .. code-block:: console =20 @@ -272,7 +272,7 @@ Applications Once the user has run the setup.sh script, built one of the EAL targets = and set up hugepages (if using one of the Linux EAL targets), the user can then move on to building and running their application or o= ne of the examples provided. =20 -The examples in the /examples directory provide a good starting point to= gain an understanding of the operation of the Intel=C2=AE DPDK. +The examples in the /examples directory provide a good starting point to= gain an understanding of the operation of the DPDK. The following command sequence shows how the helloworld sample applicati= on is built and run. As recommended in Section 4.2.1 , "Logical Core Use by Applications", the logical core layout of the platform should be determined when select= ing a core mask to use for an application. diff --git a/doc/guides/linux_gsg/sys_reqs.rst b/doc/guides/linux_gsg/sys= _reqs.rst index f712bec..8e2307b 100644 --- a/doc/guides/linux_gsg/sys_reqs.rst +++ b/doc/guides/linux_gsg/sys_reqs.rst @@ -31,31 +31,31 @@ System Requirements =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 -This chapter describes the packages required to compile the Intel=C2=AE = DPDK. +This chapter describes the packages required to compile the DPDK. =20 .. note:: =20 - If the Intel=C2=AE DPDK is being used on an Intel=C2=AE Communicatio= ns Chipset 89xx Series platform, + 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*. =20 BIOS Setting Prerequisite on x86 -------------------------------- =20 -For the majority of platforms, no special BIOS settings are needed to us= e basic Intel=C2=AE DPDK functionality. +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 ` for more information on the required changes. =20 -Compilation of the Intel=C2=AE DPDK ------------------------------- +Compilation of the DPDK +----------------------- =20 **Required Tools:** =20 .. note:: =20 Testing has been performed using Fedora* 18. The setup commands and = installed packages needed on other systems may be different. - For details on other Linux distributions and the versions tested, pl= ease consult the Intel=C2=AE DPDK Release Notes. + For details on other Linux distributions and the versions tested, pl= ease consult the DPDK Release Notes. =20 * GNU make =20 @@ -78,7 +78,7 @@ Compilation of the Intel=C2=AE DPDK =20 glibc.ppc64, libgcc.ppc64, libstdc++.ppc64 and glibc-devel.ppc64 for= IBM ppc_64; =20 -* Python, version 2.6 or 2.7, to use various helper scripts included i= n the Intel=C2=AE DPDK package +* Python, version 2.6 or 2.7, to use various helper scripts included i= n the DPDK package =20 =20 **Optional Tools:** @@ -94,10 +94,10 @@ Compilation of the Intel=C2=AE DPDK * 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. =20 -Running Intel=C2=AE DPDK Applications --------------------------------- +Running DPDK Applications +------------------------- =20 -To run an Intel=C2=AE DPDK application, some customization may be requir= ed on the target machine. +To run an DPDK application, some customization may be required on the ta= rget machine. =20 System Software ~~~~~~~~~~~~~~~ @@ -112,8 +112,8 @@ System Software =20 uname -r =20 -For details of the patches needed to use the Intel=C2=AE DPDK with earli= er kernel versions, -see the Intel=C2=AE DPDK FAQ included in the *Intel=C2=AE DPDK Release N= otes*. +For details of the patches needed to use the DPDK with earlier kernel ve= rsions, +see the DPDK FAQ included in the *DPDK Release Notes*. Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.32 kernel that alre= ady has all the necessary patches applied. =20 * glibc >=3D 2.7 (for features related to cpuset) @@ -133,9 +133,9 @@ Note also that Redhat* Linux* 6.2 and 6.3 uses a 2.6.= 32 kernel that already has * Kernel configuration =20 In the Fedora* OS and other common distributions, such as Ubuntu*, o= r RedHat Enterprise Linux*, - the vendor supplied kernel configurations can be used to run most In= tel=C2=AE DPDK applications. + 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 Intel=C2= =AE DPDK include: + For other kernel builds, options which should be enabled for DPDK in= clude: =20 * UIO support =20 @@ -156,8 +156,8 @@ and therefore less Translation Lookaside Buffers (TLB= s, high speed translation c which reduce the time it takes to translate a virtual page address to a = physical page address. Without hugepages, high TLB miss rates would occur with the standard 4k = page size, slowing performance. =20 -Reserving Hugepages for Intel=C2=AE DPDK Use -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. @@ -214,10 +214,10 @@ On a NUMA machine, pages should be allocated explic= itly on separate nodes: =20 For 1G pages, it is not possible to reserve the hugepage memory afte= r the system has booted. =20 -Using Hugepages with the Intel=C2=AE DPDK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Using Hugepages with the DPDK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -Once the hugepage memory is reserved, to make the memory available for I= ntel=C2=AE DPDK use, perform the following steps: +Once the hugepage memory is reserved, to make the memory available for D= PDK use, perform the following steps: =20 .. code-block:: console =20 @@ -240,26 +240,26 @@ Xen Domain0 Support in the Linux* Environment ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ =20 The existing memory management implementation is based on the Linux* ker= nel hugepage mechanism. -On the Xen hypervisor, hugepage support for DomainU (DomU) Guests means = that Intel=C2=AE DPDK applications work as normal for guests. +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. To work around this limitation, a new kernel module rte_dom0_mm is added= to facilitate the allocation and mapping of memory via **IOCTL** (allocation) and **MMAP** (mapping). =20 -Enabling Xen Dom0 Mode in the Intel=C2=AE DPDK -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Enabling Xen Dom0 Mode in the DPDK +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -By default, Xen Dom0 mode is disabled in the Intel=C2=AE DPDK build conf= iguration files. +By default, Xen Dom0 mode is disabled in the DPDK build configuration fi= les. To support Xen Dom0, the CONFIG_RTE_LIBRTE_XEN_DOM0 setting should be ch= anged to =E2=80=9Cy=E2=80=9D, which enables the Xen Dom0 mode at compile = time. =20 Furthermore, the CONFIG_RTE_EAL_ALLOW_INV_SOCKET_ID setting should also = be changed to =E2=80=9Cy=E2=80=9D in the case of the wrong socket ID bein= g received. =20 -Loading the Intel=C2=AE DPDK rte_dom0_mm Module -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Loading the DPDK rte_dom0_mm Module +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -To run any Intel=C2=AE DPDK application on Xen Dom0, the rte_dom0_mm mod= ule must be loaded into the running kernel with rsv_memsize option. -The module is found in the kmod sub-directory of the Intel=C2=AE DPDK ta= rget directory. -This module should be loaded using the insmod command as shown below (as= suming that the current directory is the Intel=C2=AE DPDK target director= y): +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): =20 .. code-block:: console =20 @@ -267,8 +267,8 @@ This module should be loaded using the insmod command= as shown below (assuming t =20 The value X cannot be greater than 4096(MB). =20 -Configuring Memory for Intel=C2=AE DPDK Use -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. @@ -290,7 +290,7 @@ Xen Domain0 does not support NUMA configuration, as a= result the --socket-mem co =20 The memsize value cannot be greater than the rsv_memsize value. =20 -Running the Intel=C2=AE DPDK Application on Xen Domain0 -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Running the DPDK Application on Xen Domain0 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ =20 -To run the Intel=C2=AE 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.1.0