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