2 * Copyright (C) 2012 Intel Corporation
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions
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.
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
27 __FBSDID("$FreeBSD$");
32 #include <sys/param.h>
33 #include <machine/bus.h>
36 * This file defines the public interface to the IOAT driver.
40 * Enables an interrupt for this operation. Typically, you would only enable
41 * this on the last operation in a group
43 #define DMA_INT_EN 0x1
45 * Like M_NOWAIT. Operations will return NULL if they cannot allocate a
46 * descriptor without blocking.
48 #define DMA_NO_WAIT 0x2
50 * Disallow prefetching the source of the following operation. Ordinarily, DMA
51 * operations can be pipelined on some hardware. E.g., operation 2's source
52 * may be prefetched before operation 1 completes.
55 #define _DMA_GENERIC_FLAGS (DMA_INT_EN | DMA_NO_WAIT | DMA_FENCE)
58 * Emit a CRC32C as the result of a ioat_copy_crc() or ioat_crc().
60 #define DMA_CRC_STORE 0x8
63 * Compare the CRC32C of a ioat_copy_crc() or ioat_crc() against an expeceted
64 * value. It is invalid to specify both TEST and STORE.
66 #define DMA_CRC_TEST 0x10
67 #define _DMA_CRC_TESTSTORE (DMA_CRC_STORE | DMA_CRC_TEST)
70 * Use an inline comparison CRC32C or emit an inline CRC32C result. Invalid
71 * without one of STORE or TEST.
73 #define DMA_CRC_INLINE 0x20
74 #define _DMA_CRC_FLAGS (DMA_CRC_STORE | DMA_CRC_TEST | DMA_CRC_INLINE)
77 * Hardware revision number. Different hardware revisions support different
78 * features. For example, 3.2 cannot read from MMIO space, while 3.3 can.
80 #define IOAT_VER_3_0 0x30
81 #define IOAT_VER_3_2 0x32
82 #define IOAT_VER_3_3 0x33
85 * Hardware capabilities. Different hardware revisions support different
86 * features. It is often useful to detect specific features than try to infer
87 * them from hardware version.
89 * Different channels may support different features too; for example, 'PQ' may
90 * only be supported on the first two channels of some hardware.
92 #define IOAT_DMACAP_PB (1 << 0)
93 #define IOAT_DMACAP_CRC (1 << 1)
94 #define IOAT_DMACAP_MARKER_SKIP (1 << 2)
95 #define IOAT_DMACAP_OLD_XOR (1 << 3)
96 #define IOAT_DMACAP_DCA (1 << 4)
97 #define IOAT_DMACAP_MOVECRC (1 << 5)
98 #define IOAT_DMACAP_BFILL (1 << 6)
99 #define IOAT_DMACAP_EXT_APIC (1 << 7)
100 #define IOAT_DMACAP_XOR (1 << 8)
101 #define IOAT_DMACAP_PQ (1 << 9)
102 #define IOAT_DMACAP_DMA_DIF (1 << 10)
103 #define IOAT_DMACAP_DWBES (1 << 13)
104 #define IOAT_DMACAP_RAID16SS (1 << 17)
105 #define IOAT_DMACAP_DMAMC (1 << 18)
106 #define IOAT_DMACAP_CTOS (1 << 19)
108 #define IOAT_DMACAP_STR \
109 "\20\24Completion_Timeout_Support\23DMA_with_Multicasting_Support" \
110 "\22RAID_Super_descriptors\16Descriptor_Write_Back_Error_Support" \
111 "\13DMA_with_DIF\12PQ\11XOR\10Extended_APIC_ID\07Block_Fill\06Move_CRC" \
112 "\05DCA\04Old_XOR\03Marker_Skipping\02CRC\01Page_Break"
114 typedef void *bus_dmaengine_t;
116 typedef void (*bus_dmaengine_callback_t)(void *arg, int error);
118 unsigned ioat_get_nchannels(void);
121 * Called first to acquire a reference to the DMA channel
123 * Flags may be M_WAITOK or M_NOWAIT.
125 bus_dmaengine_t ioat_get_dmaengine(uint32_t channel_index, int flags);
127 /* Release the DMA channel */
128 void ioat_put_dmaengine(bus_dmaengine_t dmaengine);
130 /* Check the DMA engine's HW version */
131 int ioat_get_hwversion(bus_dmaengine_t dmaengine);
132 size_t ioat_get_max_io_size(bus_dmaengine_t dmaengine);
133 uint32_t ioat_get_capabilities(bus_dmaengine_t dmaengine);
136 * Set interrupt coalescing on a DMA channel.
138 * The argument is in microseconds. A zero value disables coalescing. Any
139 * other value delays interrupt generation for N microseconds to provide
140 * opportunity to coalesce multiple operations into a single interrupt.
142 * Returns an error status, or zero on success.
144 * - ERANGE if the given value exceeds the delay supported by the hardware.
145 * (All current hardware supports a maximum of 0x3fff microseconds delay.)
146 * - ENODEV if the hardware does not support interrupt coalescing.
148 int ioat_set_interrupt_coalesce(bus_dmaengine_t dmaengine, uint16_t delay);
151 * Return the maximum supported coalescing period, for use in
152 * ioat_set_interrupt_coalesce(). If the hardware does not support coalescing,
155 uint16_t ioat_get_max_coalesce_period(bus_dmaengine_t dmaengine);
158 * Acquire must be called before issuing an operation to perform. Release is
159 * called after. Multiple operations can be issued within the context of one
160 * acquire and release
162 void ioat_acquire(bus_dmaengine_t dmaengine);
163 void ioat_release(bus_dmaengine_t dmaengine);
166 * Acquire_reserve can be called to ensure there is room for N descriptors. If
167 * it succeeds, the next N valid operations will successfully enqueue.
170 * - ENXIO if the channel is in an errored state, or the driver is being
172 * - EAGAIN if mflags included M_NOWAIT
174 * On failure, the caller does not hold the dmaengine.
176 int ioat_acquire_reserve(bus_dmaengine_t dmaengine, unsigned n, int mflags);
179 * Issue a blockfill operation. The 64-bit pattern 'fillpattern' is written to
180 * 'len' physically contiguous bytes at 'dst'.
182 * Only supported on devices with the BFILL capability.
184 struct bus_dmadesc *ioat_blockfill(bus_dmaengine_t dmaengine, bus_addr_t dst,
185 uint64_t fillpattern, bus_size_t len, bus_dmaengine_callback_t callback_fn,
186 void *callback_arg, uint32_t flags);
188 /* Issues the copy data operation */
189 struct bus_dmadesc *ioat_copy(bus_dmaengine_t dmaengine, bus_addr_t dst,
190 bus_addr_t src, bus_size_t len, bus_dmaengine_callback_t callback_fn,
191 void *callback_arg, uint32_t flags);
194 * Issue a copy data operation, with constraints:
195 * - src1, src2, dst1, dst2 are all page-aligned addresses
196 * - The quantity to copy is exactly 2 pages;
197 * - src1 -> dst1, src2 -> dst2
199 * Why use this instead of normal _copy()? You can copy two non-contiguous
200 * pages (src, dst, or both) with one descriptor.
202 struct bus_dmadesc *ioat_copy_8k_aligned(bus_dmaengine_t dmaengine,
203 bus_addr_t dst1, bus_addr_t dst2, bus_addr_t src1, bus_addr_t src2,
204 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags);
207 * Copy len bytes from dst to src, like ioat_copy().
209 * Additionally, accumulate a CRC32C of the data.
211 * If initialseed is not NULL, the value it points to is used to seed the
212 * initial value of the CRC32C.
214 * If flags include DMA_CRC_STORE and not DMA_CRC_INLINE, crcptr is written
215 * with the 32-bit CRC32C result (in wire format).
217 * If flags include DMA_CRC_TEST and not DMA_CRC_INLINE, the computed CRC32C is
218 * compared with the 32-bit CRC32C pointed to by crcptr. If they do not match,
219 * a channel error is raised.
221 * If the DMA_CRC_INLINE flag is set, crcptr is ignored and the DMA engine uses
222 * the 4 bytes trailing the source data (TEST) or the destination data (STORE).
224 struct bus_dmadesc *ioat_copy_crc(bus_dmaengine_t dmaengine, bus_addr_t dst,
225 bus_addr_t src, bus_size_t len, uint32_t *initialseed, bus_addr_t crcptr,
226 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags);
229 * ioat_crc() is nearly identical to ioat_copy_crc(), but does not actually
232 * Like ioat_copy_crc, ioat_crc computes a CRC32C over len bytes pointed to by
233 * src. The flags affect its operation in the same way, with one exception:
235 * If flags includes both DMA_CRC_STORE and DMA_CRC_INLINE, the computed CRC32C
236 * is written to the 4 bytes trailing the *source* data.
238 struct bus_dmadesc *ioat_crc(bus_dmaengine_t dmaengine, bus_addr_t src,
239 bus_size_t len, uint32_t *initialseed, bus_addr_t crcptr,
240 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags);
243 * Issues a null operation. This issues the operation to the hardware, but the
244 * hardware doesn't do anything with it.
246 struct bus_dmadesc *ioat_null(bus_dmaengine_t dmaengine,
247 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags);
250 #endif /* __IOAT_H__ */