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 October 31, 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_blockfill 82.Fa "bus_dmaengine_t dmaengine" 83.Fa "bus_addr_t dst" 84.Fa "uint64_t fillpattern" 85.Fa "bus_size_t len" 86.Fa "bus_dmaengine_callback_t callback_fn" 87.Fa "void *callback_arg" 88.Fa "uint32_t flags" 89.Fc 90.Ft struct bus_dmadesc * 91.Fo ioat_null 92.Fa "bus_dmaengine_t dmaengine" 93.Fa "bus_dmaengine_callback_t callback_fn" 94.Fa "void *callback_arg" 95.Fa "uint32_t flags" 96.Fc 97.Sh DESCRIPTION 98The 99.Nm 100driver provides a kernel API to a variety of DMA engines on some Intel server 101platforms. 102.Pp 103There is a number of DMA channels per CPU package. 104(Typically 4 or 8.) 105Each may be used independently. 106Operations on a single channel proceed sequentially. 107.Pp 108Blockfill operations can be used to write a 64-bit pattern to memory. 109.Pp 110Copy operations can be used to offload memory copies to the DMA engines. 111.Pp 112Null operations do nothing, but may be used to test the interrupt and callback 113mechanism. 114.Pp 115All operations can optionally trigger an interrupt at completion with the 116.Ar DMA_EN_INT 117flag. 118For example, a user might submit multiple operations to the same channel and 119only enable an interrupt and callback for the last operation. 120.Pp 121All operations are safe to use in a non-blocking context with the 122.Ar DMA_NO_WAIT 123flag. 124(Of course, allocations may fail and operations requested with 125.Ar DMA_NO_WAIT 126may return NULL.) 127.Pp 128All operations, as well as 129.Fn ioat_get_dmaengine , 130can return NULL in special circumstances. 131For example, if the 132.Nm 133driver is being unloaded, or the administrator has induced a hardware reset, or 134a usage error has resulted in a hardware error state that needs to be recovered 135from. 136.Pp 137It is invalid to attempt to submit new DMA operations in a 138.Fa bus_dmaengine_callback_t 139context. 140.Sh USAGE 141A typical user will lookup the DMA engine object for a given channel with 142.Fn ioat_get_dmaengine . 143When the user wants to offload a copy, they will first 144.Fn ioat_acquire 145the 146.Ar bus_dmaengine_t 147object for exclusive access to enqueue operations on that channel. 148Then, they will submit one or more operations using 149.Fn ioat_blockfill , 150.Fn ioat_copy , 151or 152.Fn ioat_null . 153After queueing one or more individual DMA operations, they will 154.Fn ioat_release 155the 156.Ar bus_dmaengine_t 157to drop their exclusive access to the channel. 158The routine they provided for the 159.Fa callback_fn 160argument will be invoked with the provided 161.Fa callback_arg 162when the operation is complete. 163When they are finished with the 164.Ar bus_dmaengine_t , 165the user should 166.Fn ioat_put_dmaengine . 167.Pp 168Users MUST NOT block between 169.Fn ioat_acquire 170and 171.Fn ioat_release . 172Users SHOULD NOT hold 173.Ar bus_dmaengine_t 174references for a very long time to enable fault recovery and kernel module 175unload. 176.Pp 177For an example of usage, see 178.Pa src/sys/dev/ioat/ioat_test.c . 179.Sh FILES 180.Bl -tag -compat 181.It Pa /dev/ioat_test 182test device for 183.Xr ioatcontrol 8 184.El 185.Sh SEE ALSO 186.Xr ioatcontrol 8 187.Sh HISTORY 188The 189.Nm 190driver first appeared in 191.Fx 11.0 . 192.Sh AUTHORS 193The 194.Nm 195driver was developed by 196.An \&Jim Harris Aq Mt jimharris@FreeBSD.org , 197.An \&Carl Delsey Aq Mt carl.r.delsey@intel.com , 198and 199.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . 200This manual page was written by 201.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . 202.Sh CAVEATS 203Copy operation takes bus addresses as parameters, not virtual addresses. 204.Pp 205Buffers for individual copy operations must be physically contiguous. 206.Pp 207Copies larger than max transfer size (1MB, but may vary by hardware) are not 208supported. 209Future versions will likely support this by breaking up the transfer into 210smaller sizes. 211.Sh BUGS 212The 213.Nm 214driver only supports blockfill, copy, and null operations at this time. 215The driver does not yet support advanced DMA modes, such as XOR, that some 216I/OAT devices support. 217