The Linux SCSI Generic (sg) HOWTO

The Linux SCSI Generic (sg) HOWTO

Douglas Gilbert

dgilbert@interlog.com

Copyright (c) 2001, 2002 by Douglas Gilbert

2002-05-03

Revision HistoryRevision 1.22002-05-03Revised by: dpgENOMEM, EPERM; DRIVER_SENSE-bCHECK_CONDITIONRevision 1.12002-01-26Revised by: dpgcorrections, host_status, odd dxfer_lenRevision 1.02001-12-21Revised by: dpgoriginal, 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.

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.

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

Chapter 1. Introduction

This document outlines the Linux SCSI Generic (sg) driver interface as found in the 2.4 series kernels. The driver's purpose is to allow SCSI commands to be sent directly to SCSI devices. The responses of those commands can then be obtained. This type of driver is sometimes termed as a "pass through". In the case of SCSI disks, the block subsystem which is normally used to mount and access a disk, is bypassed permitting low level operations such as formatting to be performed. Various specialized applications for writing CD-Rs and document scanning use the sg driver.

Many devices that use other physical buses (e.g. ATAPI cdroms, USB mass storage devices and IEEE 1394 sbp2 devices) utilize the SCSI command set. By using Linux pseudo SCSI device drivers which bridge between the native protocol stack and the SCSI subsystem, the upper level SCSI device drivers, including sg, can be used to control "non-SCSI" devices.

This is the third major version of the sg driver. A summary of the sg driver history is as follows:

*

sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . A copy of the original HOWTO (in plain text) is at www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt

* *

sg version 2 from lk 2.2.6 in the 2.2 series. Its documentation is available in abridged form [www.torque.net/sg/p/scsi-generic.txt? and a longer form [www.torque.net/sg/p/scsi-generic_long.txt?.

* *

sg version 3 in the linux kernel 2.4 series.

* This document can be found at the Linux Documentation Project's site at www.linuxdoc.org/HOWTO/SCSI-Generic-HOWTO/ . It is available in plain text and pdf renderings at that site. A (possibly later) version of this document can be found at www.torque.net/sg/p/sg_v3_ho.html. That is a single html page; drop the ".html" extension for multi-page html. There are also postscript, pdf and rtf renderings from the original SGML (docbook) file at the same location.

A more general description of the Linux SCSI subsystem of which sg is a part can be found in the

SCSI-2.4-HOWTO.

This document was last modified on 3rd May 2002.

Chapter 2. What the sg driver does

The sg driver permits user applications to send SCSI commands to devices that understand them. SCSI commands are 6, 10, 12 or 16 bytes long [1?. The SCSI disk driver (sd), once device initialization is complete, only sends SCSI READ and WRITE commands. There a several other interesting things one might want to do, for example, perform a low level format or turn on write caching.

Associated with some SCSI commands there is data to be written to the device. A SCSI WRITE command is one obvious example. When instructed, the sg driver arranges for data to be transferred to the device along with the SCSI command. It is possible that the lower level driver (often known as the "Host Bus Adapter" [HBA? or simply "adapter" driver) is unable to send the command to the device. An example of this occurs when the device does not respond in which case a 'host_status' or 'driver-status' error will be conveyed back to the user application.

All going well the SCSI command (and optionally some data) are conveyed to the device. The device will respond with a single byte value called the 'scsi_status'. GOOD is the scsi status indicating everything has gone well. The most common other status is CHECK CONDITION. In this latter case, the SCSI mid level issues a REQUEST SENSE SCSI command The response of the REQUEST SENSE is 18 bytes or more in length and is called the "sense buffer". It will indicate why the original command may not have been executed. It is important to realize that a CHECK CONDITION may vary in severity from informative (e.g. command needed to be retried before succeeding) to fatal (e.g. "medium error" which often indicates it is time to replace the disk).

So in all cases a user application should check the various status values. If necessary the "sense buffer" will be copied back to the user application. SCSI commands like READ convey data back to the user application (if they succeed). The sg driver arranges for this data transfer from the device to the user space, if necessary.

The description so far has concentrated on a disk device, but in reality the sg driver is not needed very often for disks because there already is a purpose built device driver for that: sd. The same is true of reading audio and data CDs (sr [scd?) and tapes (st). However scanners that understand the SCSI command set and CDR "burning" programs tend to use the sg driver. Other applications include tape "robots" and music CD "ripping".

To find out more about SCSI (draft) standards and resources visit www.t10.org. To use the sg device driver you should be familiar with the SCSI commands supported by the device that you wish to control. Getting hold of such information for devices like scanners can be quite challenging (if the vendor does not provide it).

The first SCSI command sent to a SCSI device when it is initialized is an INQUIRY. All SCSI devices should respond promptly to an INQUIRY supplying information such as the vendor, product designation and revision. Appendix C shows the sg driver being used to send an INQUIRY and print out some of the information in the response.

Chapter 3. Identifying the version of the SG driver

Earlier versions of the sg device driver either have no version number (e.g. the original driver) or a version number starting with "2". The drivers that support this new interface have a major version number of "3". The sg version numbers are of the form "x.y.z" and the single number given by the SG_GET_VERSION_NUM ioctl() is calculated by (x * 10000 + y * 100 + z). The sg driver discussed here will yield a number greater than or equal to 30000 from SG_GET_VERSION_NUM. The version number can also be seen using cat /proc/scsi/sg/version in the new driver. This document describes sg version 3.1.24 for the lk 2.4 series. Where some facility has been added during the lk 2.4 series (e.g. mmap-ed IO) and hence is not available in all versions of the lk 2.4 series, this is noted. [2?

Here is a list of sg versions that have appeared to date during the lk 2.4 series.

*

lk 2.4.0 : sg version 3.1.17

* *

lk 2.4.7 : sg version 3.1.19

Fatal PhpWiki Error