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