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
  30 /**
  31  * @internal
  32  * Returns a ethdev slot specified by the unique identifier name.
  33  *
  34  * @param       name
  35  *  The pointer to the Unique identifier name for each Ethernet device
  36  * @return
  37  *   - The pointer to the ethdev slot, on success. NULL on error
  38  */
  39 struct rte_eth_dev *rte_eth_dev_allocated(const char *name);
  40
  41 /**
  42  * @internal
  43  * Allocates a new ethdev slot for an ethernet device and returns the pointer
  44  * to that slot for the driver to use.
  45  *
  46  * @param       name    Unique identifier name for each Ethernet device
  47  * @return
  48  *   - Slot in the rte_dev_devices array for a new device;
  49  */
  50 struct rte_eth_dev *rte_eth_dev_allocate(const char *name);
  51
  52 /**
  53  * @internal
  54  * Attach to the ethdev already initialized by the primary
  55  * process.
  56  *
  57  * @param       name    Ethernet device's name.
  58  * @return
  59  *   - Success: Slot in the rte_dev_devices array for attached
  60  *        device.
  61  *   - Error: Null pointer.
  62  */
  63 struct rte_eth_dev *rte_eth_dev_attach_secondary(const char *name);
  64
  65 /**
  66  * @internal
  67  * Notify RTE_ETH_EVENT_DESTROY and release the specified ethdev port.
  68  *
  69  * The following PMD-managed data fields will be freed:
  70  *   - dev_private
  71  *   - mac_addrs
  72  *   - hash_mac_addrs
  73  * If one of these fields should not be freed,
  74  * it must be reset to NULL by the PMD, typically in dev_close method.
  75  *
  76  * @param eth_dev
  77  * Device to be detached.
  78  * @return
  79  *   - 0 on success, negative on error
  80  */
  81 int rte_eth_dev_release_port(struct rte_eth_dev *eth_dev);
  82
  83 /**
  84  * @internal
  85  * Release device queues and clear its configuration to force the user
  86  * application to reconfigure it. It is for internal use only.
  87  *
  88  * @param dev
  89  *  Pointer to struct rte_eth_dev.
  90  *
  91  * @return
  92  *  void
  93  */
  94 void _rte_eth_dev_reset(struct rte_eth_dev *dev);
  95
  96 /**
  97  * @internal Executes all the user application registered callbacks for
  98  * the specific device. It is for DPDK internal user only. User
  99  * application should not call it directly.
 100  *
 101  * @param dev
 102  *  Pointer to struct rte_eth_dev.
 103  * @param event
 104  *  Eth device interrupt event type.
 105  * @param ret_param
 106  *  To pass data back to user application.
 107  *  This allows the user application to decide if a particular function
 108  *  is permitted or not.
 109  *
 110  * @return
 111  *  int
 112  */
 113 int _rte_eth_dev_callback_process(struct rte_eth_dev *dev,
 114                 enum rte_eth_event_type event, void *ret_param);
 115
 116 /**
 117  * @internal
 118  * This is the last step of device probing.
 119  * It must be called after a port is allocated and initialized successfully.
 120  *
 121  * The notification RTE_ETH_EVENT_NEW is sent to other entities
 122  * (libraries and applications).
 123  * The state is set as RTE_ETH_DEV_ATTACHED.
 124  *
 125  * @param dev
 126  *  New ethdev port.
 127  */
 128 void rte_eth_dev_probing_finish(struct rte_eth_dev *dev);
 129
 130 /**
 131  * Create memzone for HW rings.
 132  * malloc can't be used as the physical address is needed.
 133  * If the memzone is already created, then this function returns a ptr
 134  * to the old one.
 135  *
 136  * @param eth_dev
 137  *   The *eth_dev* pointer is the address of the *rte_eth_dev* structure
 138  * @param name
 139  *   The name of the memory zone
 140  * @param queue_id
 141  *   The index of the queue to add to name
 142  * @param size
 143  *   The sizeof of the memory area
 144  * @param align
 145  *   Alignment for resulting memzone. Must be a power of 2.
 146  * @param socket_id
 147  *   The *socket_id* argument is the socket identifier in case of NUMA.
 148  */
 149 const struct rte_memzone *
 150 rte_eth_dma_zone_reserve(const struct rte_eth_dev *eth_dev, const char *name,
 151                          uint16_t queue_id, size_t size,
 152                          unsigned align, int socket_id);
 153
 154 /**
 155  * @internal
 156  * Atomically set the link status for the specific device.
 157  * It is for use by DPDK device driver use only.
 158  * User applications should not call it
 159  *
 160  * @param dev
 161  *  Pointer to struct rte_eth_dev.
 162  * @param link
 163  *  New link status value.
 164  * @return
 165  *  Same convention as eth_link_update operation.
 166  *  0   if link up status has changed
 167  *  -1  if link up status was unchanged
 168  */
 169 static inline int
 170 rte_eth_linkstatus_set(struct rte_eth_dev *dev,
 171                        const struct rte_eth_link *new_link)
 172 {
 173         volatile uint64_t *dev_link
 174                  = (volatile uint64_t *)&(dev->data->dev_link);
 175         union {
 176                 uint64_t val64;
 177                 struct rte_eth_link link;
 178         } orig;
 179
 180         RTE_BUILD_BUG_ON(sizeof(*new_link) != sizeof(uint64_t));
 181
 182         orig.val64 = rte_atomic64_exchange(dev_link,
 183                                            *(const uint64_t *)new_link);
 184
 185         return (orig.link.link_status == new_link->link_status) ? -1 : 0;
 186 }
 187
 188 /**
 189  * @internal
 190  * Atomically get the link speed and status.
 191  *
 192  * @param dev
 193  *  Pointer to struct rte_eth_dev.
 194  * @param link
 195  *  link status value.
 196  */
 197 static inline void
 198 rte_eth_linkstatus_get(const struct rte_eth_dev *dev,
 199                        struct rte_eth_link *link)
 200 {
 201         volatile uint64_t *src = (uint64_t *)&(dev->data->dev_link);
 202         uint64_t *dst = (uint64_t *)link;
 203
 204         RTE_BUILD_BUG_ON(sizeof(*link) != sizeof(uint64_t));
 205
 206 #ifdef __LP64__
 207         /* if cpu arch has 64 bit unsigned lon then implicitly atomic */
 208         *dst = *src;
 209 #else
 210         /* can't use rte_atomic64_read because it returns signed int */
 211         do {
 212                 *dst = *src;
 213         } while (!rte_atomic64_cmpset(src, *dst, *dst));
 214 #endif
 215 }
 216
 217 /**
 218  * @warning
 219  * @b EXPERIMENTAL: this API may change without prior notice.
 220  *
 221  * Allocate an unique switch domain identifier.
 222  *
 223  * A pool of switch domain identifiers which can be allocated on request. This
 224  * will enabled devices which support the concept of switch domains to request
 225  * a switch domain id which is guaranteed to be unique from other devices
 226  * running in the same process.
 227  *
 228  * @param domain_id
 229  *  switch domain identifier parameter to pass back to application
 230  *
 231  * @return
 232  *   Negative errno value on error, 0 on success.
 233  */
 234 __rte_experimental
 235 int
 236 rte_eth_switch_domain_alloc(uint16_t *domain_id);
 237
 238 /**
 239  * @warning
 240  * @b EXPERIMENTAL: this API may change without prior notice.
 241  *
 242  * Free switch domain.
 243  *
 244  * Return a switch domain identifier to the pool of free identifiers after it is
 245  * no longer in use by device.
 246  *
 247  * @param domain_id
 248  *  switch domain identifier to free
 249  *
 250  * @return
 251  *   Negative errno value on error, 0 on success.
 252  */
 253 __rte_experimental
 254 int
 255 rte_eth_switch_domain_free(uint16_t domain_id);
 256
 257 /** Generic Ethernet device arguments  */
 258 struct rte_eth_devargs {
 259         uint16_t ports[RTE_MAX_ETHPORTS];
 260         /** port/s number to enable on a multi-port single function */
 261         uint16_t nb_ports;
 262         /** number of ports in ports field */
 263         uint16_t representor_ports[RTE_MAX_ETHPORTS];
 264         /** representor port/s identifier to enable on device */
 265         uint16_t nb_representor_ports;
 266         /** number of ports in representor port field */
 267 };
 268
 269 /**
 270  * @warning
 271  * @b EXPERIMENTAL: this API may change without prior notice.
 272  *
 273  * PMD helper function to parse ethdev arguments
 274  *
 275  * @param devargs
 276  *  device arguments
 277  * @param eth_devargs
 278  *  parsed ethdev specific arguments.
 279  *
 280  * @return
 281  *   Negative errno value on error, 0 on success.
 282  */
 283 __rte_experimental
 284 int
 285 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs);
 286
 287
 288 typedef int (*ethdev_init_t)(struct rte_eth_dev *ethdev, void *init_params);
 289 typedef int (*ethdev_bus_specific_init)(struct rte_eth_dev *ethdev,
 290         void *bus_specific_init_params);
 291
 292 /**
 293  * @warning
 294  * @b EXPERIMENTAL: this API may change without prior notice.
 295  *
 296  * PMD helper function for the creation of a new ethdev ports.
 297  *
 298  * @param device
 299  *  rte_device handle.
 300  * @param name
 301  *  port name.
 302  * @param priv_data_size
 303  *  size of private data required for port.
 304  * @param bus_specific_init
 305  *  port bus specific initialisation callback function
 306  * @param bus_init_params
 307  *  port bus specific initialisation parameters
 308  * @param ethdev_init
 309  *  device specific port initialization callback function
 310  * @param init_params
 311  *  port initialisation parameters
 312  *
 313  * @return
 314  *   Negative errno value on error, 0 on success.
 315  */
 316 __rte_experimental
 317 int
 318 rte_eth_dev_create(struct rte_device *device, const char *name,
 319         size_t priv_data_size,
 320         ethdev_bus_specific_init bus_specific_init, void *bus_init_params,
 321         ethdev_init_t ethdev_init, void *init_params);
 322
 323
 324 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev);
 325
 326 /**
 327  * @warning
 328  * @b EXPERIMENTAL: this API may change without prior notice.
 329  *
 330  * PMD helper function for cleaning up the resources of a ethdev port on it's
 331  * destruction.
 332  *
 333  * @param ethdev
 334  *   ethdev handle of port.
 335  * @param ethdev_uninit
 336  *   device specific port un-initialise callback function
 337  *
 338  * @return
 339  *   Negative errno value on error, 0 on success.
 340  */
 341 __rte_experimental
 342 int
 343 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit);
 344
 345 #ifdef __cplusplus
 346 }
 347 #endif
 348
 349 #endif /* _RTE_ETHDEV_DRIVER_H_ */