Git Repo - linux.git/blame_incremental - Documentation/scsi/scsi-generic.rst

... / ...

Commit	Line	Data
	1	.. SPDX-License-Identifier: GPL-2.0
	2
	3	========================
	4	SCSI Generic (sg) driver
	5	========================
	6
	7	20020126
	8
	9	Introduction
	10	============
	11	The SCSI Generic driver (sg) is one of the four "high level" SCSI device
	12	drivers along with sd, st and sr (disk, tape and CD-ROM respectively). Sg
	13	is more generalized (but lower level) than its siblings and tends to be
	14	used on SCSI devices that don't fit into the already serviced categories.
	15	Thus sg is used for scanners, CD writers and reading audio CDs digitally
	16	amongst other things.
	17
	18	Rather than document the driver's interface here, version information
	19	is provided plus pointers (i.e. URLs) where to find documentation
	20	and examples.
	21
	22
	23	Major versions of the sg driver
	24	===============================
	25	There are three major versions of sg found in the Linux kernel (lk):
	26	- sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) .
	27	It is based in the sg_header interface structure.
	28	- sg version 2 from lk 2.2.6 in the 2.2 series. It is based on
	29	an extended version of the sg_header interface structure.
	30	- sg version 3 found in the lk 2.4 series (and the lk 2.5 series).
	31	It adds the sg_io_hdr interface structure.
	32
	33
	34	Sg driver documentation
	35	=======================
	36	The most recent documentation of the sg driver is kept at
	37
	38	- https://sg.danny.cz/sg/
	39
	40	This describes the sg version 3 driver found in the lk 2.4 series.
	41
	42	Documentation (large version) for the version 2 sg driver found in the
	43	lk 2.2 series can be found at
	44
	45	- https://sg.danny.cz/sg/p/scsi-generic_long.txt.
	46
	47	The original documentation for the sg driver (prior to lk 2.2.6) can be
	48	found in the LDP archives at
	49
	50	- https://tldp.org/HOWTO/archived/SCSI-Programming-HOWTO/index.html
	51
	52	A more general description of the Linux SCSI subsystem of which sg is a
	53	part can be found at https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO .
	54
	55
	56	Example code and utilities
	57	==========================
	58	There are two packages of sg utilities:
	59
	60	========= ==========================================================
	61	sg3_utils for the sg version 3 driver found in lk 2.4
	62	sg_utils for the sg version 2 (and original) driver found in lk 2.2
	63	and earlier
	64	========= ==========================================================
	65
	66	Both packages will work in the lk 2.4 series. However, sg3_utils offers more
	67	capabilities. They can be found at: https://sg.danny.cz/sg/sg3_utils.html and
	68	freecode.com
	69
	70	Another approach is to look at the applications that use the sg driver.
	71	These include cdrecord, cdparanoia, SANE and cdrdao.
	72
	73
	74	Mapping of Linux kernel versions to sg driver versions
	75	======================================================
	76	Here is a list of Linux kernels in the 2.4 series that had the new version
	77	of the sg driver:
	78
	79	- lk 2.4.0 : sg version 3.1.17
	80	- lk 2.4.7 : sg version 3.1.19
	81	- lk 2.4.10 : sg version 3.1.20 [#]_
	82	- lk 2.4.17 : sg version 3.1.22
	83
	84	.. [#] There were 3 changes to sg version 3.1.20 by third parties in the
	85	next six Linux kernel versions.
	86
	87	For reference here is a list of Linux kernels in the 2.2 series that had
	88	the new version of the sg driver:
	89
	90	- lk 2.2.0 : original sg version [with no version number]
	91	- lk 2.2.6 : sg version 2.1.31
	92	- lk 2.2.8 : sg version 2.1.32
	93	- lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared]
	94	- lk 2.2.14 : sg version 2.1.36
	95	- lk 2.2.16 : sg version 2.1.38
	96	- lk 2.2.17 : sg version 2.1.39
	97	- lk 2.2.20 : sg version 2.1.40
	98
	99	The lk 2.5 development series currently contains sg version 3.5.23
	100	which is functionally equivalent to sg version 3.1.22 found in lk 2.4.17.
	101
	102
	103	Douglas Gilbert
	104
	105	26th January 2002
	106
	107	[email protected]