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.Dd May 27, 2016 26.Dt IOATCONTROL 8 27.Os 28.Sh NAME 29.Nm ioatcontrol 30.Nd Userspace tool to test 31.Xr ioat 4 32.Sh SYNOPSIS 33.Nm 34.Op Fl c Ar period 35.Op Fl E 36.Op Fl e 37.Op Fl f 38.Op Fl m 39.Op Fl V 40.Op Fl x 41.Op Fl X 42.Op Fl z 43.Ar channel_number 44.Ar num_txns 45.Ar [ bufsize 46.Ar [ chain-len 47.Ar [ duration ] ] ] 48.Nm 49.Fl r 50.Op Fl c Ar period 51.Op Fl v 52.Op Fl V 53.Op Fl w 54.Op Fl z 55.Ar channel_number 56.Ar address 57.Ar [ bufsize ] 58.Sh DESCRIPTION 59.Nm 60allows one to issue some number of test operations to the 61.Xr ioat 4 62driver on a specific hardware channel. 63The arguments are as follows: 64.Bl -tag -width Ds 65.It Fl c Ar period 66Configure the channel's interrupt coalescing period, in microseconds 67(defaults to 0). 68.It Fl E 69Test contiguous 8k copy. 70.It Fl e 71Test non-contiguous 8k copy. 72.It Fl f 73Test block fill (by default, 74.Nm 75tests copy) 76.It Fl m 77Test memcpy instead of DMA. 78.It Fl V 79Verify copies/fills for accuracy 80.It Fl x 81Test DMA CRC. 82.It Fl X 83Test DMA copy with CRC. 84.It Fl z 85Zero device statistics before running test. 86.El 87.Pp 88Alternatively one can use 89.Nm 90.Fl r 91to issue DMA to or from a specific 92.Ar address . 93The arguments in "raw" mode are: 94.Bl -tag -width Ds 95.It Fl c Ar period 96As above. 97.It Fl v 98.Ar address 99is a kernel virtual address (by default, 100.Ar address 101is assumed to be a physical address) 102.It Fl V 103Verify copies/fills for accuracy 104.It Fl w 105Write to the specified 106.Ar address 107(by default, 108.Nm 109.Fl r 110reads) 111.It Fl z 112As above. 113.El 114.Pp 115.Nm 116operates in one of two modes; if the 117.Ar duration 118argument is passed, 119.Nm 120tries to estimate the copy rate in bytes per second by running 121.Ar num_txns 122repeatedly in loop. 123If 124.Ar duration 125is not passed, 126.Nm 127only runs through 128.Ar num_txns 129once and prints the total bytes copied, as well as error information. 130.Pp 131The 132.Ar bufsize 133argument determines the size of buffers to use for each 134.Fn ioat_copy 135invocation. 136The default is 256 KB. 137In raw mode, the default is 4 KB. 138.Pp 139The 140.Ar chain-len 141argument determines the number of copies to chain together in a single DMA 142transaction. 143The default is 1. 144.Pp 145The 146.Ar duration 147argument specifies an approximate time limit for the test, in milliseconds. 148.Pp 149The test will allocate two chunks of memory for each component of each 150transaction's chain. 151It will initialize them with specific data patterns. 152During the test, it submits DMA requests to copy between pairs of buffers. 153If the 154.Fl V 155flag was specified, it will compare the contents in the callback for a copy 156error. 157.Sh FILES 158.Pa /dev/ioat_test 159.Pp 160The interface between 161.Nm 162and 163.Xr ioat 4 . 164.Xr ioat 4 165exposes it with 166.Cd hw.ioat.enable_ioat_test=1 . 167.Sh DIAGNOSTICS 168The wait channel 169.Va test_submit 170indicates that the test code has enqueued all requested transactions and is 171waiting on the IOAT hardware to complete one before issuing another operation. 172.Sh SEE ALSO 173.Xr ioat 4 174.Sh HISTORY 175The 176.Xr ioat 4 177driver first appeared in 178.Fx 11.0 . 179.Sh AUTHORS 180The 181.Xr ioat 4 182driver and 183.Nm 184tool were developed by 185.An \&Jim Harris Aq Mt jimharris@FreeBSD.org , 186.An \&Carl Delsey Aq Mt carl.r.delsey@intel.com , 187and 188.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . 189This manual page was written by 190.An \&Conrad Meyer Aq Mt cem@FreeBSD.org . 191