drivers/raw/ioat/rte_ioat_rawdev.h

   1 /* SPDX-License-Identifier: BSD-3-Clause
   2  * Copyright(c) 2019 Intel Corporation
   3  */
   4
   5 #ifndef _RTE_IOAT_RAWDEV_H_
   6 #define _RTE_IOAT_RAWDEV_H_
   7
   8 #ifdef __cplusplus
   9 extern "C" {
  10 #endif
  11
  12 /**
  13  * @file rte_ioat_rawdev.h
  14  *
  15  * Definitions for using the ioat rawdev device driver
  16  *
  17  * @warning
  18  * @b EXPERIMENTAL: these structures and APIs may change without prior notice
  19  */
  20
  21 #include <rte_common.h>
  22
  23 /** Name of the device driver */
  24 #define IOAT_PMD_RAWDEV_NAME rawdev_ioat
  25 /** String reported as the device driver name by rte_rawdev_info_get() */
  26 #define IOAT_PMD_RAWDEV_NAME_STR "rawdev_ioat"
  27
  28 /**
  29  * Configuration structure for an ioat rawdev instance
  30  *
  31  * This structure is to be passed as the ".dev_private" parameter when
  32  * calling the rte_rawdev_get_info() and rte_rawdev_configure() APIs on
  33  * an ioat rawdev instance.
  34  */
  35 struct rte_ioat_rawdev_config {
  36         unsigned short ring_size; /**< size of job submission descriptor ring */
  37         bool hdls_disable;    /**< if set, ignore user-supplied handle params */
  38 };
  39
  40 /**
  41  * Enqueue a copy operation onto the ioat device
  42  *
  43  * This queues up a copy operation to be performed by hardware, but does not
  44  * trigger hardware to begin that operation.
  45  *
  46  * @param dev_id
  47  *   The rawdev device id of the ioat instance
  48  * @param src
  49  *   The physical address of the source buffer
  50  * @param dst
  51  *   The physical address of the destination buffer
  52  * @param length
  53  *   The length of the data to be copied
  54  * @param src_hdl
  55  *   An opaque handle for the source data, to be returned when this operation
  56  *   has been completed and the user polls for the completion details.
  57  *   NOTE: If hdls_disable configuration option for the device is set, this
  58  *   parameter is ignored.
  59  * @param dst_hdl
  60  *   An opaque handle for the destination data, to be returned when this
  61  *   operation has been completed and the user polls for the completion details.
  62  *   NOTE: If hdls_disable configuration option for the device is set, this
  63  *   parameter is ignored.
  64  * @return
  65  *   Number of operations enqueued, either 0 or 1
  66  */
  67 static inline int
  68 __rte_experimental
  69 rte_ioat_enqueue_copy(int dev_id, phys_addr_t src, phys_addr_t dst,
  70                 unsigned int length, uintptr_t src_hdl, uintptr_t dst_hdl);
  71
  72 /**
  73  * Add a fence to force ordering between operations
  74  *
  75  * This adds a fence to a sequence of operations to enforce ordering, such that
  76  * all operations enqueued before the fence must be completed before operations
  77  * after the fence.
  78  * NOTE: Since this fence may be added as a flag to the last operation enqueued,
  79  * this API may not function correctly when called immediately after an
  80  * "rte_ioat_perform_ops" call i.e. before any new operations are enqueued.
  81  *
  82  * @param dev_id
  83  *   The rawdev device id of the ioat instance
  84  * @return
  85  *   Number of fences enqueued, either 0 or 1
  86  */
  87 static inline int
  88 __rte_experimental
  89 rte_ioat_fence(int dev_id);
  90
  91
  92 /**
  93  * Trigger hardware to begin performing enqueued operations
  94  *
  95  * This API is used to write the "doorbell" to the hardware to trigger it
  96  * to begin the operations previously enqueued by rte_ioat_enqueue_copy()
  97  *
  98  * @param dev_id
  99  *   The rawdev device id of the ioat instance
 100  */
 101 static inline void
 102 __rte_experimental
 103 rte_ioat_perform_ops(int dev_id);
 104
 105 /**
 106  * Returns details of operations that have been completed
 107  *
 108  * If the hdls_disable option was not set when the device was configured,
 109  * the function will return to the caller the user-provided "handles" for
 110  * the copy operations which have been completed by the hardware, and not
 111  * already returned by a previous call to this API.
 112  * If the hdls_disable option for the device was set on configure, the
 113  * max_copies, src_hdls and dst_hdls parameters will be ignored, and the
 114  * function returns the number of newly-completed operations.
 115  *
 116  * @param dev_id
 117  *   The rawdev device id of the ioat instance
 118  * @param max_copies
 119  *   The number of entries which can fit in the src_hdls and dst_hdls
 120  *   arrays, i.e. max number of completed operations to report.
 121  *   NOTE: If hdls_disable configuration option for the device is set, this
 122  *   parameter is ignored.
 123  * @param src_hdls
 124  *   Array to hold the source handle parameters of the completed ops.
 125  *   NOTE: If hdls_disable configuration option for the device is set, this
 126  *   parameter is ignored.
 127  * @param dst_hdls
 128  *   Array to hold the destination handle parameters of the completed ops.
 129  *   NOTE: If hdls_disable configuration option for the device is set, this
 130  *   parameter is ignored.
 131  * @return
 132  *   -1 on error, with rte_errno set appropriately.
 133  *   Otherwise number of completed operations i.e. number of entries written
 134  *   to the src_hdls and dst_hdls array parameters.
 135  */
 136 static inline int
 137 __rte_experimental
 138 rte_ioat_completed_ops(int dev_id, uint8_t max_copies,
 139                 uintptr_t *src_hdls, uintptr_t *dst_hdls);
 140
 141 /* include the implementation details from a separate file */
 142 #include "rte_ioat_rawdev_fns.h"
 143
 144 #ifdef __cplusplus
 145 }
 146 #endif
 147
 148 #endif /* _RTE_IOAT_RAWDEV_H_ */