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