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