Table of Contents
The sg driver provides information about the SCSI subsystem and the current
internal state of the sg driver in the /proc/scsi/sg
directory. Some sg driver defaults can be changed by super user writing values
to these "pseudo" files
[20].
The following files which are readable by all:
allow_dio 0 indicates direct IO disable, 1 for enabled debug debug information including active request data def_reserved_size default buffer size reserved for each file descriptor devices one line of numeric data per device device_hdr single line of column names corresponding to 'devices' device_strs one line of vendor, product and rev info per device hosts one line of numeric data per host host_hdr single line of column names corresponding to 'hosts' host_strs one line of host information (string) per host version sg version as a number followed by a string representation
Each line in 'devices' and 'device_strs' corresponds to an sg device. For
example the first line corresponds to /dev/sg0. The line
number (origin 0) also corresponds to the sg minor device number. This
mapping is local to sg and is normally the same as given by th
cat /proc/scsi/scsi command which is reported by the SCSI
mid level driver. The two mappings may diverge when 'remove-single-device'
and 'add-single-device' are used (see the
SCSI-2.4-HOWTO for more information).
Each line in 'hosts' and 'host_strs' corresponds to a SCSI host. For example the first line corresponds to the host normally represented as "scsi0". This mapping is invariant across the SCSI sub system. [So these entries could arguably be migrated to the mid level.]
The column headers in 'device_hdr' are given below. If the device is not present (and one is present after it) then a line of "-1" entries is output. Each entry is separated by a whitespace (currently a tab):
host host number (indexes 'hosts' table, origin 0) chan channel number of device id SCSI id of device lun Logical Unit number of device type SCSI type (e.g. 0->disk, 5->cdrom, 6->scanner) opens number of opens (by sd, sr, sr and sg) at this time depth maximum queue depth supported by device busy number of commands being processed by host for this device online 1 indicates device is in normal online state, 0->offline
A SCSI device is set offline by the SCSI mid level when it decides that a device is no longer responding (e.g. the device does not respond to an SCSI INQUIRY command after it has been reset).
The column headers in 'host_hdr' are given below. Each entry is separated by a whitespace (currently a tab):
uid unique id (non-zero if multiple hosts of same type)
busy number of commands being processed for this host
cpl maximum number of command per lun (may be 0 if "device depth"
is given
sgat maximum elements of scatter gather the adapter (pseudo)
DMA can accommodate
isa 0 -> non-ISA adapter, 1 -> ISA adapter. ISA adapters are
assumed to have a 24 bit address bus limit (16 MB).
emu 0 -> real SCSI adapter, 1 -> emulated SCSI adapter
(e.g. ide-scsi device driver)
The 'def_reserved_size' is both readable and writable. It is only writable by root. It is initialized to the value of DEF_RESERVED_SIZE in the "sg.h" file. Values between 0 and 1048576 (which is 2 ** 20) are accepted and can be set from the command line with the following syntax:
$ echo "262144" > /proc/scsi/sg/def_reserved_size
Note that the actual reserved buffer associated with a file descriptor could be less than 'def_reserved_size' if appropriate memory is not available. If the sg driver is compiled into the kernel (but not when it is a module) this value can also be read at /proc/sys/kernel/sg-big-buff . This latter feature is deprecated.
The 'allow_dio' is both readable and writable. It is only writable by root. When it is 0 (default) any request to do direct IO (i.e. by setting SG_FLAG_DIRECT_IO) will be ignored and indirect IO will be done instead.
This appendix explains the output from the
/proc/scsi/sg/debug which is typically viewed by the command
cat /proc/scsi/sg/debug. Below is the (slightly
abridged) output while this command: sgp_dd if=/dev/sg0
of=/dev/null bs=512 is executing on the system. That sgp_dd
command is using command queuing to read a disk (and the data is
written to /dev/null which forgets it).
$ cat /proc/scsi/sg/debug
dev_max(currently)=7 max_active_device=1 (origin 1)
scsi_dma_free_sectors=416 sg_pool_secs_aval=320 def_reserved_size=32768
>>> device=sg0 scsi0 chan=0 id=0 lun=0 em=0 sg_tablesize=255 excl=0
FD(1): timeout=60000ms bufflen=65536 (res)sgat=2 low_dma=0
cmd_q=1 f_packid=1 k_orphan=0 closed=0
fin: id=3949312 blen=65536 dur=10ms sgat=2 op=0x28
act: id=3949440 blen=65536 t_o/elap=60000/10ms sgat=2 op=0x28
rb>> act: id=3949568 blen=65536 t_o/elap=60000/10ms sgat=2 op=0x28
act: id=3949696 blen=65536 t_o/elap=60000/0ms sgat=2 op=0x28
Those items output above that are significant to user applications are described below.
Broadly speaking the above output shows everything is going fine. Four SCSI READ(10) commands (SCSI opcode 0x28) for different ids are underway. Three commands are active while one is finished with its status and data read() and the request structure is pending deletion. The "id" corresponds to the pack_id given in the sg_io_hdr structure (or the sg_header structure). In the case if sgp_dd the pack_id value is the block number being given to the SCSI READ (or WRITE). You will notice the 4 ids are 128 apart.
The ">>>" line shows the sg device name followed by the linux scsi adapter, channel, scsi id and lun numbers. The "em=" argument indicates whether the driver emulates a SCSI HBA. The ide-scsi driver would set "em=1". The "sg_tablesize" is the maximum number of scatter gather elements supported by the adapter driver. The "excl=0" indicates no sg open() on this device is currently using the O_EXCL flag.
The next two lines starting with "FD(1)" supply data about the first
(and only in this case) open file descriptor on /dev/sg0
. The default timeout is 60 seconds however this is only
significant if the sg_header interface is being used since the
sg_io_hdr interface explicits sets the timeout on a per command basis.
"bufflen=65536" is the reserved buffer size for this file descriptor.
The "(res)sgat=2" indicates that this reserved buffer requires 2
scatter gather elements. The "low_dma" will be set to 1 for ISA HBAs
indicating only the bottom 16 MB of RAM can be used for its kernel
buffers. The "cmd_q=1" indicates command queuing is being allowed.
The "f_packid=1" indicates the SG_SET_FORCE_PACK_ID mode is on.
The "k_orphan" value is 1 in the rare cases when a SG_IO is interrupted
while a SCSI command is "in flight". The "closed" value is 1 in the
rare cases the file descriptor has been closed while a SCSI command
is "in flight".
Each line indented with 5 spaces represents a SCSI command. The state of the command is either:
prior: command hasn't been sent to mid level (rare)
act: mid level (adapter driver or device) has command
rcv: sg bottom half handler has received response to this command (awaiting read() or SG_IO ioctl to complete
fin: SCSI response (and optionally data) has been or is being read but the command data structures have not been removed
These states can be optionally prefixed by "rb>>" which means the reserved buffer is being used, "dio>>" which means this command is using direct IO, or "mmap>>" which means that mmap-ed IO is being used by this command. The "id" is the pack_id from this command's interface structure. The "blen" is the buffer length used by the data transfer associated with this command. For commands that a response has been received "dur" shows its duration in milliseconds. For commands still "in flight" an indication of "t_o/elap=60000/10ms" means this command has a timeout of 60000 milliseconds of which 10 milliseconds has already elapsed. The "sgat=2" argument indicates that this command's "blen" requires 2 scatter gather elements. The "op" value is the hexadecimal value of the SCSI command being executed.
If sg has lots of activity then the "debug" output may span many lines and in some cases appear to be corrupted. This occurs because procfs requests fixed buffer sizes of information and, if there is more data to output, returns later to get the remainder. The problem with this strategy is that sg's internal state may have changed. Rather than double buffering, the sg driver just continues from the same offset. While procfs is very useful, ioctl()s (such as SG_GET_REQUEST_TABLE) still have their place.
[20]
One strange quirk is that the /proc/scsi/sg directory
will not appear if there are no SCSI devices (or pseudo devices such as
USB mass storage) attached to the system. The reason for this is that
in the absence of SCSI devices, the SCSI mid level does not initialize
the sg driver (even if it has been loaded as a module).
When the sg driver is a module and the rmmod sg is
successfully executed then the /proc/scsi/sg directory
and its contents are removed.