net/ena: proxy AQ calls to primary process
[dpdk.git] / 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/>`_.