The Linux SCSI Generic (sg) HOWTO

Douglas Gilbert


      
     

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts.

For an online copy of the license see www.fsf.org/copyleft/fdl.html.

2005-09-22

Revision History
Revision 1.42005-09-22dpg
linuxdoc->tldp
Revision 1.32002-07-21dpg
convert to xml, autosense
Revision 1.22002-05-03dpg
ENOMEM, EPERM; DRIVER_SENSE->CHECK_CONDITION
Revision 1.12002-01-26dpg
corrections, host_status, odd dxfer_len
Revision 1.02001-12-21dpg
original, displace SCSI-PROGRAMMING-HOWTO

Abstract

This HOWTO describes the SCSI Generic driver (sg) found in the Linux 2.4 production series of kernels. It focuses on the the interface and characteristics of the driver that application writers may need to know. The driver's theory of operations is covered and some brief examples are included.


Table of Contents

1. Introduction
2. What the sg driver does
3. Identifying the version of the SG driver
4. Interface
5. Theory of operation
6. The sg_io_hdr_t structure in detail
interface_id
dxfer_direction
cmd_len
mx_sb_len
iovec_count
dxfer_len
dxferp
cmdp
sbp
timeout
flags
pack_id
usr_ptr
status
masked_status
msg_status
sb_len_wr
host_status
driver_status
resid
duration
info
7. System calls
open()
write()
read()
poll()
close()
mmap()
fcntl(sg_fd, F_SETFL, oflags | FASYNC)
Errors reported in errno
8. Ioctl()s
SG_IO
SG_GET_ACCESS_COUNT
SG_SET_COMMAND_Q (and _GET_)
SG_SET_DEBUG
SG_EMULATED_HOST
SG_SET_KEEP_ORPHAN (and _GET_)
SG_SET_FORCE_LOW_DMA
SG_GET_LOW_DMA
SG_NEXT_CMD_LEN
SG_GET_NUM_WAITING
SG_SET_FORCE_PACK_ID
SG_GET_PACK_ID
SG_GET_REQUEST_TABLE
SG_SET_RESERVED_SIZE (and _GET_ )
SG_SCSI_RESET
SG_GET_SCSI_ID
SG_GET_SG_TABLESIZE
SG_GET_TIMEOUT
SG_SET_TIMEOUT
SG_SET_TRANSFORM
SG_GET_TRANSFORM
Sg ioctls removed in version 3
SCSI_IOCTL_GET_IDLUN
SCSI_IOCTL_GET_PCI
SCSI_IOCTL_PROBE_HOST
SCSI_IOCTL_SEND_COMMAND
9. Direct and Mmap-ed IO
Direct IO
Mmap-ed IO
10. Driver and module initialization
11. Sg and the "proc" file system
/proc/scsi/sg/debug
12. Asynchronous usage of sg
A. Sg3_utils package
B. sg_header, the original sg control structure
C. Programming example
D. Debugging
E. Other references