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