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_ALL_FLAGS (DMA_INT_EN | DMA_NO_WAIT | DMA_FENCE) 56 57 /* 58 * Hardware revision number. Different hardware revisions support different 59 * features. For example, 3.2 cannot read from MMIO space, while 3.3 can. 60 */ 61 #define IOAT_VER_3_0 0x30 62 #define IOAT_VER_3_2 0x32 63 #define IOAT_VER_3_3 0x33 64 65 typedef void *bus_dmaengine_t; 66 struct bus_dmadesc; 67 typedef void (*bus_dmaengine_callback_t)(void *arg, int error); 68 69 /* 70 * Called first to acquire a reference to the DMA channel 71 */ 72 bus_dmaengine_t ioat_get_dmaengine(uint32_t channel_index); 73 74 /* Release the DMA channel */ 75 void ioat_put_dmaengine(bus_dmaengine_t dmaengine); 76 77 /* Check the DMA engine's HW version */ 78 int ioat_get_hwversion(bus_dmaengine_t dmaengine); 79 size_t ioat_get_max_io_size(bus_dmaengine_t dmaengine); 80 81 /* 82 * Set interrupt coalescing on a DMA channel. 83 * 84 * The argument is in microseconds. A zero value disables coalescing. Any 85 * other value delays interrupt generation for N microseconds to provide 86 * opportunity to coalesce multiple operations into a single interrupt. 87 * 88 * Returns an error status, or zero on success. 89 * 90 * - ERANGE if the given value exceeds the delay supported by the hardware. 91 * (All current hardware supports a maximum of 0x3fff microseconds delay.) 92 * - ENODEV if the hardware does not support interrupt coalescing. 93 */ 94 int ioat_set_interrupt_coalesce(bus_dmaengine_t dmaengine, uint16_t delay); 95 96 /* 97 * Return the maximum supported coalescing period, for use in 98 * ioat_set_interrupt_coalesce(). If the hardware does not support coalescing, 99 * returns zero. 100 */ 101 uint16_t ioat_get_max_coalesce_period(bus_dmaengine_t dmaengine); 102 103 /* 104 * Acquire must be called before issuing an operation to perform. Release is 105 * called after. Multiple operations can be issued within the context of one 106 * acquire and release 107 */ 108 void ioat_acquire(bus_dmaengine_t dmaengine); 109 void ioat_release(bus_dmaengine_t dmaengine); 110 111 /* 112 * Acquire_reserve can be called to ensure there is room for N descriptors. If 113 * it succeeds, the next N valid operations will successfully enqueue. 114 * 115 * It may fail with: 116 * - ENXIO if the channel is in an errored state, or the driver is being 117 * unloaded 118 * - EAGAIN if mflags included M_NOWAIT 119 * 120 * On failure, the caller does not hold the dmaengine. 121 */ 122 int ioat_acquire_reserve(bus_dmaengine_t dmaengine, unsigned n, int mflags); 123 124 /* 125 * Issue a blockfill operation. The 64-bit pattern 'fillpattern' is written to 126 * 'len' physically contiguous bytes at 'dst'. 127 * 128 * Only supported on devices with the BFILL capability. 129 */ 130 struct bus_dmadesc *ioat_blockfill(bus_dmaengine_t dmaengine, bus_addr_t dst, 131 uint64_t fillpattern, bus_size_t len, bus_dmaengine_callback_t callback_fn, 132 void *callback_arg, uint32_t flags); 133 134 /* Issues the copy data operation */ 135 struct bus_dmadesc *ioat_copy(bus_dmaengine_t dmaengine, bus_addr_t dst, 136 bus_addr_t src, bus_size_t len, bus_dmaengine_callback_t callback_fn, 137 void *callback_arg, uint32_t flags); 138 139 /* 140 * Issue a copy data operation, with constraints: 141 * - src1, src2, dst1, dst2 are all page-aligned addresses 142 * - The quantity to copy is exactly 2 pages; 143 * - src1 -> dst1, src2 -> dst2 144 * 145 * Why use this instead of normal _copy()? You can copy two non-contiguous 146 * pages (src, dst, or both) with one descriptor. 147 */ 148 struct bus_dmadesc *ioat_copy_8k_aligned(bus_dmaengine_t dmaengine, 149 bus_addr_t dst1, bus_addr_t dst2, bus_addr_t src1, bus_addr_t src2, 150 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 151 152 /* 153 * Issues a null operation. This issues the operation to the hardware, but the 154 * hardware doesn't do anything with it. 155 */ 156 struct bus_dmadesc *ioat_null(bus_dmaengine_t dmaengine, 157 bus_dmaengine_callback_t callback_fn, void *callback_arg, uint32_t flags); 158 159 160 #endif /* __IOAT_H__ */ 161 162