drivers: move ifc to vDPA directory
[dpdk.git] / doc / guides / eventdevs / octeontx.rst
1 ..  SPDX-License-Identifier: BSD-3-Clause
2     Copyright(c) 2017 Cavium, Inc
3
4 OCTEON TX SSOVF Eventdev Driver
5 ===============================
6
7 The OCTEON TX SSOVF PMD (**librte_pmd_octeontx_ssovf**) provides poll mode
8 eventdev driver support for the inbuilt event device found in the **Cavium OCTEON TX**
9 SoC family as well as their virtual functions (VF) in SR-IOV context.
10
11 More information can be found at `Cavium, Inc Official Website
12 <http://www.cavium.com/OCTEON-TX_ARM_Processors.html>`_.
13
14 Features
15 --------
16
17 Features of the OCTEON TX SSOVF PMD are:
18
19 - 64 Event queues
20 - 32 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
29 - HW accelerated dequeue timeout support to enable power management
30 - SR-IOV VF
31 - HW managed event timers support through TIMVF, with high precision and
32   time granularity of 1us.
33 - Up to 64 event timer adapters.
34
35 Supported OCTEON TX SoCs
36 ------------------------
37 - CN83xx
38
39 Prerequisites
40 -------------
41
42 See :doc:`../platform/octeontx` for setup information.
43
44 Pre-Installation Configuration
45 ------------------------------
46
47 Config File Options
48 ~~~~~~~~~~~~~~~~~~~
49
50 The following options can be modified in the ``config`` file.
51 Please note that enabling debugging options may affect system performance.
52
53 - ``CONFIG_RTE_LIBRTE_PMD_OCTEONTX_SSOVF`` (default ``y``)
54
55   Toggle compilation of the ``librte_pmd_octeontx_ssovf`` driver.
56
57 Driver Compilation
58 ~~~~~~~~~~~~~~~~~~
59
60 To compile the OCTEON TX SSOVF PMD for Linux arm64 gcc target, run the
61 following ``make`` command:
62
63 .. code-block:: console
64
65    cd <DPDK-source-directory>
66    make config T=arm64-thunderx-linux-gcc install
67
68
69 Initialization
70 --------------
71
72 The OCTEON TX eventdev is exposed as a vdev device which consists of a set
73 of SSO group and work-slot PCIe VF devices. On EAL initialization,
74 SSO PCIe VF devices will be probed and then the vdev device can be created
75 from the application code, or from the EAL command line based on
76 the number of probed/bound SSO PCIe VF device to DPDK by
77
78 * Invoking ``rte_vdev_init("event_octeontx")`` from the application
79
80 * Using ``--vdev="event_octeontx"`` in the EAL options, which will call
81   rte_vdev_init() internally
82
83 Example:
84
85 .. code-block:: console
86
87     ./your_eventdev_application --vdev="event_octeontx"
88
89
90 Selftest
91 --------
92
93 The functionality of OCTEON TX eventdev can be verified using this option,
94 various unit and functional tests are run to verify the sanity.
95 The tests are run once the vdev creation is successfully complete.
96
97 .. code-block:: console
98
99     --vdev="event_octeontx,selftest=1"
100
101
102 Enable TIMvf stats
103 ------------------
104 TIMvf stats can be enabled by using this option, by default the stats are
105 disabled.
106
107 .. code-block:: console
108
109     --vdev="event_octeontx,timvf_stats=1"
110
111
112 Limitations
113 -----------
114
115 Burst mode support
116 ~~~~~~~~~~~~~~~~~~
117
118 Burst mode is not supported. Dequeue and Enqueue functions accepts only single
119 event at a time.
120
121 Rx adapter support
122 ~~~~~~~~~~~~~~~~~~
123
124 When eth_octeontx is used as Rx adapter event schedule type
125 ``RTE_SCHED_TYPE_PARALLEL`` is not supported.
126
127 Event timer adapter support
128 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
129
130 When timvf is used as Event timer adapter the clock source mapping is as
131 follows:
132
133 .. code-block:: console
134
135         RTE_EVENT_TIMER_ADAPTER_CPU_CLK  = TIM_CLK_SRC_SCLK
136         RTE_EVENT_TIMER_ADAPTER_EXT_CLK0 = TIM_CLK_SRC_GPIO
137         RTE_EVENT_TIMER_ADAPTER_EXT_CLK1 = TIM_CLK_SRC_GTI
138         RTE_EVENT_TIMER_ADAPTER_EXT_CLK2 = TIM_CLK_SRC_PTP
139
140 When timvf is used as Event timer adapter event schedule type
141 ``RTE_SCHED_TYPE_PARALLEL`` is not supported.
142
143 Max mempool size
144 ~~~~~~~~~~~~~~~~
145
146 Max mempool size when using OCTEON TX Eventdev (SSO) should be limited to 128K.
147 When running dpdk-test-eventdev on OCTEON TX the application can limit the
148 number of mbufs by using the option ``--pool_sz 131072``