From: yasufum.o@gmail.com
To: spp@dpdk.org, ferruh.yigit@intel.com, yasufum.o@gmail.com
Subject: [spp] [PATCH] readme: update README
Date: Mon, 1 Jul 2019 13:12:32 +0900 [thread overview]
Message-ID: <20190701041232.34122-1-yasufum.o@gmail.com> (raw)
From: Yasufumi Ogawa <yasufum.o@gmail.com>
This patch is to `README.md` on project root for adding new features
such as `launch` command or `config`.
Signed-off-by: Yasufumi Ogawa <yasufum.o@gmail.com>
---
README.md | 213 +++++++++++++++++++++++++++++++++++++++++-------------
1 file changed, 161 insertions(+), 52 deletions(-)
diff --git a/README.md b/README.md
index 4ede2f2..e1085e0 100644
--- a/README.md
+++ b/README.md
@@ -23,43 +23,40 @@ with patch panel like simple interface.
## Architecture Overview
-The framework is composed of a primary DPDK application that is
-responsible for resource management and secondary processes as workers
-for packet forwarding. This primary application doesn't
-interact with any traffic, and is used to manage creation and freeing of
-resources only.
-
-A Python based management interfaces, `spp-ctl` and `SPP CLI`,
-are provided to control the primary DPDK application to create resources,
-which are then to be used by secondary applications.
-
-This management application provides a socket based interface for
-the primary and secondary DPDK applications to
-interface to the manager.
+SPP is a kind of DPDK
+[multi-process application](https://doc.dpdk.org/guides/prog_guide/multi_proc_support.html).
+It is composed of primary process which is responsible for resource
+management, and secondary processes as workers for packet forwarding.
+This primary process does not interact with any traffic. It is
+responsible for creation and freeing of resources shared among other
+secondary processes.
+
+A Python based management interface called SPP controller consists of
+`spp-ctl` and `SPP CLI`.
+`SPP CLI` is a command line interface of SPP, and `spp-ctl` a backend
+server for managing primary and secondary processes.
+`spp-ctl` behaves as a REST API server and `SPP CLI` sends a command via
+the REST API.
## Install
-Before using SPP, you need to install DPDK. Briefly describ here how to install
-and setup DPDK. Please refer to SPP's
+Before using SPP, you need to install DPDK. Briefly describ here how to
+install and setup DPDK. Please refer to SPP's
[Getting Started](https://doc.dpdk.org/spp/setup/getting_started.html) guide
for more details. For DPDK, refer to
[Getting Started Guide for Linux](https://doc.dpdk.org/guides/linux_gsg/index.html).
-### Install DPDK
-
-It is required to install Python and libnuma-devel library before.
+It is required to install Python3 and libnuma-devel library before.
+SPP does not support Python2 anymore.
```sh
-$ sudo apt install libnuma-dev
-
-# Python2
-$ sudo apt install python python-pip
-
-# Python3
$ sudo apt install python3 python3-pip
+$ sudo apt install libnuma-dev
```
+### DPDK
+
Clone repository and compile DPDK in any directory.
```
@@ -76,7 +73,7 @@ $ export RTE_TARGET=x86_64-native-linuxapp-gcc # depends on your env
$ make install T=$RTE_TARGET
```
-### Install SPP
+### SPP
Clone repository and compile SPP in any directory.
@@ -89,12 +86,13 @@ $ 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.
+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.
-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.
+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.
```sh
# Activate uio_pci_generic
@@ -104,8 +102,9 @@ $ sudo modprobe uio_pci_generic
$ sudo modprobe vfio-pci
```
-Once UIO driver is activated, bind network ports with the driver. DPDK provides
-`usertools/dpdk-devbind.py` for managing devices.
+Once UIO driver is activated, bind network ports with the driver.
+DPDK provides `usertools/dpdk-devbind.py` for managing devices.
+Here are some examples.
```
# Bind a port with 2a:00.0 (PCI address)
@@ -115,8 +114,8 @@ $ ./usertools/dpdk-devbind.py --bind=uio_pci_generic 2a:00.0
$ ./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`.
+After binding a port, you can find it is under the DPDK driver,
+and cannot find it by using `ifconfig` or `ip`.
```sh
$ $RTE_SDK/usertools/dpdk-devbind.py -s
@@ -129,43 +128,154 @@ Network devices using DPDK-compatible driver
## How to Use
-You should keep in mind the order of launching processes. Primary process must
-be launched before secondary processes. `spp-ctl` need to be launched before
-`spp.py`, but no need to be launched before other processes.
-In general, `spp-ctl` should be launched first, then `spp.py` and `spp_primary`
-in each of terminals without running as background process.
+You can use SPP from `bin/start.sh` script or launching each of
+processes manually. This startup script is provided for skipping to
+input many options for multiple DPDK applications.
+
+### Quick Start
+
+Start with `bin/start.sh` with configuration file `bin/config.sh`.
+First time you run the startup script, it generates the config file
+and asks to edit the config without launchin processes.
+
+Here is a part of config parameters. You do not need to change most of
+params.
+If you do not have physical NICs on your server, activate
+`PRI_VHOST_IDS` which is for setting up vhost interfaces instead of
+physical.
+
+```sh
+SPP_HOST_IP=127.0.0.1
+SPP_HUGEPAGES=/dev/hugepages
+
+# spp_primary options
+LOGLEVEL=7 # change to 8 if you refer debug messages.
+PRI_CORE_LIST=0 # required one lcore usually.
+PRI_MEM=1024
+PRI_MEMCHAN=4 # change for your memory channels.
+NUM_RINGS=8
+PRI_PORTMASK=0x03 # total num of ports of spp_primary.
+#PRI_VHOST_IDS=(11 12) # you use if you have no phy ports.
+```
+
+After you edit configuration, you can launch `spp-ctl`,
+`spp_primary` and `SPP CLI` from startup script.
+
+```sh
+$ ./bin/start.sh
+Start spp-ctl
+Start spp_primary
+Waiting for spp-ctl is ready ...
+Welcome to the SPP CLI. Type `help` or `?` to list commands.
+
+spp >
+```
+
+Check status of `spp_primary` because it takes several seconds to be
+ready. Confirm that the status is `running`.
+
+```sh
+spp > status
+- spp-ctl:
+ - address: 127.0.0.1:7777
+- primary:
+ - status: running
+- secondary:
+ - processes:
+```
+
+Now you are ready to launch secondary processes from `pri; launch`
+command, or another terminal.
+Here is an example for launching `spp_nfv` with options from
+`pri; launch`. Log file of this process is created as
+`log/spp_nfv1.log`.
+
+```sh
+spp > pri; launch nfv 1 -l 1,2 -m 512 -- -n 1 -s 127.0.0.1:6666
+```
-It has a option -b for binding address explicitly to be accessed from other
-than default, `127.0.0.1` or `localhost`.
+This `launch` command supports TAB completion. Parameters for `spp_nfv`
+are completed after secondary ID `1`.
+```sh
+spp > pri; launch nfv 1
-### SPP Controller
+# Press TAB
+spp > pri; launch nfv 1 -l 1,2 -m 512 -- -n 1 -s 127.0.0.1:6666
+```
+
+It is same as following options launching from terminal.
+
+```sh
+$ sudo ./src/nfv/x86_64-native-linuxapp-gcc/spp_nfv \
+ -l 1,2 -n 4 -m 512 \
+ --proc-type secondary \
+ -- \
+ -n 1 \
+ -s 127.0.0.1:6666
+```
+
+Parameters for completion are defined in `SPP CLI`, and you can find
+parameters with `config` command.
+
+```sh
+spp > config
+- max_secondary: "16" # The maximum number of secondary processes
+- prompt: "spp > " # Command prompt
+- topo_size: "60%" # Percentage or ratio of topo
+- sec_mem: "-m 512" # Mem size
+...
+```
+
+You can launch consequence secondary processes from CLI.
+
+```sh
+spp > pri; launch nfv 2 -l 1,3 -m 512 -- -n 2 -s 127.0.0.1:6666
+spp > pri; launch vf 3 -l 1,4,5,6 -m 512 -- -n 3 -s 127.0.0.1:6666
+...
+```
+
+### Startup Manually
+
+You should keep in mind the order of launching processes if you launch
+processes without using startup script.
+`spp-ctl` should be launched before all of other processes. Then,
+primary process must be launched before secondary processes.
+On the other hand, you can launch SPP CLI `spp.py` in any time
+after `spp-ctl`. In general, `spp-ctl` is launched first,
+then `spp.py`, `spp_primary` and secondary processes.
+
+It has a option -b for binding address explicitly to be accessed from
+other than default, `127.0.0.1` or `localhost`.
+
+In the following example, processes are launched in different terminals
+for describing options, although you can launch them with
+`pri; launch` command.
+
+#### SPP Controller
SPP controller consists of `spp-ctl` and SPP CLI.
`spp-ctl` is a HTTP server for REST APIs for managing SPP processes.
```sh
# terminal 1
-$ cd /path/to/spp
$ python3 src/spp-ctl/spp-ctl -b 192.168.1.100
```
-SPP CLI is a client of `spp-ctl` for providing simple user interface without
-using REST APIs.
+SPP CLI is a client of `spp-ctl` for providing simple user interface
+without using REST APIs.
```sh
# terminal 2
-$ cd /path/to/spp
$ python3 src/spp.py -b 192.168.1.100
```
-
-### SPP Primary
+#### SPP Processes
Launch SPP primary and secondary processes.
-SPP primary is a resource manager and initializing EAL for secondary processes.
-Secondary process behaves as a client of primary process and a worker for doing
-tasks.
+SPP primary is a resource manager and initializing EAL for secondary
+processes. Secondary process behaves as a client of primary process
+and a worker for doing tasks.
```sh
# terminal 3
@@ -185,7 +295,6 @@ one.
```sh
# terminal 4
-$ cd /path/to/spp
$ sudo ./src/nfv/x86_64-native-linuxapp-gcc/spp_nfv \
-l 2-3 -n 4 \
--proc-type=secondary \
--
2.17.1
reply other threads:[~2019-07-01 4:12 UTC|newest]
Thread overview: [no followups] expand[flat|nested] mbox.gz Atom feed
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=20190701041232.34122-1-yasufum.o@gmail.com \
--to=yasufum.o@gmail.com \
--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).