1 /* SPDX-License-Identifier: BSD-3-Clause 2 * Copyright (C) 2015 Intel Corporation. 3 * All rights reserved. 4 */ 5 6 /** \file 7 * I/OAT DMA engine driver public interface 8 */ 9 10 #ifndef SPDK_IOAT_H 11 #define SPDK_IOAT_H 12 13 #include "spdk/stdinc.h" 14 15 #ifdef __cplusplus 16 extern "C" { 17 #endif 18 19 #include "spdk/env.h" 20 21 /** 22 * Opaque handle for a single I/OAT channel returned by \ref spdk_ioat_probe(). 23 */ 24 struct spdk_ioat_chan; 25 26 /** 27 * Signature for callback function invoked when a request is completed. 28 * 29 * \param arg User-specified opaque value corresponding to cb_arg from the 30 * request submission. 31 */ 32 typedef void (*spdk_ioat_req_cb)(void *arg); 33 34 /** 35 * Callback for spdk_ioat_probe() enumeration. 36 * 37 * \param cb_ctx User-specified opaque value corresponding to cb_ctx from spdk_ioat_probe(). 38 * \param pci_dev PCI device that is being probed. 39 * 40 * \return true to attach to this device. 41 */ 42 typedef bool (*spdk_ioat_probe_cb)(void *cb_ctx, struct spdk_pci_device *pci_dev); 43 44 /** 45 * Callback for spdk_ioat_probe() to report a device that has been attached to 46 * the userspace I/OAT driver. 47 * 48 * \param cb_ctx User-specified opaque value corresponding to cb_ctx from spdk_ioat_probe(). 49 * \param pci_dev PCI device that was attached to the driver. 50 * \param ioat I/OAT channel that was attached to the driver. 51 */ 52 typedef void (*spdk_ioat_attach_cb)(void *cb_ctx, struct spdk_pci_device *pci_dev, 53 struct spdk_ioat_chan *ioat); 54 55 /** 56 * Enumerate the I/OAT devices attached to the system and attach the userspace 57 * I/OAT driver to them if desired. 58 * 59 * If called more than once, only devices that are not already attached to the 60 * SPDK I/OAT driver will be reported. 61 * 62 * To stop using the controller and release its associated resources, call 63 * spdk_ioat_detach() with the ioat_channel instance returned by this function. 64 * 65 * \param cb_ctx Opaque value which will be passed back in cb_ctx parameter of 66 * the callbacks. 67 * \param probe_cb will be called once per I/OAT device found in the system. 68 * \param attach_cb will be called for devices for which probe_cb returned true 69 * once the I/OAT controller has been attached to the userspace driver. 70 * 71 * \return 0 on success, -1 on failure. 72 */ 73 int spdk_ioat_probe(void *cb_ctx, spdk_ioat_probe_cb probe_cb, spdk_ioat_attach_cb attach_cb); 74 75 /** 76 * Detach specified device returned by spdk_ioat_probe() from the I/OAT driver. 77 * 78 * \param ioat I/OAT channel to detach from the driver. 79 */ 80 void spdk_ioat_detach(struct spdk_ioat_chan *ioat); 81 82 /** 83 * Get the maximum number of descriptors supported by the library. 84 * 85 * \param chan I/OAT channel 86 * 87 * \return maximum number of descriptors. 88 */ 89 uint32_t spdk_ioat_get_max_descriptors(struct spdk_ioat_chan *chan); 90 91 /** 92 * Build a DMA engine memory copy request. 93 * 94 * This function will build the descriptor in the channel's ring. The 95 * caller must also explicitly call spdk_ioat_flush to submit the 96 * descriptor, possibly after building additional descriptors. 97 * 98 * \param chan I/OAT channel to build request. 99 * \param cb_arg Opaque value which will be passed back as the arg parameter in 100 * the completion callback. 101 * \param cb_fn Callback function which will be called when the request is complete. 102 * \param dst Destination virtual address. 103 * \param src Source virtual address. 104 * \param nbytes Number of bytes to copy. 105 * 106 * \return 0 on success, negative errno on failure. 107 */ 108 int spdk_ioat_build_copy(struct spdk_ioat_chan *chan, 109 void *cb_arg, spdk_ioat_req_cb cb_fn, 110 void *dst, const void *src, uint64_t nbytes); 111 112 /** 113 * Build and submit a DMA engine memory copy request. 114 * 115 * This function will build the descriptor in the channel's ring and then 116 * immediately submit it by writing the channel's doorbell. Calling this 117 * function does not require a subsequent call to spdk_ioat_flush. 118 * 119 * \param chan I/OAT channel to submit request. 120 * \param cb_arg Opaque value which will be passed back as the arg parameter in 121 * the completion callback. 122 * \param cb_fn Callback function which will be called when the request is complete. 123 * \param dst Destination virtual address. 124 * \param src Source virtual address. 125 * \param nbytes Number of bytes to copy. 126 * 127 * \return 0 on success, negative errno on failure. 128 */ 129 int spdk_ioat_submit_copy(struct spdk_ioat_chan *chan, 130 void *cb_arg, spdk_ioat_req_cb cb_fn, 131 void *dst, const void *src, uint64_t nbytes); 132 133 /** 134 * Build a DMA engine memory fill request. 135 * 136 * This function will build the descriptor in the channel's ring. The 137 * caller must also explicitly call spdk_ioat_flush to submit the 138 * descriptor, possibly after building additional descriptors. 139 * 140 * \param chan I/OAT channel to build request. 141 * \param cb_arg Opaque value which will be passed back as the cb_arg parameter 142 * in the completion callback. 143 * \param cb_fn Callback function which will be called when the request is complete. 144 * \param dst Destination virtual address. 145 * \param fill_pattern Repeating eight-byte pattern to use for memory fill. 146 * \param nbytes Number of bytes to fill. 147 * 148 * \return 0 on success, negative errno on failure. 149 */ 150 int spdk_ioat_build_fill(struct spdk_ioat_chan *chan, 151 void *cb_arg, spdk_ioat_req_cb cb_fn, 152 void *dst, uint64_t fill_pattern, uint64_t nbytes); 153 154 /** 155 * Build and submit a DMA engine memory fill request. 156 * 157 * This function will build the descriptor in the channel's ring and then 158 * immediately submit it by writing the channel's doorbell. Calling this 159 * function does not require a subsequent call to spdk_ioat_flush. 160 * 161 * \param chan I/OAT channel to submit request. 162 * \param cb_arg Opaque value which will be passed back as the cb_arg parameter 163 * in the completion callback. 164 * \param cb_fn Callback function which will be called when the request is complete. 165 * \param dst Destination virtual address. 166 * \param fill_pattern Repeating eight-byte pattern to use for memory fill. 167 * \param nbytes Number of bytes to fill. 168 * 169 * \return 0 on success, negative errno on failure. 170 */ 171 int spdk_ioat_submit_fill(struct spdk_ioat_chan *chan, 172 void *cb_arg, spdk_ioat_req_cb cb_fn, 173 void *dst, uint64_t fill_pattern, uint64_t nbytes); 174 175 /** 176 * Flush previously built descriptors. 177 * 178 * Descriptors are flushed by writing the channel's dmacount doorbell 179 * register. This function enables batching multiple descriptors followed by 180 * a single doorbell write. 181 * 182 * \param chan I/OAT channel to flush. 183 */ 184 void spdk_ioat_flush(struct spdk_ioat_chan *chan); 185 186 /** 187 * Check for completed requests on an I/OAT channel. 188 * 189 * \param chan I/OAT channel to check for completions. 190 * 191 * \return number of events handled on success, negative errno on failure. 192 */ 193 int spdk_ioat_process_events(struct spdk_ioat_chan *chan); 194 195 /** 196 * DMA engine capability flags 197 */ 198 enum spdk_ioat_dma_capability_flags { 199 SPDK_IOAT_ENGINE_COPY_SUPPORTED = 0x1, /**< The memory copy is supported */ 200 SPDK_IOAT_ENGINE_FILL_SUPPORTED = 0x2, /**< The memory fill is supported */ 201 }; 202 203 /** 204 * Get the DMA engine capabilities. 205 * 206 * \param chan I/OAT channel to query. 207 * 208 * \return a combination of flags from spdk_ioat_dma_capability_flags(). 209 */ 210 uint32_t spdk_ioat_get_dma_capabilities(struct spdk_ioat_chan *chan); 211 212 #ifdef __cplusplus 213 } 214 #endif 215 216 #endif 217