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