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