1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2019 Intel Corporation
5 #ifndef _RTE_IOAT_RAWDEV_H_
6 #define _RTE_IOAT_RAWDEV_H_
13 * @file rte_ioat_rawdev.h
15 * Definitions for using the ioat rawdev device driver
18 * @b EXPERIMENTAL: these structures and APIs may change without prior notice
21 #include <rte_common.h>
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"
29 * Configuration structure for an ioat rawdev instance
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.
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
41 bool no_prefetch_completions;
45 * Enqueue a fill operation onto the ioat device
47 * This queues up a fill operation to be performed by hardware, but does not
48 * trigger hardware to begin that operation.
51 * The rawdev device id of the ioat instance
53 * The pattern to populate the destination buffer with
55 * The physical address of the destination buffer
57 * The length of the destination buffer
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.
64 * Number of operations enqueued, either 0 or 1
68 rte_ioat_enqueue_fill(int dev_id, uint64_t pattern, phys_addr_t dst,
69 unsigned int length, uintptr_t dst_hdl);
72 * Enqueue a copy operation onto the ioat device
74 * This queues up a copy operation to be performed by hardware, but does not
75 * trigger hardware to begin that operation.
78 * The rawdev device id of the ioat instance
80 * The physical address of the source buffer
82 * The physical address of the destination buffer
84 * The length of the data to be copied
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.
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.
96 * Number of operations enqueued, either 0 or 1
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);
104 * Add a fence to force ordering between operations
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
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.
114 * The rawdev device id of the ioat instance
116 * Number of fences enqueued, either 0 or 1
120 rte_ioat_fence(int dev_id);
124 * Trigger hardware to begin performing enqueued operations
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()
130 * The rawdev device id of the ioat instance
132 * 0 on success. Non-zero return on error.
136 rte_ioat_perform_ops(int dev_id);
139 * Status codes for operations.
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
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 */
153 * Returns details of operations that have been completed
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.
167 * The rawdev device id of the ioat instance
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
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
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
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
194 * -1 on device error, with rte_errno set appropriately and parameters
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.
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);
207 /* include the implementation details from a separate file */
208 #include "rte_ioat_rawdev_fns.h"
214 #endif /* _RTE_IOAT_RAWDEV_H_ */