d0f081c521
camdd(8) utility.
CCBs may be queued to the driver via the new CAMIOQUEUE ioctl, and
completed CCBs may be retrieved via the CAMIOGET ioctl. User
processes can use poll(2) or kevent(2) to get notification when
I/O has completed.
While the existing CAMIOCOMMAND blocking ioctl interface only
supports user virtual data pointers in a CCB (generally only
one per CCB), the new CAMIOQUEUE ioctl supports user virtual and
physical address pointers, as well as user virtual and physical
scatter/gather lists. This allows user applications to have more
flexibility in their data handling operations.
Kernel memory for data transferred via the queued interface is
allocated from the zone allocator in MAXPHYS sized chunks, and user
data is copied in and out. This is likely faster than the
vmapbuf()/vunmapbuf() method used by the CAMIOCOMMAND ioctl in
configurations with many processors (there are more TLB shootdowns
caused by the mapping/unmapping operation) but may not be as fast
as running with unmapped I/O.
The new memory handling model for user requests also allows
applications to send CCBs with request sizes that are larger than
MAXPHYS. The pass(4) driver now limits queued requests to the I/O
size listed by the SIM driver in the maxio field in the Path
Inquiry (XPT_PATH_INQ) CCB.
There are some things things would be good to add:
1. Come up with a way to do unmapped I/O on multiple buffers.
Currently the unmapped I/O interface operates on a struct bio,
which includes only one address and length. It would be nice
to be able to send an unmapped scatter/gather list down to
busdma. This would allow eliminating the copy we currently do
for data.
2. Add an ioctl to list currently outstanding CCBs in the various
queues.
3. Add an ioctl to cancel a request, or use the XPT_ABORT CCB to do
that.
4. Test physical address support. Virtual pointers and scatter
gather lists have been tested, but I have not yet tested
physical addresses or scatter/gather lists.
5. Investigate multiple queue support. At the moment there is one
queue of commands per pass(4) device. If multiple processes
open the device, they will submit I/O into the same queue and
get events for the same completions. This is probably the right
model for most applications, but it is something that could be
changed later on.
Also, add a new utility, camdd(8) that uses the asynchronous pass(4)
driver interface.
This utility is intended to be a basic data transfer/copy utility,
a simple benchmark utility, and an example of how to use the
asynchronous pass(4) interface.
It can copy data to and from pass(4) devices using any target queue
depth, starting offset and blocksize for the input and ouptut devices.
It currently only supports SCSI devices, but could be easily extended
to support ATA devices.
It can also copy data to and from regular files, block devices, tape
devices, pipes, stdin, and stdout. It does not support queueing
multiple commands to any of those targets, since it uses the standard
read(2)/write(2)/writev(2)/readv(2) system calls.
The I/O is done by two threads, one for the reader and one for the
writer. The reader thread sends completed read requests to the
writer thread in strictly sequential order, even if they complete
out of order. That could be modified later on for random I/O patterns
or slightly out of order I/O.
camdd(8) uses kqueue(2)/kevent(2) to get I/O completion events from
the pass(4) driver and also to send request notifications internally.
For pass(4) devcies, camdd(8) uses a single buffer (CAM_DATA_VADDR)
per CAM CCB on the reading side, and a scatter/gather list
(CAM_DATA_SG) on the writing side. In addition to testing both
interfaces, this makes any potential reblocking of I/O easier. No
data is copied between the reader and the writer, but rather the
reader's buffers are split into multiple I/O requests or combined
into a single I/O request depending on the input and output blocksize.
For the file I/O path, camdd(8) also uses a single buffer (read(2),
write(2), pread(2) or pwrite(2)) on reads, and a scatter/gather list
(readv(2), writev(2), preadv(2), pwritev(2)) on writes.
Things that would be nice to do for camdd(8) eventually:
1. Add support for I/O pattern generation. Patterns like all
zeros, all ones, LBA-based patterns, random patterns, etc. Right
Now you can always use /dev/zero, /dev/random, etc.
2. Add support for a "sink" mode, so we do only reads with no
writes. Right now, you can use /dev/null.
3. Add support for automatic queue depth probing, so that we can
figure out the right queue depth on the input and output side
for maximum throughput. At the moment it defaults to 6.
4. Add support for SATA device passthrough I/O.
5. Add support for random LBAs and/or lengths on the input and
output sides.
6. Track average per-I/O latency and busy time. The busy time
and latency could also feed in to the automatic queue depth
determination.
sys/cam/scsi/scsi_pass.h:
Define two new ioctls, CAMIOQUEUE and CAMIOGET, that queue
and fetch asynchronous CAM CCBs respectively.
Although these ioctls do not have a declared argument, they
both take a union ccb pointer. If we declare a size here,
the ioctl code in sys/kern/sys_generic.c will malloc and free
a buffer for either the CCB or the CCB pointer (depending on
how it is declared). Since we have to keep a copy of the
CCB (which is fairly large) anyway, having the ioctl malloc
and free a CCB for each call is wasteful.
sys/cam/scsi/scsi_pass.c:
Add asynchronous CCB support.
Add two new ioctls, CAMIOQUEUE and CAMIOGET.
CAMIOQUEUE adds a CCB to the incoming queue. The CCB is
executed immediately (and moved to the active queue) if it
is an immediate CCB, but otherwise it will be executed
in passstart() when a CCB is available from the transport layer.
When CCBs are completed (because they are immediate or
passdone() if they are queued), they are put on the done
queue.
If we get the final close on the device before all pending
I/O is complete, all active I/O is moved to the abandoned
queue and we increment the peripheral reference count so
that the peripheral driver instance doesn't go away before
all pending I/O is done.
The new passcreatezone() function is called on the first
call to the CAMIOQUEUE ioctl on a given device to allocate
the UMA zones for I/O requests and S/G list buffers. This
may be good to move off to a taskqueue at some point.
The new passmemsetup() function allocates memory and
scatter/gather lists to hold the user's data, and copies
in any data that needs to be written. For virtual pointers
(CAM_DATA_VADDR), the kernel buffer is malloced from the
new pass(4) driver malloc bucket. For virtual
scatter/gather lists (CAM_DATA_SG), buffers are allocated
from a new per-pass(9) UMA zone in MAXPHYS-sized chunks.
Physical pointers are passed in unchanged. We have support
for up to 16 scatter/gather segments (for the user and
kernel S/G lists) in the default struct pass_io_req, so
requests with longer S/G lists require an extra kernel malloc.
The new passcopysglist() function copies a user scatter/gather
list to a kernel scatter/gather list. The number of elements
in each list may be different, but (obviously) the amount of data
stored has to be identical.
The new passmemdone() function copies data out for the
CAM_DATA_VADDR and CAM_DATA_SG cases.
The new passiocleanup() function restores data pointers in
user CCBs and frees memory.
Add new functions to support kqueue(2)/kevent(2):
passreadfilt() tells kevent whether or not the done
queue is empty.
passkqfilter() adds a knote to our list.
passreadfiltdetach() removes a knote from our list.
Add a new function, passpoll(), for poll(2)/select(2)
to use.
Add devstat(9) support for the queued CCB path.
sys/cam/ata/ata_da.c:
Add support for the BIO_VLIST bio type.
sys/cam/cam_ccb.h:
Add a new enumeration for the xflags field in the CCB header.
(This doesn't change the CCB header, just adds an enumeration to
use.)
sys/cam/cam_xpt.c:
Add a new function, xpt_setup_ccb_flags(), that allows specifying
CCB flags.
sys/cam/cam_xpt.h:
Add a prototype for xpt_setup_ccb_flags().
sys/cam/scsi/scsi_da.c:
Add support for BIO_VLIST.
sys/dev/md/md.c:
Add BIO_VLIST support to md(4).
sys/geom/geom_disk.c:
Add BIO_VLIST support to the GEOM disk class. Re-factor the I/O size
limiting code in g_disk_start() a bit.
sys/kern/subr_bus_dma.c:
Change _bus_dmamap_load_vlist() to take a starting offset and
length.
Add a new function, _bus_dmamap_load_pages(), that will load a list
of physical pages starting at an offset.
Update _bus_dmamap_load_bio() to allow loading BIO_VLIST bios.
Allow unmapped I/O to start at an offset.
sys/kern/subr_uio.c:
Add two new functions, physcopyin_vlist() and physcopyout_vlist().
sys/pc98/include/bus.h:
Guard kernel-only parts of the pc98 machine/bus.h header with
#ifdef _KERNEL.
This allows userland programs to include <machine/bus.h> to get the
definition of bus_addr_t and bus_size_t.
sys/sys/bio.h:
Add a new bio flag, BIO_VLIST.
sys/sys/uio.h:
Add prototypes for physcopyin_vlist() and physcopyout_vlist().
share/man/man4/pass.4:
Document the CAMIOQUEUE and CAMIOGET ioctls.
usr.sbin/Makefile:
Add camdd.
usr.sbin/camdd/Makefile:
Add a makefile for camdd(8).
usr.sbin/camdd/camdd.8:
Man page for camdd(8).
usr.sbin/camdd/camdd.c:
The new camdd(8) utility.
Sponsored by: Spectra Logic
MFC after: 1 week
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
|