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>
26 * Returns a ethdev slot specified by the unique identifier name.
29 * The pointer to the Unique identifier name for each Ethernet device
31 * - The pointer to the ethdev slot, on success. NULL on error
33 struct rte_eth_dev *rte_eth_dev_allocated(const char *name);
37 * Allocates a new ethdev slot for an ethernet device and returns the pointer
38 * to that slot for the driver to use.
40 * @param name Unique identifier name for each Ethernet device
41 * @param type Device type of this Ethernet device
43 * - Slot in the rte_dev_devices array for a new device;
45 struct rte_eth_dev *rte_eth_dev_allocate(const char *name);
49 * Attach to the ethdev already initialized by the primary
52 * @param name Ethernet device's name.
54 * - Success: Slot in the rte_dev_devices array for attached
56 * - Error: Null pointer.
58 struct rte_eth_dev *rte_eth_dev_attach_secondary(const char *name);
62 * Release the specified ethdev port.
65 * The *eth_dev* pointer is the address of the *rte_eth_dev* structure.
67 * - 0 on success, negative on error
69 int rte_eth_dev_release_port(struct rte_eth_dev *eth_dev);
73 * Release device queues and clear its configuration to force the user
74 * application to reconfigure it. It is for internal use only.
77 * Pointer to struct rte_eth_dev.
82 void _rte_eth_dev_reset(struct rte_eth_dev *dev);
85 * @internal Executes all the user application registered callbacks for
86 * the specific device. It is for DPDK internal user only. User
87 * application should not call it directly.
90 * Pointer to struct rte_eth_dev.
92 * Eth device interrupt event type.
94 * To pass data back to user application.
95 * This allows the user application to decide if a particular function
96 * is permitted or not.
101 int _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
102 enum rte_eth_event_type event, void *ret_param);
106 * This is the last step of device probing.
107 * It must be called after a port is allocated and initialized successfully.
109 * The notification RTE_ETH_EVENT_NEW is sent to other entities
110 * (libraries and applications).
111 * The state is set as RTE_ETH_DEV_ATTACHED.
116 void rte_eth_dev_probing_finish(struct rte_eth_dev *dev);
119 * Create memzone for HW rings.
120 * malloc can't be used as the physical address is needed.
121 * If the memzone is already created, then this function returns a ptr
125 * The *eth_dev* pointer is the address of the *rte_eth_dev* structure
127 * The name of the memory zone
129 * The index of the queue to add to name
131 * The sizeof of the memory area
133 * Alignment for resulting memzone. Must be a power of 2.
135 * The *socket_id* argument is the socket identifier in case of NUMA.
137 const struct rte_memzone *
138 rte_eth_dma_zone_reserve(const struct rte_eth_dev *eth_dev, const char *name,
139 uint16_t queue_id, size_t size,
140 unsigned align, int socket_id);
144 * Atomically set the link status for the specific device.
145 * It is for use by DPDK device driver use only.
146 * User applications should not call it
149 * Pointer to struct rte_eth_dev.
151 * New link status value.
153 * Same convention as eth_link_update operation.
154 * 0 if link up status has changed
155 * -1 if link up status was unchanged
158 rte_eth_linkstatus_set(struct rte_eth_dev *dev,
159 const struct rte_eth_link *new_link)
161 volatile uint64_t *dev_link
162 = (volatile uint64_t *)&(dev->data->dev_link);
165 struct rte_eth_link link;
168 RTE_BUILD_BUG_ON(sizeof(*new_link) != sizeof(uint64_t));
170 orig.val64 = rte_atomic64_exchange(dev_link,
171 *(const uint64_t *)new_link);
173 return (orig.link.link_status == new_link->link_status) ? -1 : 0;
178 * Atomically get the link speed and status.
181 * Pointer to struct rte_eth_dev.
186 rte_eth_linkstatus_get(const struct rte_eth_dev *dev,
187 struct rte_eth_link *link)
189 volatile uint64_t *src = (uint64_t *)&(dev->data->dev_link);
190 uint64_t *dst = (uint64_t *)link;
192 RTE_BUILD_BUG_ON(sizeof(*link) != sizeof(uint64_t));
195 /* if cpu arch has 64 bit unsigned lon then implicitly atomic */
198 /* can't use rte_atomic64_read because it returns signed int */
201 } while (!rte_atomic64_cmpset(src, *dst, *dst));
207 * @b EXPERIMENTAL: this API may change without prior notice.
209 * Allocate an unique switch domain identifier.
211 * A pool of switch domain identifiers which can be allocated on request. This
212 * will enabled devices which support the concept of switch domains to request
213 * a switch domain id which is guaranteed to be unique from other devices
214 * running in the same process.
217 * switch domain identifier parameter to pass back to application
220 * Negative errno value on error, 0 on success.
222 int __rte_experimental
223 rte_eth_switch_domain_alloc(uint16_t *domain_id);
227 * @b EXPERIMENTAL: this API may change without prior notice.
229 * Free switch domain.
231 * Return a switch domain identifier to the pool of free identifiers after it is
232 * no longer in use by device.
235 * switch domain identifier to free
238 * Negative errno value on error, 0 on success.
240 int __rte_experimental
241 rte_eth_switch_domain_free(uint16_t domain_id);
243 /** Generic Ethernet device arguments */
244 struct rte_eth_devargs {
245 uint16_t ports[RTE_MAX_ETHPORTS];
246 /** port/s number to enable on a multi-port single function */
248 /** number of ports in ports field */
249 uint16_t representor_ports[RTE_MAX_ETHPORTS];
250 /** representor port/s identifier to enable on device */
251 uint16_t nb_representor_ports;
252 /** number of ports in representor port field */
257 * @b EXPERIMENTAL: this API may change without prior notice.
259 * PMD helper function to parse ethdev arguments
264 * parsed ethdev specific arguments.
267 * Negative errno value on error, 0 on success.
269 int __rte_experimental
270 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs);
273 typedef int (*ethdev_init_t)(struct rte_eth_dev *ethdev, void *init_params);
274 typedef int (*ethdev_bus_specific_init)(struct rte_eth_dev *ethdev,
275 void *bus_specific_init_params);
279 * @b EXPERIMENTAL: this API may change without prior notice.
281 * PMD helper function for the creation of a new ethdev ports.
287 * @param priv_data_size
288 * size of private data required for port.
289 * @param bus_specific_init
290 * port bus specific initialisation callback function
291 * @param bus_init_params
292 * port bus specific initialisation parameters
294 * device specific port initialization callback function
296 * port initialisation parameters
299 * Negative errno value on error, 0 on success.
301 int __rte_experimental
302 rte_eth_dev_create(struct rte_device *device, const char *name,
303 size_t priv_data_size,
304 ethdev_bus_specific_init bus_specific_init, void *bus_init_params,
305 ethdev_init_t ethdev_init, void *init_params);
308 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev);
312 * @b EXPERIMENTAL: this API may change without prior notice.
314 * PMD helper function for cleaing up the resources of a ethdev port on it's
318 * ethdev handle of port.
319 * @param ethdev_uninit
320 * device specific port un-initialise callback function
323 * Negative errno value on error, 0 on success.
325 int __rte_experimental
326 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit);
329 * PMD helper function to check if keeping CRC is requested
332 * When CRC_STRIP offload flag is removed and default behavior switch to
333 * strip CRC, as planned, this helper function is not that useful and will be
334 * removed. In PMDs this function will be replaced with check:
335 * if (offloads & DEV_RX_OFFLOAD_KEEP_CRC)
338 * offload bits to be applied
341 * Return positive if keeping CRC is requested,
342 * zero if stripping CRC is requested
345 rte_eth_dev_must_keep_crc(uint64_t rx_offloads)
347 if (rx_offloads & DEV_RX_OFFLOAD_CRC_STRIP)
350 /* no KEEP_CRC or CRC_STRIP offload flags means keep CRC */
358 #endif /* _RTE_ETHDEV_DRIVER_H_ */