The Linux SCSI Generic (sg) HOWTO

The Linux SCSI Generic (sg) HOWTO

Douglas Gilbert

      [email protected]
     

Copyright © 2001, 2002 by Douglas Gilbert

2002-05-03

Revision History
Revision 1.2	2002-05-03	Revised by: dpg
ENOMEM, EPERM; DRIVER_SENSE->CHECK_CONDITION
Revision 1.1	2002-01-26	Revised by: dpg
corrections, host_status, odd dxfer_len
Revision 1.0	2001-12-21	Revised by: dpg
original, displace SCSI-PROGRAMMING-HOWTO

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

6.1. interface_id

6.2. dxfer_direction

6.3. cmd_len

6.4. mx_sb_len

6.5. iovec_count

6.6. dxfer_len

6.7. dxferp

6.8. cmdp

6.9. sbp

6.10. timeout

6.11. flags

6.12. pack_id

6.13. usr_ptr

6.14. status

6.15. masked_status

6.16. msg_status

6.17. sb_len_wr

6.18. host_status

6.19. driver_status

6.20. resid

6.21. duration

6.22. info

7. System calls

7.1. open()

7.2. write()

7.3. read()

7.4. poll()

7.5. close()

7.6. mmap()

7.7. fcntl(sg_fd, F_SETFL, oflags | FASYNC)

7.8. Errors reported in errno

8. Ioctl()s

8.1. SG_IO

8.2. SG_GET_ACCESS_COUNT

8.3. SG_SET_COMMAND_Q (and _GET_)

8.4. SG_SET_DEBUG

8.5. SG_EMULATED_HOST

8.6. SG_SET_KEEP_ORPHAN (and _GET_)

8.7. SG_SET_FORCE_LOW_DMA

8.8. SG_GET_LOW_DMA

8.9. SG_NEXT_CMD_LEN

8.10. SG_GET_NUM_WAITING

8.11. SG_SET_FORCE_PACK_ID

8.12. SG_GET_PACK_ID

8.13. SG_GET_REQUEST_TABLE

8.14. SG_SET_RESERVED_SIZE (and _GET_ )

8.15. SG_SCSI_RESET

8.16. SG_GET_SCSI_ID

8.17. SG_GET_SG_TABLESIZE

8.18. SG_GET_TIMEOUT

8.19. SG_SET_TIMEOUT

8.20. SG_SET_TRANSFORM

8.21. SG_GET_TRANSFORM

8.22. Sg ioctls removed in version 3

8.23. SCSI_IOCTL_GET_IDLUN

8.24. SCSI_IOCTL_GET_PCI

8.25. SCSI_IOCTL_PROBE_HOST

8.26. SCSI_IOCTL_SEND_COMMAND

9. Direct and Mmap-ed IO

9.1. Direct IO

9.2. Mmap-ed IO

10. Driver and module initialization

11. Sg and the "proc" file system

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