diff --git a/README.md b/README.md index 3b14b2e..3e34c8d 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,21 @@ # NBA (Network Balancing Act) "A High-performance packet processing framework for heterogeneous processors," [EuroSys 2015 paper](http://an.kaist.ac.kr/~sbmoon/paper/intl-conf/2015-eurosys-nba.pdf) -## Disclaimer +## Notice for paper readers * The IDS source code is not available to the public, as it contains a derivation from industry-transferred code from [Kargus](http://shader.kaist.edu/kargus/). - You could refer to other open-source code, such as [a GPU implementation of the Aho-Corasick algorithm in Snap](https://github.com/wbsun/g4c/blob/master/g4c_ac.h). -* We used Intel DPDK v1.7 for the EuroSys 2015 paper, but have now upgraded to v1.8. +* We used Intel DPDK v1.7 for the EuroSys 2015 paper, but have now upgraded to v2.0+. -## How to compile +## Main Features -We recommend to use Ubuntu 14.04 or newer. -First you need to install some prerequisites. +* 80-Gbps packet processing with modular programming interface similar to Click. +* GPU offloading to boost complex computations such as IPsec encryption +* Automatic CPU/GPU load balancing to maximize the overall throughput -* NVIDIA CUDA 7.0 or newer - - We recommend to download the latest version of `.bin` package from [the NVIDIA website](https://developer.nvidia.com/cuda-downloads) instead of using system packages. - - A small daemon is required to "pin" GPU's interrupts to specific cores. - See details in https://gist.github.com/3404967 . - - Add `export PATH=$PATH:/usr/local/cuda/bin` to `/etc/profile` or similar places. - - Add `/usr/local/cuda/lib64` to `/etc/ld.so.conf.d/cuda.conf` (create if not exists) and run `ldconfig`. -* g++ 4.8 or newer (the compiler must support C++11 standard.) -* Intel DPDK 1.8 - - Clone from git://dpdk.org/dpdk or download the release tarball. - - Install the kernel header/source packages first. - - Run `make install T=x86_64-native-linuxapp-gcc` in the checked-out directory. -* Python 3.4 or newer - - `pip install snakemake` - - `apt-get install libpython3-dev` -* Click configuration parser - - Just run `git submodule init && git submodule update` - - It will be *automatically built* along with NBA when you first build NBA. -* `sysstat` package (or any package that offers `mpstat` command) to run experiment scripts -* If all set, then set the environment variable as follows: - - `USE_CUDA=1` - - `NBA_DPDK_PATH=/home/userid/dpdk/x86_64-native-linuxapp-gcc` - - Then run `snakemake` -* If all is well, the executable is located in `bin/main`. +## Documentation -### Compile options - -Our build script offers a few configurable parameters as environment variables: -* `NBA_DPDK_PATH`: specifies the path to Intel DPDK (required) -* `NBA_RANDOM_PORT_ACCESS`: randomizes the RX queue scanning order for each worker thread (default: false) -* `NBA_OPENSSL_PATH`: specifies the path of OpenSSL library (default: /usr) -* `USE_CUDA`: activates NVIDIA CUDA support (default: true) -* `USE_PHI`: activates Intel Xeon Phi support (default: false, not fully implemented yet) -* `USE_NVPROF`: activates nvprof API calls to track GPU-related timings (default: false) -* `USE_OPENSSL_EVP`: determines whether to use EVP API for OpenSSL that enables AES-NI support (default: true) -* `NBA_NO_HUGE`: determines whether to use huge-pages (default: true) -* `NBA_PMD`: determines what poll-mode driver to use (default: ixgbe) - -※ Boolean variables are expressed as 1 or 0. - -## How to run - -Execute `bin/main` with DPDK EAL arguments and NBA arguments. -For example, - -``` -$ sudo bin/main -cffff -n4 -- configs/rss.py configs/ipv4-router.click -``` +[See the documentation online.](http://nba.readthedocs.org/en/latest/) ## Ongoing work diff --git a/docs/gsg/build.rst b/docs/gsg/build.rst new file mode 100644 index 0000000..c922770 --- /dev/null +++ b/docs/gsg/build.rst @@ -0,0 +1,82 @@ +Building NBA +============ + +We recommend to use Ubuntu 14.04 or newer. + +Supported Platforms +------------------- + +Step-by-step Guide for Ubuntu 14.04 LTS +--------------------------------------- + +** Package and software to install ** + +* NVIDIA CUDA 7.0 or newer + - We recommend to download the latest version of `.bin` package from `the NVIDIA website`_ instead of using system packages. + +.. note:: + + A small daemon is required to "pin" GPU's interrupts to specific cores. + See details in `our gist `_. + + - Add `export PATH=$PATH:/usr/local/cuda/bin` to `/etc/profile` or similar places. + - Add `/usr/local/cuda/lib64` to `/etc/ld.so.conf.d/cuda.conf` (create if not exists) and run `ldconfig`. + +* g++ 4.8 or newer (the compiler must support C++11 standard.) + +* Intel DPDK 1.8 +.. code-block:: console + + ~$ git clone git://dpdk.org/dpdk + ~$ cd dpdk + ~/dpdk$ make install T=x86_64-native-linuxapp-gcc + +.. note:: + + You need to install the kernel header/source packages first. + +* Python 3.4 or newer + +.. code-block:: console + + pip install snakemake + apt-get install libpython3-dev + +.. note:: + + We recommend using a separate Python environment contained inside the user directory. + See pyenv for more details. + +* Click configuration parser + - Just run `git submodule init && git submodule update` + - It will be *automatically built* along with NBA when you first build NBA. + +* `sysstat` package (or any package that offers `mpstat` command) to run experiment scripts + +** Compilation ** + +* Set the environment variable as follows: + +.. code-block:: console + + $ export NBA_DPDK_PATH=/home/userid/dpdk/x86_64-native-linuxapp-gcc + $ snakemake + +* If all is well, the executable is located in `bin/main`. + +Customizing Your Build +---------------------- + +Our build script offers a few configurable parameters as environment variables: + +* `NBA_DPDK_PATH`: specifies the path to Intel DPDK (required) +* `NBA_RANDOM_PORT_ACCESS`: randomizes the RX queue scanning order for each worker thread (default: false) +* `NBA_OPENSSL_PATH`: specifies the path of OpenSSL library (default: /usr) +* `USE_CUDA`: activates NVIDIA CUDA support (default: true) +* `USE_PHI`: activates Intel Xeon Phi support (default: false, not fully implemented yet) +* `USE_NVPROF`: activates nvprof API calls to track GPU-related timings (default: false) +* `USE_OPENSSL_EVP`: determines whether to use EVP API for OpenSSL that enables AES-NI support (default: true) +* `NBA_NO_HUGE`: determines whether to use huge-pages (default: true) +* `NBA_PMD`: determines what poll-mode driver to use (default: ixgbe) + +※ Boolean variables are expressed as 1 or 0. diff --git a/docs/gsg/index.rst b/docs/gsg/index.rst new file mode 100644 index 0000000..adfcfbc --- /dev/null +++ b/docs/gsg/index.rst @@ -0,0 +1,9 @@ +Getting Started Guide +===================== + +.. toctree:: + :maxdepth: 2 + :numbered: + sys_reqs + build + running diff --git a/docs/gsg/running.rst b/docs/gsg/running.rst new file mode 100644 index 0000000..5b6b2f9 --- /dev/null +++ b/docs/gsg/running.rst @@ -0,0 +1,17 @@ +Running NBA +=========== + +Standalone Execution +-------------------- + +Execute `bin/main` with DPDK EAL arguments and NBA arguments. +For example, + +.. code-block:: console + + $ sudo bin/main -cffff -n4 -- configs/rss.py configs/ipv4-router.click + +For details about DPDK EAL arguments, see `DPDK's documentation `_. + +Scripted Execution +------------------ diff --git a/docs/gsg/sys_reqs.rst b/docs/gsg/sys_reqs.rst new file mode 100644 index 0000000..f21468c --- /dev/null +++ b/docs/gsg/sys_reqs.rst @@ -0,0 +1,10 @@ +System Requirements +=================== + +Supported Hardware +------------------ + +BIOS Settings +------------- + + diff --git a/docs/index.rst b/docs/index.rst index 64f183b..4b5e574 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,7 +9,8 @@ Welcome to Network Balancing Act's documentation! Contents: .. toctree:: - :maxdepth: 2 + :maxdepth: 1 + gsg/index