tools/tools/ioat/ioatcontrol.8

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