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_pmd_octeontx2_event**) 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
  36 Prerequisites and Compilation procedure
  37 ---------------------------------------
  38
  39    See :doc:`../platform/octeontx2` for setup information.
  40
  41 Pre-Installation Configuration
  42 ------------------------------
  43
  44 Compile time Config Options
  45 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  46
  47 The following option can be modified in the ``config`` file.
  48
  49 - ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX2_EVENTDEV`` (default ``y``)
  50
  51   Toggle compilation of the ``librte_pmd_octeontx2_event`` driver.
  52
  53 Runtime Config Options
  54 ~~~~~~~~~~~~~~~~~~~~~~
  55
  56 - ``Maximum number of in-flight events`` (default ``8192``)
  57
  58   In **Marvell OCTEON TX2** the max number of in-flight events are only limited
  59   by DRAM size, the ``xae_cnt`` devargs parameter is introduced to provide
  60   upper limit for in-flight events.
  61   For example::
  62
  63     --dev "0002:0e:00.0,xae_cnt=16384"
  64
  65 - ``Force legacy mode``
  66
  67   The ``single_ws`` devargs parameter is introduced to force legacy mode i.e
  68   single workslot mode in SSO and disable the default dual workslot mode.
  69   For example::
  70
  71     --dev "0002:0e:00.0,single_ws=1"
  72
  73 - ``Event Group QoS support``
  74
  75   SSO GGRPs i.e. queue uses DRAM & SRAM buffers to hold in-flight
  76   events. By default the buffers are assigned to the SSO GGRPs to
  77   satisfy minimum HW requirements. SSO is free to assign the remaining
  78   buffers to GGRPs based on a preconfigured threshold.
  79   We can control the QoS of SSO GGRP by modifying the above mentioned
  80   thresholds. GGRPs that have higher importance can be assigned higher
  81   thresholds than the rest. The dictionary format is as follows
  82   [Qx-XAQ-TAQ-IAQ][Qz-XAQ-TAQ-IAQ] expressed in percentages, 0 represents
  83   default.
  84   For example::
  85
  86     --dev "0002:0e:00.0,qos=[1-50-50-50]"
  87
  88 - ``Selftest``
  89
  90   The functionality of OCTEON TX2 eventdev can be verified using this option,
  91   various unit and functional tests are run to verify the sanity.
  92   The tests are run once the vdev creation is successfully complete.
  93   For example::
  94
  95     --dev "0002:0e:00.0,selftest=1"
  96
  97 - ``TIM disable NPA``
  98
  99   By default chunks are allocated from NPA then TIM can automatically free
 100   them when traversing the list of chunks. The ``tim_disable_npa`` devargs
 101   parameter disables NPA and uses software mempool to manage chunks
 102   For example::
 103
 104     --dev "0002:0e:00.0,tim_disable_npa=1"
 105
 106 - ``TIM modify chunk slots``
 107
 108   The ``tim_chnk_slots`` devargs can be used to modify number of chunk slots.
 109   Chunks are used to store event timers, a chunk can be visualised as an array
 110   where the last element points to the next chunk and rest of them are used to
 111   store events. TIM traverses the list of chunks and enqueues the event timers
 112   to SSO. The default value is 255 and the max value is 4095.
 113   For example::
 114
 115     --dev "0002:0e:00.0,tim_chnk_slots=1023"
 116
 117 - ``TIM enable arm/cancel statistics``
 118
 119   The ``tim_stats_ena`` devargs can be used to enable arm and cancel stats of
 120   event timer adapter.
 121   For example::
 122
 123     --dev "0002:0e:00.0,tim_stats_ena=1"
 124
 125 - ``TIM limit max rings reserved``
 126
 127   The ``tim_rings_lmt`` devargs can be used to limit the max number of TIM
 128   rings i.e. event timer adapter reserved on probe. Since, TIM rings are HW
 129   resources we can avoid starving other applications by not grabbing all the
 130   rings.
 131   For example::
 132
 133     --dev "0002:0e:00.0,tim_rings_lmt=5"
 134
 135 - ``TIM ring control internal parameters``
 136
 137   When using multiple TIM rings the ``tim_ring_ctl`` devargs can be used to
 138   control each TIM rings internal parameters uniquely. The following dict
 139   format is expected [ring-chnk_slots-disable_npa-stats_ena]. 0 represents
 140   default values.
 141   For Example::
 142
 143     --dev "0002:0e:00.0,tim_ring_ctl=[2-1023-1-0]"
 144
 145 Debugging Options
 146 ~~~~~~~~~~~~~~~~~
 147
 148 .. _table_octeontx2_event_debug_options:
 149
 150 .. table:: OCTEON TX2 event device debug options
 151
 152    +---+------------+-------------------------------------------------------+
 153    | # | Component  | EAL log command                                       |
 154    +===+============+=======================================================+
 155    | 1 | SSO        | --log-level='pmd\.event\.octeontx2,8'                 |
 156    +---+------------+-------------------------------------------------------+
 157    | 2 | TIM        | --log-level='pmd\.event\.octeontx2\.timer,8'          |
 158    +---+------------+-------------------------------------------------------+