Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

scsi: docs: scsi-generic: Multiple cleanups

Make the heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).

Spell "CDROM" as "CD-ROM".
Capitalize "Linux".

Use https instead of http for URLs.

Drop the Linux Documentation Project URL for the SCSI generic HOWTO
since it hasn't been updated since 2002. Use Doug Gilbert's URL
for it instead.

Drop some outdated documentation & references.

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20230518212749.18266-8-rdunlap@infradead.org
Cc: "James E.J. Bottomley" <jejb@linux.ibm.com>
Cc: "Martin K. Petersen" <martin.petersen@oracle.com>
Cc: linux-scsi@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Cc: Doug Gilbert <dgilbert@interlog.com>
Signed-off-by: Martin K. Petersen <martin.petersen@oracle.com>

authored by

Randy Dunlap and committed by
Martin K. Petersen
8ebddfee 66fcd602

+21 -32
+21 -32
Documentation/scsi/scsi-generic.rst
··· 1 1 .. SPDX-License-Identifier: GPL-2.0 2 2 3 - ======================================= 4 - Notes on Linux SCSI Generic (sg) driver 5 - ======================================= 3 + ======================== 4 + SCSI Generic (sg) driver 5 + ======================== 6 6 7 7 20020126 8 8 9 9 Introduction 10 10 ============ 11 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 CDROM respectively). Sg 12 + drivers along with sd, st and sr (disk, tape and CD-ROM respectively). Sg 13 13 is more generalized (but lower level) than its siblings and tends to be 14 14 used on SCSI devices that don't fit into the already serviced categories. 15 15 Thus sg is used for scanners, CD writers and reading audio CDs digitally ··· 22 22 23 23 Major versions of the sg driver 24 24 =============================== 25 - There are three major versions of sg found in the linux kernel (lk): 25 + There are three major versions of sg found in the Linux kernel (lk): 26 26 - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . 27 27 It is based in the sg_header interface structure. 28 28 - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on ··· 33 33 34 34 Sg driver documentation 35 35 ======================= 36 - The most recent documentation of the sg driver is kept at the Linux 37 - Documentation Project's (LDP) site: 36 + The most recent documentation of the sg driver is kept at 38 37 39 - - http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO 38 + - https://sg.danny.cz/sg/ 40 39 41 40 This describes the sg version 3 driver found in the lk 2.4 series. 42 41 43 - The LDP renders documents in single and multiple page HTML, postscript 44 - and pdf. This document can also be found at: 42 + Documentation (large version) for the version 2 sg driver found in the 43 + lk 2.2 series can be found at 45 44 46 - - http://sg.danny.cz/sg/p/sg_v3_ho.html 47 - 48 - Documentation for the version 2 sg driver found in the lk 2.2 series can 49 - be found at http://sg.danny.cz/sg/. A larger version 50 - is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. 45 + - https://sg.danny.cz/sg/p/scsi-generic_long.txt. 51 46 52 47 The original documentation for the sg driver (prior to lk 2.2.6) can be 53 - found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt 54 - and in the LDP archives. 48 + found in the LDP archives at 55 49 56 - A changelog with brief notes can be found in the 57 - /usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy 58 - and edit this file (removing its changelog for example) before placing it 59 - in /usr/include/scsi/sg.h . Driver debugging information and other notes 60 - can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file. 50 + - https://tldp.org/HOWTO/archived/SCSI-Programming-HOWTO/index.html 61 51 62 52 A more general description of the Linux SCSI subsystem of which sg is a 63 - part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . 53 + part can be found at https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . 64 54 65 55 66 56 Example code and utilities ··· 63 73 and earlier 64 74 ========= ========================================================== 65 75 66 - Both packages will work in the lk 2.4 series however sg3_utils offers more 67 - capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and 76 + Both packages will work in the lk 2.4 series. However, sg3_utils offers more 77 + capabilities. They can be found at: https://sg.danny.cz/sg/sg3_utils.html and 68 78 freecode.com 69 79 70 80 Another approach is to look at the applications that use the sg driver. ··· 73 83 74 84 Mapping of Linux kernel versions to sg driver versions 75 85 ====================================================== 76 - Here is a list of linux kernels in the 2.4 series that had new version 86 + Here is a list of Linux kernels in the 2.4 series that had the new version 77 87 of the sg driver: 78 88 79 89 - lk 2.4.0 : sg version 3.1.17 ··· 82 92 - lk 2.4.17 : sg version 3.1.22 83 93 84 94 .. [#] There were 3 changes to sg version 3.1.20 by third parties in the 85 - next six linux kernel versions. 95 + next six Linux kernel versions. 86 96 87 - For reference here is a list of linux kernels in the 2.2 series that had 88 - new version of the sg driver: 97 + For reference here is a list of Linux kernels in the 2.2 series that had 98 + the new version of the sg driver: 89 99 90 100 - lk 2.2.0 : original sg version [with no version number] 91 101 - lk 2.2.6 : sg version 2.1.31 ··· 96 106 - lk 2.2.17 : sg version 2.1.39 97 107 - lk 2.2.20 : sg version 2.1.40 98 108 99 - The lk 2.5 development series has recently commenced and it currently 100 - contains sg version 3.5.23 which is functionally equivalent to sg 101 - version 3.1.22 found in lk 2.4.17. 109 + The lk 2.5 development series currently contains sg version 3.5.23 110 + which is functionally equivalent to sg version 3.1.22 found in lk 2.4.17. 102 111 103 112 104 113 Douglas Gilbert