1.. SPDX-License-Identifier: BSD-3-Clause 2 Copyright(c) 2017 Intel Corporation. 3 4Event Ethernet Tx Adapter Library 5================================= 6 7The DPDK Eventdev API allows the application to use an event driven programming 8model for packet processing in which the event device distributes events 9referencing packets to the application cores in a dynamic load balanced fashion 10while handling atomicity and packet ordering. Event adapters provide the interface 11between the ethernet, crypto and timer devices and the event device. Event adapter 12APIs enable common application code by abstracting PMD specific capabilities. 13The Event ethernet Tx adapter provides configuration and data path APIs for the 14transmit stage of the application allowing the same application code to use eventdev 15PMD support or in its absence, a common implementation. 16 17In the common implementation, the application enqueues mbufs to the adapter 18which runs as a rte_service function. The service function dequeues events 19from its event port and transmits the mbufs referenced by these events. 20 21 22API Walk-through 23---------------- 24 25This section will introduce the reader to the adapter API. The 26application has to first instantiate an adapter which is associated with 27a single eventdev, next the adapter instance is configured with Tx queues, 28finally the adapter is started and the application can start enqueuing mbufs 29to it. 30 31Creating an Adapter Instance 32~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 33 34An adapter instance is created using ``rte_event_eth_tx_adapter_create()``. This 35function is passed the event device to be associated with the adapter and port 36configuration for the adapter to setup an event port if the adapter needs to use 37a service function. 38 39If the application desires to have finer control of eventdev port configuration, 40it can use the ``rte_event_eth_tx_adapter_create_ext()`` function. The 41``rte_event_eth_tx_adapter_create_ext()`` function is passed a callback function. 42The callback function is invoked if the adapter needs to use a service function 43and needs to create an event port for it. The callback is expected to fill the 44``struct rte_event_eth_tx_adapter_conf`` structure passed to it. 45 46.. code-block:: c 47 48 struct rte_event_dev_info dev_info; 49 struct rte_event_port_conf tx_p_conf = {0}; 50 51 err = rte_event_dev_info_get(id, &dev_info); 52 53 tx_p_conf.new_event_threshold = dev_info.max_num_events; 54 tx_p_conf.dequeue_depth = dev_info.max_event_port_dequeue_depth; 55 tx_p_conf.enqueue_depth = dev_info.max_event_port_enqueue_depth; 56 57 err = rte_event_eth_tx_adapter_create(id, dev_id, &tx_p_conf); 58 59Event device configuration for service based adapter 60~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 61 62When ``rte_event_eth_tx_adapter_create()`` is used for creating 63adapter instance, ``rte_event_dev_config::nb_event_ports`` is 64automatically incremented, and the event device is reconfigured 65with additional event port during service initialization. 66This event device reconfigure logic also increments 67the ``rte_event_dev_config::nb_single_link_event_port_queues`` 68parameter if the adapter event port config is of type 69``RTE_EVENT_PORT_CFG_SINGLE_LINK``. 70 71Application no longer needs to configure the event device with 72``rte_event_dev_config::nb_event_ports`` and 73``rte_event_dev_config::nb_single_link_event_port_queues`` 74parameters required for eth Tx adapter when the adapter is created 75using the above-mentioned API. 76 77Adding Tx Queues to the Adapter Instance 78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 79 80Ethdev Tx queues are added to the instance using the 81``rte_event_eth_tx_adapter_queue_add()`` function. A queue value 82of -1 is used to indicate all queues within a device. 83 84.. code-block:: c 85 86 int err = rte_event_eth_tx_adapter_queue_add(id, 87 eth_dev_id, 88 q); 89 90Querying Adapter Capabilities 91~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 92 93The ``rte_event_eth_tx_adapter_caps_get()`` function allows 94the application to query the adapter capabilities for an eventdev and ethdev 95combination. Currently, the only capability flag defined is 96``RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT``, the application can 97query this flag to determine if a service function is associated with the 98adapter and retrieve its service identifier using the 99``rte_event_eth_tx_adapter_service_id_get()`` API. 100 101 102.. code-block:: c 103 104 int err = rte_event_eth_tx_adapter_caps_get(dev_id, eth_dev_id, &cap); 105 106 if (!(cap & RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT)) 107 err = rte_event_eth_tx_adapter_service_id_get(id, &service_id); 108 109Linking a Queue to the Adapter's Event Port 110~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 111 112If the adapter uses a service function as described in the previous section, the 113application is required to link a queue to the adapter's event port. The adapter's 114event port can be obtained using the ``rte_event_eth_tx_adapter_event_port_get()`` 115function. The queue can be configured with the ``RTE_EVENT_QUEUE_CFG_SINGLE_LINK`` 116since it is linked to a single event port. 117 118Configuring the Service Function 119~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 120 121If the adapter uses a service function, the application can assign 122a service core to the service function as shown below. 123 124.. code-block:: c 125 126 if (rte_event_eth_tx_adapter_service_id_get(id, &service_id) == 0) 127 rte_service_map_lcore_set(service_id, TX_CORE_ID); 128 129Starting the Adapter Instance 130~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 131 132The application calls ``rte_event_eth_tx_adapter_start()`` to start the adapter. 133This function calls the start callback of the eventdev PMD if supported, 134and the ``rte_service_run_state_set()`` to enable the service function if one exists. 135 136Enqueuing Packets to the Adapter 137~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 138 139The application needs to notify the adapter about the transmit port and queue used 140to send the packet. The transmit port is set in the ``struct rte mbuf::port`` field 141and the transmit queue is set using the ``rte_event_eth_tx_adapter_txq_set()`` 142function. 143 144If the eventdev PMD supports the ``RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT`` 145capability for a given ethernet device, the application should use the 146``rte_event_eth_tx_adapter_enqueue()`` function to enqueue packets to the adapter. 147 148If the adapter uses a service function for the ethernet device then the application 149should use the ``rte_event_enqueue_burst()`` function. 150 151.. code-block:: c 152 153 struct rte_event event; 154 155 if (cap & RTE_EVENT_ETH_TX_ADAPTER_CAP_INTERNAL_PORT) { 156 157 event.mbuf = m; 158 eq_flags = 0; 159 160 m->port = tx_port; 161 rte_event_eth_tx_adapter_txq_set(m, tx_queue_id); 162 163 rte_event_eth_tx_adapter_enqueue(dev_id, ev_port, &event, 1, eq_flags); 164 } else { 165 166 event.queue_id = qid; /* event queue linked to adapter port */ 167 event.op = RTE_EVENT_OP_NEW; 168 event.event_type = RTE_EVENT_TYPE_CPU; 169 event.sched_type = RTE_SCHED_TYPE_ATOMIC; 170 event.mbuf = m; 171 172 m->port = tx_port; 173 rte_event_eth_tx_adapter_txq_set(m, tx_queue_id); 174 175 rte_event_enqueue_burst(dev_id, ev_port, &event, 1); 176 } 177 178Getting Adapter Statistics 179~~~~~~~~~~~~~~~~~~~~~~~~~~ 180 181The ``rte_event_eth_tx_adapter_stats_get()`` function reports counters defined 182in struct ``rte_event_eth_tx_adapter_stats``. The counter values are the sum of 183the counts from the eventdev PMD callback if the callback is supported, and 184the counts maintained by the service function, if one exists. 185 186Getting Adapter Instance ID 187~~~~~~~~~~~~~~~~~~~~~~~~~~~ 188 189The ``rte_event_eth_tx_adapter_instance_get()`` function reports 190Tx adapter instance ID for a specified ethernet device ID and Tx queue index. 191 192Tx event vectorization 193~~~~~~~~~~~~~~~~~~~~~~ 194 195The event device, ethernet device pairs which support the capability 196``RTE_EVENT_ETH_TX_ADAPTER_CAP_EVENT_VECTOR`` can process event vector of mbufs. 197Additionally, application can provide a hint to the Tx adapter that all the 198mbufs are destined to the same ethernet port and queue by setting the bit 199``rte_event_vector::attr_valid`` and filling `rte_event_vector::port`` and 200``rte_event_vector::queue``. 201If ``rte_event_vector::attr_valid`` is not set then the Tx adapter should peek 202into each mbuf and transmit them to the requested ethernet port and queue pair. 203 204Queue start/stop 205~~~~~~~~~~~~~~~~ 206 207The adapter can be configured to start/stop enqueueing of packets to a 208associated NIC queue using ``rte_event_eth_tx_adapter_queue_start()`` or 209``rte_event_eth_tx_adapter_queue_stop()`` respectively. By default the queue 210is in start state. 211 212These APIs help avoid some unexpected behavior with application stopping ethdev 213Tx queues and adapter being unaware of it. With these APIs, the application can 214call stop API to notify adapter that corresponding ethdev Tx queue is stopped 215and any in-flight packets are freed by adapter dataplane code. Adapter queue 216stop API is called before stopping the ethdev Tx queue. When ethdev Tx queue 217is enabled, application can notify adapter to resume processing of the packets 218for that queue by calling the start API. The ethdev Tx queue is started before 219calling adapter start API. 220 221Start function enables the adapter runtime to start enqueueing of packets 222to the Tx queue. 223 224Stop function stops the adapter runtime function from enqueueing any 225packets to the associated Tx queue. This API also frees any packets that 226may have been buffered for this queue. All inflight packets destined to the 227queue are freed by the adapter runtime until the queue is started again. 228 229Set/Get adapter runtime configuration parameters 230~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 231 232The runtime configuration parameters of adapter can be set/get using 233``rte_event_eth_tx_adapter_runtime_params_set()`` and 234``rte_event_eth_tx_adapter_runtime_params_get()`` respectively. 235The parameters that can be set/get are defined in 236``struct rte_event_eth_tx_adapter_runtime_params``. 237