net/cnxk: make inline inbound device usage as default
[dpdk.git] / doc / guides / howto / openwrt.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2019 Intel Corporation.
3
4 Enable DPDK on OpenWrt
5 ======================
6
7 This document describes how to enable Data Plane Development Kit (DPDK) on
8 OpenWrt in both a virtual and physical x86 environment.
9
10 Introduction
11 ------------
12
13 The OpenWrt project is a well-known source-based router OS which provides a
14 fully writable filesystem with package management.
15
16 Build OpenWrt
17 -------------
18
19 You can obtain OpenWrt image through https://downloads.openwrt.org/releases.
20 To fully customize your own OpenWrt, it is highly recommended to build it from
21 the source code. You can clone the OpenWrt source code as follows:
22
23 .. code-block:: console
24
25     git clone https://git.openwrt.org/openwrt/openwrt.git
26
27 OpenWrt configuration
28 ~~~~~~~~~~~~~~~~~~~~~
29
30 * Select ``x86`` in ``Target System``
31 * Select ``x86_64`` in ``Subtarget``
32 * Select ``Build the OpenWrt SDK`` for cross-compilation environment
33 * Select ``Use glibc`` in ``Advanced configuration options (for developers)``
34   then ``ToolChain Options`` and ``C Library implementation``
35
36 Kernel configuration
37 ~~~~~~~~~~~~~~~~~~~~
38
39 The following configurations should be enabled:
40
41 * ``CONFIG_VFIO_IOMMU_TYPE1=y``
42 * ``CONFIG_VFIO_VIRQFD=y``
43 * ``CONFIG_VFIO=y``
44 * ``CONFIG_VFIO_NOIOMMU=y``
45 * ``CONFIG_VFIO_PCI=y``
46 * ``CONFIG_VFIO_PCI_MMAP=y``
47 * ``CONFIG_HUGETLBFS=y``
48 * ``CONFIG_HUGETLB_PAGE=y``
49 * ``CONFIG_PROC_PAGE_MONITOR=y``
50
51 Build steps
52 ~~~~~~~~~~~
53
54 For detailed OpenWrt build steps and prerequisites, please refer to the
55 `OpenWrt build guide
56 <https://openwrt.org/docs/guide-developer/build-system/use-buildsystem>`_.
57
58 After the build is completed, you can find the images and SDK in
59 ``<OpenWrt Root>/bin/targets/x86/64-glibc/``.
60
61
62 DPDK Cross Compilation for OpenWrt
63 ----------------------------------
64
65 Pre-requisites
66 ~~~~~~~~~~~~~~
67
68 NUMA is required to run DPDK in x86.
69
70 .. note::
71
72     For compiling the NUMA lib, run ``libtool --version`` to ensure the libtool
73     version >= 2.2, otherwise the compilation will fail with errors.
74
75 .. code-block:: console
76
77     git clone https://github.com/numactl/numactl.git
78     cd numactl
79     git checkout v2.0.13 -b v2.0.13
80     ./autogen.sh
81     autoconf -i
82     export PATH=<OpenWrt SDK>/glibc/openwrt-sdk-x86-64_gcc-8.3.0_glibc.Linux-x86_64/staging_dir/toolchain-x86_64_gcc-8.3.0_glibc/bin/:$PATH
83     ./configure CC=x86_64-openwrt-linux-gnu-gcc --prefix=<OpenWrt SDK toolchain dir>
84     make install
85
86 The numa header files and lib file is generated in the include and lib folder
87 respectively under <OpenWrt SDK toolchain dir>.
88
89 Build DPDK
90 ~~~~~~~~~~
91
92 To cross compile with meson build, you need to write a customized cross file
93 first.
94
95 .. code-block:: console
96
97     [binaries]
98     c = 'x86_64-openwrt-linux-gcc'
99     cpp = 'x86_64-openwrt-linux-cpp'
100     ar = 'x86_64-openwrt-linux-ar'
101     strip = 'x86_64-openwrt-linux-strip'
102
103     meson builddir --cross-file openwrt-cross
104     ninja -C builddir
105
106 Running DPDK application on OpenWrt
107 -----------------------------------
108
109 Virtual machine
110 ~~~~~~~~~~~~~~~
111
112 * Extract the boot image
113
114 .. code-block:: console
115
116     gzip -d openwrt-x86-64-combined-ext4.img.gz
117
118 * Launch Qemu
119
120 .. code-block:: console
121
122     qemu-system-x86_64 \
123             -cpu host \
124             -smp 8 \
125             -enable-kvm \
126             -M q35 \
127             -m 2048M \
128             -object memory-backend-file,id=mem,size=2048M,mem-path=/tmp/hugepages,share=on \
129             -drive file=<Your OpenWrt images folder>/openwrt-x86-64-combined-ext4.img,id=d0,if=none,bus=0,unit=0 \
130             -device ide-hd,drive=d0,bus=ide.0 \
131             -net nic,vlan=0 \
132             -net nic,vlan=1 \
133             -net user,vlan=1 \
134             -display none \
135
136
137 Physical machine
138 ~~~~~~~~~~~~~~~~
139
140 You can use the ``dd`` tool to write the OpenWrt image to the drive you
141 want to write the image on.
142
143 .. code-block:: console
144
145     dd if=openwrt-18.06.1-x86-64-combined-squashfs.img of=/dev/sdX
146
147 Where sdX is name of the drive. (You can find it though ``fdisk -l``)
148
149 Running DPDK
150 ~~~~~~~~~~~~
151
152 More detailed info about how to run a DPDK application please refer to
153 ``Running DPDK Applications`` section of :ref:`the DPDK documentation <linux_gsg>`.
154
155 .. note::
156
157     You need to install pre-built NUMA libraries (including soft link)
158     to /usr/lib64 in OpenWrt.