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
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
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.