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 * @internal 185 * Atomically set the link status for the specific device. 186 * It is for use by DPDK device driver use only. 187 * User applications should not call it 188 * 189 * @param dev 190 * Pointer to struct rte_eth_dev. 191 * @param link 192 * New link status value. 193 * @return 194 * Same convention as eth_link_update operation. 195 * 0 if link up status has changed 196 * -1 if link up status was unchanged 197 */ 198 static inline int 199 rte_eth_linkstatus_set(struct rte_eth_dev *dev, 200 const struct rte_eth_link *new_link) 201 { 202 volatile uint64_t *dev_link 203 = (volatile uint64_t *)&(dev->data->dev_link); 204 union { 205 uint64_t val64; 206 struct rte_eth_link link; 207 } orig; 208 209 RTE_BUILD_BUG_ON(sizeof(*new_link) != sizeof(uint64_t)); 210 211 orig.val64 = rte_atomic64_exchange(dev_link, 212 *(const uint64_t *)new_link); 213 214 return (orig.link.link_status == new_link->link_status) ? -1 : 0; 215 } 216 217 /** 218 * @internal 219 * Atomically get the link speed and status. 220 * 221 * @param dev 222 * Pointer to struct rte_eth_dev. 223 * @param link 224 * link status value. 225 */ 226 static inline void 227 rte_eth_linkstatus_get(const struct rte_eth_dev *dev, 228 struct rte_eth_link *link) 229 { 230 volatile uint64_t *src = (uint64_t *)&(dev->data->dev_link); 231 uint64_t *dst = (uint64_t *)link; 232 233 RTE_BUILD_BUG_ON(sizeof(*link) != sizeof(uint64_t)); 234 235 #ifdef __LP64__ 236 /* if cpu arch has 64 bit unsigned lon then implicitly atomic */ 237 *dst = *src; 238 #else 239 /* can't use rte_atomic64_read because it returns signed int */ 240 do { 241 *dst = *src; 242 } while (!rte_atomic64_cmpset(src, *dst, *dst)); 243 #endif 244 } 245 246 /** 247 * @warning 248 * @b EXPERIMENTAL: this API may change without prior notice. 249 * 250 * Allocate an unique switch domain identifier. 251 * 252 * A pool of switch domain identifiers which can be allocated on request. This 253 * will enabled devices which support the concept of switch domains to request 254 * a switch domain id which is guaranteed to be unique from other devices 255 * running in the same process. 256 * 257 * @param domain_id 258 * switch domain identifier parameter to pass back to application 259 * 260 * @return 261 * Negative errno value on error, 0 on success. 262 */ 263 __rte_experimental 264 int 265 rte_eth_switch_domain_alloc(uint16_t *domain_id); 266 267 /** 268 * @warning 269 * @b EXPERIMENTAL: this API may change without prior notice. 270 * 271 * Free switch domain. 272 * 273 * Return a switch domain identifier to the pool of free identifiers after it is 274 * no longer in use by device. 275 * 276 * @param domain_id 277 * switch domain identifier to free 278 * 279 * @return 280 * Negative errno value on error, 0 on success. 281 */ 282 __rte_experimental 283 int 284 rte_eth_switch_domain_free(uint16_t domain_id); 285 286 /** Generic Ethernet device arguments */ 287 struct rte_eth_devargs { 288 uint16_t ports[RTE_MAX_ETHPORTS]; 289 /** port/s number to enable on a multi-port single function */ 290 uint16_t nb_ports; 291 /** number of ports in ports field */ 292 uint16_t representor_ports[RTE_MAX_ETHPORTS]; 293 /** representor port/s identifier to enable on device */ 294 uint16_t nb_representor_ports; 295 /** number of ports in representor port field */ 296 }; 297 298 /** 299 * @warning 300 * @b EXPERIMENTAL: this API may change without prior notice. 301 * 302 * PMD helper function to parse ethdev arguments 303 * 304 * @param devargs 305 * device arguments 306 * @param eth_devargs 307 * parsed ethdev specific arguments. 308 * 309 * @return 310 * Negative errno value on error, 0 on success. 311 */ 312 __rte_experimental 313 int 314 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs); 315 316 317 typedef int (*ethdev_init_t)(struct rte_eth_dev *ethdev, void *init_params); 318 typedef int (*ethdev_bus_specific_init)(struct rte_eth_dev *ethdev, 319 void *bus_specific_init_params); 320 321 /** 322 * @warning 323 * @b EXPERIMENTAL: this API may change without prior notice. 324 * 325 * PMD helper function for the creation of a new ethdev ports. 326 * 327 * @param device 328 * rte_device handle. 329 * @param name 330 * port name. 331 * @param priv_data_size 332 * size of private data required for port. 333 * @param bus_specific_init 334 * port bus specific initialisation callback function 335 * @param bus_init_params 336 * port bus specific initialisation parameters 337 * @param ethdev_init 338 * device specific port initialization callback function 339 * @param init_params 340 * port initialisation parameters 341 * 342 * @return 343 * Negative errno value on error, 0 on success. 344 */ 345 __rte_experimental 346 int 347 rte_eth_dev_create(struct rte_device *device, const char *name, 348 size_t priv_data_size, 349 ethdev_bus_specific_init bus_specific_init, void *bus_init_params, 350 ethdev_init_t ethdev_init, void *init_params); 351 352 353 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev); 354 355 /** 356 * @warning 357 * @b EXPERIMENTAL: this API may change without prior notice. 358 * 359 * PMD helper function for cleaning up the resources of a ethdev port on it's 360 * destruction. 361 * 362 * @param ethdev 363 * ethdev handle of port. 364 * @param ethdev_uninit 365 * device specific port un-initialise callback function 366 * 367 * @return 368 * Negative errno value on error, 0 on success. 369 */ 370 __rte_experimental 371 int 372 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit); 373 374 #ifdef __cplusplus 375 } 376 #endif 377 378 #endif /* _RTE_ETHDEV_DRIVER_H_ */ 379