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         /** set "no_prefetch_completions", if polling completions on separate core
  39          * from the core submitting the jobs
  40          */
  41         bool no_prefetch_completions;
  42 };
  43
  44 /**
  45  * Enqueue a fill operation onto the ioat device
  46  *
  47  * This queues up a fill operation to be performed by hardware, but does not
  48  * trigger hardware to begin that operation.
  49  *
  50  * @param dev_id
  51  *   The rawdev device id of the ioat instance
  52  * @param pattern
  53  *   The pattern to populate the destination buffer with
  54  * @param dst
  55  *   The physical address of the destination buffer
  56  * @param length
  57  *   The length of the destination buffer
  58  * @param dst_hdl
  59  *   An opaque handle for the destination data, to be returned when this
  60  *   operation has been completed and the user polls for the completion details.
  61  *   NOTE: If hdls_disable configuration option for the device is set, this
  62  *   parameter is ignored.
  63  * @return
  64  *   Number of operations enqueued, either 0 or 1
  65  */
  66 static inline int
  67 __rte_experimental
  68 rte_ioat_enqueue_fill(int dev_id, uint64_t pattern, phys_addr_t dst,
  69                 unsigned int length, uintptr_t dst_hdl);
  70
  71 /**
  72  * Enqueue a copy operation onto the ioat device
  73  *
  74  * This queues up a copy operation to be performed by hardware, but does not
  75  * trigger hardware to begin that operation.
  76  *
  77  * @param dev_id
  78  *   The rawdev device id of the ioat instance
  79  * @param src
  80  *   The physical address of the source buffer
  81  * @param dst
  82  *   The physical address of the destination buffer
  83  * @param length
  84  *   The length of the data to be copied
  85  * @param src_hdl
  86  *   An opaque handle for the source data, to be returned when this operation
  87  *   has been completed and the user polls for the completion details.
  88  *   NOTE: If hdls_disable configuration option for the device is set, this
  89  *   parameter is ignored.
  90  * @param dst_hdl
  91  *   An opaque handle for the destination data, to be returned when this
  92  *   operation has been completed and the user polls for the completion details.
  93  *   NOTE: If hdls_disable configuration option for the device is set, this
  94  *   parameter is ignored.
  95  * @return
  96  *   Number of operations enqueued, either 0 or 1
  97  */
  98 static inline int
  99 __rte_experimental
 100 rte_ioat_enqueue_copy(int dev_id, phys_addr_t src, phys_addr_t dst,
 101                 unsigned int length, uintptr_t src_hdl, uintptr_t dst_hdl);
 102
 103 /**
 104  * Add a fence to force ordering between operations
 105  *
 106  * This adds a fence to a sequence of operations to enforce ordering, such that
 107  * all operations enqueued before the fence must be completed before operations
 108  * after the fence.
 109  * NOTE: Since this fence may be added as a flag to the last operation enqueued,
 110  * this API may not function correctly when called immediately after an
 111  * "rte_ioat_perform_ops" call i.e. before any new operations are enqueued.
 112  *
 113  * @param dev_id
 114  *   The rawdev device id of the ioat instance
 115  * @return
 116  *   Number of fences enqueued, either 0 or 1
 117  */
 118 static inline int
 119 __rte_experimental
 120 rte_ioat_fence(int dev_id);
 121
 122
 123 /**
 124  * Trigger hardware to begin performing enqueued operations
 125  *
 126  * This API is used to write the "doorbell" to the hardware to trigger it
 127  * to begin the operations previously enqueued by rte_ioat_enqueue_copy()
 128  *
 129  * @param dev_id
 130  *   The rawdev device id of the ioat instance
 131  * @return
 132  *   0 on success. Non-zero return on error.
 133  */
 134 static inline int
 135 __rte_experimental
 136 rte_ioat_perform_ops(int dev_id);
 137
 138 /*
 139  *  Status codes for operations.
 140  */
 141 #define RTE_IOAT_OP_SUCCESS 0  /**< Operation completed successfully */
 142 #define RTE_IOAT_OP_SKIPPED 1  /**< Operation was not attempted (Earlier fenced op failed) */
 143 /* Values >1 indicate a failure condition */
 144 /* Error codes taken from Intel(R) Data Streaming Accelerator Architecture
 145  * Specification, section 5.7
 146  */
 147 #define RTE_IOAT_OP_ADDRESS_ERR 0x03  /**< Page fault or invalid address */
 148 #define RTE_IOAT_OP_INVALID_LEN 0x13  /**< Invalid/too big length field passed */
 149 #define RTE_IOAT_OP_OVERLAPPING_BUFS 0x16 /**< Overlapping buffers error */
 150
 151
 152 /**
 153  * Returns details of operations that have been completed
 154  *
 155  * The status of each operation is returned in the status array parameter.
 156  * If the hdls_disable option was not set when the device was configured,
 157  * the function will return to the caller the user-provided "handles" for
 158  * the copy operations which have been completed by the hardware, and not
 159  * already returned by a previous call to this API.
 160  * If the hdls_disable option for the device was set on configure, the
 161  * src_hdls and dst_hdls parameters will be ignored, and the
 162  * function returns the number of newly-completed operations.
 163  * If status is also NULL, then max_copies parameter is also ignored and the
 164  * function returns a count of the number of newly-completed operations.
 165  *
 166  * @param dev_id
 167  *   The rawdev device id of the ioat instance
 168  * @param max_copies
 169  *   The number of entries which can fit in the status, src_hdls and dst_hdls
 170  *   arrays, i.e. max number of completed operations to report.
 171  *   NOTE: If hdls_disable configuration option for the device is set, this
 172  *   parameter applies only to the "status" array if specified
 173  * @param status
 174  *   Array to hold the status of each completed operation. Array should be
 175  *   set to zeros on input, as the driver will only write error status values.
 176  *   A value of 1 implies an operation was not attempted, and any other non-zero
 177  *   value indicates operation failure.
 178  *   Parameter may be NULL if no status value checking is required.
 179  * @param num_unsuccessful
 180  *   Returns the number of elements in status where the value is non-zero,
 181  *   i.e. the operation either failed or was not attempted due to an earlier
 182  *   failure. If this value is returned as zero (the expected case), the
 183  *   status array will not have been modified by the function and need not be
 184  *   checked by software
 185  * @param src_hdls
 186  *   Array to hold the source handle parameters of the completed ops.
 187  *   NOTE: If hdls_disable configuration option for the device is set, this
 188  *   parameter is ignored, and may be NULL
 189  * @param dst_hdls
 190  *   Array to hold the destination handle parameters of the completed ops.
 191  *   NOTE: If hdls_disable configuration option for the device is set, this
 192  *   parameter is ignored, and may be NULL
 193  * @return
 194  *   -1 on device error, with rte_errno set appropriately and parameters
 195  *   unmodified.
 196  *   Otherwise number of returned operations i.e. number of valid entries
 197  *   in the status, src_hdls and dst_hdls array parameters. If status is NULL,
 198  *   and the hdls_disable config option is set, this value may be greater than
 199  *   max_copies parameter.
 200  */
 201 static inline int
 202 __rte_experimental
 203 rte_ioat_completed_ops(int dev_id, uint8_t max_copies,
 204                 uint32_t *status, uint8_t *num_unsuccessful,
 205                 uintptr_t *src_hdls, uintptr_t *dst_hdls);
 206
 207 /* include the implementation details from a separate file */
 208 #include "rte_ioat_rawdev_fns.h"
 209
 210 #ifdef __cplusplus
 211 }
 212 #endif
 213
 214 #endif /* _RTE_IOAT_RAWDEV_H_ */