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 9extern "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 */ 35struct 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 */ 66static inline int 67__rte_experimental 68rte_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 */ 98static inline int 99__rte_experimental 100rte_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 */ 118static inline int 119__rte_experimental 120rte_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 */ 134static inline int 135__rte_experimental 136rte_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 */ 201static inline int 202__rte_experimental 203rte_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_ */ 215