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