886 lines
23 KiB
Groff
886 lines
23 KiB
Groff
.\"
|
|
.\" Copyright (c) 1998, 1999, 2000, 2002, 2005 Kenneth D. Merry.
|
|
.\" 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.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, 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 DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd September 14, 1998
|
|
.Dt CAMCONTROL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm camcontrol
|
|
.Nd CAM control program
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Aq Ar command
|
|
.Op device id
|
|
.Op generic args
|
|
.Op command args
|
|
.Nm
|
|
.Ic devlist
|
|
.Op Fl v
|
|
.Nm
|
|
.Ic periphlist
|
|
.Op device id
|
|
.Op Fl n Ar dev_name
|
|
.Op Fl u Ar unit_number
|
|
.Nm
|
|
.Ic tur
|
|
.Op device id
|
|
.Op generic args
|
|
.Nm
|
|
.Ic inquiry
|
|
.Op device id
|
|
.Op generic args
|
|
.Op Fl D
|
|
.Op Fl S
|
|
.Op Fl R
|
|
.Nm
|
|
.Ic start
|
|
.Op device id
|
|
.Op generic args
|
|
.Nm
|
|
.Ic stop
|
|
.Op device id
|
|
.Op generic args
|
|
.Nm
|
|
.Ic load
|
|
.Op device id
|
|
.Op generic args
|
|
.Nm
|
|
.Ic eject
|
|
.Op device id
|
|
.Op generic args
|
|
.Nm
|
|
.Ic rescan
|
|
.Aq all | bus Ns Op :target:lun
|
|
.Nm
|
|
.Ic reset
|
|
.Aq all | bus Ns Op :target:lun
|
|
.Nm
|
|
.Ic defects
|
|
.Op device id
|
|
.Op generic args
|
|
.Aq Fl f Ar format
|
|
.Op Fl P
|
|
.Op Fl G
|
|
.Nm
|
|
.Ic modepage
|
|
.Op device id
|
|
.Op generic args
|
|
.Aq Fl m Ar page | Fl l
|
|
.Op Fl P Ar pgctl
|
|
.Op Fl b | Fl e
|
|
.Op Fl d
|
|
.Nm
|
|
.Ic cmd
|
|
.Op device id
|
|
.Op generic args
|
|
.Aq Fl c Ar cmd Op args
|
|
.Op Fl i Ar len Ar fmt
|
|
.Bk -words
|
|
.Op Fl o Ar len Ar fmt Op args
|
|
.Ek
|
|
.Nm
|
|
.Ic debug
|
|
.Op Fl I
|
|
.Op Fl P
|
|
.Op Fl T
|
|
.Op Fl S
|
|
.Op Fl X
|
|
.Op Fl c
|
|
.Aq all|off|bus Ns Op :target Ns Op :lun
|
|
.Nm
|
|
.Ic tags
|
|
.Op device id
|
|
.Op generic args
|
|
.Op Fl N Ar tags
|
|
.Op Fl q
|
|
.Op Fl v
|
|
.Nm
|
|
.Ic negotiate
|
|
.Op device id
|
|
.Op generic args
|
|
.Op Fl c
|
|
.Op Fl D Ar enable|disable
|
|
.Op Fl O Ar offset
|
|
.Op Fl q
|
|
.Op Fl R Ar syncrate
|
|
.Op Fl T Ar enable|disable
|
|
.Op Fl U
|
|
.Op Fl W Ar bus_width
|
|
.Op Fl v
|
|
.Nm
|
|
.Ic format
|
|
.Op device id
|
|
.Op generic args
|
|
.Op Fl q
|
|
.Op Fl r
|
|
.Op Fl w
|
|
.Op Fl y
|
|
.Nm
|
|
.Ic help
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
utility is designed to provide a way for users to access and control the
|
|
.Fx
|
|
CAM subsystem.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility
|
|
can cause a loss of data and/or system crashes if used improperly.
|
|
Even
|
|
expert users are encouraged to exercise caution when using this command.
|
|
Novice users should stay away from this utility.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
utility has a number of primary functions, many of which support an optional
|
|
device identifier.
|
|
A device identifier can take one of three forms:
|
|
.Bl -tag -width 14n
|
|
.It deviceUNIT
|
|
Specify a device name and unit number combination, like "da5" or "cd3".
|
|
Note that character device node names (e.g.\& /dev/da0) are
|
|
.Em not
|
|
allowed here.
|
|
.It bus:target
|
|
Specify a bus number and target id.
|
|
The bus number can be determined from
|
|
the output of
|
|
.Dq camcontrol devlist .
|
|
The lun defaults to 0.
|
|
.It bus:target:lun
|
|
Specify the bus, target and lun for a device.
|
|
(e.g.\& 1:2:0)
|
|
.El
|
|
.Pp
|
|
The device identifier, if it is specified,
|
|
.Em must
|
|
come immediately after the function name, and before any generic or
|
|
function-specific arguments.
|
|
Note that the
|
|
.Fl n
|
|
and
|
|
.Fl u
|
|
arguments described below will override any device name or unit number
|
|
specified beforehand.
|
|
The
|
|
.Fl n
|
|
and
|
|
.Fl u
|
|
arguments will
|
|
.Em not
|
|
override a specified bus:target or bus:target:lun, however.
|
|
.Pp
|
|
Most of the
|
|
.Nm
|
|
primary functions support these generic arguments:
|
|
.Bl -tag -width 14n
|
|
.It Fl C Ar count
|
|
SCSI command retry count.
|
|
In order for this to work, error recovery
|
|
.Pq Fl E
|
|
must be turned on.
|
|
.It Fl E
|
|
Instruct the kernel to perform generic SCSI error recovery for the given
|
|
command.
|
|
This is needed in order for the retry count
|
|
.Pq Fl C
|
|
to be honored.
|
|
Other than retrying commands, the generic error recovery in
|
|
the code will generally attempt to spin up drives that are not spinning.
|
|
It may take some other actions, depending upon the sense code returned from
|
|
the command.
|
|
.It Fl n Ar dev_name
|
|
Specify the device type to operate on, e.g.\& "da", "cd".
|
|
.It Fl t Ar timeout
|
|
SCSI command timeout in seconds.
|
|
This overrides the default timeout for
|
|
any given command.
|
|
.It Fl u Ar unit_number
|
|
Specify the device unit number, e.g.\& "1", "5".
|
|
.It Fl v
|
|
Be verbose, print out sense information for failed SCSI commands.
|
|
.El
|
|
.Pp
|
|
Primary command functions:
|
|
.Bl -tag -width periphlist
|
|
.It Ic devlist
|
|
List all physical devices (logical units) attached to the CAM subsystem.
|
|
This also includes a list of peripheral drivers attached to each device.
|
|
With the
|
|
.Fl v
|
|
argument, SCSI bus number, adapter name and unit numbers are printed as
|
|
well.
|
|
.It Ic periphlist
|
|
List all peripheral drivers attached to a given physical device (logical
|
|
unit).
|
|
.It Ic tur
|
|
Send the SCSI test unit ready (0x00) command to the given device.
|
|
The
|
|
.Nm
|
|
utility will report whether the device is ready or not.
|
|
.It Ic inquiry
|
|
Send a SCSI inquiry command (0x12) to a device.
|
|
By default,
|
|
.Nm
|
|
will print out the standard inquiry data, device serial number, and
|
|
transfer rate information.
|
|
The user can specify that only certain types of
|
|
inquiry data be printed:
|
|
.Bl -tag -width 4n
|
|
.It Fl D
|
|
Get the standard inquiry data.
|
|
.It Fl S
|
|
Print out the serial number.
|
|
If this flag is the only one specified,
|
|
.Nm
|
|
will not print out "Serial Number" before the value returned by the drive.
|
|
This is to aid in script writing.
|
|
.It Fl R
|
|
Print out transfer rate information.
|
|
.El
|
|
.It Ic start
|
|
Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
|
|
start bit set.
|
|
.It Ic stop
|
|
Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
|
|
start bit cleared.
|
|
.It Ic load
|
|
Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
|
|
start bit set and the load/eject bit set.
|
|
.It Ic eject
|
|
Send the SCSI Start/Stop Unit (0x1B) command to the given device with the
|
|
start bit cleared and the load/eject bit set.
|
|
.It Ic rescan
|
|
Tell the kernel to scan all busses in the system (with the
|
|
.Ar all
|
|
argument), the given bus (XPT_SCAN_BUS), or bus:target:lun
|
|
(XPT_SCAN_LUN) for new devices or devices that have gone away.
|
|
The user
|
|
may specify a scan of all busses, a single bus, or a lun.
|
|
Scanning all luns
|
|
on a target is not supported.
|
|
.It Ic reset
|
|
Tell the kernel to reset all busses in the system (with the
|
|
.Ar all
|
|
argument) or the given bus (XPT_RESET_BUS) by issuing a SCSI bus
|
|
reset for that bus, or to reset the given bus:target:lun
|
|
(XPT_RESET_DEV), typically by issuing a BUS DEVICE RESET message after
|
|
connecting to that device.
|
|
Note that this can have a destructive impact
|
|
on the system.
|
|
.It Ic defects
|
|
Send the SCSI READ DEFECT DATA (10) command (0x37) to the given device, and
|
|
print out any combination of: the total number of defects, the primary
|
|
defect list (PLIST), and the grown defect list (GLIST).
|
|
.Bl -tag -width 11n
|
|
.It Fl f Ar format
|
|
The three format options are:
|
|
.Em block ,
|
|
to print out the list as logical blocks,
|
|
.Em bfi ,
|
|
to print out the list in bytes from index format, and
|
|
.Em phys ,
|
|
to print out the list in physical sector format.
|
|
The format argument is
|
|
required.
|
|
Most drives support the physical sector format.
|
|
Some drives
|
|
support the logical block format.
|
|
Many drives, if they do not support the
|
|
requested format, return the data in an alternate format, along with sense
|
|
information indicating that the requested data format is not supported.
|
|
The
|
|
.Nm
|
|
utility
|
|
attempts to detect this, and print out whatever format the drive returns.
|
|
If the drive uses a non-standard sense code to report that it does not
|
|
support the requested format,
|
|
.Nm
|
|
will probably see the error as a failure to complete the request.
|
|
.It Fl G
|
|
Print out the grown defect list.
|
|
This is a list of bad blocks that have
|
|
been remapped since the disk left the factory.
|
|
.It Fl P
|
|
Print out the primary defect list.
|
|
.El
|
|
.Pp
|
|
If neither
|
|
.Fl P
|
|
nor
|
|
.Fl G
|
|
is specified,
|
|
.Nm
|
|
will print out the number of defects given in the READ DEFECT DATA header
|
|
returned from the drive.
|
|
.It Ic modepage
|
|
Allows the user to display and optionally edit a SCSI mode page.
|
|
The mode
|
|
page formats are located in
|
|
.Pa /usr/share/misc/scsi_modes .
|
|
This can be overridden by specifying a different file in the
|
|
.Ev SCSI_MODES
|
|
environment variable.
|
|
The
|
|
.Ic modepage
|
|
command takes several arguments:
|
|
.Bl -tag -width 12n
|
|
.It Fl d
|
|
Disable block descriptors for mode sense.
|
|
.It Fl b
|
|
Displays mode page data in binary format.
|
|
.It Fl e
|
|
This flag allows the user to edit values in the mode page.
|
|
The user may
|
|
either edit mode page values with the text editor pointed to by his
|
|
.Ev EDITOR
|
|
environment variable, or supply mode page values via standard input, using
|
|
the same format that
|
|
.Nm
|
|
uses to display mode page values.
|
|
The editor will be invoked if
|
|
.Nm
|
|
detects that standard input is terminal.
|
|
.It Fl l
|
|
Lists all available mode pages.
|
|
.It Fl m Ar mode_page
|
|
This specifies the number of the mode page the user would like to view
|
|
and/or edit.
|
|
This argument is mandatory unless
|
|
.Fl l
|
|
is specified.
|
|
.It Fl P Ar pgctl
|
|
This allows the user to specify the page control field.
|
|
Possible values are:
|
|
.Bl -tag -width xxx -compact
|
|
.It 0
|
|
Current values
|
|
.It 1
|
|
Changeable values
|
|
.It 2
|
|
Default values
|
|
.It 3
|
|
Saved values
|
|
.El
|
|
.El
|
|
.It Ic cmd
|
|
Allows the user to send an arbitrary SCSI CDB to any device.
|
|
The
|
|
.Ic cmd
|
|
function requires the
|
|
.Fl c
|
|
argument to specify the CDB.
|
|
Other arguments are optional, depending on
|
|
the command type.
|
|
The command and data specification syntax is documented
|
|
in
|
|
.Xr cam_cdbparse 3 .
|
|
NOTE: If the CDB specified causes data to be transfered to or from the
|
|
SCSI device in question, you MUST specify either
|
|
.Fl i
|
|
or
|
|
.Fl o .
|
|
.Bl -tag -width 17n
|
|
.It Fl c Ar cmd Op args
|
|
This specifies the SCSI CDB.
|
|
CDBs may be 6, 10, 12 or 16 bytes.
|
|
.It Fl i Ar len Ar fmt
|
|
This specifies the amount of data to read, and how it should be displayed.
|
|
If the format is
|
|
.Sq - ,
|
|
.Ar len
|
|
bytes of data will be read from the device and written to standard output.
|
|
.It Fl o Ar len Ar fmt Op args
|
|
This specifies the amount of data to be written to a device, and the data
|
|
that is to be written.
|
|
If the format is
|
|
.Sq - ,
|
|
.Ar len
|
|
bytes of data will be read from standard input and written to the device.
|
|
.El
|
|
.It Ic debug
|
|
Turn on CAM debugging printfs in the kernel.
|
|
This requires options CAMDEBUG
|
|
in your kernel config file.
|
|
WARNING: enabling debugging printfs currently
|
|
causes an EXTREME number of kernel printfs.
|
|
You may have difficulty
|
|
turning off the debugging printfs once they start, since the kernel will be
|
|
busy printing messages and unable to service other requests quickly.
|
|
The
|
|
.Ic debug
|
|
function takes a number of arguments:
|
|
.Bl -tag -width 18n
|
|
.It Fl I
|
|
Enable CAM_DEBUG_INFO printfs.
|
|
.It Fl P
|
|
Enable CAM_DEBUG_PERIPH printfs.
|
|
.It Fl T
|
|
Enable CAM_DEBUG_TRACE printfs.
|
|
.It Fl S
|
|
Enable CAM_DEBUG_SUBTRACE printfs.
|
|
.It Fl X
|
|
Enable CAM_DEBUG_XPT printfs.
|
|
.It Fl c
|
|
Enable CAM_DEBUG_CDB printfs.
|
|
This will cause the kernel to print out the
|
|
SCSI CDBs sent to the specified device(s).
|
|
.It all
|
|
Enable debugging for all devices.
|
|
.It off
|
|
Turn off debugging for all devices
|
|
.It bus Ns Op :target Ns Op :lun
|
|
Turn on debugging for the given bus, target or lun.
|
|
If the lun or target
|
|
and lun are not specified, they are wildcarded.
|
|
(i.e., just specifying a
|
|
bus turns on debugging printfs for all devices on that bus.)
|
|
.El
|
|
.It Ic tags
|
|
Show or set the number of "tagged openings" or simultaneous transactions
|
|
we attempt to queue to a particular device.
|
|
By default, the
|
|
.Ic tags
|
|
command, with no command-specific arguments (i.e., only generic arguments)
|
|
prints out the "soft" maximum number of transactions that can be queued to
|
|
the device in question.
|
|
For more detailed information, use the
|
|
.Fl v
|
|
argument described below.
|
|
.Bl -tag -width 7n
|
|
.It Fl N Ar tags
|
|
Set the number of tags for the given device.
|
|
This must be between the
|
|
minimum and maximum number set in the kernel quirk table.
|
|
The default for
|
|
most devices that support tagged queueing is a minimum of 2 and a maximum
|
|
of 255.
|
|
The minimum and maximum values for a given device may be
|
|
determined by using the
|
|
.Fl v
|
|
switch.
|
|
The meaning of the
|
|
.Fl v
|
|
switch for this
|
|
.Nm
|
|
subcommand is described below.
|
|
.It Fl q
|
|
Be quiet, and do not report the number of tags.
|
|
This is generally used when
|
|
setting the number of tags.
|
|
.It Fl v
|
|
The verbose flag has special functionality for the
|
|
.Em tags
|
|
argument.
|
|
It causes
|
|
.Nm
|
|
to print out the tagged queueing related fields of the XPT_GDEV_TYPE CCB:
|
|
.Bl -tag -width 13n
|
|
.It dev_openings
|
|
This is the amount of capacity for transactions queued to a given device.
|
|
.It dev_active
|
|
This is the number of transactions currently queued to a device.
|
|
.It devq_openings
|
|
This is the kernel queue space for transactions.
|
|
This count usually mirrors
|
|
dev_openings except during error recovery operations when
|
|
the device queue is frozen (device is not allowed to receive
|
|
commands), the number of dev_openings is reduced, or transaction
|
|
replay is occurring.
|
|
.It devq_queued
|
|
This is the number of transactions waiting in the kernel queue for capacity
|
|
on the device.
|
|
This number is usually zero unless error recovery is in
|
|
progress.
|
|
.It held
|
|
The held count is the number of CCBs held by peripheral drivers that have
|
|
either just been completed or are about to be released to the transport
|
|
layer for service by a device.
|
|
Held CCBs reserve capacity on a given
|
|
device.
|
|
.It mintags
|
|
This is the current "hard" minimum number of transactions that can be
|
|
queued to a device at once.
|
|
The
|
|
.Ar dev_openings
|
|
value above cannot go below this number.
|
|
The default value for
|
|
.Ar mintags
|
|
is 2, although it may be set higher or lower for various devices.
|
|
.It maxtags
|
|
This is the "hard" maximum number of transactions that can be queued to a
|
|
device at one time.
|
|
The
|
|
.Ar dev_openings
|
|
value cannot go above this number.
|
|
The default value for
|
|
.Ar maxtags
|
|
is 255, although it may be set higher or lower for various devices.
|
|
.El
|
|
.El
|
|
.It Ic negotiate
|
|
Show or negotiate various communication parameters.
|
|
Some controllers may
|
|
not support setting or changing some of these values.
|
|
For instance, the
|
|
Adaptec 174x controllers do not support changing a device's sync rate or
|
|
offset.
|
|
The
|
|
.Nm
|
|
utility
|
|
will not attempt to set the parameter if the controller indicates that it
|
|
does not support setting the parameter.
|
|
To find out what the controller
|
|
supports, use the
|
|
.Fl v
|
|
flag.
|
|
The meaning of the
|
|
.Fl v
|
|
flag for the
|
|
.Ic negotiate
|
|
command is described below.
|
|
Also, some controller drivers do not support
|
|
setting negotiation parameters, even if the underlying controller supports
|
|
negotiation changes.
|
|
Some controllers, such as the Advansys wide
|
|
controllers, support enabling and disabling synchronous negotiation for
|
|
a device, but do not support setting the synchronous negotiation rate.
|
|
.Bl -tag -width 17n
|
|
.It Fl a
|
|
Attempt to make the negotiation settings take effect immediately by sending
|
|
a Test Unit Ready command to the device.
|
|
.It Fl c
|
|
Show or set current negotiation settings.
|
|
This is the default.
|
|
.It Fl D Ar enable|disable
|
|
Enable or disable disconnection.
|
|
.It Fl O Ar offset
|
|
Set the command delay offset.
|
|
.It Fl q
|
|
Be quiet, do not print anything.
|
|
This is generally useful when you want to
|
|
set a parameter, but do not want any status information.
|
|
.It Fl R Ar syncrate
|
|
Change the synchronization rate for a device.
|
|
The sync rate is a floating
|
|
point value specified in MHz.
|
|
So, for instance,
|
|
.Sq 20.000
|
|
is a legal value, as is
|
|
.Sq 20 .
|
|
.It Fl T Ar enable|disable
|
|
Enable or disable tagged queueing for a device.
|
|
.It Fl U
|
|
Show or set user negotiation settings.
|
|
The default is to show or set
|
|
current negotiation settings.
|
|
.It Fl v
|
|
The verbose switch has special meaning for the
|
|
.Ic negotiate
|
|
subcommand.
|
|
It causes
|
|
.Nm
|
|
to print out the contents of a Path Inquiry (XPT_PATH_INQ) CCB sent to the
|
|
controller driver.
|
|
.It Fl W Ar bus_width
|
|
Specify the bus width to negotiate with a device.
|
|
The bus width is
|
|
specified in bits.
|
|
The only useful values to specify are 8, 16, and 32
|
|
bits.
|
|
The controller must support the bus width in question in order for
|
|
the setting to take effect.
|
|
.El
|
|
.Pp
|
|
In general, sync rate and offset settings will not take effect for a
|
|
device until a command has been sent to the device.
|
|
The
|
|
.Fl a
|
|
switch above will automatically send a Test Unit Ready to the device so
|
|
negotiation parameters will take effect.
|
|
.It Ic format
|
|
Issue the
|
|
.Tn SCSI
|
|
FORMAT UNIT command to the named device.
|
|
.Pp
|
|
.Em WARNING! WARNING! WARNING!
|
|
.Pp
|
|
Low level formatting a disk will destroy ALL data on the disk.
|
|
Use
|
|
extreme caution when issuing this command.
|
|
Many users low-level format
|
|
disks that do not really need to be low-level formatted.
|
|
There are
|
|
relatively few scenarios that call for low-level formatting a disk.
|
|
One reason for
|
|
low-level formatting a disk is to initialize the disk after changing
|
|
its physical sector size.
|
|
Another reason for low-level formatting a disk
|
|
is to revive the disk if you are getting "medium format corrupted" errors
|
|
from the disk in response to read and write requests.
|
|
.Pp
|
|
Some disks take longer than others to format.
|
|
Users should specify a
|
|
timeout long enough to allow the format to complete.
|
|
The default format
|
|
timeout is 3 hours, which should be long enough for most disks.
|
|
Some hard
|
|
disks will complete a format operation in a very short period of time
|
|
(on the order of 5 minutes or less).
|
|
This is often because the drive
|
|
does not really support the FORMAT UNIT command -- it just accepts the
|
|
command, waits a few minutes and then returns it.
|
|
.Pp
|
|
The
|
|
.Sq format
|
|
subcommand takes several arguments that modify its default behavior.
|
|
The
|
|
.Fl q
|
|
and
|
|
.Fl y
|
|
arguments can be useful for scripts.
|
|
.Pp
|
|
.Bl -tag -width 6n
|
|
.It Fl q
|
|
Be quiet, do not print any status messages.
|
|
This option will not disable
|
|
the questions, however.
|
|
To disable questions, use the
|
|
.Fl y
|
|
argument, below.
|
|
.It Fl r
|
|
Run in
|
|
.Dq report only
|
|
mode.
|
|
This will report status on a format that is already running on the drive.
|
|
.It Fl w
|
|
Issue a non-immediate format command.
|
|
By default,
|
|
.Nm
|
|
issues the FORMAT UNIT command with the immediate bit set.
|
|
This tells the
|
|
device to immediately return the format command, before the format has
|
|
actually completed.
|
|
Then,
|
|
.Nm
|
|
gathers
|
|
.Tn SCSI
|
|
sense information from the device every second to determine how far along
|
|
in the format process it is.
|
|
If the
|
|
.Fl w
|
|
argument is specified,
|
|
.Nm
|
|
will issue a non-immediate format command, and will be unable to print any
|
|
information to let the user know what percentage of the disk has been
|
|
formatted.
|
|
.It Fl y
|
|
Do not ask any questions.
|
|
By default,
|
|
.Nm
|
|
will ask the user if he/she really wants to format the disk in question,
|
|
and also if the default format command timeout is acceptable.
|
|
The user
|
|
will not be asked about the timeout if a timeout is specified on the
|
|
command line.
|
|
.El
|
|
.It Ic help
|
|
Print out verbose usage information.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
The
|
|
.Ev SCSI_MODES
|
|
variable allows the user to specify an alternate mode page format file.
|
|
.Pp
|
|
The
|
|
.Ev EDITOR
|
|
variable determines which text editor
|
|
.Nm
|
|
starts when editing mode pages.
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/share/misc/scsi_modes -compact
|
|
.It Pa /usr/share/misc/scsi_modes
|
|
is the SCSI mode format database.
|
|
.It Pa /dev/xpt0
|
|
is the transport layer device.
|
|
.It Pa /dev/pass*
|
|
are the CAM application passthrough devices.
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Dl camcontrol eject -n cd -u 1 -v
|
|
.Pp
|
|
Eject the CD from cd1, and print SCSI sense information if the command
|
|
fails.
|
|
.Pp
|
|
.Dl camcontrol tur da0
|
|
.Pp
|
|
Send the SCSI test unit ready command to da0.
|
|
The
|
|
.Nm
|
|
utility will report whether the disk is ready, but will not display sense
|
|
information if the command fails since the
|
|
.Fl v
|
|
switch was not specified.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
camcontrol tur da1 -E -C 4 -t 50 -v
|
|
.Ed
|
|
.Pp
|
|
Send a test unit ready command to da1.
|
|
Enable kernel error recovery.
|
|
Specify a retry count of 4, and a timeout of 50 seconds.
|
|
Enable sense
|
|
printing (with the
|
|
.Fl v
|
|
flag) if the command fails.
|
|
Since error recovery is turned on, the
|
|
disk will be spun up if it is not currently spinning.
|
|
The
|
|
.Nm
|
|
utility will report whether the disk is ready.
|
|
.Bd -literal -offset indent
|
|
camcontrol cmd -n cd -u 1 -v -c "3C 00 00 00 00 00 00 00 0e 00" \e
|
|
-i 0xe "s1 i3 i1 i1 i1 i1 i1 i1 i1 i1 i1 i1"
|
|
.Ed
|
|
.Pp
|
|
Issue a READ BUFFER command (0x3C) to cd1.
|
|
Display the buffer size of cd1,
|
|
and display the first 10 bytes from the cache on cd1.
|
|
Display SCSI sense
|
|
information if the command fails.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
camcontrol cmd -n cd -u 1 -v -c "3B 00 00 00 00 00 00 00 0e 00" \e
|
|
-o 14 "00 00 00 00 1 2 3 4 5 6 v v v v" 7 8 9 8
|
|
.Ed
|
|
.Pp
|
|
Issue a WRITE BUFFER (0x3B) command to cd1.
|
|
Write out 10 bytes of data,
|
|
not including the (reserved) 4 byte header.
|
|
Print out sense information if
|
|
the command fails.
|
|
Be very careful with this command, improper use may
|
|
cause data corruption.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
camcontrol modepage da3 -m 1 -e -P 3
|
|
.Ed
|
|
.Pp
|
|
Edit mode page 1 (the Read-Write Error Recover page) for da3, and save the
|
|
settings on the drive.
|
|
Mode page 1 contains a disk drive's auto read and
|
|
write reallocation settings, among other things.
|
|
.Pp
|
|
.Dl camcontrol rescan all
|
|
.Pp
|
|
Rescan all SCSI busses in the system for devices that have been added,
|
|
removed or changed.
|
|
.Pp
|
|
.Dl camcontrol rescan 0
|
|
.Pp
|
|
Rescan SCSI bus 0 for devices that have been added, removed or changed.
|
|
.Pp
|
|
.Dl camcontrol rescan 0:1:0
|
|
.Pp
|
|
Rescan SCSI bus 0, target 1, lun 0 to see if it has been added, removed, or
|
|
changed.
|
|
.Pp
|
|
.Dl camcontrol tags da5 -N 24
|
|
.Pp
|
|
Set the number of concurrent transactions for da5 to 24.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
camcontrol negotiate -n da -u 4 -T disable
|
|
.Ed
|
|
.Pp
|
|
Disable tagged queueing for da4.
|
|
.Pp
|
|
.Bd -literal -offset indent
|
|
camcontrol negotiate -n da -u 3 -R 20.000 -O 15 -a
|
|
.Ed
|
|
.Pp
|
|
Negotiate a sync rate of 20MHz and an offset of 15 with da3.
|
|
Then send a
|
|
Test Unit Ready command to make the settings take effect.
|
|
.Sh SEE ALSO
|
|
.Xr cam 3 ,
|
|
.Xr cam_cdbparse 3 ,
|
|
.Xr cam 4 ,
|
|
.Xr pass 4 ,
|
|
.Xr xpt 4
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
utility first appeared in
|
|
.Fx 3.0 .
|
|
.Pp
|
|
The mode page editing code and arbitrary SCSI command code are based upon
|
|
code in the old
|
|
.Xr scsi 8
|
|
utility and
|
|
.Xr scsi 3
|
|
library, written by Julian Elischer and Peter Dufault.
|
|
The
|
|
.Xr scsi 8
|
|
program first appeared in
|
|
.Bx 386 0.1.2.4 ,
|
|
and first appeared in
|
|
.Fx
|
|
in
|
|
.Fx 2.0.5 .
|
|
.Sh AUTHORS
|
|
.An Kenneth Merry Aq ken@FreeBSD.org
|
|
.Sh BUGS
|
|
The code that parses the generic command line arguments does not know that
|
|
some of the subcommands take multiple arguments.
|
|
So if, for instance, you
|
|
tried something like this:
|
|
.Bd -literal -offset indent
|
|
camcontrol cmd -n da -u 1 -c "00 00 00 00 00 v" 0x00 -v
|
|
.Ed
|
|
.Pp
|
|
The sense information from the test unit ready command would not get
|
|
printed out, since the first
|
|
.Xr getopt 3
|
|
call in
|
|
.Nm
|
|
bails out when it sees the second argument to
|
|
.Fl c
|
|
(0x00),
|
|
above.
|
|
Fixing this behavior would take some gross code, or changes to the
|
|
.Xr getopt 3
|
|
interface.
|
|
The best way to circumvent this problem is to always make sure
|
|
to specify generic
|
|
.Nm
|
|
arguments before any command-specific arguments.
|