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