doc/guides/eventdevs/octeontx2.rst

   1 ..  SPDX-License-Identifier: BSD-3-Clause
   2     Copyright(c) 2019 Marvell International Ltd.
   3
   4 OCTEON TX2 SSO Eventdev Driver
   5 ===============================
   6
   7 The OCTEON TX2 SSO PMD (**librte_event_octeontx2**) provides poll mode
   8 eventdev driver support for the inbuilt event device found in the **Marvell OCTEON TX2**
   9 SoC family.
  10
  11 More information about OCTEON TX2 SoC can be found at `Marvell Official Website
  12 <https://www.marvell.com/embedded-processors/infrastructure-processors/>`_.
  13
  14 Features
  15 --------
  16
  17 Features of the OCTEON TX2 SSO PMD are:
  18
  19 - 256 Event queues
  20 - 26 (dual) and 52 (single) Event ports
  21 - HW event scheduler
  22 - Supports 1M flows per event queue
  23 - Flow based event pipelining
  24 - Flow pinning support in flow based event pipelining
  25 - Queue based event pipelining
  26 - Supports ATOMIC, ORDERED, PARALLEL schedule types per flow
  27 - Event scheduling QoS based on event queue priority
  28 - Open system with configurable amount of outstanding events limited only by
  29   DRAM
  30 - HW accelerated dequeue timeout support to enable power management
  31 - HW managed event timers support through TIM, with high precision and
  32   time granularity of 2.5us.
  33 - Up to 256 TIM rings aka event timer adapters.
  34 - Up to 8 rings traversed in parallel.
  35 - HW managed packets enqueued from ethdev to eventdev exposed through event eth
  36   RX adapter.
  37 - N:1 ethernet device Rx queue to Event queue mapping.
  38 - Lockfree Tx from event eth Tx adapter using ``RTE_ETH_TX_OFFLOAD_MT_LOCKFREE``
  39   capability while maintaining receive packet order.
  40 - Full Rx/Tx offload support defined through ethdev queue config.
  41
  42 Prerequisites and Compilation procedure
  43 ---------------------------------------
  44
  45    See :doc:`../platform/octeontx2` for setup information.
  46
  47
  48 Runtime Config Options
  49 ----------------------
  50
  51 - ``Maximum number of in-flight events`` (default ``8192``)
  52
  53   In **Marvell OCTEON TX2** the max number of in-flight events are only limited
  54   by DRAM size, the ``xae_cnt`` devargs parameter is introduced to provide
  55   upper limit for in-flight events.
  56   For example::
  57
  58     -a 0002:0e:00.0,xae_cnt=16384
  59
  60 - ``Force legacy mode``
  61
  62   The ``single_ws`` devargs parameter is introduced to force legacy mode i.e
  63   single workslot mode in SSO and disable the default dual workslot mode.
  64   For example::
  65
  66     -a 0002:0e:00.0,single_ws=1
  67
  68 - ``Event Group QoS support``
  69
  70   SSO GGRPs i.e. queue uses DRAM & SRAM buffers to hold in-flight
  71   events. By default the buffers are assigned to the SSO GGRPs to
  72   satisfy minimum HW requirements. SSO is free to assign the remaining
  73   buffers to GGRPs based on a preconfigured threshold.
  74   We can control the QoS of SSO GGRP by modifying the above mentioned
  75   thresholds. GGRPs that have higher importance can be assigned higher
  76   thresholds than the rest. The dictionary format is as follows
  77   [Qx-XAQ-TAQ-IAQ][Qz-XAQ-TAQ-IAQ] expressed in percentages, 0 represents
  78   default.
  79   For example::
  80
  81     -a 0002:0e:00.0,qos=[1-50-50-50]
  82
  83 - ``TIM disable NPA``
  84
  85   By default chunks are allocated from NPA then TIM can automatically free
  86   them when traversing the list of chunks. The ``tim_disable_npa`` devargs
  87   parameter disables NPA and uses software mempool to manage chunks
  88   For example::
  89
  90     -a 0002:0e:00.0,tim_disable_npa=1
  91
  92 - ``TIM modify chunk slots``
  93
  94   The ``tim_chnk_slots`` devargs can be used to modify number of chunk slots.
  95   Chunks are used to store event timers, a chunk can be visualised as an array
  96   where the last element points to the next chunk and rest of them are used to
  97   store events. TIM traverses the list of chunks and enqueues the event timers
  98   to SSO. The default value is 255 and the max value is 4095.
  99   For example::
 100
 101     -a 0002:0e:00.0,tim_chnk_slots=1023
 102
 103 - ``TIM enable arm/cancel statistics``
 104
 105   The ``tim_stats_ena`` devargs can be used to enable arm and cancel stats of
 106   event timer adapter.
 107   For example::
 108
 109     -a 0002:0e:00.0,tim_stats_ena=1
 110
 111 - ``TIM limit max rings reserved``
 112
 113   The ``tim_rings_lmt`` devargs can be used to limit the max number of TIM
 114   rings i.e. event timer adapter reserved on probe. Since, TIM rings are HW
 115   resources we can avoid starving other applications by not grabbing all the
 116   rings.
 117   For example::
 118
 119     -a 0002:0e:00.0,tim_rings_lmt=5
 120
 121 - ``TIM ring control internal parameters``
 122
 123   When using multiple TIM rings the ``tim_ring_ctl`` devargs can be used to
 124   control each TIM rings internal parameters uniquely. The following dict
 125   format is expected [ring-chnk_slots-disable_npa-stats_ena]. 0 represents
 126   default values.
 127   For Example::
 128
 129     -a 0002:0e:00.0,tim_ring_ctl=[2-1023-1-0]
 130
 131 - ``Lock NPA contexts in NDC``
 132
 133    Lock NPA aura and pool contexts in NDC cache.
 134    The device args take hexadecimal bitmask where each bit represent the
 135    corresponding aura/pool id.
 136
 137    For example::
 138
 139       -a 0002:0e:00.0,npa_lock_mask=0xf
 140
 141 - ``Force Rx Back pressure``
 142
 143    Force Rx back pressure when same mempool is used across ethernet device
 144    connected to event device.
 145
 146    For example::
 147
 148       -a 0002:0e:00.0,force_rx_bp=1
 149
 150 Debugging Options
 151 -----------------
 152
 153 .. _table_octeontx2_event_debug_options:
 154
 155 .. table:: OCTEON TX2 event device debug options
 156
 157    +---+------------+-------------------------------------------------------+
 158    | # | Component  | EAL log command                                       |
 159    +===+============+=======================================================+
 160    | 1 | SSO        | --log-level='pmd\.event\.octeontx2,8'                 |
 161    +---+------------+-------------------------------------------------------+
 162    | 2 | TIM        | --log-level='pmd\.event\.octeontx2\.timer,8'          |
 163    +---+------------+-------------------------------------------------------+
 164
 165 Limitations
 166 -----------
 167
 168 Rx adapter support
 169 ~~~~~~~~~~~~~~~~~~
 170
 171 Using the same mempool for all the ethernet device ports connected to
 172 event device would cause back pressure to be asserted only on the first
 173 ethernet device.
 174 Back pressure is automatically disabled when using same mempool for all the
 175 ethernet devices connected to event device to override this applications can
 176 use `force_rx_bp=1` device arguments.
 177 Using unique mempool per each ethernet device is recommended when they are
 178 connected to event device.