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 cleaning 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_ */ 339