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         meson build -Dexamples=<application>
  98         ninja -C build
  99
 100 The example applications can be compiled using the following:
 101
 102 .. code-block:: console
 103
 104         meson build -Dexamples=<application>
 105         ninja -C build
 106
 107 Cross Compilation
 108 ~~~~~~~~~~~~~~~~~
 109
 110 The DPDK applications can be cross-compiled on any x86 based platform. The
 111 OCTEON TX SDK need to be installed on the build system. The SDK package will
 112 provide the required toolchain etc.
 113
 114 Refer to :doc:`../linux_gsg/cross_build_dpdk_for_arm64` for generic arm64 details.
 115
 116 The following steps can be used to perform cross-compilation with OCTEON TX
 117 SDK 6.2.0 patch 3:
 118
 119 .. code-block:: console
 120
 121         cd <sdk_install_dir>
 122         source env-setup
 123
 124 The above steps will prepare build system with required toolchain.
 125 Now this build system can be used to build applications for **OCTEON TX** :sup:`®` platforms.
 126
 127 .. code-block:: console
 128
 129         cd <dpdk directory>
 130         meson build --cross-file config/arm/arm64_thunderx_linux_gcc
 131         ninja -C build
 132
 133 The example applications can be compiled using the following:
 134
 135 .. code-block:: console
 136
 137         cd <dpdk directory>
 138         meson build --cross-file config/arm/arm64_thunderx_linux_gcc -Dexamples=<application>
 139         ninja -C build
 140
 141 .. note::
 142
 143    By default, meson cross compilation uses ``aarch64-linux-gnu-gcc`` toolchain,
 144    if OCTEON TX SDK 6.2.0 patch 3 is available then it can be used by
 145    overriding the c, cpp, ar, strip ``binaries`` attributes to respective thunderx
 146    toolchain binaries in ``config/arm/arm64_thunderx_linux_gcc`` file.
 147
 148 SDK and related information can be obtained from: `Cavium support site <https://support.cavium.com/>`_.