devtools/cocci: create safer version of strlcpy script
[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  * @internal
26  * Returns a ethdev slot specified by the unique identifier name.
27  *
28  * @param       name
29  *  The pointer to the Unique identifier name for each Ethernet device
30  * @return
31  *   - The pointer to the ethdev slot, on success. NULL on error
32  */
33 struct rte_eth_dev *rte_eth_dev_allocated(const char *name);
34
35 /**
36  * @internal
37  * Allocates a new ethdev slot for an ethernet device and returns the pointer
38  * to that slot for the driver to use.
39  *
40  * @param       name    Unique identifier name for each Ethernet device
41  * @return
42  *   - Slot in the rte_dev_devices array for a new device;
43  */
44 struct rte_eth_dev *rte_eth_dev_allocate(const char *name);
45
46 /**
47  * @internal
48  * Attach to the ethdev already initialized by the primary
49  * process.
50  *
51  * @param       name    Ethernet device's name.
52  * @return
53  *   - Success: Slot in the rte_dev_devices array for attached
54  *        device.
55  *   - Error: Null pointer.
56  */
57 struct rte_eth_dev *rte_eth_dev_attach_secondary(const char *name);
58
59 /**
60  * @internal
61  * Notify RTE_ETH_EVENT_DESTROY and release the specified ethdev port.
62  *
63  * The following PMD-managed data fields will be freed:
64  *   - dev_private
65  *   - mac_addrs
66  *   - hash_mac_addrs
67  * If one of these fields should not be freed,
68  * it must be reset to NULL by the PMD, typically in dev_close method.
69  *
70  * @param eth_dev
71  * Device to be detached.
72  * @return
73  *   - 0 on success, negative on error
74  */
75 int rte_eth_dev_release_port(struct rte_eth_dev *eth_dev);
76
77 /**
78  * @internal
79  * Release device queues and clear its configuration to force the user
80  * application to reconfigure it. It is for internal use only.
81  *
82  * @param dev
83  *  Pointer to struct rte_eth_dev.
84  *
85  * @return
86  *  void
87  */
88 void _rte_eth_dev_reset(struct rte_eth_dev *dev);
89
90 /**
91  * @internal Executes all the user application registered callbacks for
92  * the specific device. It is for DPDK internal user only. User
93  * application should not call it directly.
94  *
95  * @param dev
96  *  Pointer to struct rte_eth_dev.
97  * @param event
98  *  Eth device interrupt event type.
99  * @param ret_param
100  *  To pass data back to user application.
101  *  This allows the user application to decide if a particular function
102  *  is permitted or not.
103  *
104  * @return
105  *  int
106  */
107 int _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
108                 enum rte_eth_event_type event, void *ret_param);
109
110 /**
111  * @internal
112  * This is the last step of device probing.
113  * It must be called after a port is allocated and initialized successfully.
114  *
115  * The notification RTE_ETH_EVENT_NEW is sent to other entities
116  * (libraries and applications).
117  * The state is set as RTE_ETH_DEV_ATTACHED.
118  *
119  * @param dev
120  *  New ethdev port.
121  */
122 void rte_eth_dev_probing_finish(struct rte_eth_dev *dev);
123
124 /**
125  * Create memzone for HW rings.
126  * malloc can't be used as the physical address is needed.
127  * If the memzone is already created, then this function returns a ptr
128  * to the old one.
129  *
130  * @param eth_dev
131  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
132  * @param name
133  *   The name of the memory zone
134  * @param queue_id
135  *   The index of the queue to add to name
136  * @param size
137  *   The sizeof of the memory area
138  * @param align
139  *   Alignment for resulting memzone. Must be a power of 2.
140  * @param socket_id
141  *   The *socket_id* argument is the socket identifier in case of NUMA.
142  */
143 const struct rte_memzone *
144 rte_eth_dma_zone_reserve(const struct rte_eth_dev *eth_dev, const char *name,
145                          uint16_t queue_id, size_t size,
146                          unsigned align, int socket_id);
147
148 /**
149  * @internal
150  * Atomically set the link status for the specific device.
151  * It is for use by DPDK device driver use only.
152  * User applications should not call it
153  *
154  * @param dev
155  *  Pointer to struct rte_eth_dev.
156  * @param link
157  *  New link status value.
158  * @return
159  *  Same convention as eth_link_update operation.
160  *  0   if link up status has changed
161  *  -1  if link up status was unchanged
162  */
163 static inline int
164 rte_eth_linkstatus_set(struct rte_eth_dev *dev,
165                        const struct rte_eth_link *new_link)
166 {
167         volatile uint64_t *dev_link
168                  = (volatile uint64_t *)&(dev->data->dev_link);
169         union {
170                 uint64_t val64;
171                 struct rte_eth_link link;
172         } orig;
173
174         RTE_BUILD_BUG_ON(sizeof(*new_link) != sizeof(uint64_t));
175
176         orig.val64 = rte_atomic64_exchange(dev_link,
177                                            *(const uint64_t *)new_link);
178
179         return (orig.link.link_status == new_link->link_status) ? -1 : 0;
180 }
181
182 /**
183  * @internal
184  * Atomically get the link speed and status.
185  *
186  * @param dev
187  *  Pointer to struct rte_eth_dev.
188  * @param link
189  *  link status value.
190  */
191 static inline void
192 rte_eth_linkstatus_get(const struct rte_eth_dev *dev,
193                        struct rte_eth_link *link)
194 {
195         volatile uint64_t *src = (uint64_t *)&(dev->data->dev_link);
196         uint64_t *dst = (uint64_t *)link;
197
198         RTE_BUILD_BUG_ON(sizeof(*link) != sizeof(uint64_t));
199
200 #ifdef __LP64__
201         /* if cpu arch has 64 bit unsigned lon then implicitly atomic */
202         *dst = *src;
203 #else
204         /* can't use rte_atomic64_read because it returns signed int */
205         do {
206                 *dst = *src;
207         } while (!rte_atomic64_cmpset(src, *dst, *dst));
208 #endif
209 }
210
211 /**
212  * @warning
213  * @b EXPERIMENTAL: this API may change without prior notice.
214  *
215  * Allocate an unique switch domain identifier.
216  *
217  * A pool of switch domain identifiers which can be allocated on request. This
218  * will enabled devices which support the concept of switch domains to request
219  * a switch domain id which is guaranteed to be unique from other devices
220  * running in the same process.
221  *
222  * @param domain_id
223  *  switch domain identifier parameter to pass back to application
224  *
225  * @return
226  *   Negative errno value on error, 0 on success.
227  */
228 int __rte_experimental
229 rte_eth_switch_domain_alloc(uint16_t *domain_id);
230
231 /**
232  * @warning
233  * @b EXPERIMENTAL: this API may change without prior notice.
234  *
235  * Free switch domain.
236  *
237  * Return a switch domain identifier to the pool of free identifiers after it is
238  * no longer in use by device.
239  *
240  * @param domain_id
241  *  switch domain identifier to free
242  *
243  * @return
244  *   Negative errno value on error, 0 on success.
245  */
246 int __rte_experimental
247 rte_eth_switch_domain_free(uint16_t domain_id);
248
249 /** Generic Ethernet device arguments  */
250 struct rte_eth_devargs {
251         uint16_t ports[RTE_MAX_ETHPORTS];
252         /** port/s number to enable on a multi-port single function */
253         uint16_t nb_ports;
254         /** number of ports in ports field */
255         uint16_t representor_ports[RTE_MAX_ETHPORTS];
256         /** representor port/s identifier to enable on device */
257         uint16_t nb_representor_ports;
258         /** number of ports in representor port field */
259 };
260
261 /**
262  * @warning
263  * @b EXPERIMENTAL: this API may change without prior notice.
264  *
265  * PMD helper function to parse ethdev arguments
266  *
267  * @param devargs
268  *  device arguments
269  * @param eth_devargs
270  *  parsed ethdev specific arguments.
271  *
272  * @return
273  *   Negative errno value on error, 0 on success.
274  */
275 int __rte_experimental
276 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs);
277
278
279 typedef int (*ethdev_init_t)(struct rte_eth_dev *ethdev, void *init_params);
280 typedef int (*ethdev_bus_specific_init)(struct rte_eth_dev *ethdev,
281         void *bus_specific_init_params);
282
283 /**
284  * @warning
285  * @b EXPERIMENTAL: this API may change without prior notice.
286  *
287  * PMD helper function for the creation of a new ethdev ports.
288  *
289  * @param device
290  *  rte_device handle.
291  * @param name
292  *  port name.
293  * @param priv_data_size
294  *  size of private data required for port.
295  * @param bus_specific_init
296  *  port bus specific initialisation callback function
297  * @param bus_init_params
298  *  port bus specific initialisation parameters
299  * @param ethdev_init
300  *  device specific port initialization callback function
301  * @param init_params
302  *  port initialisation parameters
303  *
304  * @return
305  *   Negative errno value on error, 0 on success.
306  */
307 int __rte_experimental
308 rte_eth_dev_create(struct rte_device *device, const char *name,
309         size_t priv_data_size,
310         ethdev_bus_specific_init bus_specific_init, void *bus_init_params,
311         ethdev_init_t ethdev_init, void *init_params);
312
313
314 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev);
315
316 /**
317  * @warning
318  * @b EXPERIMENTAL: this API may change without prior notice.
319  *
320  * PMD helper function for cleaing up the resources of a ethdev port on it's
321  * destruction.
322  *
323  * @param ethdev
324  *   ethdev handle of port.
325  * @param ethdev_uninit
326  *   device specific port un-initialise callback function
327  *
328  * @return
329  *   Negative errno value on error, 0 on success.
330  */
331 int __rte_experimental
332 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit);
333
334 #ifdef __cplusplus
335 }
336 #endif
337
338 #endif /* _RTE_ETHDEV_DRIVER_H_ */