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