doc: add runtime option examples to hns3 guide
[dpdk.git] / doc / guides / eventdevs / cnxk.rst
1 .. SPDX-License-Identifier: BSD-3-Clause
2    Copyright(c) 2021 Marvell.
3
4 Marvell cnxk SSO Eventdev Driver
5 ================================
6
7 The SSO PMD (**librte_event_cnxk**) and provides poll mode
8 eventdev driver support for the inbuilt event device found in the
9 **Marvell OCTEON cnxk** SoC family.
10
11 More information about OCTEON cnxk SoC can be found at `Marvell Official Website
12 <https://www.marvell.com/embedded-processors/infrastructure-processors/>`_.
13
14 Supported OCTEON cnxk SoCs
15 --------------------------
16
17 - CN9XX
18 - CN10XX
19
20 Features
21 --------
22
23 Features of the OCTEON cnxk SSO PMD are:
24
25 - 256 Event queues
26 - 26 (dual) and 52 (single) Event ports on CN9XX
27 - 52 Event ports on CN10XX
28 - HW event scheduler
29 - Supports 1M flows per event queue
30 - Flow based event pipelining
31 - Flow pinning support in flow based event pipelining
32 - Queue based event pipelining
33 - Supports ATOMIC, ORDERED, PARALLEL schedule types per flow
34 - Event scheduling QoS based on event queue priority
35 - Open system with configurable amount of outstanding events limited only by
36   DRAM
37 - HW accelerated dequeue timeout support to enable power management
38 - HW managed event timers support through TIM, with high precision and
39   time granularity of 2.5us on CN9K and 1us on CN10K.
40 - Up to 256 TIM rings a.k.a event timer adapters.
41 - Up to 8 rings traversed in parallel.
42
43 Prerequisites and Compilation procedure
44 ---------------------------------------
45
46    See :doc:`../platform/cnxk` for setup information.
47
48
49 Runtime Config Options
50 ----------------------
51
52 - ``Maximum number of in-flight events`` (default ``8192``)
53
54   In **Marvell OCTEON cnxk** the max number of in-flight events are only limited
55   by DRAM size, the ``xae_cnt`` devargs parameter is introduced to provide
56   upper limit for in-flight events.
57
58   For example::
59
60     -a 0002:0e:00.0,xae_cnt=16384
61
62 - ``CN9K Getwork mode``
63
64   CN9K ``single_ws`` devargs parameter is introduced to select single workslot
65   mode in SSO and disable the default dual workslot mode.
66
67   For example::
68
69     -a 0002:0e:00.0,single_ws=1
70
71 - ``CN10K Getwork mode``
72
73   CN10K supports multiple getwork prefetch modes, by default the prefetch
74   mode is set to none.
75
76   For example::
77
78     -a 0002:0e:00.0,gw_mode=1
79
80 - ``Event Group QoS support``
81
82   SSO GGRPs i.e. queue uses DRAM & SRAM buffers to hold in-flight
83   events. By default the buffers are assigned to the SSO GGRPs to
84   satisfy minimum HW requirements. SSO is free to assign the remaining
85   buffers to GGRPs based on a preconfigured threshold.
86   We can control the QoS of SSO GGRP by modifying the above mentioned
87   thresholds. GGRPs that have higher importance can be assigned higher
88   thresholds than the rest. The dictionary format is as follows
89   [Qx-XAQ-TAQ-IAQ][Qz-XAQ-TAQ-IAQ] expressed in percentages, 0 represents
90   default.
91
92   For example::
93
94     -a 0002:0e:00.0,qos=[1-50-50-50]
95
96 - ``TIM disable NPA``
97
98   By default chunks are allocated from NPA then TIM can automatically free
99   them when traversing the list of chunks. The ``tim_disable_npa`` devargs
100   parameter disables NPA and uses software mempool to manage chunks
101
102   For example::
103
104     -a 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
114   For example::
115
116     -a 0002:0e:00.0,tim_chnk_slots=1023
117
118 - ``TIM enable arm/cancel statistics``
119
120   The ``tim_stats_ena`` devargs can be used to enable arm and cancel stats of
121   event timer adapter.
122
123   For example::
124
125     -a 0002:0e:00.0,tim_stats_ena=1
126
127 - ``TIM limit max rings reserved``
128
129   The ``tim_rings_lmt`` devargs can be used to limit the max number of TIM
130   rings i.e. event timer adapter reserved on probe. Since, TIM rings are HW
131   resources we can avoid starving other applications by not grabbing all the
132   rings.
133
134   For example::
135
136     -a 0002:0e:00.0,tim_rings_lmt=5
137
138 - ``TIM ring control internal parameters``
139
140   When using multiple TIM rings the ``tim_ring_ctl`` devargs can be used to
141   control each TIM rings internal parameters uniquely. The following dict
142   format is expected [ring-chnk_slots-disable_npa-stats_ena]. 0 represents
143   default values.
144
145   For Example::
146
147     -a 0002:0e:00.0,tim_ring_ctl=[2-1023-1-0]
148
149 Debugging Options
150 -----------------
151
152 .. _table_octeon_cnxk_event_debug_options:
153
154 .. table:: OCTEON cnxk event device debug options
155
156    +---+------------+-------------------------------------------------------+
157    | # | Component  | EAL log command                                       |
158    +===+============+=======================================================+
159    | 1 | SSO        | --log-level='pmd\.event\.cnxk,8'                      |
160    +---+------------+-------------------------------------------------------+
161    | 2 | TIM        | --log-level='pmd\.event\.cnxk\.timer,8'               |
162    +---+------------+-------------------------------------------------------+