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.