usr.sbin/camdd/camdd.8

   1 .\"
   2 .\" Copyright (c) 2015 Spectra Logic Corporation
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions, and the following disclaimer,
  10 .\"    without modification.
  11 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  13 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  14 .\"    including a substantially similar Disclaimer requirement for further
  15 .\"    binary redistribution.
  16 .\"
  17 .\" NO WARRANTY
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGES.
  29 .\"
  30 .\" Authors: Ken Merry           (Spectra Logic Corporation)
  31 .\"
  32 .\" $FreeBSD$
  33 .\"
  34 .Dd November 11, 2015
  35 .Dt CAMDD 8
  36 .Os
  37 .Sh NAME
  38 .Nm camdd
  39 .Nd CAM data transfer utility
  40 .Sh SYNOPSIS
  41 .Nm
  42 .Aq Fl i|o Ar pass=pass_dev|file=filename,bs=blocksize,[...]
  43 .Op Fl C Ar retry_count
  44 .Op Fl E
  45 .Op Fl m Ar max_io
  46 .Op Fl t Ar timeout
  47 .Op Fl v
  48 .Op Fl h
  49 .Sh DESCRIPTION
  50 The
  51 .Nm
  52 utility is a sequential data transfer utility that offers standard
  53 .Xr read 2
  54 and
  55 .Xr write 2
  56 operation in addition to a mode that uses the asynchronous
  57 .Xr pass 4
  58 API.
  59 The asynchronous
  60 .Xr pass 4
  61 API allows multiple requests to be queued to a device simultaneously.
  62 .Pp
  63 .Nm
  64 collects performance information and will display it when the transfer
  65 completes, when
  66 .Nm
  67 is terminated or when it receives a SIGINFO signal.
  68 .Pp
  69 The following options are available:
  70 .Bl -tag -width 12n
  71 .It Fl i | o Ar args
  72 Specify the input and output device or file.
  73 Both
  74 .Fl i
  75 and
  76 .Fl o
  77 must be specified.
  78 There are a number of parameters that can be specified.
  79 One of the first two (file or pass) MUST be specified to indicate which I/O
  80 method to use on the device in question.
  81 .Bl -tag -width 9n
  82 .It pass=dev
  83 Specify a
  84 .Xr pass 4
  85 device to operate on.
  86 This requests that
  87 .Nm
  88 access the device in question be accessed via the asynchronous
  89 .Xr pass 4
  90 interface.
  91 .Pp
  92 The device name can be a
  93 .Xr pass 4
  94 name and unit number, for instance
  95 .Dq pass0 ,
  96 or a regular peripheral driver name and unit number, for instance
  97 .Dq da5 .
  98 It can also be the path of a
  99 .Xr pass 4
 100 or other disk device, like
 101 .Dq /dev/da5 .
 102 It may also be a bus:target:lun, for example:
 103 .Dq 0:5:0 .
 104 .Pp
 105 Only
 106 .Xr pass 4
 107 devices for
 108 .Tn SCSI
 109 disk-like devices are supported.
 110 .Tn ATA
 111 devices are not currently supported, but support could be added later.
 112 Specifically,
 113 .Tn SCSI
 114 Direct Access (type 0), WORM (type 4), CDROM (type 5), and RBC (Reduced
 115 Block Command, type 14) devices are supported.
 116 Tape drives, medium changers, enclosures etc. are not supported.
 117 .It file=path
 118 Specify a file or device to operate on.
 119 This requests that the file or device in question be accessed using the
 120 standard
 121 .Xr read 2
 122 and
 123 .Xr write 2
 124 system calls.
 125 The file interface does not support queueing multiple commands at a time.
 126 It does support probing disk sector size and capacity information, and tape
 127 blocksize and maximum transfer size information.
 128 The file interface supports standard files, disks, tape drives, special
 129 devices, pipes and standard input and output.
 130 If the file is specified as a
 131 .Dq - ,
 132 standard input or standard output are used.
 133 For tape devices, the specified blocksize will be the size that
 134 .Nm
 135 attempts to use to write to or read from the tape.
 136 When writing to a tape device, the blocksize is treated like a disk sector
 137 size.
 138 So, that means
 139 .Nm
 140 will not write anything smaller than the sector size.
 141 At the end of a transfer, if there isn't sufficient data from the reader
 142 to yield a full block,
 143 .Nm
 144 will add zeros on the end of the data from the reader to make up a full
 145 block.
 146 .It bs=N
 147 Specify the blocksize to use for transfers.
 148 .Nm
 149 will attempt to read or write using the requested blocksize.
 150 .Pp
 151 Note that the blocksize given only applies to either the input or the
 152 output path.
 153 To use the same blocksize for the input and output transfers, you must
 154 specify that blocksize with both the
 155 .Fl i
 156 and
 157 .Fl o
 158 arguments.
 159 .Pp
 160 The blocksize may be specified in bytes, or using any suffix (e.g. k, M, G)
 161 supported by
 162 .Xr expand_number 3 .
 163 .It offset=N
 164 Specify the starting offset for the input or output device or file.
 165 The offset may be specified in bytes, or by using any suffix (e.g. k, M, G)
 166 supported by
 167 .Xr expand_number 3 .
 168 .It depth=N
 169 Specify a desired queue depth for the input or output path.
 170 .Nm
 171 will attempt to keep the requested number of requests of the specified
 172 blocksize queued to the input or output device.
 173 Queue depths greater than 1 are only supported for the asynchronous
 174 .Xr pass 4
 175 output method.
 176 The queue depth is maintained on a best effort basis, and may not be
 177 possible to maintain for especially fast devices.
 178 For writes, maintaining the queue depth also depends on a sufficiently
 179 fast reading device.
 180 .It mcs=N
 181 Specify the minimum command size to use for
 182 .Xr pass 4
 183 devices.
 184 Some devices do not support 6 byte
 185 .Tn SCSI
 186 commands.
 187 The
 188 .Xr da 4
 189 device handles this restriction automatically, but the
 190 .Xr pass 4
 191 device allows the user to specify the
 192 .Tn SCSI
 193 command used.
 194 If a device does not accept 6 byte
 195 .Tn SCSI
 196 READ/WRITE commands (which is the default at lower LBAs), it will generally
 197 accept 10 byte
 198 .Tn SCSI
 199 commands instead.
 200 .It debug=N
 201 Specify the debug level for this device.
 202 There is currently only one debug level setting, so setting this to any
 203 non-zero value will turn on debugging.
 204 The debug facility may be expanded in the future.
 205 .El
 206 .It Fl C Ar count
 207 Specify the retry count for commands sent via the asynchronous
 208 .Xr pass 4
 209 interface.
 210 This does not apply to commands sent via the file interface.
 211 .It Fl E
 212 Enable kernel error recovery for the
 213 .Xr pass 4
 214 driver.
 215 If error recovery is not enabled, unit attention conditions and other
 216 transient failures may cause the transfer to fail.
 217 .It Fl m Ar size
 218 Specify the maximum amount of data to be transferred.
 219 This may be specified in bytes, or by using any suffix (e.g. K, M, G)
 220 supported by
 221 .Xr expand_number 3 .
 222 .It Fl t Ar timeout
 223 Specify the command timeout in seconds to use for commands sent via the
 224 .Xr pass 4
 225 driver.
 226 .It Fl v
 227 Enable verbose reporting of errors.
 228 This is recommended to aid in debugging any
 229 .Tn SCSI
 230 issues that come up.
 231 .It Fl h
 232 Display the
 233 .Nm
 234 usage message.
 235 .El
 236 .Pp
 237 If
 238 .Nm
 239 receives a SIGINFO signal, it will print the current input and output byte
 240 counts, elapsed runtime and average throughput.
 241 If
 242 .Nm
 243 receives a SIGINT signal, it will print the current input and output byte
 244 counts, elapsed runtime and average throughput and then exit.
 245 .Sh EXAMPLES
 246 .Dl camdd -i pass=da8,bs=512k,depth=4 -o pass=da3,bs=512k,depth=4
 247 .Pp
 248 Copy all data from da8 to da3 using a blocksize of 512k for both drives,
 249 and attempt to maintain a queue depth of 4 on both the input and output
 250 devices.
 251 The transfer will stop when the end of either device is reached.
 252 .Pp
 253 .Dl camdd -i file=/dev/zero,bs=1M -o pass=da5,bs=1M,depth=4 -m 100M
 254 .Pp
 255 Read 1MB blocks of zeros from /dev/zero, and write them to da5 with a
 256 desired queue depth of 4.
 257 Stop the transfer after 100MB has been written.
 258 .Pp
 259 .Dl camdd -i pass=da8,bs=1M,depth=3 -o file=disk.img
 260 .Pp
 261 Copy disk da8 using a 1MB blocksize and desired queue depth of 3 to the
 262 file disk.img.
 263 .Pp
 264 .Dl camdd -i file=/etc/rc -o file=-
 265 .Pp
 266 Read the file /etc/rc and write it to standard output.
 267 .Pp
 268 .Dl camdd -i pass=da10,bs=64k,depth=16 -o file=/dev/nsa0,bs=128k
 269 .Pp
 270 Copy 64K blocks from the disk da10 with a queue depth of 16, and write
 271 to the tape drive sa0 with a 128k blocksize.
 272 The copy will stop when either the end of the disk or tape is reached.
 273 .Sh SEE ALSO
 274 .Xr cam 3 ,
 275 .Xr cam 4 ,
 276 .Xr pass 4 ,
 277 .Xr camcontrol 8
 278 .Sh HISTORY
 279 .Nm
 280 first appeared in
 281 .Fx 10.2
 282 .Sh AUTHORS
 283 .An Kenneth Merry Aq Mt ken@FreeBSD.org