cc984b0a5a
The comment before the .Dd macro was missing a quotation mark, so that the date of the man page was always today. MFC after: 3 days
284 lines
8.4 KiB
Groff
284 lines
8.4 KiB
Groff
.\"
|
|
.\" Copyright (c) 2015 Spectra Logic Corporation
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions, and the following disclaimer,
|
|
.\" without modification.
|
|
.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
|
|
.\" substantially similar to the "NO WARRANTY" disclaimer below
|
|
.\" ("Disclaimer") and any redistribution must be conditioned upon
|
|
.\" including a substantially similar Disclaimer requirement for further
|
|
.\" binary redistribution.
|
|
.\"
|
|
.\" NO WARRANTY
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
|
|
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
|
|
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
|
|
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
|
|
.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
|
|
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGES.
|
|
.\"
|
|
.\" Authors: Ken Merry (Spectra Logic Corporation)
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 11, 2015
|
|
.Dt CAMDD 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm camdd
|
|
.Nd CAM data transfer utility
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Aq Fl i|o Ar pass=pass_dev|file=filename,bs=blocksize,[...]
|
|
.Op Fl C Ar retry_count
|
|
.Op Fl E
|
|
.Op Fl m Ar max_io
|
|
.Op Fl t Ar timeout
|
|
.Op Fl v
|
|
.Op Fl h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is a sequential data transfer utility that offers standard
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
operation in addition to a mode that uses the asynchronous
|
|
.Xr pass 4
|
|
API.
|
|
The asynchronous
|
|
.Xr pass 4
|
|
API allows multiple requests to be queued to a device simultaneously.
|
|
.Pp
|
|
.Nm
|
|
collects performance information and will display it when the transfer
|
|
completes, when
|
|
.Nm
|
|
is terminated or when it receives a SIGINFO signal.
|
|
.Pp
|
|
The following options are available:
|
|
.Bl -tag -width 12n
|
|
.It Fl i | o Ar args
|
|
Specify the input and output device or file.
|
|
Both
|
|
.Fl i
|
|
and
|
|
.Fl o
|
|
must be specified.
|
|
There are a number of parameters that can be specified.
|
|
One of the first two (file or pass) MUST be specified to indicate which I/O
|
|
method to use on the device in question.
|
|
.Bl -tag -width 9n
|
|
.It pass=dev
|
|
Specify a
|
|
.Xr pass 4
|
|
device to operate on.
|
|
This requests that
|
|
.Nm
|
|
access the device in question be accessed via the asynchronous
|
|
.Xr pass 4
|
|
interface.
|
|
.Pp
|
|
The device name can be a
|
|
.Xr pass 4
|
|
name and unit number, for instance
|
|
.Dq pass0 ,
|
|
or a regular peripheral driver name and unit number, for instance
|
|
.Dq da5 .
|
|
It can also be the path of a
|
|
.Xr pass 4
|
|
or other disk device, like
|
|
.Dq /dev/da5 .
|
|
It may also be a bus:target:lun, for example:
|
|
.Dq 0:5:0 .
|
|
.Pp
|
|
Only
|
|
.Xr pass 4
|
|
devices for
|
|
.Tn SCSI
|
|
disk-like devices are supported.
|
|
.Tn ATA
|
|
devices are not currently supported, but support could be added later.
|
|
Specifically,
|
|
.Tn SCSI
|
|
Direct Access (type 0), WORM (type 4), CDROM (type 5), and RBC (Reduced
|
|
Block Command, type 14) devices are supported.
|
|
Tape drives, medium changers, enclosures etc. are not supported.
|
|
.It file=path
|
|
Specify a file or device to operate on.
|
|
This requests that the file or device in question be accessed using the
|
|
standard
|
|
.Xr read 2
|
|
and
|
|
.Xr write 2
|
|
system calls.
|
|
The file interface does not support queueing multiple commands at a time.
|
|
It does support probing disk sector size and capacity information, and tape
|
|
blocksize and maximum transfer size information.
|
|
The file interface supports standard files, disks, tape drives, special
|
|
devices, pipes and standard input and output.
|
|
If the file is specified as a
|
|
.Dq - ,
|
|
standard input or standard output are used.
|
|
For tape devices, the specified blocksize will be the size that
|
|
.Nm
|
|
attempts to use to write to or read from the tape.
|
|
When writing to a tape device, the blocksize is treated like a disk sector
|
|
size.
|
|
So, that means
|
|
.Nm
|
|
will not write anything smaller than the sector size.
|
|
At the end of a transfer, if there isn't sufficient data from the reader
|
|
to yield a full block,
|
|
.Nm
|
|
will add zeros on the end of the data from the reader to make up a full
|
|
block.
|
|
.It bs=N
|
|
Specify the blocksize to use for transfers.
|
|
.Nm
|
|
will attempt to read or write using the requested blocksize.
|
|
.Pp
|
|
Note that the blocksize given only applies to either the input or the
|
|
output path.
|
|
To use the same blocksize for the input and output transfers, you must
|
|
specify that blocksize with both the
|
|
.Fl i
|
|
and
|
|
.Fl o
|
|
arguments.
|
|
.Pp
|
|
The blocksize may be specified in bytes, or using any suffix (e.g. k, M, G)
|
|
supported by
|
|
.Xr expand_number 3 .
|
|
.It offset=N
|
|
Specify the starting offset for the input or output device or file.
|
|
The offset may be specified in bytes, or by using any suffix (e.g. k, M, G)
|
|
supported by
|
|
.Xr expand_number 3 .
|
|
.It depth=N
|
|
Specify a desired queue depth for the input or output path.
|
|
.Nm
|
|
will attempt to keep the requested number of requests of the specified
|
|
blocksize queued to the input or output device.
|
|
Queue depths greater than 1 are only supported for the asynchronous
|
|
.Xr pass 4
|
|
output method.
|
|
The queue depth is maintained on a best effort basis, and may not be
|
|
possible to maintain for especially fast devices.
|
|
For writes, maintaining the queue depth also depends on a sufficiently
|
|
fast reading device.
|
|
.It mcs=N
|
|
Specify the minimum command size to use for
|
|
.Xr pass 4
|
|
devices.
|
|
Some devices do not support 6 byte
|
|
.Tn SCSI
|
|
commands.
|
|
The
|
|
.Xr da 4
|
|
device handles this restriction automatically, but the
|
|
.Xr pass 4
|
|
device allows the user to specify the
|
|
.Tn SCSI
|
|
command used.
|
|
If a device does not accept 6 byte
|
|
.Tn SCSI
|
|
READ/WRITE commands (which is the default at lower LBAs), it will generally
|
|
accept 10 byte
|
|
.Tn SCSI
|
|
commands instead.
|
|
.It debug=N
|
|
Specify the debug level for this device.
|
|
There is currently only one debug level setting, so setting this to any
|
|
non-zero value will turn on debugging.
|
|
The debug facility may be expanded in the future.
|
|
.El
|
|
.It Fl C Ar count
|
|
Specify the retry count for commands sent via the asynchronous
|
|
.Xr pass 4
|
|
interface.
|
|
This does not apply to commands sent via the file interface.
|
|
.It Fl E
|
|
Enable kernel error recovery for the
|
|
.Xr pass 4
|
|
driver.
|
|
If error recovery is not enabled, unit attention conditions and other
|
|
transient failures may cause the transfer to fail.
|
|
.It Fl m Ar size
|
|
Specify the maximum amount of data to be transferred.
|
|
This may be specified in bytes, or by using any suffix (e.g. K, M, G)
|
|
supported by
|
|
.Xr expand_number 3 .
|
|
.It Fl t Ar timeout
|
|
Specify the command timeout in seconds to use for commands sent via the
|
|
.Xr pass 4
|
|
driver.
|
|
.It Fl v
|
|
Enable verbose reporting of errors.
|
|
This is recommended to aid in debugging any
|
|
.Tn SCSI
|
|
issues that come up.
|
|
.It Fl h
|
|
Display the
|
|
.Nm
|
|
usage message.
|
|
.El
|
|
.Pp
|
|
If
|
|
.Nm
|
|
receives a SIGINFO signal, it will print the current input and output byte
|
|
counts, elapsed runtime and average throughput.
|
|
If
|
|
.Nm
|
|
receives a SIGINT signal, it will print the current input and output byte
|
|
counts, elapsed runtime and average throughput and then exit.
|
|
.Sh EXAMPLES
|
|
.Dl camdd -i pass=da8,bs=512k,depth=4 -o pass=da3,bs=512k,depth=4
|
|
.Pp
|
|
Copy all data from da8 to da3 using a blocksize of 512k for both drives,
|
|
and attempt to maintain a queue depth of 4 on both the input and output
|
|
devices.
|
|
The transfer will stop when the end of either device is reached.
|
|
.Pp
|
|
.Dl camdd -i file=/dev/zero,bs=1M -o pass=da5,bs=1M,depth=4 -m 100M
|
|
.Pp
|
|
Read 1MB blocks of zeros from /dev/zero, and write them to da5 with a
|
|
desired queue depth of 4.
|
|
Stop the transfer after 100MB has been written.
|
|
.Pp
|
|
.Dl camdd -i pass=da8,bs=1M,depth=3 -o file=disk.img
|
|
.Pp
|
|
Copy disk da8 using a 1MB blocksize and desired queue depth of 3 to the
|
|
file disk.img.
|
|
.Pp
|
|
.Dl camdd -i file=/etc/rc -o file=-
|
|
.Pp
|
|
Read the file /etc/rc and write it to standard output.
|
|
.Pp
|
|
.Dl camdd -i pass=da10,bs=64k,depth=16 -o file=/dev/nsa0,bs=128k
|
|
.Pp
|
|
Copy 64K blocks from the disk da10 with a queue depth of 16, and write
|
|
to the tape drive sa0 with a 128k blocksize.
|
|
The copy will stop when either the end of the disk or tape is reached.
|
|
.Sh SEE ALSO
|
|
.Xr cam 3 ,
|
|
.Xr cam 4 ,
|
|
.Xr pass 4 ,
|
|
.Xr camcontrol 8
|
|
.Sh HISTORY
|
|
.Nm
|
|
first appeared in
|
|
.Fx 10.2
|
|
.Sh AUTHORS
|
|
.An Kenneth Merry Aq Mt ken@FreeBSD.org
|