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