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