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