1.\" Copyright (c) 2015 EMC / Isilon Storage Division 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.\" $FreeBSD$ 26.\" 27.Dd December 9, 2015 28.Dt IOAT 4 29.Os 30.Sh NAME 31.Nm I/OAT 32.Nd Intel I/O Acceleration Technology 33.Sh SYNOPSIS 34To compile this driver into your kernel, 35place the following line in your kernel configuration file: 36.Bd -ragged -offset indent 37.Cd "device ioat" 38.Ed 39.Pp 40Or, to load the driver as a module at boot, place the following line in 41.Xr loader.conf 5 : 42.Bd -literal -offset indent 43ioat_load="YES" 44.Ed 45.Pp 46In 47.Xr loader.conf 5 : 48.Pp 49.Cd hw.ioat.force_legacy_interrupts=0 50.Pp 51In 52.Xr loader.conf 5 or 53.Xr sysctl.conf 5 : 54.Pp 55.Cd hw.ioat.enable_ioat_test=0 56.Cd hw.ioat.debug_level=0 57(only critical errors; maximum of 3) 58.Pp 59.Ft typedef void 60.Fn (*bus_dmaengine_callback_t) "void *arg" "int error" 61.Pp 62.Ft bus_dmaengine_t 63.Fn ioat_get_dmaengine "uint32_t channel_index" 64.Ft void 65.Fn ioat_put_dmaengine "bus_dmaengine_t dmaengine" 66.Ft void 67.Fn ioat_acquire "bus_dmaengine_t dmaengine" 68.Ft void 69.Fn ioat_release "bus_dmaengine_t dmaengine" 70.Ft struct bus_dmadesc * 71.Fo ioat_copy 72.Fa "bus_dmaengine_t dmaengine" 73.Fa "bus_addr_t dst" 74.Fa "bus_addr_t src" 75.Fa "bus_size_t len" 76.Fa "bus_dmaengine_callback_t callback_fn" 77.Fa "void *callback_arg" 78.Fa "uint32_t flags" 79.Fc 80.Ft struct bus_dmadesc * 81.Fo ioat_copy_8k_aligned 82.Fa "bus_dmaengine_t dmaengine" 83.Fa "bus_addr_t dst1" 84.Fa "bus_addr_t dst2" 85.Fa "bus_addr_t src1" 86.Fa "bus_addr_t src2" 87.Fa "bus_dmaengine_callback_t callback_fn" 88.Fa "void *callback_arg" 89.Fa "uint32_t flags" 90.Fc 91.Ft struct bus_dmadesc * 92.Fo ioat_blockfill 93.Fa "bus_dmaengine_t dmaengine" 94.Fa "bus_addr_t dst" 95.Fa "uint64_t fillpattern" 96.Fa "bus_size_t len" 97.Fa "bus_dmaengine_callback_t callback_fn" 98.Fa "void *callback_arg" 99.Fa "uint32_t flags" 100.Fc 101.Ft struct bus_dmadesc * 102.Fo ioat_null 103.Fa "bus_dmaengine_t dmaengine" 104.Fa "bus_dmaengine_callback_t callback_fn" 105.Fa "void *callback_arg" 106.Fa "uint32_t flags" 107.Fc 108.Sh DESCRIPTION 109The 110.Nm 111driver provides a kernel API to a variety of DMA engines on some Intel server 112platforms. 113.Pp 114There is a number of DMA channels per CPU package. 115(Typically 4 or 8.) 116Each may be used independently. 117Operations on a single channel proceed sequentially. 118.Pp 119Blockfill operations can be used to write a 64-bit pattern to memory. 120.Pp 121Copy operations can be used to offload memory copies to the DMA engines. 122.Pp 123Null operations do nothing, but may be used to test the interrupt and callback 124mechanism. 125.Pp 126All operations can optionally trigger an interrupt at completion with the 127.Ar DMA_EN_INT 128flag. 129For example, a user might submit multiple operations to the same channel and 130only enable an interrupt and callback for the last operation. 131.Pp 132All operations are safe to use in a non-blocking context with the 133.Ar DMA_NO_WAIT 134flag. 135(Of course, allocations may fail and operations requested with 136.Ar DMA_NO_WAIT 137may return NULL.) 138.Pp 139All operations, as well as 140.Fn ioat_get_dmaengine , 141can return NULL in special circumstances. 142For example, if the 143.Nm 144driver is being unloaded, or the administrator has induced a hardware reset, or 145a usage error has resulted in a hardware error state that needs to be recovered 146from. 147.Pp 148It is invalid to attempt to submit new DMA operations in a 149.Fa bus_dmaengine_callback_t 150context. 151.Sh USAGE 152A typical user will lookup the DMA engine object for a given channel with 153.Fn ioat_get_dmaengine . 154When the user wants to offload a copy, they will first 155.Fn ioat_acquire 156the 157.Ar bus_dmaengine_t 158object for exclusive access to enqueue operations on that channel. 159Then, they will submit one or more operations using 160.Fn ioat_blockfill , 161.Fn ioat_copy , 162or 163.Fn ioat_null . 164After queuing one or more individual DMA operations, they will 165.Fn ioat_release 166the 167.Ar bus_dmaengine_t 168to drop their exclusive access to the channel. 169The routine they provided for the 170.Fa callback_fn 171argument will be invoked with the provided 172.Fa callback_arg 173when the operation is complete. 174When they are finished with the 175.Ar bus_dmaengine_t , 176the user should 177.Fn ioat_put_dmaengine . 178.Pp 179Users MUST NOT block between 180.Fn ioat_acquire 181and 182.Fn ioat_release . 183Users SHOULD NOT hold 184.Ar bus_dmaengine_t 185references for a very long time to enable fault recovery and kernel module 186unload. 187.Pp 188For an example of usage, see 189.Pa src/sys/dev/ioat/ioat_test.c . 190.Sh FILES 191.Bl -tag -compat 192.It Pa /dev/ioat_test 193test device for 194.Xr ioatcontrol 8 195.El 196.Sh SEE ALSO 197.Xr ioatcontrol 8 198.Sh HISTORY 199The 200.Nm 201driver first appeared in 202.Fx 11.0 . 203.Sh AUTHORS 204The 205.Nm 206driver was developed by 207.An \&Jim Harris Aq Mt jimharris@FreeBSD.org , 208.An \&Carl Delsey Aq Mt carl.r.delsey@intel.com , 209and 210.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . 211This manual page was written by 212.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . 213.Sh CAVEATS 214Copy operation takes bus addresses as parameters, not virtual addresses. 215.Pp 216Buffers for individual copy operations must be physically contiguous. 217.Pp 218Copies larger than max transfer size (1MB, but may vary by hardware) are not 219supported. 220Future versions will likely support this by breaking up the transfer into 221smaller sizes. 222.Sh BUGS 223The 224.Nm 225driver only supports blockfill, copy, and null operations at this time. 226The driver does not yet support advanced DMA modes, such as XOR, that some 227I/OAT devices support. 228