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