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 50The 51.Nm 52utility is a sequential data transfer utility that offers standard 53.Xr read 2 54and 55.Xr write 2 56operation in addition to a mode that uses the asynchronous 57.Xr pass 4 58API. 59The asynchronous 60.Xr pass 4 61API allows multiple requests to be queued to a device simultaneously. 62.Pp 63.Nm 64collects performance information and will display it when the transfer 65completes, when 66.Nm 67is terminated or when it receives a SIGINFO signal. 68.Pp 69The following options are available: 70.Bl -tag -width 12n 71.It Fl i | o Ar args 72Specify the input and output device or file. 73Both 74.Fl i 75and 76.Fl o 77must be specified. 78There are a number of parameters that can be specified. 79One of the first two (file or pass) MUST be specified to indicate which I/O 80method to use on the device in question. 81.Bl -tag -width 9n 82.It pass=dev 83Specify a 84.Xr pass 4 85device to operate on. 86This requests that 87.Nm 88access the device in question be accessed via the asynchronous 89.Xr pass 4 90interface. 91.Pp 92The device name can be a 93.Xr pass 4 94name and unit number, for instance 95.Dq pass0 , 96or a regular peripheral driver name and unit number, for instance 97.Dq da5 . 98It can also be the path of a 99.Xr pass 4 100or other disk device, like 101.Dq /dev/da5 . 102It may also be a bus:target:lun, for example: 103.Dq 0:5:0 . 104.Pp 105Only 106.Xr pass 4 107devices for 108.Tn SCSI 109disk-like devices are supported. 110.Tn ATA 111devices are not currently supported, but support could be added later. 112Specifically, 113.Tn SCSI 114Direct Access (type 0), WORM (type 4), CDROM (type 5), and RBC (Reduced 115Block Command, type 14) devices are supported. 116Tape drives, medium changers, enclosures etc. are not supported. 117.It file=path 118Specify a file or device to operate on. 119This requests that the file or device in question be accessed using the 120standard 121.Xr read 2 122and 123.Xr write 2 124system calls. 125The file interface does not support queueing multiple commands at a time. 126It does support probing disk sector size and capacity information, and tape 127blocksize and maximum transfer size information. 128The file interface supports standard files, disks, tape drives, special 129devices, pipes and standard input and output. 130If the file is specified as a 131.Dq - , 132standard input or standard output are used. 133For tape devices, the specified blocksize will be the size that 134.Nm 135attempts to use to write to or read from the tape. 136When writing to a tape device, the blocksize is treated like a disk sector 137size. 138So, that means 139.Nm 140will not write anything smaller than the sector size. 141At the end of a transfer, if there isn't sufficient data from the reader 142to yield a full block, 143.Nm 144will add zeros on the end of the data from the reader to make up a full 145block. 146.It bs=N 147Specify the blocksize to use for transfers. 148.Nm 149will attempt to read or write using the requested blocksize. 150.Pp 151Note that the blocksize given only applies to either the input or the 152output path. 153To use the same blocksize for the input and output transfers, you must 154specify that blocksize with both the 155.Fl i 156and 157.Fl o 158arguments. 159.Pp 160The blocksize may be specified in bytes, or using any suffix (e.g. k, M, G) 161supported by 162.Xr expand_number 3 . 163.It offset=N 164Specify the starting offset for the input or output device or file. 165The offset may be specified in bytes, or by using any suffix (e.g. k, M, G) 166supported by 167.Xr expand_number 3 . 168.It depth=N 169Specify a desired queue depth for the input or output path. 170.Nm 171will attempt to keep the requested number of requests of the specified 172blocksize queued to the input or output device. 173Queue depths greater than 1 are only supported for the asynchronous 174.Xr pass 4 175output method. 176The queue depth is maintained on a best effort basis, and may not be 177possible to maintain for especially fast devices. 178For writes, maintaining the queue depth also depends on a sufficiently 179fast reading device. 180.It mcs=N 181Specify the minimum command size to use for 182.Xr pass 4 183devices. 184Some devices do not support 6 byte 185.Tn SCSI 186commands. 187The 188.Xr da 4 189device handles this restriction automatically, but the 190.Xr pass 4 191device allows the user to specify the 192.Tn SCSI 193command used. 194If a device does not accept 6 byte 195.Tn SCSI 196READ/WRITE commands (which is the default at lower LBAs), it will generally 197accept 10 byte 198.Tn SCSI 199commands instead. 200.It debug=N 201Specify the debug level for this device. 202There is currently only one debug level setting, so setting this to any 203non-zero value will turn on debugging. 204The debug facility may be expanded in the future. 205.El 206.It Fl C Ar count 207Specify the retry count for commands sent via the asynchronous 208.Xr pass 4 209interface. 210This does not apply to commands sent via the file interface. 211.It Fl E 212Enable kernel error recovery for the 213.Xr pass 4 214driver. 215If error recovery is not enabled, unit attention conditions and other 216transient failures may cause the transfer to fail. 217.It Fl m Ar size 218Specify the maximum amount of data to be transferred. 219This may be specified in bytes, or by using any suffix (e.g. K, M, G) 220supported by 221.Xr expand_number 3 . 222.It Fl t Ar timeout 223Specify the command timeout in seconds to use for commands sent via the 224.Xr pass 4 225driver. 226.It Fl v 227Enable verbose reporting of errors. 228This is recommended to aid in debugging any 229.Tn SCSI 230issues that come up. 231.It Fl h 232Display the 233.Nm 234usage message. 235.El 236.Pp 237If 238.Nm 239receives a SIGINFO signal, it will print the current input and output byte 240counts, elapsed runtime and average throughput. 241If 242.Nm 243receives a SIGINT signal, it will print the current input and output byte 244counts, 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 248Copy all data from da8 to da3 using a blocksize of 512k for both drives, 249and attempt to maintain a queue depth of 4 on both the input and output 250devices. 251The 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 255Read 1MB blocks of zeros from /dev/zero, and write them to da5 with a 256desired queue depth of 4. 257Stop 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 261Copy disk da8 using a 1MB blocksize and desired queue depth of 3 to the 262file disk.img. 263.Pp 264.Dl camdd -i file=/etc/rc -o file=- 265.Pp 266Read 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 270Copy 64K blocks from the disk da10 with a queue depth of 16, and write 271to the tape drive sa0 with a 128k blocksize. 272The 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 280first appeared in 281.Fx 10.2 282.Sh AUTHORS 283.An Kenneth Merry Aq Mt ken@FreeBSD.org 284