1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2017 Intel Corporation
5 #ifndef _RTE_ETHDEV_DRIVER_H_
6 #define _RTE_ETHDEV_DRIVER_H_
11 * RTE Ethernet Device PMD API
13 * These APIs for the use from Ethernet drivers, user applications shouldn't
18 #include <rte_ethdev.h>
27 #define RTE_ETH_QUEUE_STATE_STOPPED 0
28 #define RTE_ETH_QUEUE_STATE_STARTED 1
29 #define RTE_ETH_QUEUE_STATE_HAIRPIN 2
33 * Check if the selected Rx queue is hairpin queue.
36 * Pointer to the selected device.
41 * - (1) if the queue is hairpin queue, 0 otherwise.
43 int rte_eth_dev_is_rx_hairpin_queue(struct rte_eth_dev *dev, uint16_t queue_id);
47 * Check if the selected Tx queue is hairpin queue.
50 * Pointer to the selected device.
55 * - (1) if the queue is hairpin queue, 0 otherwise.
57 int rte_eth_dev_is_tx_hairpin_queue(struct rte_eth_dev *dev, uint16_t queue_id);
61 * Returns a ethdev slot specified by the unique identifier name.
64 * The pointer to the Unique identifier name for each Ethernet device
66 * - The pointer to the ethdev slot, on success. NULL on error
68 struct rte_eth_dev *rte_eth_dev_allocated(const char *name);
72 * Allocates a new ethdev slot for an ethernet device and returns the pointer
73 * to that slot for the driver to use.
75 * @param name Unique identifier name for each Ethernet device
77 * - Slot in the rte_dev_devices array for a new device;
79 struct rte_eth_dev *rte_eth_dev_allocate(const char *name);
83 * Attach to the ethdev already initialized by the primary
86 * @param name Ethernet device's name.
88 * - Success: Slot in the rte_dev_devices array for attached
90 * - Error: Null pointer.
92 struct rte_eth_dev *rte_eth_dev_attach_secondary(const char *name);
96 * Notify RTE_ETH_EVENT_DESTROY and release the specified ethdev port.
98 * The following PMD-managed data fields will be freed:
102 * If one of these fields should not be freed,
103 * it must be reset to NULL by the PMD, typically in dev_close method.
106 * Device to be detached.
108 * - 0 on success, negative on error
110 int rte_eth_dev_release_port(struct rte_eth_dev *eth_dev);
114 * Release device queues and clear its configuration to force the user
115 * application to reconfigure it. It is for internal use only.
118 * Pointer to struct rte_eth_dev.
123 void _rte_eth_dev_reset(struct rte_eth_dev *dev);
126 * @internal Executes all the user application registered callbacks for
127 * the specific device. It is for DPDK internal user only. User
128 * application should not call it directly.
131 * Pointer to struct rte_eth_dev.
133 * Eth device interrupt event type.
135 * To pass data back to user application.
136 * This allows the user application to decide if a particular function
137 * is permitted or not.
142 int _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
143 enum rte_eth_event_type event, void *ret_param);
147 * This is the last step of device probing.
148 * It must be called after a port is allocated and initialized successfully.
150 * The notification RTE_ETH_EVENT_NEW is sent to other entities
151 * (libraries and applications).
152 * The state is set as RTE_ETH_DEV_ATTACHED.
157 void rte_eth_dev_probing_finish(struct rte_eth_dev *dev);
160 * Create memzone for HW rings.
161 * malloc can't be used as the physical address is needed.
162 * If the memzone is already created, then this function returns a ptr
166 * The *eth_dev* pointer is the address of the *rte_eth_dev* structure
168 * The name of the memory zone
170 * The index of the queue to add to name
172 * The sizeof of the memory area
174 * Alignment for resulting memzone. Must be a power of 2.
176 * The *socket_id* argument is the socket identifier in case of NUMA.
178 const struct rte_memzone *
179 rte_eth_dma_zone_reserve(const struct rte_eth_dev *eth_dev, const char *name,
180 uint16_t queue_id, size_t size,
181 unsigned align, int socket_id);
184 * Free previously allocated memzone for HW rings.
187 * The *eth_dev* pointer is the address of the *rte_eth_dev* structure
189 * The name of the memory zone
191 * The index of the queue to add to name
193 * Negative errno value on error, 0 on success.
197 rte_eth_dma_zone_free(const struct rte_eth_dev *eth_dev, const char *name,
202 * Atomically set the link status for the specific device.
203 * It is for use by DPDK device driver use only.
204 * User applications should not call it
207 * Pointer to struct rte_eth_dev.
209 * New link status value.
211 * Same convention as eth_link_update operation.
212 * 0 if link up status has changed
213 * -1 if link up status was unchanged
216 rte_eth_linkstatus_set(struct rte_eth_dev *dev,
217 const struct rte_eth_link *new_link)
219 volatile uint64_t *dev_link
220 = (volatile uint64_t *)&(dev->data->dev_link);
223 struct rte_eth_link link;
226 RTE_BUILD_BUG_ON(sizeof(*new_link) != sizeof(uint64_t));
228 orig.val64 = rte_atomic64_exchange(dev_link,
229 *(const uint64_t *)new_link);
231 return (orig.link.link_status == new_link->link_status) ? -1 : 0;
236 * Atomically get the link speed and status.
239 * Pointer to struct rte_eth_dev.
244 rte_eth_linkstatus_get(const struct rte_eth_dev *dev,
245 struct rte_eth_link *link)
247 volatile uint64_t *src = (uint64_t *)&(dev->data->dev_link);
248 uint64_t *dst = (uint64_t *)link;
250 RTE_BUILD_BUG_ON(sizeof(*link) != sizeof(uint64_t));
253 /* if cpu arch has 64 bit unsigned lon then implicitly atomic */
256 /* can't use rte_atomic64_read because it returns signed int */
259 } while (!rte_atomic64_cmpset(src, *dst, *dst));
265 * @b EXPERIMENTAL: this API may change without prior notice.
267 * Allocate an unique switch domain identifier.
269 * A pool of switch domain identifiers which can be allocated on request. This
270 * will enabled devices which support the concept of switch domains to request
271 * a switch domain id which is guaranteed to be unique from other devices
272 * running in the same process.
275 * switch domain identifier parameter to pass back to application
278 * Negative errno value on error, 0 on success.
282 rte_eth_switch_domain_alloc(uint16_t *domain_id);
286 * @b EXPERIMENTAL: this API may change without prior notice.
288 * Free switch domain.
290 * Return a switch domain identifier to the pool of free identifiers after it is
291 * no longer in use by device.
294 * switch domain identifier to free
297 * Negative errno value on error, 0 on success.
301 rte_eth_switch_domain_free(uint16_t domain_id);
303 /** Generic Ethernet device arguments */
304 struct rte_eth_devargs {
305 uint16_t ports[RTE_MAX_ETHPORTS];
306 /** port/s number to enable on a multi-port single function */
308 /** number of ports in ports field */
309 uint16_t representor_ports[RTE_MAX_ETHPORTS];
310 /** representor port/s identifier to enable on device */
311 uint16_t nb_representor_ports;
312 /** number of ports in representor port field */
317 * @b EXPERIMENTAL: this API may change without prior notice.
319 * PMD helper function to parse ethdev arguments
324 * parsed ethdev specific arguments.
327 * Negative errno value on error, 0 on success.
331 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs);
334 typedef int (*ethdev_init_t)(struct rte_eth_dev *ethdev, void *init_params);
335 typedef int (*ethdev_bus_specific_init)(struct rte_eth_dev *ethdev,
336 void *bus_specific_init_params);
340 * @b EXPERIMENTAL: this API may change without prior notice.
342 * PMD helper function for the creation of a new ethdev ports.
348 * @param priv_data_size
349 * size of private data required for port.
350 * @param bus_specific_init
351 * port bus specific initialisation callback function
352 * @param bus_init_params
353 * port bus specific initialisation parameters
355 * device specific port initialization callback function
357 * port initialisation parameters
360 * Negative errno value on error, 0 on success.
364 rte_eth_dev_create(struct rte_device *device, const char *name,
365 size_t priv_data_size,
366 ethdev_bus_specific_init bus_specific_init, void *bus_init_params,
367 ethdev_init_t ethdev_init, void *init_params);
370 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev);
374 * @b EXPERIMENTAL: this API may change without prior notice.
376 * PMD helper function for cleaning up the resources of a ethdev port on it's
380 * ethdev handle of port.
381 * @param ethdev_uninit
382 * device specific port un-initialise callback function
385 * Negative errno value on error, 0 on success.
389 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit);
395 #endif /* _RTE_ETHDEV_DRIVER_H_ */