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 27__FBSDID("$FreeBSD$"); 28 29#ifndef __IOAT_H__ 30#define __IOAT_H__ 31 32#include <sys/param.h> 33#include <machine/bus.h> 34 35/* 36 * This file defines the public interface to the IOAT driver. 37 */ 38 39/* 40 * Enables an interrupt for this operation. Typically, you would only enable 41 * this on the last operation in a group 42 */ 43#define DMA_INT_EN 0x1 44/* 45 * Like M_NOWAIT. Operations will return NULL if they cannot allocate a 46 * descriptor without blocking. 47 */ 48#define DMA_NO_WAIT 0x2 49/* 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. 53 */ 54#define DMA_FENCE 0x4 55#define _DMA_GENERIC_FLAGS (DMA_INT_EN | DMA_NO_WAIT | DMA_FENCE) 56 57/* 58 * Emit a CRC32C as the result of a ioat_copy_crc() or ioat_crc(). 59 */ 60#define DMA_CRC_STORE 0x8 61 62/* 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. 65 */ 66#define DMA_CRC_TEST 0x10 67#define _DMA_CRC_TESTSTORE (DMA_CRC_STORE | DMA_CRC_TEST) 68 69/* 70 * Use an inline comparison CRC32C or emit an inline CRC32C result. Invalid 71 * without one of STORE or TEST. 72 */ 73#define DMA_CRC_INLINE 0x20 74#define _DMA_CRC_FLAGS (DMA_CRC_STORE | DMA_CRC_TEST | DMA_CRC_INLINE) 75 76/* 77 * Hardware revision number. Different hardware revisions support different 78 * features. For example, 3.2 cannot read from MMIO space, while 3.3 can. 79 */ 80#define IOAT_VER_3_0 0x30 81#define IOAT_VER_3_2 0x32 82#define IOAT_VER_3_3 0x33 83 84typedef void *bus_dmaengine_t; 85struct bus_dmadesc; 86typedef void (*bus_dmaengine_callback_t)(void *arg, int error); 87 88unsigned ioat_get_nchannels(void); 89 90/* 91 * Called first to acquire a reference to the DMA channel 92 * 93 * Flags may be M_WAITOK or M_NOWAIT. 94 */ 95bus_dmaengine_t ioat_get_dmaengine(uint32_t channel_index, int flags); 96 97/* Release the DMA channel */ 98void ioat_put_dmaengine(bus_dmaengine_t dmaengine); 99 100/* Check the DMA engine's HW version */ 101int ioat_get_hwversion(bus_dmaengine_t dmaengine); 102size_t ioat_get_max_io_size(bus_dmaengine_t dmaengine); 103 104/* 105 * Set interrupt coalescing on a DMA channel. 106 * 107 * The argument is in microseconds. A zero value disables coalescing. Any 108 * other value delays interrupt generation for N microseconds to provide 109 * opportunity to coalesce multiple operations into a single interrupt. 110 * 111 * Returns an error status, or zero on success. 112 * 113 * - ERANGE if the given value exceeds the delay supported by the hardware. 114 * (All current hardware supports a maximum of 0x3fff microseconds delay.) 115 * - ENODEV if the hardware does not support interrupt coalescing. 116 */ 117int ioat_set_interrupt_coalesce(bus_dmaengine_t dmaengine, uint16_t delay); 118 119/* 120 * Return the maximum supported coalescing period, for use in 121 * ioat_set_interrupt_coalesce(). If the hardware does not support coalescing, 122 * returns zero. 123 */ 124uint16_t ioat_get_max_coalesce_period(bus_dmaengine_t dmaengine); 125 126/* 127 * Acquire must be called before issuing an operation to perform. Release is 128 * called after. Multiple operations can be issued within the context of one 129 * acquire and release 130 */ 131void ioat_acquire(bus_dmaengine_t dmaengine); 132void ioat_release(bus_dmaengine_t dmaengine); 133 134/* 135 * Acquire_reserve can be called to ensure there is room for N descriptors. If 136 * it succeeds, the next N valid operations will successfully enqueue. 137 * 138 * It may fail with: 139 * - ENXIO if the channel is in an errored state, or the driver is being 140 * unloaded 141 * - EAGAIN if mflags included M_NOWAIT 142 * 143 * On failure, the caller does not hold the dmaengine. 144 */ 145int ioat_acquire_reserve(bus_dmaengine_t dmaengine, unsigned n, int mflags); 146 147/* 148 * Issue a blockfill operation. The 64-bit pattern 'fillpattern' is written to 149 * 'len' physically contiguous bytes at 'dst'. 150 * 151 * Only supported on devices with the BFILL capability. 152 */ 153struct bus_dmadesc *ioat_blockfill(bus_dmaengine_t dmaengine, bus_addr_t dst, 154 uint64_t fillpattern, bus_size_t len, bus_dmaengine_callback_t callback_fn, 155 void *callback_arg, uint32_t flags); 156 157/* Issues the copy data operation */ 158struct bus_dmadesc *ioat_copy(bus_dmaengine_t dmaengine, bus_addr_t dst, 159 bus_addr_t src, bus_size_t len, bus_dmaengine_callback_t callback_fn, 160 void *callback_arg, uint32_t flags); 161 162/* 163 * Issue a copy data operation, with constraints: 164 * - src1, src2, dst1, dst2 are all page-aligned addresses 165 * - The quantity to copy is exactly 2 pages; 166 * - src1 -> dst1, src2 -> dst2 167 * 168 * Why use this instead of normal _copy()? You can copy two non-contiguous 169 * pages (src, dst, or both) with one descriptor. 170 */ 171struct bus_dmadesc *ioat_copy_8k_aligned(bus_dmaengine_t dmaengine, 172 bus_addr_t dst1, bus_addr_t dst2, bus_addr_t src1, bus_addr_t src2, 173 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 174 175/* 176 * Copy len bytes from dst to src, like ioat_copy(). 177 * 178 * Additionally, accumulate a CRC32C of the data. 179 * 180 * If initialseed is not NULL, the value it points to is used to seed the 181 * initial value of the CRC32C. 182 * 183 * If flags include DMA_CRC_STORE and not DMA_CRC_INLINE, crcptr is written 184 * with the 32-bit CRC32C result (in wire format). 185 * 186 * If flags include DMA_CRC_TEST and not DMA_CRC_INLINE, the computed CRC32C is 187 * compared with the 32-bit CRC32C pointed to by crcptr. If they do not match, 188 * a channel error is raised. 189 * 190 * If the DMA_CRC_INLINE flag is set, crcptr is ignored and the DMA engine uses 191 * the 4 bytes trailing the source data (TEST) or the destination data (STORE). 192 */ 193struct bus_dmadesc *ioat_copy_crc(bus_dmaengine_t dmaengine, bus_addr_t dst, 194 bus_addr_t src, bus_size_t len, uint32_t *initialseed, bus_addr_t crcptr, 195 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 196 197/* 198 * ioat_crc() is nearly identical to ioat_copy_crc(), but does not actually 199 * move data around. 200 * 201 * Like ioat_copy_crc, ioat_crc computes a CRC32C over len bytes pointed to by 202 * src. The flags affect its operation in the same way, with one exception: 203 * 204 * If flags includes both DMA_CRC_STORE and DMA_CRC_INLINE, the computed CRC32C 205 * is written to the 4 bytes trailing the *source* data. 206 */ 207struct bus_dmadesc *ioat_crc(bus_dmaengine_t dmaengine, bus_addr_t src, 208 bus_size_t len, uint32_t *initialseed, bus_addr_t crcptr, 209 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 210 211/* 212 * Issues a null operation. This issues the operation to the hardware, but the 213 * hardware doesn't do anything with it. 214 */ 215struct bus_dmadesc *ioat_null(bus_dmaengine_t dmaengine, 216 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 217 218 219#endif /* __IOAT_H__ */ 220 221