NAME
scsictl — control a SCSI device
SYNOPSIS
scsictl
[-akq]
[-m
mode[=
value]]...
[-c
command]...
device
scsictl
-o
ola_params arguments...
scsictl -p pr_clear key device
scsictl
[-k]
-t tgtid
{-c
command}... ctrl
DESCRIPTION
The
scsictl
command provides a mechanism for controlling a SCSI device.
It can be used to query mode parameters,
set configurable mode parameters,
and perform SCSI commands.
The operations are performed in the same order
as they appear on the command line.
The second form, as shown above, supports the online addition of a supported
SCSI card to a system.
This option cannot be used with any other options available
for this command.
The
scsictl
command can be used to clear persistent reservation from a device,
as shown in the third form above, using the
-p
option.
Some of the commands can be used on a controller device as shown in the
fourth form.
The list of commands supported on a controller device
is provided in the
-t
option description below.
device
specifies the character special file to use.
ctrl
specifies the special file of a parallel SCSI controller node.
Options
scsictl
recognizes the following options.
Mode parameters and commands need only be specified up to a unique prefix.
When abbreviating a mode parameter or command,
at least the first three characters must be supplied.
- -a
Display the status of all mode parameters available,
separated by semicolon-blank
(; )
or newline.
- -c command
Cause the device to perform the specified command.
If multiple commands need to be specified, then each command must
be prefixed by the
-c
option.
command
can be one of the following:
- erase
For magneto-optical devices that support write without erase,
this command can be used to pre-erase the whole surface
to increase data throughput on subsequent write operations.
This command maintains exclusive access to the surface during the pre-erasure.
- sync_cache
For devices that have an internal write cache,
this command causes the device to flush its cache to the physical medium.
- domain_val
Domain validation allows the user to check the quality of transmissions
across the bus and helps to find problems like faulty and missing
terminators, bad components, and so on.
This command is only valid for Ultra160 and later devices.
If any errors encountered during domain validation, they
will be logged in the
syslog.
- get_bus_parms
This command displays information about limits and negotiable parameters of
a bus.
- get_lun_parms
This command displays information about limits and negotiable parameters of
a physical or a virtual peripheral device.
- get_target_parms
This command displays information about limits and negotiable parameters of
a target peripheral device.
- reset_target
This command causes a target reset task management function to be sent to
the associated target.
- reset_bus
This command causes the system to generate a SCSI bus reset condition on
the associated bus. A SCSI bus reset condition causes all devices on the
bus to be reset (including clearing all active commands on all devices).
- -k
Continue processing arguments even after an error is detected.
The default behavior is to exit immediately when an error is detected.
Command line syntax is always verified for correctness, regardless of the
-k
option.
Improper command line syntax causes
scsictl
to exit without performing any operations on the device.
- -m mode
Display the status of the specified
mode
parameter.
mode
can be one of the following:
- immediate_report
For devices that support immediate reporting,
this mode controls how the device responds to write requests.
If immediate report is enabled
(1),
write requests can be acknowledged
before the data is physically transferred to the media.
If immediate report is disabled
(0),
the device is forced
to await the completion of any write request before reporting its status.
- ir
Equivalent to
immediate_report.
- queue_depth
For devices that support a queue depth greater than the system default,
this mode controls how many I/Os the
driver will attempt to queue to the device at any one time.
Valid values are
(1-255).
Some disk devices will not support the maximum queue depth
settable by this command.
Setting the queue depth in software to a value
larger than the disk can handle will result in I/Os being held off
once a QUEUE FULL condition exists on the disk.
- -m mode=value
Set the mode parameter
mode
to
value.
The available mode parameters and values are listed above.
Mode parameters that take only a binary value
(1
or
0)
can also be specified as either
on
or
off,
respectively.
- -o command
Currently this option supports only the following command:
- ola_params
This command should be followed by five arguments namely,
hw_path,
scsi_id,
width,
period,
and
offset.
Actual values of
scsi_id,
width,
period
and
offset
are decided by the hardware.
If the hardware is not capable of supporting the requested values,
they will be brought to the maximum capability of the card.
A value of
-1
may be specified for
scsi_id,
width,
period
and
offset
in order to use the hardware default values.
Note:
This command does not validate any of the arguments passed.
Therefore, it does not show any output upon successful completion.
- -p pr_clear key device
Use the
scsictl
command with the
-p pr_clear
option
to clear the persistent reservation from a device.
This command cannot be
used with any other
scsictl
options or commands.
This command should be followed by two arguments:
key
and
device.
key
is a string of characters which was used while setting persistent
reservation. This
key
can be in any of the following two formats:
- (a)
Text format: can contain any of alphanumeric characters.
In this format length of the
key
should not exceed 8 characters.
- (b)
Hex format: preceded by 0x or 0X, can contain any of hexadecimal digit.
In this format length of the string should not exceed 18 characters in
total (including 0x or 0X).
- -q
Suppress the labels that are normally printed
when mode parameters are displayed.
Mode parameter values are printed
in the same order as they appear on the command line,
separated by semicolon-blank
(; )
or newline.
- -t tgtid ctrl
Specify
tgtid
as the SCSI target parameter on which operation needs to be initiated.
The valid range of
tgtid
value is between 0 and 15.
In agile addressing the
tgtid
is the
port_id
returned by the command
scsimgr get_info -H
target_path.
See
intro(7)
for information about agile addressing and
scsimgr(1M).
The commands supported with the
-t
option are
domain_val,
get_bus_parms,
get_target_parms,
reset_target
and
reset_bus.
See the
-c
option for explanations of these commands.
ctrl
specifies the special file of a parallel SCSI controller node.
RETURN VALUE
scsictl
exits with one of the following values:
- 0
Operation successful.
- >0
Error condition occurred.
DIAGNOSTICS
Diagnostic messages are generally self-explanatory.
EXAMPLES
To display all the mode parameters, turn
immediate_report
on, and redisplay the value of
immediate_report:
scsictl -a -m ir=1 -m ir /dev/rdsk/c0t6d0
producing the following output:
immediate_report = 0; queue_depth = 8; immediate_report = 1
The same operation with labels suppressed:
scsictl -aq -m ir=1 -m ir /dev/rdsk/c0t6d0
produces the following output:
To clear persistent reservation from a device:
scsictl -p pr_clear key /dev/rdsk/c0t6d0
To add a supported SCSI card online at
2/4.0.0:
scsictl -o ola_params 2/4.0.0 -1 -1 -1 -1
To issue a
get_target_parms
command on a SCSI target with a
tgtid
of 2 using
/dev/c8xx2
as the
ctrl
device:
scsictl -t 2 -c get_target_parms /dev/c8xx2
To display limits and negotiable parameters of a device and
then reset the SCSI target:
scsictl -c get_lun_parms -c reset_target /dev/rdsk/c0t6d0
WARNINGS
Not all devices support all mode parameters and commands listed above.
Changing a mode parameter may have no effect on such a device.
Issuing a command that is not supported by a device
can cause an error message to be generated.
scsictl
is not supported on sequential-access devices using the tape driver.
The
immediate_report
mode applies to the entire device; the section number of the
device
argument is ignored.
To aid recovery, immediate reporting is not used for
writes of file system data structures
that are maintained by the operating system,
writes to a hard disk (but not a magneto-optical device)
through the character-device interface,
or writes to regular files that the user has made synchronous with
O_SYNC
or
O_DSYNC
(see
open(2)
and
fcntl(2)).
DEPENDENCIES
disc3
When the system is rebooted, the
disc3
driver always resets the value of the
immediate_report
mode parameter to
off.
If
ioctl()
or
scsictl
is used to change the setting of immediate reporting on a SCSI device,
the new value becomes the default setting
upon subsequent configuration (for example, opens) of this device
and retains its value across system or device powerfail recovery.
However, on the next system reboot, the
immediate-report
mode parameter is again reset to the value of the tunable system parameter,
default_disk_ir.
This is set using the
kctune
command.
sdisk
If
ioctl()
or
scsictl
is used to change the setting of immediate reporting on a SCSI device,
the new value becomes the default setting
upon subsequent configuration (for example, opens) of this device
until the "last close" of the device,
that is, when neither the system nor any application has the device open
(for example, unmounting a file system via
umount
and then mounting it again via
mount
(see
mount(1M)).
On the next "first open",
the
immediate-report
mode parameter is again reset to the value of the tunable system parameter,
default_disk_ir.
This is set using the
kctune
command.
Printable version
