doc: update LTS release cadence
[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 Procedure to Setup Platform
160 ---------------------------
161
162 There are three main prerequisites for setting up DPDK on cnxk
163 compatible board:
164
165 1. **RVU AF Linux kernel driver**
166
167    The dependent kernel drivers can be obtained from the
168    `kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/net/ethernet/marvell/octeontx2>`_.
169
170    Alternatively, the Marvell SDK also provides the required kernel drivers.
171
172    Linux kernel should be configured with the following features enabled:
173
174 .. code-block:: console
175
176         # 64K pages enabled for better performance
177         CONFIG_ARM64_64K_PAGES=y
178         CONFIG_ARM64_VA_BITS_48=y
179         # huge pages support enabled
180         CONFIG_HUGETLBFS=y
181         CONFIG_HUGETLB_PAGE=y
182         # VFIO enabled with TYPE1 IOMMU at minimum
183         CONFIG_VFIO_IOMMU_TYPE1=y
184         CONFIG_VFIO_VIRQFD=y
185         CONFIG_VFIO=y
186         CONFIG_VFIO_NOIOMMU=y
187         CONFIG_VFIO_PCI=y
188         CONFIG_VFIO_PCI_MMAP=y
189         # SMMUv3 driver
190         CONFIG_ARM_SMMU_V3=y
191         # ARMv8.1 LSE atomics
192         CONFIG_ARM64_LSE_ATOMICS=y
193         # OCTEONTX2 drivers
194         CONFIG_OCTEONTX2_MBOX=y
195         CONFIG_OCTEONTX2_AF=y
196         # Enable if netdev PF driver required
197         CONFIG_OCTEONTX2_PF=y
198         # Enable if netdev VF driver required
199         CONFIG_OCTEONTX2_VF=y
200         CONFIG_CRYPTO_DEV_OCTEONTX2_CPT=y
201         # Enable if OCTEONTX2 DMA PF driver required
202         CONFIG_OCTEONTX2_DPI_PF=n
203
204 2. **ARM64 Linux Tool Chain**
205
206    For example, the *aarch64* Linaro Toolchain, which can be obtained from
207    `here <https://releases.linaro.org/components/toolchain/binaries/7.4-2019.02/aarch64-linux-gnu/>`_.
208
209    Alternatively, the Marvell SDK also provides GNU GCC toolchain, which is
210    optimized for cnxk CPU.
211
212 3. **Rootfile system**
213
214    Any *aarch64* supporting filesystem may be used. For example,
215    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
216    from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
217
218    Alternatively, the Marvell SDK provides the buildroot based root filesystem.
219    The SDK includes all the above prerequisites necessary to bring up the cnxk board.
220
221 - Follow the DPDK :doc:`../linux_gsg/index` to setup the basic DPDK environment.
222
223
224 Debugging Options
225 -----------------
226
227 .. _table_cnxk_common_debug_options:
228
229 .. table:: cnxk common debug options
230
231    +---+------------+-------------------------------------------------------+
232    | # | Component  | EAL log command                                       |
233    +===+============+=======================================================+
234    | 1 | Common     | --log-level='pmd\.cnxk\.base,8'                       |
235    +---+------------+-------------------------------------------------------+
236    | 2 | Mailbox    | --log-level='pmd\.cnxk\.mbox,8'                       |
237    +---+------------+-------------------------------------------------------+
238
239 Debugfs support
240 ~~~~~~~~~~~~~~~
241
242 The **RVU AF Linux kernel driver** provides support to dump RVU blocks
243 context or stats using debugfs.
244
245 Enable ``debugfs`` by:
246
247 1. Compile kernel with debugfs enabled, i.e ``CONFIG_DEBUGFS=y``.
248 2. Boot OCTEON CN9K/CN10K with debugfs supported kernel.
249 3. Verify ``debugfs`` mounted by default "mount | grep -i debugfs" or mount it manually by using.
250
251 .. code-block:: console
252
253        # mount -t debugfs none /sys/kernel/debug
254
255 Currently ``debugfs`` supports the following RVU blocks NIX, NPA, NPC, NDC,
256 SSO & RPM.
257
258 The file structure under ``/sys/kernel/debug`` is as follows
259
260 .. code-block:: console
261
262         octeontx2/
263         |
264         cn10k/
265         |-- rpm
266         |   |-- rpm0
267         |   |   '-- lmac0
268         |   |       '-- stats
269         |   |-- rpm1
270         |   |   |-- lmac0
271         |   |   |   '-- stats
272         |   |   '-- lmac1
273         |   |       '-- stats
274         |   '-- rpm2
275         |       '-- lmac0
276         |           '-- stats
277         |-- cpt
278         |   |-- cpt_engines_info
279         |   |-- cpt_engines_sts
280         |   |-- cpt_err_info
281         |   |-- cpt_lfs_info
282         |   '-- cpt_pc
283         |---- nix
284         |   |-- cq_ctx
285         |   |-- ndc_rx_cache
286         |   |-- ndc_rx_hits_miss
287         |   |-- ndc_tx_cache
288         |   |-- ndc_tx_hits_miss
289         |   |-- qsize
290         |   |-- rq_ctx
291         |   '-- sq_ctx
292         |-- npa
293         |   |-- aura_ctx
294         |   |-- ndc_cache
295         |   |-- ndc_hits_miss
296         |   |-- pool_ctx
297         |   '-- qsize
298         |-- npc
299         |    |-- mcam_info
300         |    |-- mcam_rules
301         |    '-- rx_miss_act_stats
302         |-- rsrc_alloc
303         '-- sso
304              |-- hws
305              |   '-- sso_hws_info
306              '-- hwgrp
307                  |-- sso_hwgrp_aq_thresh
308                  |-- sso_hwgrp_iaq_walk
309                  |-- sso_hwgrp_pc
310                  |-- sso_hwgrp_free_list_walk
311                  |-- sso_hwgrp_ient_walk
312                  '-- sso_hwgrp_taq_walk
313
314 RVU block LF allocation:
315
316 .. code-block:: console
317
318         cat /sys/kernel/debug/cn10k/rsrc_alloc
319
320         pcifunc    NPA    NIX    SSO GROUP    SSOWS    TIM    CPT
321         PF1         0       0
322         PF4                 1
323         PF13                          0, 1     0, 1      0
324
325 RPM example usage:
326
327 .. code-block:: console
328
329         cat /sys/kernel/debug/cn10k/rpm/rpm0/lmac0/stats
330
331         =======Link Status======
332
333         Link is UP 25000 Mbps
334
335         =======NIX RX_STATS(rpm port level)======
336
337         rx_ucast_frames: 0
338         rx_mcast_frames: 0
339         rx_bcast_frames: 0
340         rx_frames: 0
341         rx_bytes: 0
342         rx_drops: 0
343         rx_errors: 0
344
345         =======NIX TX_STATS(rpm port level)======
346
347         tx_ucast_frames: 0
348         tx_mcast_frames: 0
349         tx_bcast_frames: 0
350         tx_frames: 0
351         tx_bytes: 0
352         tx_drops: 0
353
354         =======rpm RX_STATS======
355
356         Octets of received packets: 0
357         Octets of received packets with out error: 0
358         Received packets with alignment errors: 0
359         Control/PAUSE packets received: 0
360         Packets received with Frame too long Errors: 0
361         Packets received with a1nrange length Errors: 0
362         Received packets: 0
363         Packets received with FrameCheckSequenceErrors: 0
364         Packets received with VLAN header: 0
365         Error packets: 0
366         Packets received with unicast DMAC: 0
367         Packets received with multicast DMAC: 0
368         Packets received with broadcast DMAC: 0
369         Dropped packets: 0
370         Total frames received on interface: 0
371         Packets received with an octet count < 64: 0
372         Packets received with an octet count == 64: 0
373         Packets received with an octet count of 65–127: 0
374         Packets received with an octet count of 128-255: 0
375         Packets received with an octet count of 256-511: 0
376         Packets received with an octet count of 512-1023: 0
377         Packets received with an octet count of 1024-1518: 0
378         Packets received with an octet count of > 1518: 0
379         Oversized Packets: 0
380         Jabber Packets: 0
381         Fragmented Packets: 0
382         CBFC(class based flow control) pause frames received for class 0: 0
383         CBFC pause frames received for class 1: 0
384         CBFC pause frames received for class 2: 0
385         CBFC pause frames received for class 3: 0
386         CBFC pause frames received for class 4: 0
387         CBFC pause frames received for class 5: 0
388         CBFC pause frames received for class 6: 0
389         CBFC pause frames received for class 7: 0
390         CBFC pause frames received for class 8: 0
391         CBFC pause frames received for class 9: 0
392         CBFC pause frames received for class 10: 0
393         CBFC pause frames received for class 11: 0
394         CBFC pause frames received for class 12: 0
395         CBFC pause frames received for class 13: 0
396         CBFC pause frames received for class 14: 0
397         CBFC pause frames received for class 15: 0
398         MAC control packets received: 0
399
400         =======rpm TX_STATS======
401
402         Total octets sent on the interface: 0
403         Total octets transmitted OK: 0
404         Control/Pause frames sent: 0
405         Total frames transmitted OK: 0
406         Total frames sent with VLAN header: 0
407         Error Packets: 0
408         Packets sent to unicast DMAC: 0
409         Packets sent to the multicast DMAC: 0
410         Packets sent to a broadcast DMAC: 0
411         Packets sent with an octet count == 64: 0
412         Packets sent with an octet count of 65–127: 0
413         Packets sent with an octet count of 128-255: 0
414         Packets sent with an octet count of 256-511: 0
415         Packets sent with an octet count of 512-1023: 0
416         Packets sent with an octet count of 1024-1518: 0
417         Packets sent with an octet count of > 1518: 0
418         CBFC(class based flow control) pause frames transmitted for class 0: 0
419         CBFC pause frames transmitted for class 1: 0
420         CBFC pause frames transmitted for class 2: 0
421         CBFC pause frames transmitted for class 3: 0
422         CBFC pause frames transmitted for class 4: 0
423         CBFC pause frames transmitted for class 5: 0
424         CBFC pause frames transmitted for class 6: 0
425         CBFC pause frames transmitted for class 7: 0
426         CBFC pause frames transmitted for class 8: 0
427         CBFC pause frames transmitted for class 9: 0
428         CBFC pause frames transmitted for class 10: 0
429         CBFC pause frames transmitted for class 11: 0
430         CBFC pause frames transmitted for class 12: 0
431         CBFC pause frames transmitted for class 13: 0
432         CBFC pause frames transmitted for class 14: 0
433         CBFC pause frames transmitted for class 15: 0
434         MAC control packets sent: 0
435         Total frames sent on the interface: 0
436
437 CPT example usage:
438
439 .. code-block:: console
440
441         cat /sys/kernel/debug/cn10k/cpt/cpt_pc
442
443         CPT instruction requests   0
444         CPT instruction latency    0
445         CPT NCB read requests      0
446         CPT NCB read latency       0
447         CPT read requests caused by UC fills   0
448         CPT active cycles pc       1395642
449         CPT clock count pc         5579867595493
450
451 NIX example usage:
452
453 .. code-block:: console
454
455         Usage: echo <nixlf> [cq number/all] > /sys/kernel/debug/cn10k/nix/cq_ctx
456                cat /sys/kernel/debug/cn10k/nix/cq_ctx
457         echo 0 0 > /sys/kernel/debug/cn10k/nix/cq_ctx
458         cat /sys/kernel/debug/cn10k/nix/cq_ctx
459
460         =====cq_ctx for nixlf:0 and qidx:0 is=====
461         W0: base                        158ef1a00
462
463         W1: wrptr                       0
464         W1: avg_con                     0
465         W1: cint_idx                    0
466         W1: cq_err                      0
467         W1: qint_idx                    0
468         W1: bpid                        0
469         W1: bp_ena                      0
470
471         W2: update_time                 31043
472         W2:avg_level                    255
473         W2: head                        0
474         W2:tail                         0
475
476         W3: cq_err_int_ena              5
477         W3:cq_err_int                   0
478         W3: qsize                       4
479         W3:caching                      1
480         W3: substream                   0x000
481         W3: ena                                 1
482         W3: drop_ena                    1
483         W3: drop                        64
484         W3: bp                          0
485
486 NPA example usage:
487
488 .. code-block:: console
489
490         Usage: echo <npalf> [pool number/all] > /sys/kernel/debug/cn10k/npa/pool_ctx
491                cat /sys/kernel/debug/cn10k/npa/pool_ctx
492         echo 0 0 > /sys/kernel/debug/cn10k/npa/pool_ctx
493         cat /sys/kernel/debug/cn10k/npa/pool_ctx
494
495         ======POOL : 0=======
496         W0: Stack base          1375bff00
497         W1: ena                 1
498         W1: nat_align           1
499         W1: stack_caching       1
500         W1: stack_way_mask      0
501         W1: buf_offset          1
502         W1: buf_size            19
503         W2: stack_max_pages     24315
504         W2: stack_pages         24314
505         W3: op_pc               267456
506         W4: stack_offset        2
507         W4: shift               5
508         W4: avg_level           255
509         W4: avg_con             0
510         W4: fc_ena              0
511         W4: fc_stype            0
512         W4: fc_hyst_bits        0
513         W4: fc_up_crossing      0
514         W4: update_time         62993
515         W5: fc_addr             0
516         W6: ptr_start           1593adf00
517         W7: ptr_end             180000000
518         W8: err_int             0
519         W8: err_int_ena         7
520         W8: thresh_int          0
521         W8: thresh_int_ena      0
522         W8: thresh_up           0
523         W8: thresh_qint_idx     0
524         W8: err_qint_idx        0
525
526 NPC example usage:
527
528 .. code-block:: console
529
530         cat /sys/kernel/debug/cn10k/npc/mcam_info
531
532         NPC MCAM info:
533         RX keywidth    : 224bits
534         TX keywidth    : 224bits
535
536         MCAM entries   : 2048
537         Reserved       : 158
538         Available      : 1890
539
540         MCAM counters  : 512
541         Reserved       : 1
542         Available      : 511
543
544 SSO example usage:
545
546 .. code-block:: console
547
548         Usage: echo [<hws>/all] > /sys/kernel/debug/cn10k/sso/hws/sso_hws_info
549         echo 0 > /sys/kernel/debug/cn10k/sso/hws/sso_hws_info
550
551         ==================================================
552         SSOW HWS[0] Arbitration State      0x0
553         SSOW HWS[0] Guest Machine Control  0x0
554         SSOW HWS[0] SET[0] Group Mask[0] 0xffffffffffffffff
555         SSOW HWS[0] SET[0] Group Mask[1] 0xffffffffffffffff
556         SSOW HWS[0] SET[0] Group Mask[2] 0xffffffffffffffff
557         SSOW HWS[0] SET[0] Group Mask[3] 0xffffffffffffffff
558         SSOW HWS[0] SET[1] Group Mask[0] 0xffffffffffffffff
559         SSOW HWS[0] SET[1] Group Mask[1] 0xffffffffffffffff
560         SSOW HWS[0] SET[1] Group Mask[2] 0xffffffffffffffff
561         SSOW HWS[0] SET[1] Group Mask[3] 0xffffffffffffffff
562         ==================================================
563
564 Compile DPDK
565 ------------
566
567 DPDK may be compiled either natively on OCTEON CN9K/CN10K platform or cross-compiled on
568 an x86 based platform.
569
570 Native Compilation
571 ~~~~~~~~~~~~~~~~~~
572
573 .. code-block:: console
574
575         meson build
576         ninja -C build
577
578 Cross Compilation
579 ~~~~~~~~~~~~~~~~~
580
581 Refer to :doc:`../linux_gsg/cross_build_dpdk_for_arm64` for generic arm64 details.
582
583 .. code-block:: console
584
585         meson build --cross-file config/arm/arm64_cn10k_linux_gcc
586         ninja -C build
587
588 .. note::
589
590    By default, meson cross compilation uses ``aarch64-linux-gnu-gcc`` toolchain,
591    if Marvell toolchain is available then it can be used by overriding the
592    c, cpp, ar, strip ``binaries`` attributes to respective Marvell
593    toolchain binaries in ``config/arm/arm64_cn10k_linux_gcc`` file.