From d4d79340fb7b3f6e9d69a47304b165207145b6d1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:16:03 +0100 Subject: scsi: docs: convert scsi-generic.txt to ReST Link: https://lore.kernel.org/r/f57b8ddf30397c2c7213e49634e5e9cbd4246368.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/scsi-generic.rst | 118 ++++++++++++++++++++++++++++++++++++ Documentation/scsi/scsi-generic.txt | 101 ------------------------------ MAINTAINERS | 2 +- drivers/scsi/Kconfig | 2 +- include/scsi/sg.h | 2 +- 6 files changed, 122 insertions(+), 104 deletions(-) create mode 100644 Documentation/scsi/scsi-generic.rst delete mode 100644 Documentation/scsi/scsi-generic.txt diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 471982ef461d..119280f26da6 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -34,5 +34,6 @@ Linux SCSI Subsystem scsi-changer scsi_eh scsi_fc_transport + scsi-generic scsi_transport_srp/figures diff --git a/Documentation/scsi/scsi-generic.rst b/Documentation/scsi/scsi-generic.rst new file mode 100644 index 000000000000..258505e557a6 --- /dev/null +++ b/Documentation/scsi/scsi-generic.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Notes on Linux SCSI Generic (sg) driver +======================================= + + 20020126 + +Introduction +============ +The SCSI Generic driver (sg) is one of the four "high level" SCSI device +drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg +is more generalized (but lower level) than its siblings and tends to be +used on SCSI devices that don't fit into the already serviced categories. +Thus sg is used for scanners, CD writers and reading audio CDs digitally +amongst other things. + +Rather than document the driver's interface here, version information +is provided plus pointers (i.e. URLs) where to find documentation +and examples. + + +Major versions of the sg driver +=============================== +There are three major versions of sg found in the linux kernel (lk): + - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . + It is based in the sg_header interface structure. + - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on + an extended version of the sg_header interface structure. + - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). + It adds the sg_io_hdr interface structure. + + +Sg driver documentation +======================= +The most recent documentation of the sg driver is kept at the Linux +Documentation Project's (LDP) site: + +- http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO + +This describes the sg version 3 driver found in the lk 2.4 series. + +The LDP renders documents in single and multiple page HTML, postscript +and pdf. This document can also be found at: + +- http://sg.danny.cz/sg/p/sg_v3_ho.html + +Documentation for the version 2 sg driver found in the lk 2.2 series can +be found at http://sg.danny.cz/sg/. A larger version +is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. + +The original documentation for the sg driver (prior to lk 2.2.6) can be +found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt +and in the LDP archives. + +A changelog with brief notes can be found in the +/usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy +and edit this file (removing its changelog for example) before placing it +in /usr/include/scsi/sg.h . Driver debugging information and other notes +can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file. + +A more general description of the Linux SCSI subsystem of which sg is a +part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . + + +Example code and utilities +========================== +There are two packages of sg utilities: + + ========= ========================================================== + sg3_utils for the sg version 3 driver found in lk 2.4 + sg_utils for the sg version 2 (and original) driver found in lk 2.2 + and earlier + ========= ========================================================== + +Both packages will work in the lk 2.4 series however sg3_utils offers more +capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and +freecode.com + +Another approach is to look at the applications that use the sg driver. +These include cdrecord, cdparanoia, SANE and cdrdao. + + +Mapping of Linux kernel versions to sg driver versions +====================================================== +Here is a list of linux kernels in the 2.4 series that had new version +of the sg driver: + + - lk 2.4.0 : sg version 3.1.17 + - lk 2.4.7 : sg version 3.1.19 + - lk 2.4.10 : sg version 3.1.20 [#]_ + - lk 2.4.17 : sg version 3.1.22 + +.. [#] There were 3 changes to sg version 3.1.20 by third parties in the + next six linux kernel versions. + +For reference here is a list of linux kernels in the 2.2 series that had +new version of the sg driver: + + - lk 2.2.0 : original sg version [with no version number] + - lk 2.2.6 : sg version 2.1.31 + - lk 2.2.8 : sg version 2.1.32 + - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared] + - lk 2.2.14 : sg version 2.1.36 + - lk 2.2.16 : sg version 2.1.38 + - lk 2.2.17 : sg version 2.1.39 + - lk 2.2.20 : sg version 2.1.40 + +The lk 2.5 development series has recently commenced and it currently +contains sg version 3.5.23 which is functionally equivalent to sg +version 3.1.22 found in lk 2.4.17. + + +Douglas Gilbert + +26th January 2002 + +dgilbert@interlog.com diff --git a/Documentation/scsi/scsi-generic.txt b/Documentation/scsi/scsi-generic.txt deleted file mode 100644 index 51be20a6a14d..000000000000 --- a/Documentation/scsi/scsi-generic.txt +++ /dev/null @@ -1,101 +0,0 @@ - Notes on Linux SCSI Generic (sg) driver - --------------------------------------- - 20020126 -Introduction -============ -The SCSI Generic driver (sg) is one of the four "high level" SCSI device -drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg -is more generalized (but lower level) than its siblings and tends to be -used on SCSI devices that don't fit into the already serviced categories. -Thus sg is used for scanners, CD writers and reading audio CDs digitally -amongst other things. - -Rather than document the driver's interface here, version information -is provided plus pointers (i.e. URLs) where to find documentation -and examples. - - -Major versions of the sg driver -=============================== -There are three major versions of sg found in the linux kernel (lk): - - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . - It is based in the sg_header interface structure. - - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on - an extended version of the sg_header interface structure. - - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). - It adds the sg_io_hdr interface structure. - - -Sg driver documentation -======================= -The most recent documentation of the sg driver is kept at the Linux -Documentation Project's (LDP) site: -http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO -This describes the sg version 3 driver found in the lk 2.4 series. -The LDP renders documents in single and multiple page HTML, postscript -and pdf. This document can also be found at: -http://sg.danny.cz/sg/p/sg_v3_ho.html - -Documentation for the version 2 sg driver found in the lk 2.2 series can -be found at http://sg.danny.cz/sg/. A larger version -is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. - -The original documentation for the sg driver (prior to lk 2.2.6) can be -found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt -and in the LDP archives. - -A changelog with brief notes can be found in the -/usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy -and edit this file (removing its changelog for example) before placing it -in /usr/include/scsi/sg.h . Driver debugging information and other notes -can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file. - -A more general description of the Linux SCSI subsystem of which sg is a -part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . - - -Example code and utilities -========================== -There are two packages of sg utilities: - - sg3_utils for the sg version 3 driver found in lk 2.4 - - sg_utils for the sg version 2 (and original) driver found in lk 2.2 - and earlier -Both packages will work in the lk 2.4 series however sg3_utils offers more -capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and -freecode.com - -Another approach is to look at the applications that use the sg driver. -These include cdrecord, cdparanoia, SANE and cdrdao. - - -Mapping of Linux kernel versions to sg driver versions -====================================================== -Here is a list of linux kernels in the 2.4 series that had new version -of the sg driver: - lk 2.4.0 : sg version 3.1.17 - lk 2.4.7 : sg version 3.1.19 - lk 2.4.10 : sg version 3.1.20 ** - lk 2.4.17 : sg version 3.1.22 - -** There were 3 changes to sg version 3.1.20 by third parties in the - next six linux kernel versions. - -For reference here is a list of linux kernels in the 2.2 series that had -new version of the sg driver: - lk 2.2.0 : original sg version [with no version number] - lk 2.2.6 : sg version 2.1.31 - lk 2.2.8 : sg version 2.1.32 - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared] - lk 2.2.14 : sg version 2.1.36 - lk 2.2.16 : sg version 2.1.38 - lk 2.2.17 : sg version 2.1.39 - lk 2.2.20 : sg version 2.1.40 - -The lk 2.5 development series has recently commenced and it currently -contains sg version 3.5.23 which is functionally equivalent to sg -version 3.1.22 found in lk 2.4.17 . - - -Douglas Gilbert -26th January 2002 -dgilbert@interlog.com diff --git a/MAINTAINERS b/MAINTAINERS index 5a831cc4916f..af7cc8b330c4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14797,7 +14797,7 @@ M: Doug Gilbert L: linux-scsi@vger.kernel.org W: http://sg.danny.cz/sg S: Maintained -F: Documentation/scsi/scsi-generic.txt +F: Documentation/scsi/scsi-generic.rst F: drivers/scsi/sg.c F: include/scsi/sg.h diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig index 6cb9abb0898d..bdf65b0bb78b 100644 --- a/drivers/scsi/Kconfig +++ b/drivers/scsi/Kconfig @@ -133,7 +133,7 @@ config CHR_DEV_SG quality digital reader of audio CDs (). For other devices, it's possible that you'll have to write the driver software yourself. Please read the file - for more information. + for more information. To compile this driver as a module, choose M here and read . The module will be called sg. diff --git a/include/scsi/sg.h b/include/scsi/sg.h index 29c7ad04d2e2..7327e12f3373 100644 --- a/include/scsi/sg.h +++ b/include/scsi/sg.h @@ -24,7 +24,7 @@ * http://sg.danny.cz/sg [alternatively check the MAINTAINERS file] * The documentation for the sg version 3 driver can be found at: * http://sg.danny.cz/sg/p/sg_v3_ho.html - * Also see: /Documentation/scsi/scsi-generic.txt + * Also see: /Documentation/scsi/scsi-generic.rst * * For utility and test programs see: http://sg.danny.cz/sg/sg3_utils.html */ -- cgit v1.2.3