]>
Commit | Line | Data |
---|---|---|
11fdf7f2 TL |
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 | |
9f95a23c TL |
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. | |
11fdf7f2 TL |
69 | * |
70 | * @param eth_dev | |
9f95a23c | 71 | * Device to be detached. |
11fdf7f2 TL |
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 | * | |
9f95a23c | 320 | * PMD helper function for cleaning up the resources of a ethdev port on it's |
11fdf7f2 TL |
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 | ||
11fdf7f2 TL |
334 | #ifdef __cplusplus |
335 | } | |
336 | #endif | |
337 | ||
338 | #endif /* _RTE_ETHDEV_DRIVER_H_ */ |