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