doc/guides/platform/octeontx.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2017 Cavium, Inc
   3
   4 OCTEON TX Board Support Package
   5 ===============================
   6
   7 This doc has information about steps to setup OCTEON TX platform
   8 and information about common offload hw block drivers of
   9 **Cavium OCTEON TX** SoC family.
  10
  11
  12 More information about SoC can be found at `Cavium, Inc Official Website
  13 <http://www.cavium.com/OCTEON-TX_ARM_Processors.html>`_.
  14
  15 Common Offload HW Block Drivers
  16 -------------------------------
  17
  18 1. **Crypto Driver**
  19    See :doc:`../cryptodevs/octeontx` for octeontx crypto driver
  20    information.
  21
  22 2. **Eventdev Driver**
  23    See :doc:`../eventdevs/octeontx` for octeontx ssovf eventdev driver
  24    information.
  25
  26 3. **Mempool Driver**
  27    See :doc:`../mempool/octeontx` for octeontx fpavf mempool driver
  28    information.
  29
  30 Steps To Setup Platform
  31 -----------------------
  32
  33 There are three main pre-prerequisites for setting up Platform drivers on
  34 OCTEON TX compatible board:
  35
  36 1. **OCTEON TX Linux kernel PF driver for Network acceleration HW blocks**
  37
  38    The OCTEON TX Linux kernel drivers (includes the required PF driver for the
  39    Platform drivers) are available on Github at `octeontx-kmod <https://github.com/caviumnetworks/octeontx-kmod>`_
  40    along with build, install and dpdk usage instructions.
  41
  42 .. note::
  43
  44    The PF driver and the required microcode for the crypto offload block will be
  45    available with OCTEON TX SDK only. So for using crypto offload, follow the steps
  46    mentioned in :ref:`setup_platform_using_OCTEON_TX_SDK`.
  47
  48 2. **ARM64 Tool Chain**
  49
  50    For example, the *aarch64* Linaro Toolchain, which can be obtained from
  51    `here <https://releases.linaro.org/components/toolchain/binaries/4.9-2017.01/aarch64-linux-gnu>`_.
  52
  53 3. **Rootfile system**
  54
  55    Any *aarch64* supporting filesystem can be used. For example,
  56    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
  57    from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
  58
  59    As an alternative method, Platform drivers can also be executed using images provided
  60    as part of SDK from Cavium. The SDK includes all the above prerequisites necessary
  61    to bring up a OCTEON TX board. Please refer :ref:`setup_platform_using_OCTEON_TX_SDK`.
  62
  63 - Follow the DPDK :doc:`../linux_gsg/index` to setup the basic DPDK environment.
  64
  65 .. _setup_platform_using_OCTEON_TX_SDK:
  66
  67 Setup Platform Using OCTEON TX SDK
  68 ----------------------------------
  69
  70 The OCTEON TX platform drivers can be compiled either natively on
  71 **OCTEON TX** :sup:`®` board or cross-compiled on an x86 based platform.
  72
  73 The **OCTEON TX** :sup:`®` board must be running the linux kernel based on
  74 OCTEON TX SDK 6.2.0 patch 3. In this, the PF drivers for all hardware
  75 offload blocks are already built in.
  76
  77 Native Compilation
  78 ~~~~~~~~~~~~~~~~~~
  79
  80 If the kernel and modules are cross-compiled and copied to the target board,
  81 some intermediate binaries required for native build would be missing on the
  82 target board. To make sure all the required binaries are available in the
  83 native architecture, the linux sources need to be compiled once natively.
  84
  85 .. code-block:: console
  86
  87         cd /lib/modules/$(uname -r)/source
  88         make menuconfig
  89         make
  90
  91 The above steps would rebuild the modules and the required intermediate binaries.
  92 Once the target is ready for native compilation, the OCTEON TX platform
  93 drivers can be compiled with the following steps,
  94
  95 .. code-block:: console
  96
  97         cd <dpdk directory>
  98         make config T=arm64-thunderx-linuxapp-gcc
  99         make
 100
 101 The example applications can be compiled using the following:
 102
 103 .. code-block:: console
 104
 105         cd <dpdk directory>
 106         export RTE_SDK=$PWD
 107         export RTE_TARGET=build
 108         cd examples/<application>
 109         make
 110
 111 Cross Compilation
 112 ~~~~~~~~~~~~~~~~~
 113
 114 The DPDK applications can be cross-compiled on any x86 based platform. The
 115 OCTEON TX SDK need to be installed on the build system. The SDK package will
 116 provide the required toolchain etc.
 117
 118 Refer to :doc:`../linux_gsg/cross_build_dpdk_for_arm64` for further steps on
 119 compilation. The 'host' & 'CC' to be used in the commands would change,
 120 in addition to the paths to which libnuma related files have to be
 121 copied.
 122
 123 The following steps can be used to perform cross-compilation with OCTEON TX
 124 SDK 6.2.0 patch 3:
 125
 126 .. code-block:: console
 127
 128         cd <sdk_install_dir>
 129         source env-setup
 130
 131         git clone https://github.com/numactl/numactl.git
 132         cd numactl
 133         git checkout v2.0.11 -b v2.0.11
 134         ./autogen.sh
 135         autoconf -i
 136         ./configure --host=aarch64-thunderx-linux CC=aarch64-thunderx-linux-gnu-gcc --prefix=<numa install dir>
 137         make install
 138
 139 The above steps will prepare build system with numa additions. Now this build system can be used
 140 to build applications for **OCTEON TX** :sup:`®` platforms.
 141
 142 .. code-block:: console
 143
 144         cd <dpdk directory>
 145         export RTE_SDK=$PWD
 146         export RTE_KERNELDIR=$THUNDER_ROOT/linux/kernel/linux
 147         make config T=arm64-thunderx-linuxapp-gcc
 148         make -j CROSS=aarch64-thunderx-linux-gnu- CONFIG_RTE_KNI_KMOD=n CONFIG_RTE_EAL_IGB_UIO=n EXTRA_CFLAGS="-isystem <numa_install_dir>/include" EXTRA_LDFLAGS="-L<numa_install_dir>/lib -lnuma"
 149
 150 If NUMA support is not required, it can be disabled as explained in
 151 :doc:`../linux_gsg/cross_build_dpdk_for_arm64`.
 152
 153 Following steps could be used in that case.
 154
 155 .. code-block:: console
 156
 157         make config T=arm64-thunderx-linuxapp-gcc
 158         make CROSS=aarch64-thunderx-linux-gnu-
 159
 160
 161 SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.