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 fill operation onto the ioat device
  42  *
  43  * This queues up a fill 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 pattern
  49  *   The pattern to populate the destination buffer with
  50  * @param dst
  51  *   The physical address of the destination buffer
  52  * @param length
  53  *   The length of the destination buffer
  54  * @param dst_hdl
  55  *   An opaque handle for the destination data, to be returned when this
  56  *   operation 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  * @return
  60  *   Number of operations enqueued, either 0 or 1
  61  */
  62 static inline int
  63 __rte_experimental
  64 rte_ioat_enqueue_fill(int dev_id, uint64_t pattern, phys_addr_t dst,
  65                 unsigned int length, uintptr_t dst_hdl);
  66
  67 /**
  68  * Enqueue a copy operation onto the ioat device
  69  *
  70  * This queues up a copy operation to be performed by hardware, but does not
  71  * trigger hardware to begin that operation.
  72  *
  73  * @param dev_id
  74  *   The rawdev device id of the ioat instance
  75  * @param src
  76  *   The physical address of the source buffer
  77  * @param dst
  78  *   The physical address of the destination buffer
  79  * @param length
  80  *   The length of the data to be copied
  81  * @param src_hdl
  82  *   An opaque handle for the source data, to be returned when this operation
  83  *   has been completed and the user polls for the completion details.
  84  *   NOTE: If hdls_disable configuration option for the device is set, this
  85  *   parameter is ignored.
  86  * @param dst_hdl
  87  *   An opaque handle for the destination data, to be returned when this
  88  *   operation has been completed and the user polls for the completion details.
  89  *   NOTE: If hdls_disable configuration option for the device is set, this
  90  *   parameter is ignored.
  91  * @return
  92  *   Number of operations enqueued, either 0 or 1
  93  */
  94 static inline int
  95 __rte_experimental
  96 rte_ioat_enqueue_copy(int dev_id, phys_addr_t src, phys_addr_t dst,
  97                 unsigned int length, uintptr_t src_hdl, uintptr_t dst_hdl);
  98
  99 /**
 100  * Add a fence to force ordering between operations
 101  *
 102  * This adds a fence to a sequence of operations to enforce ordering, such that
 103  * all operations enqueued before the fence must be completed before operations
 104  * after the fence.
 105  * NOTE: Since this fence may be added as a flag to the last operation enqueued,
 106  * this API may not function correctly when called immediately after an
 107  * "rte_ioat_perform_ops" call i.e. before any new operations are enqueued.
 108  *
 109  * @param dev_id
 110  *   The rawdev device id of the ioat instance
 111  * @return
 112  *   Number of fences enqueued, either 0 or 1
 113  */
 114 static inline int
 115 __rte_experimental
 116 rte_ioat_fence(int dev_id);
 117
 118
 119 /**
 120  * Trigger hardware to begin performing enqueued operations
 121  *
 122  * This API is used to write the "doorbell" to the hardware to trigger it
 123  * to begin the operations previously enqueued by rte_ioat_enqueue_copy()
 124  *
 125  * @param dev_id
 126  *   The rawdev device id of the ioat instance
 127  * @return
 128  *   0 on success. Non-zero return on error.
 129  */
 130 static inline int
 131 __rte_experimental
 132 rte_ioat_perform_ops(int dev_id);
 133
 134 /**
 135  * Returns details of operations that have been completed
 136  *
 137  * If the hdls_disable option was not set when the device was configured,
 138  * the function will return to the caller the user-provided "handles" for
 139  * the copy operations which have been completed by the hardware, and not
 140  * already returned by a previous call to this API.
 141  * If the hdls_disable option for the device was set on configure, the
 142  * max_copies, src_hdls and dst_hdls parameters will be ignored, and the
 143  * function returns the number of newly-completed operations.
 144  *
 145  * @param dev_id
 146  *   The rawdev device id of the ioat instance
 147  * @param max_copies
 148  *   The number of entries which can fit in the src_hdls and dst_hdls
 149  *   arrays, i.e. max number of completed operations to report.
 150  *   NOTE: If hdls_disable configuration option for the device is set, this
 151  *   parameter is ignored.
 152  * @param src_hdls
 153  *   Array to hold the source handle parameters of the completed ops.
 154  *   NOTE: If hdls_disable configuration option for the device is set, this
 155  *   parameter is ignored.
 156  * @param dst_hdls
 157  *   Array to hold the destination handle parameters of the completed ops.
 158  *   NOTE: If hdls_disable configuration option for the device is set, this
 159  *   parameter is ignored.
 160  * @return
 161  *   -1 on error, with rte_errno set appropriately.
 162  *   Otherwise number of completed operations i.e. number of entries written
 163  *   to the src_hdls and dst_hdls array parameters.
 164  */
 165 static inline int
 166 __rte_experimental
 167 rte_ioat_completed_ops(int dev_id, uint8_t max_copies,
 168                 uintptr_t *src_hdls, uintptr_t *dst_hdls);
 169
 170 /* include the implementation details from a separate file */
 171 #include "rte_ioat_rawdev_fns.h"
 172
 173 #ifdef __cplusplus
 174 }
 175 #endif
 176
 177 #endif /* _RTE_IOAT_RAWDEV_H_ */