130f4520cb
CTL is a disk and processor device emulation subsystem originally written
for Copan Systems under Linux starting in 2003. It has been shipping in
Copan (now SGI) products since 2005.
It was ported to FreeBSD in 2008, and thanks to an agreement between SGI
(who acquired Copan's assets in 2010) and Spectra Logic in 2010, CTL is
available under a BSD-style license. The intent behind the agreement was
that Spectra would work to get CTL into the FreeBSD tree.
Some CTL features:
- Disk and processor device emulation.
- Tagged queueing
- SCSI task attribute support (ordered, head of queue, simple tags)
- SCSI implicit command ordering support. (e.g. if a read follows a mode
select, the read will be blocked until the mode select completes.)
- Full task management support (abort, LUN reset, target reset, etc.)
- Support for multiple ports
- Support for multiple simultaneous initiators
- Support for multiple simultaneous backing stores
- Persistent reservation support
- Mode sense/select support
- Error injection support
- High Availability support (1)
- All I/O handled in-kernel, no userland context switch overhead.
(1) HA Support is just an API stub, and needs much more to be fully
functional.
ctl.c: The core of CTL. Command handlers and processing,
character driver, and HA support are here.
ctl.h: Basic function declarations and data structures.
ctl_backend.c,
ctl_backend.h: The basic CTL backend API.
ctl_backend_block.c,
ctl_backend_block.h: The block and file backend. This allows for using
a disk or a file as the backing store for a LUN.
Multiple threads are started to do I/O to the
backing device, primarily because the VFS API
requires that to get any concurrency.
ctl_backend_ramdisk.c: A "fake" ramdisk backend. It only allocates a
small amount of memory to act as a source and sink
for reads and writes from an initiator. Therefore
it cannot be used for any real data, but it can be
used to test for throughput. It can also be used
to test initiators' support for extremely large LUNs.
ctl_cmd_table.c: This is a table with all 256 possible SCSI opcodes,
and command handler functions defined for supported
opcodes.
ctl_debug.h: Debugging support.
ctl_error.c,
ctl_error.h: CTL-specific wrappers around the CAM sense building
functions.
ctl_frontend.c,
ctl_frontend.h: These files define the basic CTL frontend port API.
ctl_frontend_cam_sim.c: This is a CTL frontend port that is also a CAM SIM.
This frontend allows for using CTL without any
target-capable hardware. So any LUNs you create in
CTL are visible in CAM via this port.
ctl_frontend_internal.c,
ctl_frontend_internal.h:
This is a frontend port written for Copan to do
some system-specific tasks that required sending
commands into CTL from inside the kernel. This
isn't entirely relevant to FreeBSD in general,
but can perhaps be repurposed.
ctl_ha.h: This is a stubbed-out High Availability API. Much
more is needed for full HA support. See the
comments in the header and the description of what
is needed in the README.ctl.txt file for more
details.
ctl_io.h: This defines most of the core CTL I/O structures.
union ctl_io is conceptually very similar to CAM's
union ccb.
ctl_ioctl.h: This defines all ioctls available through the CTL
character device, and the data structures needed
for those ioctls.
ctl_mem_pool.c,
ctl_mem_pool.h: Generic memory pool implementation used by the
internal frontend.
ctl_private.h: Private data structres (e.g. CTL softc) and
function prototypes. This also includes the SCSI
vendor and product names used by CTL.
ctl_scsi_all.c,
ctl_scsi_all.h: CTL wrappers around CAM sense printing functions.
ctl_ser_table.c: Command serialization table. This defines what
happens when one type of command is followed by
another type of command.
ctl_util.c,
ctl_util.h: CTL utility functions, primarily designed to be
used from userland. See ctladm for the primary
consumer of these functions. These include CDB
building functions.
scsi_ctl.c: CAM target peripheral driver and CTL frontend port.
This is the path into CTL for commands from
target-capable hardware/SIMs.
README.ctl.txt: CTL code features, roadmap, to-do list.
usr.sbin/Makefile: Add ctladm.
ctladm/Makefile,
ctladm/ctladm.8,
ctladm/ctladm.c,
ctladm/ctladm.h,
ctladm/util.c: ctladm(8) is the CTL management utility.
It fills a role similar to camcontrol(8).
It allow configuring LUNs, issuing commands,
injecting errors and various other control
functions.
usr.bin/Makefile: Add ctlstat.
ctlstat/Makefile
ctlstat/ctlstat.8,
ctlstat/ctlstat.c: ctlstat(8) fills a role similar to iostat(8).
It reports I/O statistics for CTL.
sys/conf/files: Add CTL files.
sys/conf/NOTES: Add device ctl.
sys/cam/scsi_all.h: To conform to more recent specs, the inquiry CDB
length field is now 2 bytes long.
Add several mode page definitions for CTL.
sys/cam/scsi_all.c: Handle the new 2 byte inquiry length.
sys/dev/ciss/ciss.c,
sys/dev/ata/atapi-cam.c,
sys/cam/scsi/scsi_targ_bh.c,
scsi_target/scsi_cmds.c,
mlxcontrol/interface.c: Update for 2 byte inquiry length field.
scsi_da.h: Add versions of the format and rigid disk pages
that are in a more reasonable format for CTL.
amd64/conf/GENERIC,
i386/conf/GENERIC,
ia64/conf/GENERIC,
sparc64/conf/GENERIC: Add device ctl.
i386/conf/PAE: The CTL frontend SIM at least does not compile
cleanly on PAE.
Sponsored by: Copan Systems, SGI and Spectra Logic
MFC after: 1 month
964 lines
27 KiB
Groff
964 lines
27 KiB
Groff
.\"
|
|
.\" Copyright (c) 2003 Silicon Graphics International Corp.
|
|
.\" 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.
|
|
.\"
|
|
.\" ctladm utility man page.
|
|
.\"
|
|
.\" Author: Ken Merry <ken@FreeBSD.org>
|
|
.\"
|
|
.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd July 8, 2011
|
|
.Dt CTLADM 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ctladm
|
|
.Nd CAM Target Layer control utility
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Aq Ar command
|
|
.Op target:lun
|
|
.Op generic args
|
|
.Op command args
|
|
.Nm
|
|
.Ic tur
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Nm
|
|
.Ic inquiry
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Nm
|
|
.Ic reqsense
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Nm
|
|
.Ic reportluns
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Nm
|
|
.Ic read
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Aq Fl l Ar lba
|
|
.Aq Fl d Ar datalen
|
|
.Aq Fl f Ar file|-
|
|
.Aq Fl b Ar blocksize_bytes
|
|
.Op Fl c Ar cdbsize
|
|
.Op Fl N
|
|
.Nm
|
|
.Ic write
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Aq Fl l Ar lba
|
|
.Aq Fl d Ar datalen
|
|
.Aq Fl f Ar file|-
|
|
.Aq Fl b Ar blocksize_bytes
|
|
.Op Fl c Ar cdbsize
|
|
.Op Fl N
|
|
.Nm
|
|
.Ic bbrread
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Aq Fl -l Ar lba
|
|
.Aq Fl -d Ar datalen
|
|
.Nm
|
|
.Ic readcap
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Op Fl c Ar cdbsize
|
|
.Nm
|
|
.Ic modesense
|
|
.Aq target:lun
|
|
.Aq Fl m Ar page | Fl l
|
|
.Op Fl P Ar pc
|
|
.Op Fl d
|
|
.Op Fl S Ar subpage
|
|
.Op Fl c Ar size
|
|
.Nm
|
|
.Ic start
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Op Fl i
|
|
.Op Fl o
|
|
.Nm
|
|
.Ic stop
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Op Fl i
|
|
.Op Fl o
|
|
.Nm
|
|
.Ic synccache
|
|
.Aq target:lun
|
|
.Op general options
|
|
.Op Fl l Ar lba
|
|
.Op Fl b Ar blockcount
|
|
.Op Fl r
|
|
.Op Fl i
|
|
.Op Fl c Ar cdbsize
|
|
.Nm
|
|
.Ic shutdown
|
|
.Op general options
|
|
.Nm
|
|
.Ic startup
|
|
.Op general options
|
|
.Nm
|
|
.Ic hardstop
|
|
.Nm
|
|
.Ic hardstart
|
|
.Nm
|
|
.Ic lunlist
|
|
.Nm
|
|
.Ic delay
|
|
.Aq target:lun
|
|
.Aq Fl l Ar datamove|done
|
|
.Aq Fl t Ar secs
|
|
.Op Fl T Ar oneshot|cont
|
|
.Nm
|
|
.Ic realsync Aq on|off|query
|
|
.Nm
|
|
.Ic setsync interval
|
|
.Aq target:lun
|
|
.Aq Fl i Ar interval
|
|
.Nm
|
|
.Ic getsync
|
|
.Aq target:lun
|
|
.Nm
|
|
.Ic inject
|
|
.Aq Fl i Ar action
|
|
.Aq Fl p Ar pattern
|
|
.Op Fl r Ar lba,len
|
|
.Op Fl s Ar len fmt Op Ar args
|
|
.Op Fl c
|
|
.Op Fl d Ar delete_id
|
|
.Nm
|
|
.Ic create
|
|
.Aq Fl b Ar backend
|
|
.Op Fl B Ar blocksize
|
|
.Op Fl d Ar device_id
|
|
.Op Fl l Ar lun_id
|
|
.Op Fl o Ar name=value
|
|
.Op Fl s Ar size_bytes
|
|
.Op Fl S Ar serial_num
|
|
.Op Fl t Ar device_type
|
|
.Nm
|
|
.Ic remove
|
|
.Aq Fl b Ar backend
|
|
.Aq Fl l Ar lun_id
|
|
.Op Fl o Ar name=value
|
|
.Nm
|
|
.Ic devlist
|
|
.Op Fl b Ar backend
|
|
.Op Fl v
|
|
.Op Fl x
|
|
.Nm
|
|
.Ic port
|
|
.Op Fl l
|
|
.Op Fl o Ar on|off
|
|
.Op Fl w Ar wwpn
|
|
.Op Fl W Ar wwnn
|
|
.Op Fl p Ar targ_port
|
|
.Op Fl t Ar fe_type
|
|
.Op Fl q
|
|
.Op Fl x
|
|
.Nm
|
|
.Ic dumpooa
|
|
.Nm
|
|
.Ic dumpstructs
|
|
.Nm
|
|
.Ic help
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is designed to provide a way to access and control the CAM Target
|
|
Layer (CTL).
|
|
It provides a way to send
|
|
.Tn SCSI
|
|
commands to the CTL layer, and also provides
|
|
some meta-commands that utilize
|
|
.Tn SCSI
|
|
commands.
|
|
(For instance, the
|
|
.Ic lunlist
|
|
command is implemented using the
|
|
.Tn SCSI
|
|
REPORT LUNS and INQUIRY commands.)
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility has a number of primary functions, many of which require a device
|
|
identifier.
|
|
The device identifier takes the following form:
|
|
.Bl -tag -width 14n
|
|
.It target:lun
|
|
Specify the target (almost always 0) and LUN number to operate on.
|
|
.El
|
|
Many of the primary functions of the
|
|
.Nm
|
|
utility take the following optional arguments:
|
|
.Pp
|
|
.Bl -tag -width 10n
|
|
.It Fl C Ar retries
|
|
Specify the number of times to retry a command in the event of failure.
|
|
.It Fl D Ar device
|
|
Specify the device to open. This allows opening a device other than the
|
|
default device,
|
|
.Pa /dev/cam/ctl ,
|
|
to be opened for sending commands.
|
|
.It Fl I Ar id
|
|
Specify the initiator number to use.
|
|
By default,
|
|
.Nm
|
|
will use 7 as the initiator number.
|
|
.El
|
|
.Pp
|
|
Primary commands:
|
|
.Bl -tag -width 11n
|
|
.It Ic tur
|
|
Send the
|
|
.Tn SCSI
|
|
TEST UNIT READY command to the device and report whether or not it is
|
|
ready.
|
|
.It Ic inquiry
|
|
Send the
|
|
.Tn SCSI
|
|
INQUIRY command to the device and display some of the returned inquiry
|
|
data.
|
|
.It Ic reqsense
|
|
Send the
|
|
.Tn SCSI
|
|
REQUEST SENSE command to the device and display the returned sense
|
|
information.
|
|
.It Ic reportluns
|
|
Send the
|
|
.Tn SCSI
|
|
REPORT LUNS command to the device and display supported LUNs.
|
|
.It Ic read
|
|
Send a
|
|
.Tn SCSI
|
|
READ command to the device, and write the requested data to a file or
|
|
stdout.
|
|
.Bl -tag -width 12n
|
|
.It Fl l Ar lba
|
|
Specify the starting Logical Block Address for the READ. This can be
|
|
specified in decimal, octal (starting with 0), hexadecimal (starting with
|
|
0x) or any other base supported by
|
|
.Xr strtoull 3 .
|
|
.It Fl d Ar datalen
|
|
Specify the length, in 512 byte blocks, of the READ request.
|
|
.It Fl f Ar file
|
|
Specify the destination for the data read by the READ command. Either a
|
|
filename or
|
|
.Sq -
|
|
for stdout may be specified.
|
|
.It Fl c Ar cdbsize
|
|
Specify the minimum
|
|
.Tn SCSI
|
|
CDB (Command Data Block) size to be used for the READ request. Allowable
|
|
values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
|
|
requested, a larger CDB size may be used to satisfy the request. (e.g.,
|
|
for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
|
|
.It Fl b Ar blocksize
|
|
Specify the blocksize of the underlying
|
|
.Tn SCSI
|
|
device, so the transfer length
|
|
can be calculated accurately. The blocksize can be obtained via the
|
|
.Tn SCSI
|
|
READ CAPACITY command.
|
|
.It Fl N
|
|
Do not copy data to
|
|
.Nm
|
|
from the kernel when doing a read, just execute the command without copying
|
|
data.
|
|
This is to be used for performance testing.
|
|
.El
|
|
.It Ic write
|
|
Read data from a file or stdin, and write the data to the device using the
|
|
.Tn SCSI
|
|
WRITE command.
|
|
.Bl -tag -width 12n
|
|
.It Fl l Ar lba
|
|
Specify the starting Logical Block Address for the WRITE. This can be
|
|
specified in decimal, octal (starting with 0), hexadecimal (starting with
|
|
0x) or any other base supported by
|
|
.Xr strtoull 3 .
|
|
.It Fl d Ar atalen
|
|
Specify the length, in 512 byte blocks, of the WRITE request.
|
|
.It Fl f Ar file
|
|
Specify the source for the data to be written by the WRITE command. Either a
|
|
filename or
|
|
.Sq -
|
|
for stdin may be specified.
|
|
.It Fl c Ar cdbsize
|
|
Specify the minimum
|
|
.Tn SCSI
|
|
CDB (Command Data Block) size to be used for the READ request. Allowable
|
|
values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
|
|
requested, a larger CDB size may be used to satisfy the request. (e.g.,
|
|
for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
|
|
.It Fl b Ar blocksize
|
|
Specify the blocksize of the underlying
|
|
.Tn SCSI
|
|
device, so the transfer length
|
|
can be calculated accurately. The blocksize can be obtained via the
|
|
.Tn SCSI
|
|
READ CAPACITY command.
|
|
.It Fl N
|
|
Do not copy data to
|
|
.Nm
|
|
to the kernel when doing a write, just execute the command without copying
|
|
data.
|
|
This is to be used for performance testing.
|
|
.El
|
|
.It Ic bbrread
|
|
Issue a SCSI READ command to the logical device to potentially force a bad
|
|
block on a disk in the RAID set to be reconstructed from the other disks in
|
|
the array. This command should only be used on an array that is in the
|
|
normal state. If used on a critical array, it could cause the array to go
|
|
offline if the bad block to be remapped is on one of the disks that is
|
|
still active in the array.
|
|
.Pp
|
|
The data for this particular command will be discarded, and not returned to
|
|
the user.
|
|
.Pp
|
|
In order to determine which LUN to read from, the user should first
|
|
determine which LUN the disk with a bad block belongs to. Then he should
|
|
map the bad disk block back to the logical block address for the array in
|
|
order to determine which LBA to pass in to the
|
|
.Ic bbrread
|
|
command.
|
|
.Pp
|
|
This command is primarily intended for testing. In practice, bad block
|
|
remapping will generally be triggered by the in-kernel Disk Aerobics and
|
|
Disk Scrubbing code.
|
|
.Bl -tag -width 10n
|
|
.It Fl l Ar lba
|
|
Specify the starting Logical Block Address.
|
|
.It Fl d Ar datalen
|
|
Specify the amount of data in bytes to read from the LUN. This must be a
|
|
multiple of the LUN blocksize.
|
|
.El
|
|
.It Ic readcap
|
|
Send the
|
|
.Tn SCSI
|
|
READ CAPACITY command to the device and display the device size and device
|
|
block size. By default, READ CAPACITY(10) is
|
|
used. If the device returns a maximum LBA of 0xffffffff, however,
|
|
.Nm
|
|
will automatically issue a READ CAPACITY(16), which is implemented as a
|
|
service action of the SERVICE ACTION IN(16) opcode. The user can specify
|
|
the minimum CDB size with the
|
|
.Fl c
|
|
argument. Valid values for the
|
|
.Fl c
|
|
option are 10 and 16. If a 10 byte CDB is specified, the request will be
|
|
automatically reissued with a 16 byte CDB if the maximum LBA returned is
|
|
0xffffffff.
|
|
.It Ic modesense
|
|
Send a
|
|
.Tn SCSI
|
|
MODE SENSE command to the device, and display the requested mode page(s) or
|
|
page list.
|
|
.Bl -tag -width 10n
|
|
.It Fl m Ar page
|
|
Specify the mode page to display. This option and the
|
|
.Fl l
|
|
option are mutually exclusive. One of the two must be specified, though.
|
|
Mode page numbers may be specified in decimal or hexadecimal.
|
|
.It Fl l
|
|
Request that the list of mode pages supported by the device be returned.
|
|
This option and the
|
|
.Fl m
|
|
option are mutually exclusive. One of the two must be specified, though.
|
|
.It Fl P Ar pc
|
|
Specify the mode page page control value. Possible values are:
|
|
.Bl -tag -width 2n -compact
|
|
.It 0
|
|
Current values.
|
|
.It 1
|
|
Changeable value bitmask.
|
|
.It 2
|
|
Default values.
|
|
.It 3
|
|
Saved values.
|
|
.El
|
|
.It Fl d
|
|
Disable block descriptors when sending the mode sense request.
|
|
.It Fl S Ar subpage
|
|
Specify the subpage used with the mode sense request.
|
|
.It Fl c Ar cdbsize
|
|
Specify the CDB size used for the mode sense request. Supported values are
|
|
6 and 10.
|
|
.El
|
|
.It Ic start
|
|
Send the
|
|
.Tn SCSI
|
|
START STOP UNIT command to the specified LUN with the start
|
|
bit set.
|
|
.Bl -tag -width 4n
|
|
.It Fl i
|
|
Set the immediate bit in the CDB. Note that CTL does not support the
|
|
immediate bit, so this is primarily useful for making sure that CTL returns
|
|
the proper error.
|
|
.It Fl o
|
|
Set the Copan proprietary on/offline bit in the CDB. When this flag is
|
|
used, the LUN will be marked online again (see the description of the
|
|
.Ic shutdown
|
|
and
|
|
.Ic startup
|
|
commands). When this flag is used with a
|
|
start command, the LUN will NOT be spun up. You need to use a start
|
|
command without the
|
|
.Fl o
|
|
flag to spin up the disks in the LUN.
|
|
.El
|
|
.It Ic stop
|
|
Send the
|
|
.Tn SCSI
|
|
START STOP UNIT command to the specified LUN with the start
|
|
bit cleared. We use an ordered tag to stop the LUN, so we can guarantee
|
|
that all pending I/O executes before it is stopped. (CTL guarantees this
|
|
anyway, but
|
|
.Nm
|
|
sends an ordered tag for completeness.)
|
|
.Bl -tag -width 4n
|
|
.It Fl i
|
|
Set the immediate bit in the CDB. Note that CTL does not support the
|
|
immediate bit, so this is primarily useful for making sure that CTL returns
|
|
the proper error.
|
|
.It Fl o
|
|
Set the Copan proprietary on/offline bit in the CDB. When this flag is
|
|
used, the LUN will be spun down and taken offline ("Logical unit not ready,
|
|
manual intervention required"). See the description of the
|
|
.Ic shutdown
|
|
and
|
|
.Ic startup
|
|
options.
|
|
.El
|
|
.It Ic synccache
|
|
Send the
|
|
.Tn SCSI
|
|
SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE
|
|
CACHE(10) is used. If the specified starting LBA is greater than
|
|
0xffffffff or the length is greater than 0xffff, though,
|
|
SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used
|
|
if the user specifies a 16 byte CDB with the
|
|
.Fl c
|
|
argument.
|
|
.Bl -tag -width 14n
|
|
.It Fl l Ar lba
|
|
Specify the starting LBA of the cache region to synchronize. This option is a
|
|
no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
|
|
cache for the entire LUN.
|
|
.It Fl b Ar blockcount
|
|
Specify the length of the cache region to synchronize. This option is a
|
|
no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
|
|
cache for the entire LUN.
|
|
.It Fl r
|
|
Specify relative addressing for the starting LBA. CTL does not support
|
|
relative addressing, since it only works for linked commands, and CTL
|
|
doesn't support linked commands.
|
|
.It Fl i
|
|
Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE
|
|
command rather than waiting for the cache to finish syncing. CTL does not
|
|
support this bit.
|
|
.It Fl c Ar cdbsize
|
|
Specify the minimum CDB size. Valid values are 10 and 16 bytes.
|
|
.El
|
|
.It Ic shutdown
|
|
Issue a
|
|
.Tn SCSI
|
|
START STOP UNIT command with the start bit cleared and the on/offline bit
|
|
set to all direct access LUNs. This will spin down all direct access LUNs,
|
|
and mark them offline ("Logical unit not ready, manual intervention
|
|
required"). Once marked offline, the state can only be cleared by sending
|
|
a START STOP UNIT command with the start bit set and the on/offline bit
|
|
set. The
|
|
.Nm
|
|
commands
|
|
.Ic startup
|
|
and
|
|
.Ic start
|
|
will accomplish this. Note that the
|
|
on/offline bit is a non-standard Copan extension to the
|
|
.Tn SCSI
|
|
START STOP UNIT command, so merely sending a normal start command from an
|
|
initiator will not clear the condition. (This is by design.)
|
|
.It Ic startup
|
|
Issue a
|
|
.Tn SCSI
|
|
START STOP UNIT command with the start bit set and the on/offline bit set
|
|
to all direct access LUNs. This will mark all direct access LUNs "online"
|
|
again. It will not cause any LUNs to start up. A separate start command
|
|
without the on/offline bit set is necessary for that.
|
|
.It Ic hardstop
|
|
Use the kernel facility for stopping all direct access LUNs and setting the
|
|
offline bit. Unlike the
|
|
.Ic shutdown
|
|
command above, this command allows shutting down LUNs with I/O active. It
|
|
will also issue a LUN reset to any reserved LUNs to break the reservation
|
|
so that the LUN can be stopped.
|
|
.Ic shutdown
|
|
command instead.
|
|
.It Ic hardstart
|
|
This command is functionally identical to the
|
|
.Ic startup
|
|
command described above. The primary difference is that the LUNs are
|
|
enumerated and commands sent by the in-kernel Front End Target Driver
|
|
instead of by
|
|
.Nm .
|
|
.It Ic lunlist
|
|
List all LUNs registered with CTL.
|
|
Because this command uses the ioctl port, it will only work when the FETDs
|
|
(Front End Target Drivers) are enabled.
|
|
This command is the equivalent of doing a REPORT LUNS on one LUN and then
|
|
and then an INQUIRY on each LUN in the system.
|
|
.It Ic delay
|
|
Delay commands at the given location. There are two places where commands
|
|
may be delayed currently: before data is transferred
|
|
.Pq Dq datamove
|
|
and just prior to sending status to the host
|
|
.Pq Dq done .
|
|
One of the two must be supplied as an argument to the
|
|
.Fl l
|
|
option. The
|
|
.Fl t
|
|
option must also be specified.
|
|
.Bl -tag -width 12n
|
|
.It Fl l Ar delayloc
|
|
Delay command(s) at the specified location.
|
|
This can either be at the data movement stage (datamove) or prior to
|
|
command completion (done).
|
|
.It Fl t Ar delaytime
|
|
Delay command(s) for the specified number of seconds. This must be
|
|
specified. If set to 0, it will clear out any previously set delay for
|
|
this particular location (datamove or done).
|
|
.It Fl T Ar delaytype
|
|
Specify the delay type.
|
|
By default, the
|
|
.Ic delay
|
|
option will delay the next command sent to the given LUN.
|
|
With the
|
|
.Fl T Ar cont
|
|
option, every command will be delayed by the specified period of time.
|
|
With the
|
|
.Fl T Ar oneshot
|
|
the next command sent to the given LUN will be delayed and all subsequent
|
|
commands will be completed normally.
|
|
This is the default.
|
|
.El
|
|
.It Ic realsync
|
|
Query and control CTL's SYNCHRONIZE CACHE behavior. The
|
|
.Sq query
|
|
argument
|
|
will show whether SYNCHRONIZE CACHE commands are being sent to the backend
|
|
or not.
|
|
The default is to send SYNCHRONIZE CACHE commands to the backend.
|
|
The
|
|
.Sq on
|
|
argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
|
|
sent to the backend.
|
|
The
|
|
.Sq off
|
|
argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
|
|
immediately returned to the initiator with successful status.
|
|
.It Ic setsync
|
|
For a given lun, only actually service every Nth SYNCHRONIZE CACHE command
|
|
that is sent. This can be used for debugging the optimal time period for
|
|
sending SYNCHRONIZE cache commands. An interval of 0 means that the cache
|
|
will be flushed for this LUN every time a SYNCHRONIZE CACHE command is
|
|
received.
|
|
.Pp
|
|
You must specify the target and LUN you want to modify.
|
|
.It Ic getsync
|
|
Get the interval at which we actually service the SYNCHRONIZE CACHE
|
|
command, as set by the
|
|
.Ic setsync
|
|
command above.
|
|
The reported number means that we will actually flush the cache on every
|
|
Nth SYNCHRONIZE CACHE command. A value of 0 means that we will flush the
|
|
cache every time.
|
|
.Pp
|
|
You must specify the target and LUN you want to query.
|
|
.It Ic inject
|
|
Inject the specified type of error for the LUN specified, when a command
|
|
that matches the given pattern is seen.
|
|
The sense data returned is in either fixed or descriptor format, depending
|
|
upon the status of the D_SENSE bit in the control mode page (page 0xa) for
|
|
the LUN.
|
|
.Pp
|
|
Errors are only injected for commands that have not already failed for
|
|
other reasons.
|
|
By default, only the first command matching the pattern specified is
|
|
returned with the supplied error.
|
|
.Pp
|
|
If the
|
|
.Fl c
|
|
flag is specified, all commands matching the pattern will be returned with
|
|
the specified error until the error injection command is deleted with
|
|
.Fl d
|
|
flag.
|
|
.Bl -tag -width 17n
|
|
.It Fl i Ar action
|
|
Specify the error to return:
|
|
.Bl -tag -width 10n
|
|
.It aborted
|
|
Return the next matching command on the specified LUN with the sense key
|
|
ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
|
|
failure").
|
|
.It mediumerr
|
|
Return the next matching command on the specified LUN with the sense key
|
|
MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
|
|
reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
|
|
for write errors.
|
|
.It ua
|
|
Return the next matching command on the specified LUN with the sense key
|
|
UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
|
|
DEVICE RESET OCCURRED").
|
|
.It custom
|
|
Return the next matching command on the specified LUN with the supplied
|
|
sense data.
|
|
The
|
|
.Fl s
|
|
argument must be specified.
|
|
.El
|
|
.It Fl p Ar pattern
|
|
Specify which commands should be returned with the given error.
|
|
.Bl -tag -width 10n
|
|
.It read
|
|
The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
|
|
.It write
|
|
The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
|
|
AND VERIFY(10), etc.
|
|
.It rw
|
|
The error should apply to both read and write type commands.
|
|
.It readcap
|
|
The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
|
|
.It tur
|
|
The error should apply to TEST UNIT READY commands.
|
|
.It any
|
|
The error should apply to any command.
|
|
.El
|
|
.It Fl r Ar lba,len
|
|
Specify the starting lba and length of the range of LBAs which should
|
|
trigger an error.
|
|
This option is only applies when read and/or write patterns are specified.
|
|
If used with other command types, the error will never be triggered.
|
|
.It Fl s Ar len fmt Op Ar args
|
|
Specify the sense data that is to be returned for custom actions.
|
|
If the format is
|
|
.Sq - ,
|
|
len bytes of sense data will be read from standard input and written to the
|
|
sense buffer.
|
|
If len is longer than 252 bytes (the maximum allowable
|
|
.Tn SCSI
|
|
sense data length), it will be truncated to that length.
|
|
The sense data format is described in
|
|
.Xr cam_cdparse 3 .
|
|
.It Fl c
|
|
The error injection should be persistent, instead of happening once.
|
|
Persistent errors must be deleted with the
|
|
.Fl d
|
|
argument.
|
|
.It Fl d Ar delete_id
|
|
Delete the specified error injection serial number.
|
|
The serial number is returned when the error is injected.
|
|
.El
|
|
.It Ic port
|
|
Perform one of several CTL frontend port operations.
|
|
Either get a list of frontend ports
|
|
.Pq Fl l ,
|
|
turn one or more frontends on
|
|
or off
|
|
.Pq Fl o Ar on|off ,
|
|
or set the World Wide Node Name
|
|
.Pq Fl w Ar wwnn
|
|
or World Wide Port Name
|
|
.Pq Fl W Ar wwpn
|
|
for a given port.
|
|
One of
|
|
.Fl l ,
|
|
.Fl o ,
|
|
or
|
|
.Fl w
|
|
or
|
|
.Fl W
|
|
must be specified.
|
|
The WWNN and WWPN may both be specified at the same time, but cannot be
|
|
combined with enabling/disabling or listing ports.
|
|
.Bl -tag -width 12n
|
|
.It Fl l
|
|
List all CTL frontend ports or a specific port type or number.
|
|
.It Fl o Ar on|off
|
|
Turn the specified CTL frontend ports off or on.
|
|
If no port number or port type is specified, all ports are turned on or
|
|
off.
|
|
.It Fl p Ar targ_port
|
|
Specify the frontend port number.
|
|
The port numbers can be found in the frontend port list.
|
|
.It Fl q
|
|
Omit the header in the port list output.
|
|
.It Fl t Ar fe_type
|
|
Specify the frontend type.
|
|
Currently defined port types are
|
|
.Dq fc
|
|
(Fibre Channel),
|
|
.Dq scsi
|
|
(Parallel SCSI),
|
|
.Dq ioctl
|
|
(CTL ioctl interface),
|
|
and
|
|
.Dq internal
|
|
(CTL CAM SIM).
|
|
.It Fl w Ar wwnn
|
|
Set the World Wide Node Name for the given port.
|
|
The
|
|
.Fl n
|
|
argument must be specified, since this is only possible to implement on a
|
|
single port.
|
|
As a general rule, the WWNN should be the same across all ports on the
|
|
system.
|
|
.It Fl W Ar wwpn
|
|
Set the World Wide Node Name for the given port.
|
|
The
|
|
.Fl n
|
|
argument must be specified, since this is only possible to implement on a
|
|
single port.
|
|
As a general rule, the WWPN must be different for every port in the system.
|
|
.It Fl x
|
|
Output the port list in XML format.
|
|
.El
|
|
.It Ic dumpooa
|
|
Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
|
|
.It Ic dumpstructs
|
|
Dump the CTL structures to the console.
|
|
.It Ic create
|
|
Create a new LUN.
|
|
The backend must be specified, and depending upon the backend requested,
|
|
some of the other options may be required.
|
|
If the LUN is created successfully, the LUN configuration will be
|
|
displayed.
|
|
If LUN creation fails, a message will be displayed describing the failure.
|
|
.Bl -tag -width 14n
|
|
.It Fl b Ar backend
|
|
The
|
|
.Fl b
|
|
flag is required.
|
|
This specifies the name backend to use when creating the LUN.
|
|
Examples are
|
|
.Dq ramdisk
|
|
and
|
|
.Dq block .
|
|
.It Fl B Ar blocksize
|
|
Specify the blocksize of the backend in bytes.
|
|
.It Fl d Ar device_id
|
|
Specify the LUN-associated string to use in the
|
|
.Tn SCSI
|
|
INQUIRY VPD page 0x83 data.
|
|
.It Fl l Ar lun_id
|
|
Request that a particular LUN number be assigned.
|
|
If the requested LUN number is not available, the request will fail.
|
|
.It Fl o Ar name=value
|
|
Specify a backend-specific name/value pair.
|
|
Multiple
|
|
.Fl o
|
|
arguments may be specified.
|
|
Refer to the backend documentation for arguments that may be used.
|
|
.It Fl s Ar size_bytes
|
|
Specify the size of the LUN in bytes.
|
|
Some backends may allow setting the size (e.g. the ramdisk backend) and for
|
|
others the size may be implicit (e.g. the block backend).
|
|
.It Fl S Ar serial_num
|
|
Specify the serial number to be used in the
|
|
.Tn SCSI
|
|
INQUIRY VPD page 0x80 data.
|
|
.It Fl t Ar device_type
|
|
Specify the numeric SCSI device type to use when creating the LUN.
|
|
For example, the Direct Access type is 0.
|
|
If this flag is not used, the type of LUN created is backend-specific.
|
|
Not all LUN types are supported.
|
|
Currently CTL only supports Direct Access (type 0) and Processor (type 3)
|
|
LUNs.
|
|
The backend requested may or may not support all of the LUN types that CTL
|
|
supports.
|
|
.El
|
|
.It Ic remove
|
|
Remove a LUN.
|
|
The backend must be specified, and the LUN number must also be specified.
|
|
Backend-specific options may also be specified with the
|
|
.Fl o
|
|
flag.
|
|
.Bl -tag -width 14n
|
|
.It Fl b Ar backend
|
|
Specify the backend that owns the LUN to be removed.
|
|
Examples are
|
|
.Dq ramdisk
|
|
and
|
|
.Dq block .
|
|
.It Fl l Ar lun_id
|
|
Specify the LUN number to remove.
|
|
.It Fl o Ar name=value
|
|
Specify a backend-specific name/value pair.
|
|
Multiple
|
|
.Fl o
|
|
arguments may be specified.
|
|
Refer to the backend documentation for arguments that may be used.
|
|
.El
|
|
.It Ic devlist
|
|
Get a list of all configured LUNs.
|
|
This also includes the LUN size and blocksize, serial number and device ID.
|
|
.Bl -tag -width 11n
|
|
.It Fl b Ar backend
|
|
Specify the backend.
|
|
This restricts the LUN list to the named backend.
|
|
Examples are
|
|
.Dq ramdisk
|
|
and
|
|
.Dq block .
|
|
.It Fl v
|
|
Be verbose.
|
|
This will also display any backend-specific LUN attributes in addition to
|
|
the standard per-LUN information.
|
|
.It Fl x
|
|
Dump the raw XML.
|
|
The LUN list information from the kernel comes in XML format, and this
|
|
option allows the display of the raw XML data.
|
|
This option and the
|
|
.Fl v
|
|
and
|
|
.Fl b
|
|
options are mutually exclusive.
|
|
If you specify
|
|
.Fl x ,
|
|
the entire LUN database is displayed in XML format.
|
|
.El
|
|
.It Ic help
|
|
Display
|
|
.Nm
|
|
usage information.
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Dl ctladm tur 0:1
|
|
.Pp
|
|
Send a
|
|
.Tn SCSI
|
|
TEST UNIT READY command to LUN 1.
|
|
.Pp
|
|
.Dl ctladm modesense 0:1 -l
|
|
.Pp
|
|
Display the list of mode pages supported by LUN 1.
|
|
.Pp
|
|
.Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10
|
|
.Pp
|
|
Display the saved version of the Control mode page (page 10) on LUN 0.
|
|
Disable fetching block descriptors, and use a 10 byte MODE SENSE command
|
|
instead of the default 6 byte command.
|
|
.Pp
|
|
.Bd -literal
|
|
ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo
|
|
.Ed
|
|
.Pp
|
|
Read the first 512 byte block from LUN 2 and dump it to the file
|
|
.Pa foo .
|
|
.Bd -literal
|
|
ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
|
|
.Ed
|
|
.Pp
|
|
Read 10240 bytes from the file
|
|
.Pa /tmp/bar
|
|
and write it to target 0, LUN 3.
|
|
starting at LBA 0xff432140.
|
|
.Pp
|
|
.Dl ctladm create -b ramdisk -s 10485760000000000
|
|
.Pp
|
|
Create a LUN with the
|
|
.Dq fake
|
|
ramdisk as a backing store.
|
|
The LUN will claim to have a size of approximately 10 terabytes.
|
|
.Pp
|
|
.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
|
|
.Pp
|
|
Create a LUN using the block backend, and specify the file
|
|
.Pa src/usr.sbin/ctladm/ctladm.8
|
|
as the backing store.
|
|
The size of the LUN will be derived from the size of the file.
|
|
.Pp
|
|
.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
|
|
.Pp
|
|
Create a LUN using the block backend, specify the file
|
|
.Pa src/usr.sbin/ctladm/ctladm.8
|
|
as the backing store, and specify the
|
|
.Tn SCSI
|
|
VPD page 0x80 and 0x83 serial number (
|
|
.Fl S)
|
|
and device ID (
|
|
.Fl d).
|
|
.Pp
|
|
.Dl ctladm remove -b block -l 12
|
|
.Pp
|
|
Remove LUN 12, which is handled by the block backend, from the system.
|
|
.Pp
|
|
.Dl ctladm devlist
|
|
.Pp
|
|
List configured LUNs in the system, along with their backend and serial
|
|
number.
|
|
This works when the Front End Target Drivers are enabled or disabled.
|
|
.Pp
|
|
.Dl ctladm lunlist
|
|
.Pp
|
|
List all LUNs in the system, along with their inquiry data and device type.
|
|
This only works when the FETDs are enabled, since the commands go through the
|
|
ioctl port.
|
|
.Pp
|
|
.Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c
|
|
.Pp
|
|
Inject a medium error on LUN 6 for every read that covers the first 512
|
|
blocks of the LUN.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
|
|
.Ed
|
|
.Pp
|
|
Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
|
|
This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
|
|
0x04,0x02 ("Logical unit not ready, initializing command required").
|
|
.Sh SEE ALSO
|
|
.Xr cam 3 ,
|
|
.Xr cam_cdbparse 3 ,
|
|
.Xr cam 4 ,
|
|
.Xr xpt 4 ,
|
|
.Xr camcontrol 8
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility was originally written during the Winter/Spring of 2003 as an
|
|
interface to CTL.
|
|
.Sh AUTHORS
|
|
.An Ken Merry Aq ken@FreeBSD.org
|