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  * 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 __rte_experimental
 229 int
 230 rte_eth_switch_domain_alloc(uint16_t *domain_id);
 231
 232 /**
 233  * @warning
 234  * @b EXPERIMENTAL: this API may change without prior notice.
 235  *
 236  * Free switch domain.
 237  *
 238  * Return a switch domain identifier to the pool of free identifiers after it is
 239  * no longer in use by device.
 240  *
 241  * @param domain_id
 242  *  switch domain identifier to free
 243  *
 244  * @return
 245  *   Negative errno value on error, 0 on success.
 246  */
 247 __rte_experimental
 248 int
 249 rte_eth_switch_domain_free(uint16_t domain_id);
 250
 251 /** Generic Ethernet device arguments  */
 252 struct rte_eth_devargs {
 253         uint16_t ports[RTE_MAX_ETHPORTS];
 254         /** port/s number to enable on a multi-port single function */
 255         uint16_t nb_ports;
 256         /** number of ports in ports field */
 257         uint16_t representor_ports[RTE_MAX_ETHPORTS];
 258         /** representor port/s identifier to enable on device */
 259         uint16_t nb_representor_ports;
 260         /** number of ports in representor port field */
 261 };
 262
 263 /**
 264  * @warning
 265  * @b EXPERIMENTAL: this API may change without prior notice.
 266  *
 267  * PMD helper function to parse ethdev arguments
 268  *
 269  * @param devargs
 270  *  device arguments
 271  * @param eth_devargs
 272  *  parsed ethdev specific arguments.
 273  *
 274  * @return
 275  *   Negative errno value on error, 0 on success.
 276  */
 277 __rte_experimental
 278 int
 279 rte_eth_devargs_parse(const char *devargs, struct rte_eth_devargs *eth_devargs);
 280
 281
 282 typedef int (*ethdev_init_t)(struct rte_eth_dev *ethdev, void *init_params);
 283 typedef int (*ethdev_bus_specific_init)(struct rte_eth_dev *ethdev,
 284         void *bus_specific_init_params);
 285
 286 /**
 287  * @warning
 288  * @b EXPERIMENTAL: this API may change without prior notice.
 289  *
 290  * PMD helper function for the creation of a new ethdev ports.
 291  *
 292  * @param device
 293  *  rte_device handle.
 294  * @param name
 295  *  port name.
 296  * @param priv_data_size
 297  *  size of private data required for port.
 298  * @param bus_specific_init
 299  *  port bus specific initialisation callback function
 300  * @param bus_init_params
 301  *  port bus specific initialisation parameters
 302  * @param ethdev_init
 303  *  device specific port initialization callback function
 304  * @param init_params
 305  *  port initialisation parameters
 306  *
 307  * @return
 308  *   Negative errno value on error, 0 on success.
 309  */
 310 __rte_experimental
 311 int
 312 rte_eth_dev_create(struct rte_device *device, const char *name,
 313         size_t priv_data_size,
 314         ethdev_bus_specific_init bus_specific_init, void *bus_init_params,
 315         ethdev_init_t ethdev_init, void *init_params);
 316
 317
 318 typedef int (*ethdev_uninit_t)(struct rte_eth_dev *ethdev);
 319
 320 /**
 321  * @warning
 322  * @b EXPERIMENTAL: this API may change without prior notice.
 323  *
 324  * PMD helper function for cleaning up the resources of a ethdev port on it's
 325  * destruction.
 326  *
 327  * @param ethdev
 328  *   ethdev handle of port.
 329  * @param ethdev_uninit
 330  *   device specific port un-initialise callback function
 331  *
 332  * @return
 333  *   Negative errno value on error, 0 on success.
 334  */
 335 __rte_experimental
 336 int
 337 rte_eth_dev_destroy(struct rte_eth_dev *ethdev, ethdev_uninit_t ethdev_uninit);
 338
 339 #ifdef __cplusplus
 340 }
 341 #endif
 342
 343 #endif /* _RTE_ETHDEV_DRIVER_H_ */