net/ice: fix memory leak when releasing VSI
[dpdk.git] / lib / librte_ethdev / rte_ethdev_driver.h
1 /* SPDX-License-Identifier: BSD-3-Clause
2  * Copyright(c) 2017 Intel Corporation
3  */
4
5 #ifndef _RTE_ETHDEV_DRIVER_H_
6 #define _RTE_ETHDEV_DRIVER_H_
7
8 /**
9  * @file
10  *
11  * RTE Ethernet Device PMD API
12  *
13  * These APIs for the use from Ethernet drivers, user applications shouldn't
14  * use them.
15  *
16  */
17
18 #include <rte_ethdev.h>
19
20 #ifdef __cplusplus
21 extern "C" {
22 #endif
23
24 /**
25  * RX/TX queue states
26  */
27 #define RTE_ETH_QUEUE_STATE_STOPPED 0
28 #define RTE_ETH_QUEUE_STATE_STARTED 1
29 #define RTE_ETH_QUEUE_STATE_HAIRPIN 2
30
31 /**
32  * @internal
33  * Check if the selected Rx queue is hairpin queue.
34  *
35  * @param dev
36  *  Pointer to the selected device.
37  * @param queue_id
38  *  The selected queue.
39  *
40  * @return
41  *   - (1) if the queue is hairpin queue, 0 otherwise.
42  */
43 int rte_eth_dev_is_rx_hairpin_queue(struct rte_eth_dev *dev, uint16_t queue_id);
44
45 /**
46  * @internal
47  * Check if the selected Tx queue is hairpin queue.
48  *
49  * @param dev
50  *  Pointer to the selected device.
51  * @param queue_id
52  *  The selected queue.
53  *
54  * @return
55  *   - (1) if the queue is hairpin queue, 0 otherwise.
56  */
57 int rte_eth_dev_is_tx_hairpin_queue(struct rte_eth_dev *dev, uint16_t queue_id);
58
59 /**
60  * @internal
61  * Returns a ethdev slot specified by the unique identifier name.
62  *
63  * @param       name
64  *  The pointer to the Unique identifier name for each Ethernet device
65  * @return
66  *   - The pointer to the ethdev slot, on success. NULL on error
67  */
68 struct rte_eth_dev *rte_eth_dev_allocated(const char *name);
69
70 /**
71  * @internal
72  * Allocates a new ethdev slot for an ethernet device and returns the pointer
73  * to that slot for the driver to use.
74  *
75  * @param       name    Unique identifier name for each Ethernet device
76  * @return
77  *   - Slot in the rte_dev_devices array for a new device;
78  */
79 struct rte_eth_dev *rte_eth_dev_allocate(const char *name);
80
81 /**
82  * @internal
83  * Attach to the ethdev already initialized by the primary
84  * process.
85  *
86  * @param       name    Ethernet device's name.
87  * @return
88  *   - Success: Slot in the rte_dev_devices array for attached
89  *        device.
90  *   - Error: Null pointer.
91  */
92 struct rte_eth_dev *rte_eth_dev_attach_secondary(const char *name);
93
94 /**
95  * @internal
96  * Notify RTE_ETH_EVENT_DESTROY and release the specified ethdev port.
97  *
98  * The following PMD-managed data fields will be freed:
99  *   - dev_private
100  *   - mac_addrs
101  *   - hash_mac_addrs
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.
104  *
105  * @param eth_dev
106  * Device to be detached.
107  * @return
108  *   - 0 on success, negative on error
109  */
110 int rte_eth_dev_release_port(struct rte_eth_dev *eth_dev);
111
112 /**
113  * @internal
114  * Release device queues and clear its configuration to force the user
115  * application to reconfigure it. It is for internal use only.
116  *
117  * @param dev
118  *  Pointer to struct rte_eth_dev.
119  *
120  * @return
121  *  void
122  */
123 void _rte_eth_dev_reset(struct rte_eth_dev *dev);
124
125 /**
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.
129  *
130  * @param dev
131  *  Pointer to struct rte_eth_dev.
132  * @param event
133  *  Eth device interrupt event type.
134  * @param ret_param
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.
138  *
139  * @return
140  *  int
141  */
142 int _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
143                 enum rte_eth_event_type event, void *ret_param);
144
145 /**
146  * @internal
147  * This is the last step of device probing.
148  * It must be called after a port is allocated and initialized successfully.
149  *
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.
153  *
154  * @param dev
155  *  New ethdev port.
156  */
157 void rte_eth_dev_probing_finish(struct rte_eth_dev *dev);
158
159 /**
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
163  * to the old one.
164  *
165  * @param eth_dev
166  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
167  * @param name
168  *   The name of the memory zone
169  * @param queue_id
170  *   The index of the queue to add to name
171  * @param size
172  *   The sizeof of the memory area
173  * @param align
174  *   Alignment for resulting memzone. Must be a power of 2.
175  * @param socket_id
176  *   The *socket_id* argument is the socket identifier in case of NUMA.
177  */
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);
182
183 /**
184  * Free previously allocated memzone for HW rings.
185  *
186  * @param eth_dev
187  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
188  * @param name
189  *   The name of the memory zone
190  * @param queue_id
191  *   The index of the queue to add to name
192  * @return
193  *   Negative errno value on error, 0 on success.
194  */
195 __rte_internal
196 int
197 rte_eth_dma_zone_free(const struct rte_eth_dev *eth_dev, const char *name,
198                  uint16_t queue_id);
199
200 /**
201  * @internal
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
205  *
206  * @param dev
207  *  Pointer to struct rte_eth_dev.
208  * @param link
209  *  New link status value.
210  * @return
211  *  Same convention as eth_link_update operation.
212  *  0   if link up status has changed
213  *  -1  if link up status was unchanged
214  */
215 static inline int
216 rte_eth_linkstatus_set(struct rte_eth_dev *dev,
217                        const struct rte_eth_link *new_link)
218 {
219         volatile uint64_t *dev_link
220                  = (volatile uint64_t *)&(dev->data->dev_link);
221         union {
222                 uint64_t val64;
223                 struct rte_eth_link link;
224         } orig;
225
226         RTE_BUILD_BUG_ON(sizeof(*new_link) != sizeof(uint64_t));
227
228         orig.val64 = rte_atomic64_exchange(dev_link,
229                                            *(const uint64_t *)new_link);
230
231         return (orig.link.link_status == new_link->link_status) ? -1 : 0;
232 }
233
234 /**
235  * @internal
236  * Atomically get the link speed and status.
237  *
238  * @param dev
239  *  Pointer to struct rte_eth_dev.
240  * @param link
241  *  link status value.
242  */
243 static inline void
244 rte_eth_linkstatus_get(const struct rte_eth_dev *dev,
245                        struct rte_eth_link *link)
246 {
247         volatile uint64_t *src = (uint64_t *)&(dev->data->dev_link);
248         uint64_t *dst = (uint64_t *)link;
249
250         RTE_BUILD_BUG_ON(sizeof(*link) != sizeof(uint64_t));
251
252 #ifdef __LP64__
253         /* if cpu arch has 64 bit unsigned lon then implicitly atomic */
254         *dst = *src;
255 #else
256         /* can't use rte_atomic64_read because it returns signed int */
257         do {
258                 *dst = *src;
259         } while (!rte_atomic64_cmpset(src, *dst, *dst));
260 #endif
261 }
262
263 /**
264  * @warning
265  * @b EXPERIMENTAL: this API may change without prior notice.
266  *
267  * Allocate an unique switch domain identifier.
268  *
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.
273  *
274  * @param domain_id
275  *  switch domain identifier parameter to pass back to application
276  *
277  * @return
278  *   Negative errno value on error, 0 on success.
279  */
280 __rte_experimental
281 int
282 rte_eth_switch_domain_alloc(uint16_t *domain_id);
283
284 /**
285  * @warning
286  * @b EXPERIMENTAL: this API may change without prior notice.
287  *
288  * Free switch domain.
289  *
290  * Return a switch domain identifier to the pool of free identifiers after it is
291  * no longer in use by device.
292  *
293  * @param domain_id
294  *  switch domain identifier to free
295  *
296  * @return
297  *   Negative errno value on error, 0 on success.
298  */
299 __rte_experimental
300 int
301 rte_eth_switch_domain_free(uint16_t domain_id);
302
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 */
307         uint16_t nb_ports;
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 */
313 };
314
315 /**
316  * @warning
317  * @b EXPERIMENTAL: this API may change without prior notice.
318  *
319  * PMD helper function to parse ethdev arguments
320  *
321  * @param devargs
322  *  device arguments
323  * @param eth_devargs
324  *  parsed ethdev specific arguments.
325  *
326  * @return
327  *   Negative errno value on error, 0 on success.
328  */
329 __rte_experimental
330 int
331 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs);
332
333
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);
337
338 /**
339  * @warning
340  * @b EXPERIMENTAL: this API may change without prior notice.
341  *
342  * PMD helper function for the creation of a new ethdev ports.
343  *
344  * @param device
345  *  rte_device handle.
346  * @param name
347  *  port name.
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
354  * @param ethdev_init
355  *  device specific port initialization callback function
356  * @param init_params
357  *  port initialisation parameters
358  *
359  * @return
360  *   Negative errno value on error, 0 on success.
361  */
362 __rte_experimental
363 int
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);
368
369
370 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev);
371
372 /**
373  * @warning
374  * @b EXPERIMENTAL: this API may change without prior notice.
375  *
376  * PMD helper function for cleaning up the resources of a ethdev port on it's
377  * destruction.
378  *
379  * @param ethdev
380  *   ethdev handle of port.
381  * @param ethdev_uninit
382  *   device specific port un-initialise callback function
383  *
384  * @return
385  *   Negative errno value on error, 0 on success.
386  */
387 __rte_experimental
388 int
389 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit);
390
391 #ifdef __cplusplus
392 }
393 #endif
394
395 #endif /* _RTE_ETHDEV_DRIVER_H_ */