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