From: ogawa.yasufumi@lab.ntt.co.jp
To: spp@dpdk.org, ferruh.yigit@intel.com
Cc: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Subject: [spp] [PATCH 09/15] docs: update getting_started section
Date: Thu, 1 Feb 2018 13:04:55 +0900 [thread overview]
Message-ID: <20180201040501.8004-9-ogawa.yasufumi@lab.ntt.co.jp> (raw)
In-Reply-To: <20180201040501.8004-1-ogawa.yasufumi@lab.ntt.co.jp>
From: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
Add explanation for setting up hugepages and binding network ports.
Signed-off-by: Yasufumi Ogawa <ogawa.yasufumi@lab.ntt.co.jp>
---
docs/guides/setup/getting_started.rst | 240 ++++++++++++++++++++++++++++++++++
1 file changed, 240 insertions(+)
diff --git a/docs/guides/setup/getting_started.rst b/docs/guides/setup/getting_started.rst
index b24666a..04df517 100644
--- a/docs/guides/setup/getting_started.rst
+++ b/docs/guides/setup/getting_started.rst
@@ -1,3 +1,5 @@
+.. _getting_started:
+
.. BSD LICENSE
Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
All rights reserved.
@@ -31,3 +33,241 @@
Getting Started
===============
+
+Setup
+-----
+
+Reserving Hugepages
+~~~~~~~~~~~~~~~~~~~
+
+Hugepages must be enabled for running DPDK with high performance.
+Hugepage support is required to reserve large amount size of pages,
+2MB or 1GB per page, to less TLB (Translation Lookaside Buffers) and
+to reduce cache miss.
+Less TLB means that it reduce the time for translating virtual address
+to physical.
+
+Hugepage reservation might be different for 2MB or 1GB.
+
+For 1GB page, hugepage setting must be activated while booting system.
+It must be defined in boot loader configuration, usually is
+``/etc/default/grub``.
+Add an entry to define pagesize and the number of pages.
+Here is an example. `` hugepagesz`` is for the size and ``hugepages``
+is for the number of pages.
+
+.. code-block:: console
+
+ GRUB_CMDLINE_LINUX="default_hugepagesz=1G hugepagesz=1G hugepages=8"
+
+.. note::
+
+ 1GB hugepages might not be supported in your machine. It depends on
+ that CPUs support 1GB pages or not. You can check it by referring
+ ``/proc/cpuinfo``. If it is supported, you can find ``pdpe1gb`` in
+ the ``flags`` attribute.
+
+ .. code-block:: console
+
+ $ cat /proc/cpuinfo | pdpe1gb
+
+For 2MB page, you can activate hugepages while booting or at anytime
+after system is booted.
+Define hugepages setting in ``/etc/default/grub`` to activate it while
+booting, or overwrite the number of 2MB hugepages as following.
+
+.. code-block:: console
+
+ $ echo 1024 > /sys/kernel/mm/hugepages/hugepages-2048kB/nr_hugepages
+
+In this case, 1024 pages of 2MB (totally 2048 MB) are reserved.
+
+
+Mount hugepages
+~~~~~~~~~~~~~~~
+
+Make the memory available for using hugepages from DPDK.
+
+.. code-block:: console
+
+ mkdir /mnt/huge
+ mount -t hugetlbfs nodev /mnt/huge
+
+It is also available while booting by adding a configuration of mount
+point in ``/etc/fstab``, or after booted.
+
+The mount point for 2MB or 1GB can be made permanent accross reboot.
+For 2MB, it is no need to declare the size of hugepages explicity.
+
+.. code-block:: console
+
+ nodev /mnt/huge hugetlbfs defaults 0 0
+
+For 1GB, the size of hugepage must be specified.
+
+.. code-block:: console
+
+ nodev /mnt/huge_1GB hugetlbfs pagesize=1GB 0 0
+
+
+Install DPDK and SPP
+--------------------
+
+Before using SPP, you need to install DPDK.
+In this document, briefly describ how to install and setup DPDK.
+Refer to `DPDK documentation
+<https://dpdk.org/doc/guides/>`_ for more details.
+For Linux, see `Getting Started Guide for Linux
+<http://www.dpdk.org/doc/guides/linux_gsg/index.html>`_ .
+
+First, download and compile DPDK in any directory.
+Compiling DPDK takes a few minutes.
+
+.. code-block:: console
+
+ $ cd /path/to/any
+ $ git clone http://dpdk.org/git/dpdk
+ $ cd dpdk
+ $ export RTE_SDK=$(pwd)
+ $ export RTE_TARGET=x86_64-native-linuxapp-gcc # depends on your env
+ $ make install T=$RTE_TARGET
+
+Then, download and compile SPP in any directory.
+
+.. code-block:: console
+
+ $ cd /path/to/any
+ $ git clone http://dpdk.org/git/apps/spp
+ $ cd spp
+ $ make # Confirm that $RTE_SDK and $RTE_TARGET are set
+
+
+Binding Network Ports to DPDK
+-----------------------------
+
+Network ports must be bound to DPDK with a UIO (Userspace IO) driver.
+UIO driver is for mapping device memory to userspace and registering
+interrupts.
+
+UIO Drivers
+~~~~~~~~~~~
+
+You usually use the standard ``uio_pci_generic`` for many use cases
+or ``vfio-pci`` for more robust and secure cases.
+Both of drivers are included by default in modern Linux kernel.
+
+.. code-block:: console
+
+ # Activate uio_pci_generic
+ $ sudo modprobe uio_pci_generic
+
+ # or vfio-pci
+ $ sudo modprobe vfio-pci
+
+You can also use kmod included in DPDK instead of ``uio_pci_generic``
+or ``vfio-pci``.
+
+.. code-block:: console
+
+ sudo modprobe uio
+ sudo insmod kmod/igb_uio.ko
+
+Binding Network Ports
+~~~~~~~~~~~~~~~~~~~~~
+
+Once UIO driver is activated, bind network ports with the driver.
+DPDK provides ``usertools/dpdk-devbind.py`` for managing devices.
+
+Find ports for binding to DPDK by running the tool with ``-s`` option.
+
+.. code-block:: console
+
+ $ $RTE_SDK/usertools/dpdk-devbind.py --status
+
+ Network devices using DPDK-compatible driver
+ ============================================
+ <none>
+
+ Network devices using kernel driver
+ ===================================
+ 0000:29:00.0 '82571EB Gigabit Ethernet Controller (Copper) 10bc' if=enp41s0f0 drv=e1000e unused=
+ 0000:29:00.1 '82571EB Gigabit Ethernet Controller (Copper) 10bc' if=enp41s0f1 drv=e1000e unused=
+ 0000:2a:00.0 '82571EB Gigabit Ethernet Controller (Copper) 10bc' if=enp42s0f0 drv=e1000e unused=
+ 0000:2a:00.1 '82571EB Gigabit Ethernet Controller (Copper) 10bc' if=enp42s0f1 drv=e1000e unused=
+
+ Other Network devices
+ =====================
+ <none>
+ ....
+
+You can find network ports are bound to kernel driver and not to DPDK.
+To bind a port to DPDK, run ``dpdk-devbind.py`` with specifying a driver
+and a device ID.
+Device ID is a PCI address of the device or more friendly style like
+``eth0`` found by ``ifconfig`` or ``ip`` command..
+
+.. code-block:: console
+
+ # Bind a port with 2a:00.0 (PCI address)
+ ./usertools/dpdk-devbind.py --bind=uio_pci_generic 2a:00.0
+
+ # or eth0
+ ./usertools/dpdk-devbind.py --bind=uio_pci_generic eth0
+
+
+After binding two ports, you can find it is under the DPDK driver and
+cannot find it by using ``ifconfig`` or ``ip``.
+
+.. code-block:: console
+
+ $ $RTE_SDK/usertools/dpdk-devbind.py -s
+
+ Network devices using DPDK-compatible driver
+ ============================================
+ 0000:2a:00.0 '82571EB Gigabit Ethernet Controller (Copper) 10bc' drv=uio_pci_generic unused=vfio-pci
+ 0000:2a:00.1 '82571EB Gigabit Ethernet Controller (Copper) 10bc' drv=uio_pci_generic unused=vfio-pci
+
+ Network devices using kernel driver
+ ===================================
+ 0000:29:00.0 '82571EB Gigabit Ethernet Controller (Copper) 10bc' if=enp41s0f0 drv=e1000e unused=vfio-pci,uio_pci_generic
+ 0000:29:00.1 '82571EB Gigabit Ethernet Controller (Copper) 10bc' if=enp41s0f1 drv=e1000e unused=vfio-pci,uio_pci_generic
+
+ Other Network devices
+ =====================
+ <none>
+ ....
+
+
+Run DPDK Sample Application
+---------------------------
+
+You had better to run DPDK sample application before SPP
+as checking DPDK is setup properly.
+
+Try ``l2fwd`` as an example.
+
+.. code-block:: console
+
+ $ cd $RTE_SDK/examples/l2fwd
+ $ make
+ CC main.o
+ LD l2fwd
+ INSTALL-APP l2fwd
+ INSTALL-MAP l2fwd.map
+
+In this case, run this application with two options.
+
+ - -c: core mask
+ - -p: port mask
+
+.. code-block:: console
+
+ $ sudo ./build/app/l2fwd \
+ -c 0x03 \
+ -- -p 0x3
+
+It must be separated with ``--`` to specify which option is
+for EAL or application.
+Refer to `L2 Forwarding Sample Application
+<https://dpdk.org/doc/guides/sample_app_ug/l2_forward_real_virtual.html>`_
+for more details.
--
2.7.4
next prev parent reply other threads:[~2018-02-01 4:05 UTC|newest]
Thread overview: 17+ messages / expand[flat|nested] mbox.gz Atom feed top
2018-02-01 4:04 [spp] [PATCH 01/15] docs: add rst docs ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 02/15] docs: add overview ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 03/15] docs: add primary commands ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 04/15] docs: add common commands ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 05/15] docs: add secondary commands ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 06/15] docs: add descriptions for pri commands ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 07/15] docs: fix erata of help command ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 08/15] docs: revise index in setup chapter ogawa.yasufumi
2018-02-01 4:04 ` ogawa.yasufumi [this message]
2018-02-01 4:04 ` [spp] [PATCH 10/15] docs: update howto_use section ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 11/15] docs: add performance_opt section ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 12/15] docs: update use_cases section ogawa.yasufumi
2018-02-01 4:04 ` [spp] [PATCH 13/15] docs: update overview section ogawa.yasufumi
2018-02-01 4:05 ` [spp] [PATCH 14/15] docs: add compile script for rst documentation ogawa.yasufumi
2018-02-01 4:05 ` [spp] [PATCH 15/15] makefile: add target for compile rst documents ogawa.yasufumi
2018-02-05 2:34 ` [spp] [PATCH 01/15] docs: add rst docs Yasufumi Ogawa
2018-02-06 15:22 ` Ferruh Yigit
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20180201040501.8004-9-ogawa.yasufumi@lab.ntt.co.jp \
--to=ogawa.yasufumi@lab.ntt.co.jp \
--cc=ferruh.yigit@intel.com \
--cc=spp@dpdk.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).