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