net/hns3: support PF device with copper PHYs
[dpdk.git] / doc / guides / platform / octeontx2.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2019 Marvell International Ltd.
3
4 Marvell OCTEON TX2 Platform Guide
5 =================================
6
7 This document gives an overview of **Marvell OCTEON TX2** RVU H/W block,
8 packet flow and procedure to build DPDK on OCTEON TX2 platform.
9
10 More information about OCTEON TX2 SoC can be found at `Marvell Official Website
11 <https://www.marvell.com/embedded-processors/infrastructure-processors/>`_.
12
13 Supported OCTEON TX2 SoCs
14 -------------------------
15
16 - CN98xx
17 - CN96xx
18 - CN93xx
19
20 OCTEON TX2 Resource Virtualization Unit architecture
21 ----------------------------------------------------
22
23 The :numref:`figure_octeontx2_resource_virtualization` diagram depicts the
24 RVU architecture and a resource provisioning example.
25
26 .. _figure_octeontx2_resource_virtualization:
27
28 .. figure:: img/octeontx2_resource_virtualization.*
29
30     OCTEON TX2 Resource virtualization architecture and provisioning example
31
32
33 Resource Virtualization Unit (RVU) on Marvell's OCTEON TX2 SoC maps HW
34 resources belonging to the network, crypto and other functional blocks onto
35 PCI-compatible physical and virtual functions.
36
37 Each functional block has multiple local functions (LFs) for
38 provisioning to different PCIe devices. RVU supports multiple PCIe SRIOV
39 physical functions (PFs) and virtual functions (VFs).
40
41 The :numref:`table_octeontx2_rvu_dpdk_mapping` shows the various local
42 functions (LFs) provided by the RVU and its functional mapping to
43 DPDK subsystem.
44
45 .. _table_octeontx2_rvu_dpdk_mapping:
46
47 .. table:: RVU managed functional blocks and its mapping to DPDK subsystem
48
49    +---+-----+--------------------------------------------------------------+
50    | # | LF  | DPDK subsystem mapping                                       |
51    +===+=====+==============================================================+
52    | 1 | NIX | rte_ethdev, rte_tm, rte_event_eth_[rt]x_adapter, rte_security|
53    +---+-----+--------------------------------------------------------------+
54    | 2 | NPA | rte_mempool                                                  |
55    +---+-----+--------------------------------------------------------------+
56    | 3 | NPC | rte_flow                                                     |
57    +---+-----+--------------------------------------------------------------+
58    | 4 | CPT | rte_cryptodev, rte_event_crypto_adapter                      |
59    +---+-----+--------------------------------------------------------------+
60    | 5 | SSO | rte_eventdev                                                 |
61    +---+-----+--------------------------------------------------------------+
62    | 6 | TIM | rte_event_timer_adapter                                      |
63    +---+-----+--------------------------------------------------------------+
64    | 7 | LBK | rte_ethdev                                                   |
65    +---+-----+--------------------------------------------------------------+
66    | 8 | DPI | rte_rawdev                                                   |
67    +---+-----+--------------------------------------------------------------+
68    | 9 | SDP | rte_ethdev                                                   |
69    +---+-----+--------------------------------------------------------------+
70    | 10| REE | rte_regexdev                                                 |
71    +---+-----+--------------------------------------------------------------+
72
73 PF0 is called the administrative / admin function (AF) and has exclusive
74 privileges to provision RVU functional block's LFs to each of the PF/VF.
75
76 PF/VFs communicates with AF via a shared memory region (mailbox).Upon receiving
77 requests from PF/VF, AF does resource provisioning and other HW configuration.
78
79 AF is always attached to host, but PF/VFs may be used by host kernel itself,
80 or attached to VMs or to userspace applications like DPDK, etc. So, AF has to
81 handle provisioning/configuration requests sent by any device from any domain.
82
83 The AF driver does not receive or process any data.
84 It is only a configuration driver used in control path.
85
86 The :numref:`figure_octeontx2_resource_virtualization` diagram also shows a
87 resource provisioning example where,
88
89 1. PFx and PFx-VF0 bound to Linux netdev driver.
90 2. PFx-VF1 ethdev driver bound to the first DPDK application.
91 3. PFy ethdev driver, PFy-VF0 ethdev driver, PFz eventdev driver, PFm-VF0 cryptodev driver bound to the second DPDK application.
92
93 LBK HW Access
94 -------------
95
96 Loopback HW Unit (LBK) receives packets from NIX-RX and sends packets back to NIX-TX.
97 The loopback block has N channels and contains data buffering that is shared across
98 all channels. The LBK HW Unit is abstracted using ethdev subsystem, Where PF0's
99 VFs are exposed as ethdev device and odd-even pairs of VFs are tied together,
100 that is, packets sent on odd VF end up received on even VF and vice versa.
101 This would enable HW accelerated means of communication between two domains
102 where even VF bound to the first domain and odd VF bound to the second domain.
103
104 Typical application usage models are,
105
106 #. Communication between the Linux kernel and DPDK application.
107 #. Exception path to Linux kernel from DPDK application as SW ``KNI`` replacement.
108 #. Communication between two different DPDK applications.
109
110 SDP interface
111 -------------
112
113 System DPI Packet Interface unit(SDP) provides PCIe endpoint support for remote host
114 to DMA packets into and out of OCTEON TX2 SoC. SDP interface comes in to live only when
115 OCTEON TX2 SoC is connected in PCIe endpoint mode. It can be used to send/receive
116 packets to/from remote host machine using input/output queue pairs exposed to it.
117 SDP interface receives input packets from remote host from NIX-RX and sends packets
118 to remote host using NIX-TX. Remote host machine need to use corresponding driver
119 (kernel/user mode) to communicate with SDP interface on OCTEON TX2 SoC. SDP supports
120 single PCIe SRIOV physical function(PF) and multiple virtual functions(VF's). Users
121 can bind PF or VF to use SDP interface and it will be enumerated as ethdev ports.
122
123 The primary use case for SDP is to enable the smart NIC use case. Typical usage models are,
124
125 #. Communication channel between remote host and OCTEON TX2 SoC over PCIe.
126 #. Transfer packets received from network interface to remote host over PCIe and
127    vice-versa.
128
129 OCTEON TX2 packet flow
130 ----------------------
131
132 The :numref:`figure_octeontx2_packet_flow_hw_accelerators` diagram depicts
133 the packet flow on OCTEON TX2 SoC in conjunction with use of various HW accelerators.
134
135 .. _figure_octeontx2_packet_flow_hw_accelerators:
136
137 .. figure:: img/octeontx2_packet_flow_hw_accelerators.*
138
139     OCTEON TX2 packet flow in conjunction with use of HW accelerators
140
141 HW Offload Drivers
142 ------------------
143
144 This section lists dataplane H/W block(s) available in OCTEON TX2 SoC.
145
146 #. **Ethdev Driver**
147    See :doc:`../nics/octeontx2` for NIX Ethdev driver information.
148
149 #. **Mempool Driver**
150    See :doc:`../mempool/octeontx2` for NPA mempool driver information.
151
152 #. **Event Device Driver**
153    See :doc:`../eventdevs/octeontx2` for SSO event device driver information.
154
155 #. **DMA Rawdev Driver**
156    See :doc:`../rawdevs/octeontx2_dma` for DMA driver information.
157
158 #. **Crypto Device Driver**
159    See :doc:`../cryptodevs/octeontx2` for CPT crypto device driver information.
160
161 #. **Regex Device Driver**
162    See :doc:`../regexdevs/octeontx2` for REE regex device driver information.
163
164 Procedure to Setup Platform
165 ---------------------------
166
167 There are three main prerequisites for setting up DPDK on OCTEON TX2
168 compatible board:
169
170 1. **OCTEON TX2 Linux kernel driver**
171
172    The dependent kernel drivers can be obtained from the
173    `kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/net/ethernet/marvell/octeontx2>`_.
174
175    Alternatively, the Marvell SDK also provides the required kernel drivers.
176
177    Linux kernel should be configured with the following features enabled:
178
179 .. code-block:: console
180
181         # 64K pages enabled for better performance
182         CONFIG_ARM64_64K_PAGES=y
183         CONFIG_ARM64_VA_BITS_48=y
184         # huge pages support enabled
185         CONFIG_HUGETLBFS=y
186         CONFIG_HUGETLB_PAGE=y
187         # VFIO enabled with TYPE1 IOMMU at minimum
188         CONFIG_VFIO_IOMMU_TYPE1=y
189         CONFIG_VFIO_VIRQFD=y
190         CONFIG_VFIO=y
191         CONFIG_VFIO_NOIOMMU=y
192         CONFIG_VFIO_PCI=y
193         CONFIG_VFIO_PCI_MMAP=y
194         # SMMUv3 driver
195         CONFIG_ARM_SMMU_V3=y
196         # ARMv8.1 LSE atomics
197         CONFIG_ARM64_LSE_ATOMICS=y
198         # OCTEONTX2 drivers
199         CONFIG_OCTEONTX2_MBOX=y
200         CONFIG_OCTEONTX2_AF=y
201         # Enable if netdev PF driver required
202         CONFIG_OCTEONTX2_PF=y
203         # Enable if netdev VF driver required
204         CONFIG_OCTEONTX2_VF=y
205         CONFIG_CRYPTO_DEV_OCTEONTX2_CPT=y
206         # Enable if OCTEONTX2 DMA PF driver required
207         CONFIG_OCTEONTX2_DPI_PF=n
208
209 2. **ARM64 Linux Tool Chain**
210
211    For example, the *aarch64* Linaro Toolchain, which can be obtained from
212    `here <https://releases.linaro.org/components/toolchain/binaries/7.4-2019.02/aarch64-linux-gnu/>`_.
213
214    Alternatively, the Marvell SDK also provides GNU GCC toolchain, which is
215    optimized for OCTEON TX2 CPU.
216
217 3. **Rootfile system**
218
219    Any *aarch64* supporting filesystem may be used. For example,
220    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
221    from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
222
223    Alternatively, the Marvell SDK provides the buildroot based root filesystem.
224    The SDK includes all the above prerequisites necessary to bring up the OCTEON TX2 board.
225
226 - Follow the DPDK :doc:`../linux_gsg/index` to setup the basic DPDK environment.
227
228
229 Debugging Options
230 -----------------
231
232 .. _table_octeontx2_common_debug_options:
233
234 .. table:: OCTEON TX2 common debug options
235
236    +---+------------+-------------------------------------------------------+
237    | # | Component  | EAL log command                                       |
238    +===+============+=======================================================+
239    | 1 | Common     | --log-level='pmd\.octeontx2\.base,8'                  |
240    +---+------------+-------------------------------------------------------+
241    | 2 | Mailbox    | --log-level='pmd\.octeontx2\.mbox,8'                  |
242    +---+------------+-------------------------------------------------------+
243
244 Debugfs support
245 ~~~~~~~~~~~~~~~
246
247 The **OCTEON TX2 Linux kernel driver** provides support to dump RVU blocks
248 context or stats using debugfs.
249
250 Enable ``debugfs`` by:
251
252 1. Compile kernel with debugfs enabled, i.e ``CONFIG_DEBUGFS=y``.
253 2. Boot OCTEON TX2 with debugfs supported kernel.
254 3. Verify ``debugfs`` mounted by default "mount | grep -i debugfs" or mount it manually by using.
255
256 .. code-block:: console
257
258        # mount -t debugfs none /sys/kernel/debug
259
260 Currently ``debugfs`` supports the following RVU blocks NIX, NPA, NPC, NDC,
261 SSO & CGX.
262
263 The file structure under ``/sys/kernel/debug`` is as follows
264
265 .. code-block:: console
266
267         octeontx2/
268         |-- cgx
269         |   |-- cgx0
270         |   |   '-- lmac0
271         |   |       '-- stats
272         |   |-- cgx1
273         |   |   |-- lmac0
274         |   |   |   '-- stats
275         |   |   '-- lmac1
276         |   |       '-- stats
277         |   '-- cgx2
278         |       '-- lmac0
279         |           '-- stats
280         |-- cpt
281         |   |-- cpt_engines_info
282         |   |-- cpt_engines_sts
283         |   |-- cpt_err_info
284         |   |-- cpt_lfs_info
285         |   '-- cpt_pc
286         |---- nix
287         |   |-- cq_ctx
288         |   |-- ndc_rx_cache
289         |   |-- ndc_rx_hits_miss
290         |   |-- ndc_tx_cache
291         |   |-- ndc_tx_hits_miss
292         |   |-- qsize
293         |   |-- rq_ctx
294         |   |-- sq_ctx
295         |   '-- tx_stall_hwissue
296         |-- npa
297         |   |-- aura_ctx
298         |   |-- ndc_cache
299         |   |-- ndc_hits_miss
300         |   |-- pool_ctx
301         |   '-- qsize
302         |-- npc
303         |    |-- mcam_info
304         |    '-- rx_miss_act_stats
305         |-- rsrc_alloc
306         '-- sso
307              |-- hws
308              |   '-- sso_hws_info
309              '-- hwgrp
310                  |-- sso_hwgrp_aq_thresh
311                  |-- sso_hwgrp_iaq_walk
312                  |-- sso_hwgrp_pc
313                  |-- sso_hwgrp_free_list_walk
314                  |-- sso_hwgrp_ient_walk
315                  '-- sso_hwgrp_taq_walk
316
317 RVU block LF allocation:
318
319 .. code-block:: console
320
321         cat /sys/kernel/debug/octeontx2/rsrc_alloc
322
323         pcifunc    NPA    NIX    SSO GROUP    SSOWS    TIM    CPT
324         PF1         0       0
325         PF4                 1
326         PF13                          0, 1     0, 1      0
327
328 CGX example usage:
329
330 .. code-block:: console
331
332         cat /sys/kernel/debug/octeontx2/cgx/cgx2/lmac0/stats
333
334         =======Link Status======
335         Link is UP 40000 Mbps
336         =======RX_STATS======
337         Received packets: 0
338         Octets of received packets: 0
339         Received PAUSE packets: 0
340         Received PAUSE and control packets: 0
341         Filtered DMAC0 (NIX-bound) packets: 0
342         Filtered DMAC0 (NIX-bound) octets: 0
343         Packets dropped due to RX FIFO full: 0
344         Octets dropped due to RX FIFO full: 0
345         Error packets: 0
346         Filtered DMAC1 (NCSI-bound) packets: 0
347         Filtered DMAC1 (NCSI-bound) octets: 0
348         NCSI-bound packets dropped: 0
349         NCSI-bound octets dropped: 0
350         =======TX_STATS======
351         Packets dropped due to excessive collisions: 0
352         Packets dropped due to excessive deferral: 0
353         Multiple collisions before successful transmission: 0
354         Single collisions before successful transmission: 0
355         Total octets sent on the interface: 0
356         Total frames sent on the interface: 0
357         Packets sent with an octet count < 64: 0
358         Packets sent with an octet count == 64: 0
359         Packets sent with an octet count of 65127: 0
360         Packets sent with an octet count of 128-255: 0
361         Packets sent with an octet count of 256-511: 0
362         Packets sent with an octet count of 512-1023: 0
363         Packets sent with an octet count of 1024-1518: 0
364         Packets sent with an octet count of > 1518: 0
365         Packets sent to a broadcast DMAC: 0
366         Packets sent to the multicast DMAC: 0
367         Transmit underflow and were truncated: 0
368         Control/PAUSE packets sent: 0
369
370 CPT example usage:
371
372 .. code-block:: console
373
374         cat /sys/kernel/debug/octeontx2/cpt/cpt_pc
375
376         CPT instruction requests   0
377         CPT instruction latency    0
378         CPT NCB read requests      0
379         CPT NCB read latency       0
380         CPT read requests caused by UC fills   0
381         CPT active cycles pc       1395642
382         CPT clock count pc         5579867595493
383
384 NIX example usage:
385
386 .. code-block:: console
387
388         Usage: echo <nixlf> [cq number/all] > /sys/kernel/debug/octeontx2/nix/cq_ctx
389                cat /sys/kernel/debug/octeontx2/nix/cq_ctx
390         echo 0 0 > /sys/kernel/debug/octeontx2/nix/cq_ctx
391         cat /sys/kernel/debug/octeontx2/nix/cq_ctx
392
393         =====cq_ctx for nixlf:0 and qidx:0 is=====
394         W0: base                        158ef1a00
395
396         W1: wrptr                       0
397         W1: avg_con                     0
398         W1: cint_idx                    0
399         W1: cq_err                      0
400         W1: qint_idx                    0
401         W1: bpid                        0
402         W1: bp_ena                      0
403
404         W2: update_time                 31043
405         W2:avg_level                    255
406         W2: head                        0
407         W2:tail                         0
408
409         W3: cq_err_int_ena              5
410         W3:cq_err_int                   0
411         W3: qsize                       4
412         W3:caching                      1
413         W3: substream                   0x000
414         W3: ena                                 1
415         W3: drop_ena                    1
416         W3: drop                        64
417         W3: bp                          0
418
419 NPA example usage:
420
421 .. code-block:: console
422
423         Usage: echo <npalf> [pool number/all] > /sys/kernel/debug/octeontx2/npa/pool_ctx
424                cat /sys/kernel/debug/octeontx2/npa/pool_ctx
425         echo 0 0 > /sys/kernel/debug/octeontx2/npa/pool_ctx
426         cat /sys/kernel/debug/octeontx2/npa/pool_ctx
427
428         ======POOL : 0=======
429         W0: Stack base          1375bff00
430         W1: ena                 1
431         W1: nat_align           1
432         W1: stack_caching       1
433         W1: stack_way_mask      0
434         W1: buf_offset          1
435         W1: buf_size            19
436         W2: stack_max_pages     24315
437         W2: stack_pages         24314
438         W3: op_pc               267456
439         W4: stack_offset        2
440         W4: shift               5
441         W4: avg_level           255
442         W4: avg_con             0
443         W4: fc_ena              0
444         W4: fc_stype            0
445         W4: fc_hyst_bits        0
446         W4: fc_up_crossing      0
447         W4: update_time         62993
448         W5: fc_addr             0
449         W6: ptr_start           1593adf00
450         W7: ptr_end             180000000
451         W8: err_int             0
452         W8: err_int_ena         7
453         W8: thresh_int          0
454         W8: thresh_int_ena      0
455         W8: thresh_up           0
456         W8: thresh_qint_idx     0
457         W8: err_qint_idx        0
458
459 NPC example usage:
460
461 .. code-block:: console
462
463         cat /sys/kernel/debug/octeontx2/npc/mcam_info
464
465         NPC MCAM info:
466         RX keywidth    : 224bits
467         TX keywidth    : 224bits
468
469         MCAM entries   : 2048
470         Reserved       : 158
471         Available      : 1890
472
473         MCAM counters  : 512
474         Reserved       : 1
475         Available      : 511
476
477 SSO example usage:
478
479 .. code-block:: console
480
481         Usage: echo [<hws>/all] > /sys/kernel/debug/octeontx2/sso/hws/sso_hws_info
482         echo 0 > /sys/kernel/debug/octeontx2/sso/hws/sso_hws_info
483
484         ==================================================
485         SSOW HWS[0] Arbitration State      0x0
486         SSOW HWS[0] Guest Machine Control  0x0
487         SSOW HWS[0] SET[0] Group Mask[0] 0xffffffffffffffff
488         SSOW HWS[0] SET[0] Group Mask[1] 0xffffffffffffffff
489         SSOW HWS[0] SET[0] Group Mask[2] 0xffffffffffffffff
490         SSOW HWS[0] SET[0] Group Mask[3] 0xffffffffffffffff
491         SSOW HWS[0] SET[1] Group Mask[0] 0xffffffffffffffff
492         SSOW HWS[0] SET[1] Group Mask[1] 0xffffffffffffffff
493         SSOW HWS[0] SET[1] Group Mask[2] 0xffffffffffffffff
494         SSOW HWS[0] SET[1] Group Mask[3] 0xffffffffffffffff
495         ==================================================
496
497 Compile DPDK
498 ------------
499
500 DPDK may be compiled either natively on OCTEON TX2 platform or cross-compiled on
501 an x86 based platform.
502
503 Native Compilation
504 ~~~~~~~~~~~~~~~~~~
505
506 .. code-block:: console
507
508         meson build
509         ninja -C build
510
511 Cross Compilation
512 ~~~~~~~~~~~~~~~~~
513
514 Refer to :doc:`../linux_gsg/cross_build_dpdk_for_arm64` for generic arm64 details.
515
516 .. code-block:: console
517
518         meson build --cross-file config/arm/arm64_octeontx2_linux_gcc
519         ninja -C build
520
521 .. note::
522
523    By default, meson cross compilation uses ``aarch64-linux-gnu-gcc`` toolchain,
524    if Marvell toolchain is available then it can be used by overriding the
525    c, cpp, ar, strip ``binaries`` attributes to respective Marvell
526    toolchain binaries in ``config/arm/arm64_octeontx2_linux_gcc`` file.