1..  SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2019 Marvell International Ltd.
3
4OCTEON TX2 SSO Eventdev Driver
5===============================
6
7The OCTEON TX2 SSO PMD (**librte_event_octeontx2**) provides poll mode
8eventdev driver support for the inbuilt event device found in the **Marvell OCTEON TX2**
9SoC family.
10
11More information about OCTEON TX2 SoC can be found at `Marvell Official Website
12<https://www.marvell.com/embedded-processors/infrastructure-processors/>`_.
13
14Features
15--------
16
17Features 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
42Prerequisites and Compilation procedure
43---------------------------------------
44
45   See :doc:`../platform/octeontx2` for setup information.
46
47
48Runtime 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
141Debugging Options
142-----------------
143
144.. _table_octeontx2_event_debug_options:
145
146.. table:: OCTEON TX2 event device debug options
147
148   +---+------------+-------------------------------------------------------+
149   | # | Component  | EAL log command                                       |
150   +===+============+=======================================================+
151   | 1 | SSO        | --log-level='pmd\.event\.octeontx2,8'                 |
152   +---+------------+-------------------------------------------------------+
153   | 2 | TIM        | --log-level='pmd\.event\.octeontx2\.timer,8'          |
154   +---+------------+-------------------------------------------------------+
155