| blob | af556bb7bd2e712748a9e94d655501c9dbe822c8 |
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