Organize the SCSI documentation into categories instead of
alphabetically by filename.
Modify several of the document chapter headings so that they are
shorter and easier to find.
Make several updates to the scsi-generic driver documentation.
[PATCH 01/11] Docs/scsi: organize the SCSI documentation
[PATCH 02/11] Docs/scsi: introduction: multiple cleanups
[PATCH 03/11] Docs/scsi: arcmsr: use a chapter heading for clarity
[PATCH 04/11] Docs/scsi: scsi-changer: shorten the chapter heading
[PATCH 05/11] Docs/scsi: dc395x: shorten the chapter heading
[PATCH 06/11] Docs/scsi: scsi_fc_transport: fix typo in heading
[PATCH 07/11] Docs/scsi: scsi-generic: multiple cleanups
[PATCH 08/11] Docs/scsi: g_NCR5380: shorten chapter heading
[PATCH 09/11] Docs/scsi: megaraid: clarify chapter heading
[PATCH 10/11] Docs/scsi: ncr53c8xx: shorten chapter heading
[PATCH 11/11] Docs/scsi: sym53c8xx_2: shorten chapter heading
Documentation/scsi/arcmsr_spec.rst | 1
Documentation/scsi/dc395x.rst | 6 +-
Documentation/scsi/g_NCR5380.rst | 6 +-
Documentation/scsi/index.rst | 37 ++++++++++++--
Documentation/scsi/megaraid.rst | 6 +-
Documentation/scsi/ncr53c8xx.rst | 6 +-
Documentation/scsi/scsi-changer.rst | 6 +-
Documentation/scsi/scsi-generic.rst | 53 ++++++++-------------
Documentation/scsi/scsi.rst | 23 +++------
Documentation/scsi/scsi_fc_transport.rst | 8 +--
Documentation/scsi/sym53c8xx_2.rst | 6 +-
11 files changed, 86 insertions(+), 72 deletions(-)
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Gerd Knorr <[email protected]>
Cc: Oliver Neukum <[email protected]>
Cc: Ali Akcaagac <[email protected]>
Cc: Jamie Lenehan <[email protected]>
Cc: [email protected]
Cc: James Smart <[email protected]>
Cc: Doug Gilbert <[email protected]>
Cc: Finn Thain <[email protected]>
Cc: Michael Schmitz <[email protected]>
Cc: Kashyap Desai <[email protected]>
Cc: Sumit Saxena <[email protected]>
Cc: Shivasharan S <[email protected]>
Cc: [email protected]
Cc: Matthew Wilcox <[email protected]>
Include "Megaraid" in the chapter heading so that it is clear
what subject the document is about. This improves viewing in the TOC.
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Kashyap Desai <[email protected]>
Cc: Sumit Saxena <[email protected]>
Cc: Shivasharan S <[email protected]>
Cc: [email protected]
---
Documentation/scsi/megaraid.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff -- a/Documentation/scsi/megaraid.rst b/Documentation/scsi/megaraid.rst
--- a/Documentation/scsi/megaraid.rst
+++ b/Documentation/scsi/megaraid.rst
@@ -1,8 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
-==========================
-Notes on Management Module
-==========================
+=================================
+Megaraid Common Management Module
+=================================
Overview
--------
Make the heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Oliver Neukum <[email protected]>
Cc: Ali Akcaagac <[email protected]>
Cc: Jamie Lenehan <[email protected]>
Cc: [email protected]
---
Documentation/scsi/dc395x.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff -- a/Documentation/scsi/dc395x.rst b/Documentation/scsi/dc395x.rst
--- a/Documentation/scsi/dc395x.rst
+++ b/Documentation/scsi/dc395x.rst
@@ -1,8 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
-======================================
-README file for the dc395x SCSI driver
-======================================
+==================
+dc395x SCSI driver
+==================
Status
------
Make the heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Gerd Knorr <[email protected]>
---
Documentation/scsi/scsi-changer.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff -- a/Documentation/scsi/scsi-changer.rst b/Documentation/scsi/scsi-changer.rst
--- a/Documentation/scsi/scsi-changer.rst
+++ b/Documentation/scsi/scsi-changer.rst
@@ -1,8 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
-========================================
-README for the SCSI media changer driver
-========================================
+=========================
+SCSI media changer driver
+=========================
This is a driver for SCSI Medium Changer devices, which are listed
with "Type: Medium Changer" in /proc/scsi/scsi.
Make the chapter heading concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Matthew Wilcox <[email protected]>
---
Documentation/scsi/sym53c8xx_2.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff -- a/Documentation/scsi/sym53c8xx_2.rst b/Documentation/scsi/sym53c8xx_2.rst
--- a/Documentation/scsi/sym53c8xx_2.rst
+++ b/Documentation/scsi/sym53c8xx_2.rst
@@ -1,8 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
-=========================================
-The Linux SYM-2 driver documentation file
-=========================================
+============
+SYM-2 driver
+============
Written by Gerard Roudier <[email protected]>
Break the SCSI documentation up into categories:
Introduction, APIs, driver parameters, and host adapter drivers
instead of alphabetical by document file name (i.e., no organization).
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
---
Documentation/scsi/index.rst | 37 ++++++++++++++++++++++++++++-----
1 file changed, 32 insertions(+), 5 deletions(-)
diff -- a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst
--- a/Documentation/scsi/index.rst
+++ b/Documentation/scsi/index.rst
@@ -7,6 +7,38 @@ SCSI Subsystem
.. toctree::
:maxdepth: 1
+Introduction
+============
+
+.. toctree::
+ :maxdepth: 1
+
+ scsi
+
+SCSI driver APIs
+================
+
+.. toctree::
+ :maxdepth: 1
+
+ scsi_mid_low_api
+ scsi_eh
+
+SCSI driver parameters
+======================
+
+.. toctree::
+ :maxdepth: 1
+
+ scsi-parameters
+ link_power_management_policy
+
+SCSI host adapter drivers
+=========================
+
+.. toctree::
+ :maxdepth: 1
+
53c700
aacraid
advansys
@@ -25,7 +57,6 @@ SCSI Subsystem
hpsa
hptiop
libsas
- link_power_management_policy
lpfc
megaraid
ncr53c8xx
@@ -33,12 +64,8 @@ SCSI Subsystem
ppa
qlogicfas
scsi-changer
- scsi_eh
scsi_fc_transport
scsi-generic
- scsi_mid_low_api
- scsi-parameters
- scsi
sd-parameters
smartpqi
st
Make the chapter heading concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
---
Documentation/scsi/ncr53c8xx.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff -- a/Documentation/scsi/ncr53c8xx.rst b/Documentation/scsi/ncr53c8xx.rst
--- a/Documentation/scsi/ncr53c8xx.rst
+++ b/Documentation/scsi/ncr53c8xx.rst
@@ -1,8 +1,8 @@
.. SPDX-License-Identifier: GPL-2.0
-=================================================
-The Linux NCR53C8XX/SYM53C8XX drivers README file
-=================================================
+===========================
+NCR53C8XX/SYM53C8XX drivers
+===========================
Written by Gerard Roudier <[email protected]>
Make the chapter heading be concise yet still descriptive.
This makes the subsystem table of contents more readable (IMO).
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Cc: Finn Thain <[email protected]>
Cc: Michael Schmitz <[email protected]>
---
Documentation/scsi/g_NCR5380.rst | 6 +++---
1 file changed, 3 insertions(+), 3 deletions(-)
diff -- a/Documentation/scsi/g_NCR5380.rst b/Documentation/scsi/g_NCR5380.rst
--- a/Documentation/scsi/g_NCR5380.rst
+++ b/Documentation/scsi/g_NCR5380.rst
@@ -1,9 +1,9 @@
.. SPDX-License-Identifier: GPL-2.0
.. include:: <isonum.txt>
-==========================================
-README file for the Linux g_NCR5380 driver
-==========================================
+================
+g_NCR5380 driver
+================
Copyright |copy| 1993 Drew Eckhard
Modify URLs to use https instead of http.
Remove ancient URLs that don't work.
Change "scsi" in text to "SCSI".
Change "cdrom" in text to "CD-ROM".
Drop the reference to "autoclean" for modules since I can't
find it in any current documentation.
Signed-off-by: Randy Dunlap <[email protected]>
Cc: "James E.J. Bottomley" <[email protected]>
Cc: "Martin K. Petersen" <[email protected]>
Cc: [email protected]
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
---
Documentation/scsi/scsi.rst | 23 ++++++++++-------------
1 file changed, 10 insertions(+), 13 deletions(-)
diff -- a/Documentation/scsi/scsi.rst b/Documentation/scsi/scsi.rst
--- a/Documentation/scsi/scsi.rst
+++ b/Documentation/scsi/scsi.rst
@@ -6,30 +6,28 @@ SCSI subsystem documentation
The Linux Documentation Project (LDP) maintains a document describing
the SCSI subsystem in the Linux kernel (lk) 2.4 series. See:
-http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
+https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
and multiple page HTML renderings as well as postscript and pdf.
-It can also be found at:
-http://web.archive.org/web/%2E/http://www.torque.net/scsi/SCSI-2.4-HOWTO
Notes on using modules in the SCSI subsystem
============================================
-The scsi support in the linux kernel can be modularized in a number of
+The SCSI support in the Linux kernel can be modularized in a number of
different ways depending upon the needs of the end user. To understand
your options, we should first define a few terms.
-The scsi-core (also known as the "mid level") contains the core of scsi
-support. Without it you can do nothing with any of the other scsi drivers.
-The scsi core support can be a module (scsi_mod.o), or it can be built into
-the kernel. If the core is a module, it must be the first scsi module
+The scsi-core (also known as the "mid level") contains the core of SCSI
+support. Without it you can do nothing with any of the other SCSI drivers.
+The SCSI core support can be a module (scsi_mod.o), or it can be built into
+the kernel. If the core is a module, it must be the first SCSI module
loaded, and if you unload the modules, it will have to be the last one
-unloaded. In practice the modprobe and rmmod commands (and "autoclean")
+unloaded. In practice the modprobe and rmmod commands
will enforce the correct ordering of loading and unloading modules in
the SCSI subsystem.
The individual upper and lower level drivers can be loaded in any order
-once the scsi core is present in the kernel (either compiled in or loaded
-as a module). The disk driver (sd_mod.o), cdrom driver (sr_mod.o),
-tape driver [1]_ (st.o) and scsi generics driver (sg.o) represent the upper
+once the SCSI core is present in the kernel (either compiled in or loaded
+as a module). The disk driver (sd_mod.o), CD-ROM driver (sr_mod.o),
+tape driver [1]_ (st.o) and SCSI generics driver (sg.o) represent the upper
level drivers to support the various assorted devices which can be
controlled. You can for example load the tape driver to use the tape drive,
and then unload it once you have no further need for the driver (and release
@@ -44,4 +42,3 @@ built into the kernel.
.. [1] There is a variant of the st driver for controlling OnStream tape
devices. Its module name is osst.o .
-
On Thu, 18 May 2023, Randy Dunlap wrote:
> Modify URLs to use https instead of http.
> Remove ancient URLs that don't work.
> Change "scsi" in text to "SCSI".
> Change "cdrom" in text to "CD-ROM".
> Drop the reference to "autoclean" for modules since I can't
> find it in any current documentation.
>
> Signed-off-by: Randy Dunlap <[email protected]>
> Cc: "James E.J. Bottomley" <[email protected]>
> Cc: "Martin K. Petersen" <[email protected]>
> Cc: [email protected]
> Cc: Jonathan Corbet <[email protected]>
> Cc: [email protected]
> ---
> Documentation/scsi/scsi.rst | 23 ++++++++++-------------
> 1 file changed, 10 insertions(+), 13 deletions(-)
>
> diff -- a/Documentation/scsi/scsi.rst b/Documentation/scsi/scsi.rst
> --- a/Documentation/scsi/scsi.rst
> +++ b/Documentation/scsi/scsi.rst
> @@ -6,30 +6,28 @@ SCSI subsystem documentation
>
> The Linux Documentation Project (LDP) maintains a document describing
> the SCSI subsystem in the Linux kernel (lk) 2.4 series. See:
> -http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
> +https://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . The LDP has single
> and multiple page HTML renderings as well as postscript and pdf.
> -It can also be found at:
> -http://web.archive.org/web/%2E/http://www.torque.net/scsi/SCSI-2.4-HOWTO
>
That link got corrupted by commit b7223d9bdec. It used to be
http://web.archive.org/web/*/http://www.torque.net/scsi/SCSI-2.4-HOWTO
which does actually work.
FWIW, I'm not in favour of replacing any links with archive.org links
unless no better source can be found. I am in favour of citations in the
form of a link with retrieval date. In this context the date can often be
inferred from commit or release dates.
Therefore, a second commit, 0ea6e611221, could also be reverted with
regards to this link (if you're planning to edit it). Just my $0.02.
On Thu, 18 May 2023, Randy Dunlap wrote:
> Make the chapter heading be concise yet still descriptive.
> This makes the subsystem table of contents more readable (IMO).
>
> Signed-off-by: Randy Dunlap <[email protected]>
> Cc: "James E.J. Bottomley" <[email protected]>
> Cc: "Martin K. Petersen" <[email protected]>
> Cc: [email protected]
> Cc: Jonathan Corbet <[email protected]>
> Cc: [email protected]
> Cc: Finn Thain <[email protected]>
> Cc: Michael Schmitz <[email protected]>
Acked-by: Finn Thain <[email protected]>
> ---
> Documentation/scsi/g_NCR5380.rst | 6 +++---
> 1 file changed, 3 insertions(+), 3 deletions(-)
>
> diff -- a/Documentation/scsi/g_NCR5380.rst b/Documentation/scsi/g_NCR5380.rst
> --- a/Documentation/scsi/g_NCR5380.rst
> +++ b/Documentation/scsi/g_NCR5380.rst
> @@ -1,9 +1,9 @@
> .. SPDX-License-Identifier: GPL-2.0
> .. include:: <isonum.txt>
>
> -==========================================
> -README file for the Linux g_NCR5380 driver
> -==========================================
> +================
> +g_NCR5380 driver
> +================
>
> Copyright |copy| 1993 Drew Eckhard
>
>
Randy,
> Organize the SCSI documentation into categories instead of
> alphabetically by filename.
>
> Modify several of the document chapter headings so that they are
> shorter and easier to find.
>
> Make several updates to the scsi-generic driver documentation.
Applied to 6.5/scsi-staging, thanks!
--
Martin K. Petersen Oracle Linux Engineering
On Thu, 18 May 2023 14:27:38 -0700, Randy Dunlap wrote:
> Organize the SCSI documentation into categories instead of
> alphabetically by filename.
>
> Modify several of the document chapter headings so that they are
> shorter and easier to find.
>
> Make several updates to the scsi-generic driver documentation.
>
> [...]
Applied to 6.5/scsi-queue, thanks!
[01/11] Docs/scsi: organize the SCSI documentation
https://git.kernel.org/mkp/scsi/c/682b07d2ff54
[02/11] Docs/scsi: introduction: multiple cleanups
https://git.kernel.org/mkp/scsi/c/c4e672ac8c49
[03/11] Docs/scsi: arcmsr: use a chapter heading for clarity
https://git.kernel.org/mkp/scsi/c/1d3e21238f50
[04/11] Docs/scsi: scsi-changer: shorten the chapter heading
https://git.kernel.org/mkp/scsi/c/a292835f69c6
[05/11] Docs/scsi: dc395x: shorten the chapter heading
https://git.kernel.org/mkp/scsi/c/573a43f26d80
[06/11] Docs/scsi: scsi_fc_transport: fix typo in heading
https://git.kernel.org/mkp/scsi/c/66fcd6026c71
[07/11] Docs/scsi: scsi-generic: multiple cleanups
https://git.kernel.org/mkp/scsi/c/8ebddfeef518
[08/11] Docs/scsi: g_NCR5380: shorten chapter heading
https://git.kernel.org/mkp/scsi/c/b636a0297e4f
[09/11] Docs/scsi: megaraid: clarify chapter heading
https://git.kernel.org/mkp/scsi/c/0176d3395a3a
[10/11] Docs/scsi: ncr53c8xx: shorten chapter heading
https://git.kernel.org/mkp/scsi/c/7c891fe3db3a
[11/11] Docs/scsi: sym53c8xx_2: shorten chapter heading
https://git.kernel.org/mkp/scsi/c/f047d1e38bdf
--
Martin K. Petersen Oracle Linux Engineering
On 5/19/23 04:27, Randy Dunlap wrote:
> -======================================
> -README file for the dc395x SCSI driver
> -======================================
> +==================
> +dc395x SCSI driver
> +==================
>
Acked-by: Bagas Sanjaya <[email protected]>
--
An old man doll... just what I always wanted! - Clara