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