doc/guides/platform/octeontx2.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2019 Marvell International Ltd.
   3
   4 Marvell OCTEON TX2 Platform Guide
   5 =================================
   6
   7 This document gives an overview of **Marvell OCTEON TX2** RVU H/W block,
   8 packet flow and procedure to build DPDK on OCTEON TX2 platform.
   9
  10 More information about OCTEON TX2 SoC can be found at `Marvell Official Website
  11 <https://www.marvell.com/embedded-processors/infrastructure-processors/>`_.
  12
  13 Supported OCTEON TX2 SoCs
  14 -------------------------
  15
  16 - CN96xx
  17 - CN93xx
  18 - CNF95xx
  19
  20 OCTEON TX2 Resource Virtualization Unit architecture
  21 ----------------------------------------------------
  22
  23 The :numref:`figure_octeontx2_resource_virtualization` diagram depicts the
  24 RVU architecture and a resource provisioning example.
  25
  26 .. _figure_octeontx2_resource_virtualization:
  27
  28 .. figure:: img/octeontx2_resource_virtualization.*
  29
  30     OCTEON TX2 Resource virtualization architecture and provisioning example
  31
  32
  33 Resource Virtualization Unit (RVU) on Marvell's OCTEON TX2 SoC maps HW
  34 resources belonging to the network, crypto and other functional blocks onto
  35 PCI-compatible physical and virtual functions.
  36
  37 Each functional block has multiple local functions (LFs) for
  38 provisioning to different PCIe devices. RVU supports multiple PCIe SRIOV
  39 physical functions (PFs) and virtual functions (VFs).
  40
  41 The :numref:`table_octeontx2_rvu_dpdk_mapping` shows the various local
  42 functions (LFs) provided by the RVU and its functional mapping to
  43 DPDK subsystem.
  44
  45 .. _table_octeontx2_rvu_dpdk_mapping:
  46
  47 .. table:: RVU managed functional blocks and its mapping to DPDK subsystem
  48
  49    +---+-----+--------------------------------------------------------------+
  50    | # | LF  | DPDK subsystem mapping                                       |
  51    +===+=====+==============================================================+
  52    | 1 | NIX | rte_ethdev, rte_tm, rte_event_eth_[rt]x_adapter, rte_security|
  53    +---+-----+--------------------------------------------------------------+
  54    | 2 | NPA | rte_mempool                                                  |
  55    +---+-----+--------------------------------------------------------------+
  56    | 3 | NPC | rte_flow                                                     |
  57    +---+-----+--------------------------------------------------------------+
  58    | 4 | CPT | rte_cryptodev, rte_event_crypto_adapter                      |
  59    +---+-----+--------------------------------------------------------------+
  60    | 5 | SSO | rte_eventdev                                                 |
  61    +---+-----+--------------------------------------------------------------+
  62    | 6 | TIM | rte_event_timer_adapter                                      |
  63    +---+-----+--------------------------------------------------------------+
  64    | 7 | LBK | rte_ethdev                                                   |
  65    +---+-----+--------------------------------------------------------------+
  66    | 8 | DPI | rte_rawdev                                                   |
  67    +---+-----+--------------------------------------------------------------+
  68
  69 PF0 is called the administrative / admin function (AF) and has exclusive
  70 privileges to provision RVU functional block's LFs to each of the PF/VF.
  71
  72 PF/VFs communicates with AF via a shared memory region (mailbox).Upon receiving
  73 requests from PF/VF, AF does resource provisioning and other HW configuration.
  74
  75 AF is always attached to host, but PF/VFs may be used by host kernel itself,
  76 or attached to VMs or to userspace applications like DPDK, etc. So, AF has to
  77 handle provisioning/configuration requests sent by any device from any domain.
  78
  79 The AF driver does not receive or process any data.
  80 It is only a configuration driver used in control path.
  81
  82 The :numref:`figure_octeontx2_resource_virtualization` diagram also shows a
  83 resource provisioning example where,
  84
  85 1. PFx and PFx-VF0 bound to Linux netdev driver.
  86 2. PFx-VF1 ethdev driver bound to the first DPDK application.
  87 3. PFy ethdev driver, PFy-VF0 ethdev driver, PFz eventdev driver, PFm-VF0 cryptodev driver bound to the second DPDK application.
  88
  89 LBK HW Access
  90 -------------
  91
  92 Loopback HW Unit (LBK) receives packets from NIX-RX and sends packets back to NIX-TX.
  93 The loopback block has N channels and contains data buffering that is shared across
  94 all channels. The LBK HW Unit is abstracted using ethdev subsystem, Where PF0's
  95 VFs are exposed as ethdev device and odd-even pairs of VFs are tied together,
  96 that is, packets sent on odd VF end up received on even VF and vice versa.
  97 This would enable HW accelerated means of communication between two domains
  98 where even VF bound to the first domain and odd VF bound to the second domain.
  99
 100 Typical application usage models are,
 101
 102 #. Communication between the Linux kernel and DPDK application.
 103 #. Exception path to Linux kernel from DPDK application as SW ``KNI`` replacement.
 104 #. Communication between two different DPDK applications.
 105
 106 OCTEON TX2 packet flow
 107 ----------------------
 108
 109 The :numref:`figure_octeontx2_packet_flow_hw_accelerators` diagram depicts
 110 the packet flow on OCTEON TX2 SoC in conjunction with use of various HW accelerators.
 111
 112 .. _figure_octeontx2_packet_flow_hw_accelerators:
 113
 114 .. figure:: img/octeontx2_packet_flow_hw_accelerators.*
 115
 116     OCTEON TX2 packet flow in conjunction with use of HW accelerators
 117
 118 HW Offload Drivers
 119 ------------------
 120
 121 This section lists dataplane H/W block(s) available in OCTEON TX2 SoC.
 122
 123 #. **Ethdev Driver**
 124    See :doc:`../nics/octeontx2` for NIX Ethdev driver information.
 125
 126 #. **Mempool Driver**
 127    See :doc:`../mempool/octeontx2` for NPA mempool driver information.
 128
 129 #. **Event Device Driver**
 130    See :doc:`../eventdevs/octeontx2` for SSO event device driver information.
 131
 132 #. **DMA Rawdev Driver**
 133    See :doc:`../rawdevs/octeontx2_dma` for DMA driver information.
 134
 135 Procedure to Setup Platform
 136 ---------------------------
 137
 138 There are three main prerequisites for setting up DPDK on OCTEON TX2
 139 compatible board:
 140
 141 1. **OCTEON TX2 Linux kernel driver**
 142
 143    The dependent kernel drivers can be obtained from the
 144    `kernel.org <https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/drivers/net/ethernet/marvell/octeontx2>`_.
 145
 146    Alternatively, the Marvell SDK also provides the required kernel drivers.
 147
 148    Linux kernel should be configured with the following features enabled:
 149
 150 .. code-block:: console
 151
 152         # 64K pages enabled for better performance
 153         CONFIG_ARM64_64K_PAGES=y
 154         CONFIG_ARM64_VA_BITS_48=y
 155         # huge pages support enabled
 156         CONFIG_HUGETLBFS=y
 157         CONFIG_HUGETLB_PAGE=y
 158         # VFIO enabled with TYPE1 IOMMU at minimum
 159         CONFIG_VFIO_IOMMU_TYPE1=y
 160         CONFIG_VFIO_VIRQFD=y
 161         CONFIG_VFIO=y
 162         CONFIG_VFIO_NOIOMMU=y
 163         CONFIG_VFIO_PCI=y
 164         CONFIG_VFIO_PCI_MMAP=y
 165         # SMMUv3 driver
 166         CONFIG_ARM_SMMU_V3=y
 167         # ARMv8.1 LSE atomics
 168         CONFIG_ARM64_LSE_ATOMICS=y
 169         # OCTEONTX2 drivers
 170         CONFIG_OCTEONTX2_MBOX=y
 171         CONFIG_OCTEONTX2_AF=y
 172         # Enable if netdev PF driver required
 173         CONFIG_OCTEONTX2_PF=y
 174         # Enable if netdev VF driver required
 175         CONFIG_OCTEONTX2_VF=y
 176         CONFIG_CRYPTO_DEV_OCTEONTX2_CPT=y
 177         # Enable if OCTEONTX2 DMA PF driver required
 178         CONFIG_OCTEONTX2_DPI_PF=n
 179
 180 2. **ARM64 Linux Tool Chain**
 181
 182    For example, the *aarch64* Linaro Toolchain, which can be obtained from
 183    `here <https://releases.linaro.org/components/toolchain/binaries/7.4-2019.02/aarch64-linux-gnu/>`_.
 184
 185    Alternatively, the Marvell SDK also provides GNU GCC toolchain, which is
 186    optimized for OCTEON TX2 CPU.
 187
 188 3. **Rootfile system**
 189
 190    Any *aarch64* supporting filesystem may be used. For example,
 191    Ubuntu 15.10 (Wily) or 16.04 LTS (Xenial) userland which can be obtained
 192    from `<http://cdimage.ubuntu.com/ubuntu-base/releases/16.04/release/ubuntu-base-16.04.1-base-arm64.tar.gz>`_.
 193
 194    Alternatively, the Marvell SDK provides the buildroot based root filesystem.
 195    The SDK includes all the above prerequisites necessary to bring up the OCTEON TX2 board.
 196
 197 - Follow the DPDK :doc:`../linux_gsg/index` to setup the basic DPDK environment.
 198
 199
 200 Debugging Options
 201 -----------------
 202
 203 .. _table_octeontx2_common_debug_options:
 204
 205 .. table:: OCTEON TX2 common debug options
 206
 207    +---+------------+-------------------------------------------------------+
 208    | # | Component  | EAL log command                                       |
 209    +===+============+=======================================================+
 210    | 1 | Common     | --log-level='pmd\.octeontx2\.base,8'                  |
 211    +---+------------+-------------------------------------------------------+
 212    | 2 | Mailbox    | --log-level='pmd\.octeontx2\.mbox,8'                  |
 213    +---+------------+-------------------------------------------------------+
 214
 215 Debugfs support
 216 ~~~~~~~~~~~~~~~
 217
 218 The **OCTEON TX2 Linux kernel driver** provides support to dump RVU blocks
 219 context or stats using debugfs.
 220
 221 Enable ``debugfs`` by:
 222
 223 1. Compile kernel with debugfs enabled, i.e ``CONFIG_DEBUGFS=y``.
 224 2. Boot OCTEON TX2 with debugfs supported kernel.
 225 3. Verify ``debugfs`` mounted by default "mount | grep -i debugfs" or mount it manually by using.
 226
 227 .. code-block:: console
 228
 229        # mount -t debugfs none /sys/kernel/debug
 230
 231 Currently ``debugfs`` supports the following RVU blocks NIX, NPA, NPC, NDC,
 232 SSO & CGX.
 233
 234 The file structure under ``/sys/kernel/debug`` is as follows
 235
 236 .. code-block:: console
 237
 238         octeontx2/
 239         |-- cgx
 240         |   |-- cgx0
 241         |   |   '-- lmac0
 242         |   |       '-- stats
 243         |   |-- cgx1
 244         |   |   |-- lmac0
 245         |   |   |   '-- stats
 246         |   |   '-- lmac1
 247         |   |       '-- stats
 248         |   '-- cgx2
 249         |       '-- lmac0
 250         |           '-- stats
 251         |-- cpt
 252         |   |-- cpt_engines_info
 253         |   |-- cpt_engines_sts
 254         |   |-- cpt_err_info
 255         |   |-- cpt_lfs_info
 256         |   '-- cpt_pc
 257         |---- nix
 258         |   |-- cq_ctx
 259         |   |-- ndc_rx_cache
 260         |   |-- ndc_rx_hits_miss
 261         |   |-- ndc_tx_cache
 262         |   |-- ndc_tx_hits_miss
 263         |   |-- qsize
 264         |   |-- rq_ctx
 265         |   |-- sq_ctx
 266         |   '-- tx_stall_hwissue
 267         |-- npa
 268         |   |-- aura_ctx
 269         |   |-- ndc_cache
 270         |   |-- ndc_hits_miss
 271         |   |-- pool_ctx
 272         |   '-- qsize
 273         |-- npc
 274         |    |-- mcam_info
 275         |    '-- rx_miss_act_stats
 276         |-- rsrc_alloc
 277         '-- sso
 278              |-- hws
 279              |   '-- sso_hws_info
 280              '-- hwgrp
 281                  |-- sso_hwgrp_aq_thresh
 282                  |-- sso_hwgrp_iaq_walk
 283                  |-- sso_hwgrp_pc
 284                  |-- sso_hwgrp_free_list_walk
 285                  |-- sso_hwgrp_ient_walk
 286                  '-- sso_hwgrp_taq_walk
 287
 288 RVU block LF allocation:
 289
 290 .. code-block:: console
 291
 292         cat /sys/kernel/debug/octeontx2/rsrc_alloc
 293
 294         pcifunc    NPA    NIX    SSO GROUP    SSOWS    TIM    CPT
 295         PF1         0       0
 296         PF4                 1
 297         PF13                          0, 1     0, 1      0
 298
 299 CGX example usage:
 300
 301 .. code-block:: console
 302
 303         cat /sys/kernel/debug/octeontx2/cgx/cgx2/lmac0/stats
 304
 305         =======Link Status======
 306         Link is UP 40000 Mbps
 307         =======RX_STATS======
 308         Received packets: 0
 309         Octets of received packets: 0
 310         Received PAUSE packets: 0
 311         Received PAUSE and control packets: 0
 312         Filtered DMAC0 (NIX-bound) packets: 0
 313         Filtered DMAC0 (NIX-bound) octets: 0
 314         Packets dropped due to RX FIFO full: 0
 315         Octets dropped due to RX FIFO full: 0
 316         Error packets: 0
 317         Filtered DMAC1 (NCSI-bound) packets: 0
 318         Filtered DMAC1 (NCSI-bound) octets: 0
 319         NCSI-bound packets dropped: 0
 320         NCSI-bound octets dropped: 0
 321         =======TX_STATS======
 322         Packets dropped due to excessive collisions: 0
 323         Packets dropped due to excessive deferral: 0
 324         Multiple collisions before successful transmission: 0
 325         Single collisions before successful transmission: 0
 326         Total octets sent on the interface: 0
 327         Total frames sent on the interface: 0
 328         Packets sent with an octet count < 64: 0
 329         Packets sent with an octet count == 64: 0
 330         Packets sent with an octet count of 65127: 0
 331         Packets sent with an octet count of 128-255: 0
 332         Packets sent with an octet count of 256-511: 0
 333         Packets sent with an octet count of 512-1023: 0
 334         Packets sent with an octet count of 1024-1518: 0
 335         Packets sent with an octet count of > 1518: 0
 336         Packets sent to a broadcast DMAC: 0
 337         Packets sent to the multicast DMAC: 0
 338         Transmit underflow and were truncated: 0
 339         Control/PAUSE packets sent: 0
 340
 341 CPT example usage:
 342
 343 .. code-block:: console
 344
 345         cat /sys/kernel/debug/octeontx2/cpt/cpt_pc
 346
 347         CPT instruction requests   0
 348         CPT instruction latency    0
 349         CPT NCB read requests      0
 350         CPT NCB read latency       0
 351         CPT read requests caused by UC fills   0
 352         CPT active cycles pc       1395642
 353         CPT clock count pc         5579867595493
 354
 355 NIX example usage:
 356
 357 .. code-block:: console
 358
 359         Usage: echo <nixlf> [cq number/all] > /sys/kernel/debug/octeontx2/nix/cq_ctx
 360                cat /sys/kernel/debug/octeontx2/nix/cq_ctx
 361         echo 0 0 > /sys/kernel/debug/octeontx2/nix/cq_ctx
 362         cat /sys/kernel/debug/octeontx2/nix/cq_ctx
 363
 364         =====cq_ctx for nixlf:0 and qidx:0 is=====
 365         W0: base                        158ef1a00
 366
 367         W1: wrptr                       0
 368         W1: avg_con                     0
 369         W1: cint_idx                    0
 370         W1: cq_err                      0
 371         W1: qint_idx                    0
 372         W1: bpid                        0
 373         W1: bp_ena                      0
 374
 375         W2: update_time                 31043
 376         W2:avg_level                    255
 377         W2: head                        0
 378         W2:tail                         0
 379
 380         W3: cq_err_int_ena              5
 381         W3:cq_err_int                   0
 382         W3: qsize                       4
 383         W3:caching                      1
 384         W3: substream                   0x000
 385         W3: ena                                 1
 386         W3: drop_ena                    1
 387         W3: drop                        64
 388         W3: bp                          0
 389
 390 NPA example usage:
 391
 392 .. code-block:: console
 393
 394         Usage: echo <npalf> [pool number/all] > /sys/kernel/debug/octeontx2/npa/pool_ctx
 395                cat /sys/kernel/debug/octeontx2/npa/pool_ctx
 396         echo 0 0 > /sys/kernel/debug/octeontx2/npa/pool_ctx
 397         cat /sys/kernel/debug/octeontx2/npa/pool_ctx
 398
 399         ======POOL : 0=======
 400         W0: Stack base          1375bff00
 401         W1: ena                 1
 402         W1: nat_align           1
 403         W1: stack_caching       1
 404         W1: stack_way_mask      0
 405         W1: buf_offset          1
 406         W1: buf_size            19
 407         W2: stack_max_pages     24315
 408         W2: stack_pages         24314
 409         W3: op_pc               267456
 410         W4: stack_offset        2
 411         W4: shift               5
 412         W4: avg_level           255
 413         W4: avg_con             0
 414         W4: fc_ena              0
 415         W4: fc_stype            0
 416         W4: fc_hyst_bits        0
 417         W4: fc_up_crossing      0
 418         W4: update_time         62993
 419         W5: fc_addr             0
 420         W6: ptr_start           1593adf00
 421         W7: ptr_end             180000000
 422         W8: err_int             0
 423         W8: err_int_ena         7
 424         W8: thresh_int          0
 425         W8: thresh_int_ena      0
 426         W8: thresh_up           0
 427         W8: thresh_qint_idx     0
 428         W8: err_qint_idx        0
 429
 430 NPC example usage:
 431
 432 .. code-block:: console
 433
 434         cat /sys/kernel/debug/octeontx2/npc/mcam_info
 435
 436         NPC MCAM info:
 437         RX keywidth    : 224bits
 438         TX keywidth    : 224bits
 439
 440         MCAM entries   : 2048
 441         Reserved       : 158
 442         Available      : 1890
 443
 444         MCAM counters  : 512
 445         Reserved       : 1
 446         Available      : 511
 447
 448 SSO example usage:
 449
 450 .. code-block:: console
 451
 452         Usage: echo [<hws>/all] > /sys/kernel/debug/octeontx2/sso/hws/sso_hws_info
 453         echo 0 > /sys/kernel/debug/octeontx2/sso/hws/sso_hws_info
 454
 455         ==================================================
 456         SSOW HWS[0] Arbitration State      0x0
 457         SSOW HWS[0] Guest Machine Control  0x0
 458         SSOW HWS[0] SET[0] Group Mask[0] 0xffffffffffffffff
 459         SSOW HWS[0] SET[0] Group Mask[1] 0xffffffffffffffff
 460         SSOW HWS[0] SET[0] Group Mask[2] 0xffffffffffffffff
 461         SSOW HWS[0] SET[0] Group Mask[3] 0xffffffffffffffff
 462         SSOW HWS[0] SET[1] Group Mask[0] 0xffffffffffffffff
 463         SSOW HWS[0] SET[1] Group Mask[1] 0xffffffffffffffff
 464         SSOW HWS[0] SET[1] Group Mask[2] 0xffffffffffffffff
 465         SSOW HWS[0] SET[1] Group Mask[3] 0xffffffffffffffff
 466         ==================================================
 467
 468 Compile DPDK
 469 ------------
 470
 471 DPDK may be compiled either natively on OCTEON TX2 platform or cross-compiled on
 472 an x86 based platform.
 473
 474 Native Compilation
 475 ~~~~~~~~~~~~~~~~~~
 476
 477 make build
 478 ^^^^^^^^^^
 479
 480 .. code-block:: console
 481
 482         make config T=arm64-octeontx2-linux-gcc
 483         make -j
 484
 485 The example applications can be compiled using the following:
 486
 487 .. code-block:: console
 488
 489         cd <dpdk directory>
 490         export RTE_SDK=$PWD
 491         export RTE_TARGET=build
 492         cd examples/<application>
 493         make -j
 494
 495 meson build
 496 ^^^^^^^^^^^
 497
 498 .. code-block:: console
 499
 500         meson build
 501         ninja -C build
 502
 503 Cross Compilation
 504 ~~~~~~~~~~~~~~~~~
 505
 506 Refer to :doc:`../linux_gsg/cross_build_dpdk_for_arm64` for generic arm64 details.
 507
 508 make build
 509 ^^^^^^^^^^
 510
 511 .. code-block:: console
 512
 513         make config T=arm64-octeontx2-linux-gcc
 514         make -j CROSS=aarch64-marvell-linux-gnu- CONFIG_RTE_KNI_KMOD=n
 515
 516 meson build
 517 ^^^^^^^^^^^
 518
 519 .. code-block:: console
 520
 521         meson build --cross-file config/arm/arm64_octeontx2_linux_gcc
 522         ninja -C build
 523
 524 .. note::
 525
 526    By default, meson cross compilation uses ``aarch64-linux-gnu-gcc`` toolchain,
 527    if Marvell toolchain is available then it can be used by overriding the
 528    c, cpp, ar, strip ``binaries`` attributes to respective Marvell
 529    toolchain binaries in ``config/arm/arm64_octeontx2_linux_gcc`` file.