1 /*- 2 * Copyright (C) 2012 Intel Corporation 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 1. Redistributions of source code must retain the above copyright 9 * notice, this list of conditions and the following disclaimer. 10 * 2. Redistributions in binary form must reproduce the above copyright 11 * notice, this list of conditions and the following disclaimer in the 12 * documentation and/or other materials provided with the distribution. 13 * 14 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24 * SUCH DAMAGE. 25 */ 26 #ifndef __IOAT_H__ 27 #define __IOAT_H__ 28 29 #include <sys/param.h> 30 #include <machine/bus.h> 31 32 /* 33 * This file defines the public interface to the IOAT driver. 34 */ 35 36 /* 37 * Enables an interrupt for this operation. Typically, you would only enable 38 * this on the last operation in a group 39 */ 40 #define DMA_INT_EN 0x1 41 /* 42 * Like M_NOWAIT. Operations will return NULL if they cannot allocate a 43 * descriptor without blocking. 44 */ 45 #define DMA_NO_WAIT 0x2 46 /* 47 * Disallow prefetching the source of the following operation. Ordinarily, DMA 48 * operations can be pipelined on some hardware. E.g., operation 2's source 49 * may be prefetched before operation 1 completes. 50 */ 51 #define DMA_FENCE 0x4 52 #define _DMA_GENERIC_FLAGS (DMA_INT_EN | DMA_NO_WAIT | DMA_FENCE) 53 54 /* 55 * Emit a CRC32C as the result of a ioat_copy_crc() or ioat_crc(). 56 */ 57 #define DMA_CRC_STORE 0x8 58 59 /* 60 * Compare the CRC32C of a ioat_copy_crc() or ioat_crc() against an expeceted 61 * value. It is invalid to specify both TEST and STORE. 62 */ 63 #define DMA_CRC_TEST 0x10 64 #define _DMA_CRC_TESTSTORE (DMA_CRC_STORE | DMA_CRC_TEST) 65 66 /* 67 * Use an inline comparison CRC32C or emit an inline CRC32C result. Invalid 68 * without one of STORE or TEST. 69 */ 70 #define DMA_CRC_INLINE 0x20 71 #define _DMA_CRC_FLAGS (DMA_CRC_STORE | DMA_CRC_TEST | DMA_CRC_INLINE) 72 73 /* 74 * Hardware revision number. Different hardware revisions support different 75 * features. For example, 3.2 cannot read from MMIO space, while 3.3 can. 76 */ 77 #define IOAT_VER_3_0 0x30 78 #define IOAT_VER_3_2 0x32 79 #define IOAT_VER_3_3 0x33 80 81 /* 82 * Hardware capabilities. Different hardware revisions support different 83 * features. It is often useful to detect specific features than try to infer 84 * them from hardware version. 85 * 86 * Different channels may support different features too; for example, 'PQ' may 87 * only be supported on the first two channels of some hardware. 88 */ 89 #define IOAT_DMACAP_PB (1 << 0) 90 #define IOAT_DMACAP_CRC (1 << 1) 91 #define IOAT_DMACAP_MARKER_SKIP (1 << 2) 92 #define IOAT_DMACAP_OLD_XOR (1 << 3) 93 #define IOAT_DMACAP_DCA (1 << 4) 94 #define IOAT_DMACAP_MOVECRC (1 << 5) 95 #define IOAT_DMACAP_BFILL (1 << 6) 96 #define IOAT_DMACAP_EXT_APIC (1 << 7) 97 #define IOAT_DMACAP_XOR (1 << 8) 98 #define IOAT_DMACAP_PQ (1 << 9) 99 #define IOAT_DMACAP_DMA_DIF (1 << 10) 100 #define IOAT_DMACAP_DWBES (1 << 13) 101 #define IOAT_DMACAP_RAID16SS (1 << 17) 102 #define IOAT_DMACAP_DMAMC (1 << 18) 103 #define IOAT_DMACAP_CTOS (1 << 19) 104 105 #define IOAT_DMACAP_STR \ 106 "\20\24Completion_Timeout_Support\23DMA_with_Multicasting_Support" \ 107 "\22RAID_Super_descriptors\16Descriptor_Write_Back_Error_Support" \ 108 "\13DMA_with_DIF\12PQ\11XOR\10Extended_APIC_ID\07Block_Fill\06Move_CRC" \ 109 "\05DCA\04Old_XOR\03Marker_Skipping\02CRC\01Page_Break" 110 111 typedef void *bus_dmaengine_t; 112 struct bus_dmadesc; 113 typedef void (*bus_dmaengine_callback_t)(void *arg, int error); 114 115 unsigned ioat_get_nchannels(void); 116 117 /* 118 * Called first to acquire a reference to the DMA channel 119 * 120 * Flags may be M_WAITOK or M_NOWAIT. 121 */ 122 bus_dmaengine_t ioat_get_dmaengine(uint32_t channel_index, int flags); 123 124 /* Release the DMA channel */ 125 void ioat_put_dmaengine(bus_dmaengine_t dmaengine); 126 127 /* Check the DMA engine's HW version */ 128 int ioat_get_hwversion(bus_dmaengine_t dmaengine); 129 size_t ioat_get_max_io_size(bus_dmaengine_t dmaengine); 130 uint32_t ioat_get_capabilities(bus_dmaengine_t dmaengine); 131 int ioat_get_domain(bus_dmaengine_t dmaengine, int *domain); 132 133 /* 134 * Set interrupt coalescing on a DMA channel. 135 * 136 * The argument is in microseconds. A zero value disables coalescing. Any 137 * other value delays interrupt generation for N microseconds to provide 138 * opportunity to coalesce multiple operations into a single interrupt. 139 * 140 * Returns an error status, or zero on success. 141 * 142 * - ERANGE if the given value exceeds the delay supported by the hardware. 143 * (All current hardware supports a maximum of 0x3fff microseconds delay.) 144 * - ENODEV if the hardware does not support interrupt coalescing. 145 */ 146 int ioat_set_interrupt_coalesce(bus_dmaengine_t dmaengine, uint16_t delay); 147 148 /* 149 * Return the maximum supported coalescing period, for use in 150 * ioat_set_interrupt_coalesce(). If the hardware does not support coalescing, 151 * returns zero. 152 */ 153 uint16_t ioat_get_max_coalesce_period(bus_dmaengine_t dmaengine); 154 155 /* 156 * Acquire must be called before issuing an operation to perform. Release is 157 * called after. Multiple operations can be issued within the context of one 158 * acquire and release 159 */ 160 void ioat_acquire(bus_dmaengine_t dmaengine); 161 void ioat_release(bus_dmaengine_t dmaengine); 162 163 /* 164 * Acquire_reserve can be called to ensure there is room for N descriptors. If 165 * it succeeds, the next N valid operations will successfully enqueue. 166 * 167 * It may fail with: 168 * - ENXIO if the channel is in an errored state, or the driver is being 169 * unloaded 170 * - EAGAIN if mflags included M_NOWAIT 171 * 172 * On failure, the caller does not hold the dmaengine. 173 */ 174 int ioat_acquire_reserve(bus_dmaengine_t dmaengine, unsigned n, int mflags) 175 __result_use_check; 176 177 /* 178 * Issue a blockfill operation. The 64-bit pattern 'fillpattern' is written to 179 * 'len' physically contiguous bytes at 'dst'. 180 * 181 * Only supported on devices with the BFILL capability. 182 */ 183 struct bus_dmadesc *ioat_blockfill(bus_dmaengine_t dmaengine, bus_addr_t dst, 184 uint64_t fillpattern, bus_size_t len, bus_dmaengine_callback_t callback_fn, 185 void *callback_arg, uint32_t flags); 186 187 /* Issues the copy data operation */ 188 struct bus_dmadesc *ioat_copy(bus_dmaengine_t dmaengine, bus_addr_t dst, 189 bus_addr_t src, bus_size_t len, bus_dmaengine_callback_t callback_fn, 190 void *callback_arg, uint32_t flags); 191 192 /* 193 * Issue a copy data operation, with constraints: 194 * - src1, src2, dst1, dst2 are all page-aligned addresses 195 * - The quantity to copy is exactly 2 pages; 196 * - src1 -> dst1, src2 -> dst2 197 * 198 * Why use this instead of normal _copy()? You can copy two non-contiguous 199 * pages (src, dst, or both) with one descriptor. 200 */ 201 struct bus_dmadesc *ioat_copy_8k_aligned(bus_dmaengine_t dmaengine, 202 bus_addr_t dst1, bus_addr_t dst2, bus_addr_t src1, bus_addr_t src2, 203 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 204 205 /* 206 * Copy len bytes from dst to src, like ioat_copy(). 207 * 208 * Additionally, accumulate a CRC32C of the data. 209 * 210 * If initialseed is not NULL, the value it points to is used to seed the 211 * initial value of the CRC32C. 212 * 213 * If flags include DMA_CRC_STORE and not DMA_CRC_INLINE, crcptr is written 214 * with the 32-bit CRC32C result (in wire format). 215 * 216 * If flags include DMA_CRC_TEST and not DMA_CRC_INLINE, the computed CRC32C is 217 * compared with the 32-bit CRC32C pointed to by crcptr. If they do not match, 218 * a channel error is raised. 219 * 220 * If the DMA_CRC_INLINE flag is set, crcptr is ignored and the DMA engine uses 221 * the 4 bytes trailing the source data (TEST) or the destination data (STORE). 222 */ 223 struct bus_dmadesc *ioat_copy_crc(bus_dmaengine_t dmaengine, bus_addr_t dst, 224 bus_addr_t src, bus_size_t len, uint32_t *initialseed, bus_addr_t crcptr, 225 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 226 227 /* 228 * ioat_crc() is nearly identical to ioat_copy_crc(), but does not actually 229 * move data around. 230 * 231 * Like ioat_copy_crc, ioat_crc computes a CRC32C over len bytes pointed to by 232 * src. The flags affect its operation in the same way, with one exception: 233 * 234 * If flags includes both DMA_CRC_STORE and DMA_CRC_INLINE, the computed CRC32C 235 * is written to the 4 bytes trailing the *source* data. 236 */ 237 struct bus_dmadesc *ioat_crc(bus_dmaengine_t dmaengine, bus_addr_t src, 238 bus_size_t len, uint32_t *initialseed, bus_addr_t crcptr, 239 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 240 241 /* 242 * Issues a null operation. This issues the operation to the hardware, but the 243 * hardware doesn't do anything with it. 244 */ 245 struct bus_dmadesc *ioat_null(bus_dmaengine_t dmaengine, 246 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 247 248 249 #endif /* __IOAT_H__ */ 250 251