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