path: root/DEPENDENCIES

Prerequisites for building the OpenDataPlane (ODP) API

1. Linux kernel >= 2.6.32

   Earlier versions may or may not work.

2. autotools

   automake
   autoconf
   libtool
   pkg-config

   On Debian/Ubuntu systems:
   $ sudo apt-get install automake autoconf libtool pkg-config

   On CentOS/RedHat/Fedora systems:
   $ sudo yum install automake autoconf libtool pkgconfig

3. Required libraries

   Libraries currently required to link: openssl, libatomic

3.1 OpenSSL native compile

   For native compilation, simply load the necessary libraries using the appropriate
   tool set.

   On Debian/Ubuntu systems:
   $ sudo apt-get install libssl-dev

   On CentOS/RedHat/Fedora systems:
   $ sudo yum install openssl-devel

3.2 OpenSSL cross compilation

   Cross compilation requires cross compiling the individual libraries.  In order for
   a cross compiled executable to run on a target system, one must build the same
   version as that which is installed on the target rootfs.

   For example, to build openssl for both 32 and 64 bit compilation:

   # Clone openssl repository
   $ git clone git://git.openssl.org/openssl.git
   $ cd openssl

   # The command "git tag" will list all tags available in the repo.
   $ git tag

   # Checkout the specific tag to match openssl library in your target rootfs
   $ git checkout <tag name>

   # Build and install 32 bit version of openssl
   $ ./Configure linux-generic32 --cross-compile-prefix=arm-linux-gnueabihf- \
     --prefix=/home/user/src/install-openssl shared
   $ make
   $ make install

   # Build and install 64 bit version of openssl
   $ ./Configure linux-generic64 --cross-compile-prefix=aarch64-linux-gnu- \
     --prefix=/home/user/src/install-openssl-aarch64 shared
   $ make
   $ make install

   # You may now build either 32 or 64 bit ODP
   $ git clone https://github.com/Linaro/odp.git odp
   $ cd odp
   $ ./bootstrap

   # Build 32 bit version of ODP
   $ ./configure --host=arm-linux-gnueabihf \
     --with-openssl-path=/home/user/src/install-openssl
   $ make

   # Or build 64 bit version of ODP
   $ ./configure --host=aarch64-linux-gnu \
     --with-openssl-path=/home/user/src/install-openssl-aarch64
   $ make

3.3 Netmap packet I/O support (optional)

   Netmap accelerated ODP packet I/O.

3.3.1 Building netmap kernel modules

   ODP works at least with the latest release version of netmap, which is
   currently 11.2. However, if possible one should try to use the latest netmap
   master branch commit for the best performance and the latest bug fixes.

   # Checkout netmap code
   $ git clone https://github.com/luigirizzo/netmap.git
   $ cd netmap
   $ git checkout v11.2 (optional)

   This is enough to build ODP. If you don't want to build netmap kernel
   modules you can jump to section 3.3.2.

   Netmap consists of a core kernel module (netmap.ko), optional modified
   device drivers and user space API headers to access the netmap
   functionality. It is recommended to build both the core module and modified
   device drivers for optimal performance.

   Netmap builds as an out-of-tree kernel module, you need matching kernel
   sources to compile it. General build instructions can be found in the packet
   README: https://github.com/luigirizzo/netmap/blob/master/LINUX/README.

   If you are running Ubuntu/Debian with the stock kernel and you want to
   compile both netmap.ko and modified drivers, these steps will guide you
   through it.

   # Download kernel headers
   $ sudo apt-get install linux-headers-$(uname -r)

   # Download kernel source matching to the headers
   $ sudo apt-get install linux-source
   # or
   $ apt-get source linux-image-$(uname -r)

   The source archive will be placed in /usr/src/linux-source-<kernel-version>
   (or in the current directory if using apt-get source). You will need to
   locate it and extract it to a convenient place.

   # Compile netmap
   $ cd <netmap_dir>/LINUX
   $ ./configure --kernel-sources=<path_to_kernel_src>
   $ make

3.3.2 Building ODP

   $ cd <odp_dir>
   $ ./bootstrap
   $ ./configure --with-netmap-path=<netmap_dir>
   $ make

3.3.3 Inserting netmap kernel modules

   In order to use netmap I/O you need to insert at least the core netmap
   kernel module.

   $ cd <netmap_dir>/LINUX
   $ sudo insmod netmap.ko

   To insert the optional modified drivers you first need to remove the
   original drivers, if loaded (and if not linked into the kernel). For
   example, if using ixgbe:

   $ cd <netmap_path>/LINUX
   $ sudo rmmod ixgbe
   $ sudo insmod ixgbe/ixgbe.ko

   To restore the original drivers you should be able to use modprobe.

3.3.4 Running ODP with netmap I/O

   ODP applications will use netmap for packet I/O by default as long as the
   netmap kernel module is loaded. If socket I/O is desired instead, it can be
   activated by setting the environment variable ODP_PKTIO_DISABLE_NETMAP.

3.4 DPDK packet I/O support (optional)

   Use DPDK for ODP packet I/O.

   DPDK pktio adds a depency to NUMA library.
   # Debian/Ubuntu
   $ sudo apt-get install libnuma-dev
   # CentOS/RedHat/Fedora
   $ sudo yum install numactl-devel

   Note: only packet I/O is accelerated with DPDK. Use
        https://github.com/Linaro/odp-dpdk.git
   for fully accelerated odp dpdk platform.

3.4.1 Building DPDK and ODP with DPDK pktio support

   DPDK packet I/O has been tested to work with DPDK v17.08.

   Follow steps in ./scripts/build-pktio-dpdk

3.4.2 Setup system

   # Load DPDK modules
   $ sudo /sbin/modprobe uio
   $ cd <dpdk-dir>
   $ sudo insmod x86_64-native-linuxapp-gcc/kmod/igb_uio.ko

   Reserve and mount hugepages and bind supported interfaces to DPDK modules
   following the DPDK documentation. ODP DPDK packet I/O has been tested with
   512 x 2MB hugepages. All this can be done with the DPDK setup script
   (<dpdk-dir>/tools/dpdk-setup.sh).

3.4.3 Running ODP with DPDK pktio

   ODP applications will try use DPDK for packet I/O by default. If some other
   I/O type is desired instead, DPDK I/O can be disabled by setting the
   environment variable ODP_PKTIO_DISABLE_DPDK.

   DPDK interfaces are accessed using indices. For example, two first DPDK
   interfaces can be used with the odp_l2fwd example as follows:
   $ cd <odp_dir>
   $ sudo ./test/performance/odp_l2fwd -i 0,1 -c 2 -m 0

   Additionally, DPDK command line options can be passed to the application
   using ODP_PKTIO_DPDK_PARAMS environment variable. For example, allocate
   1024MB of memory:
   $ sudo ODP_PKTIO_DPDK_PARAMS="-m 1024" ./test/performance/odp_l2fwd -i 0 -c 1

4.0 Packages needed to build API tests

   CUnit test framework version 2.1-3 is required
   CUnit provides a framework to run the API test suite that proves conformance to the
   ODP API. The home page http://cunit.sourceforge.net/doc/introduction.html

4.1 Native CUnit install

   # Debian/Ubuntu
   $ apt-get install libcunit1-dev

4.2 Built from src

   export CUNIT_VERSION=2.1-3
   curl -sSOL http://sourceforge.net/projects/cunit/files/CUnit/${CUNIT_VERSION}/CUnit-${CUNIT_VERSION}.tar.bz2
   tar -jxf *.bz2
   cd CUnit*
   ./bootstrap

   # Install CUnit into the default location (/usr/local). This is needed for
   # 'make distcheck'.
   ./configure
   make
   sudo make install

   # On RedHat you also have to add path /usr/local/lib to /etc/ld.so.conf

   # ... OR ... Install CUnit into user defined location. The same path is
   # used in step 4.4: PKG_CONFIG_PATH=/home/<my_cunit_path>/lib/pkgconfig
   ./configure --prefix=/home/<my_cunit_path>
   make
   make install

   # Also (in Ubuntu/RedHat at least) run ldconfig to update shared lib
   # cache or reboot, before trying to run e.g. 'make distcheck'.
   sudo ldconfig

4.3 Cross compile of CUnit

   $ git svn clone http://svn.code.sf.net/p/cunit/code/trunk cunit-code
   $ cd cunit-code
   $ ./bootstrap
   $ ./configure --host=arm-linux-gnueabihf --prefix=/home/${USER}/src/install-cunit

4.4 Using CUnit with ODP

   Configure will automatically look for CUnit if validation testsuite is
   enabled. By default it uses pkg-config to locate CUnit. Usually no
   additional configuration will be required. Few corner cases:

   # User directory installation
   ./configure PKG_CONFIG_PATH=/home/<my_cunit_path>/lib/pkgconfig

   # ... OR directly specifying flags
   ./configure CUNIT_CFLAGS="-I/home/<my_cunit_path>/include" CUNIT_LIBS="/home/<my_cunit_path>/lib -lcunit"

5.0 Documentation Images & Doxygen

  Images are stored as svg files. No conversions for these are needed.

  Message squence diagrams are stored as msc files and the svg versions generated when the docs are built
  mscgen is used
  #Debian/Ubuntu
  # apt-get install mscgen

5.1 API Guide
See http://www.stack.nl/~dimitri/doxygen/manual/install.html

The tested version of doxygen is 1.8.8

5.1.1 HTML
   # Debian/Ubuntu
   $ apt-get install doxygen graphviz

5.2 User guides

5.2.1 HTML
   # Debian/Ubuntu
   $ apt-get install asciidoctor source-highlight librsvg2-bin

6.0 Submitting patches

   When submitting patches they should be checked with ./scripts/checkpatch.pl
   To have this tool also check spelling you need codespell.
   # Debian/Ubuntu
   #sudo apt install codespell