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