Merge tag 'scsi-misc' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi

Pull SCSI updates from James Bottomley:
 "This series has a huge amount of churn because it pulls in Mauro's doc
  update changing all our txt files to rst ones.

  Excluding that, we have the usual driver updates (qla2xxx, ufs, lpfc,
  zfcp, ibmvfc, pm80xx, aacraid), a treewide update for scnprintf and
  some other minor updates.

  The major core change is Hannes moving functions out of the aacraid
  driver and into the core"

* tag 'scsi-misc' of git://git.kernel.org/pub/scm/linux/kernel/git/jejb/scsi: (223 commits)
  scsi: aic7xxx: aic97xx: Remove FreeBSD-specific code
  scsi: ufs: Do not rely on prefetched data
  scsi: dc395x: remove dc395x_bios_param
  scsi: libiscsi: Fix error count for active session
  scsi: hpsa: correct race condition in offload enabled
  scsi: message: fusion: Replace zero-length array with flexible-array member
  scsi: qedi: Add PCI shutdown handler support
  scsi: qedi: Add MFW error recovery process
  scsi: ufs: Enable block layer runtime PM for well-known logical units
  scsi: ufs-qcom: Override devfreq parameters
  scsi: ufshcd: Let vendor override devfreq parameters
  scsi: ufshcd: Update the set frequency to devfreq
  scsi: ufs: Resume ufs host before accessing ufs device
  scsi: ufs-mediatek: customize the delay for enabling host
  scsi: ufs: make HCE polling more compact to improve initialization latency
  scsi: ufs: allow custom delay prior to host enabling
  scsi: ufs-mediatek: use common delay function
  scsi: ufs: introduce common and flexible delay function
  scsi: ufs: use an enum for host capabilities
  scsi: ufs: fix uninitialized tx_lanes in ufshcd_disable_tx_lcc()
  ...

56 files changed, 7051 insertions, 5328 deletions

diff --git a/Documentation/driver-api/libata.rst b/Documentation/driver-api/libata.rst
index 207f0d24de69..e2f87b82b074 100644
--- a/Documentation/driver-api/libata.rst
+++ b/Documentation/driver-api/libata.rst
@@ -401,7 +401,7 @@ Error handling
 ==============
 
 This chapter describes how errors are handled under libata. Readers are
-advised to read SCSI EH (Documentation/scsi/scsi_eh.txt) and ATA
+advised to read SCSI EH (Documentation/scsi/scsi_eh.rst) and ATA
 exceptions doc first.
 
 Origins of commands
diff --git a/Documentation/index.rst b/Documentation/index.rst
index 9df95bab4de8..01795a40da29 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -131,6 +131,7 @@ needed).
    bpf/index
    usb/index
    PCI/index
+   scsi/index
    misc-devices/index
    scheduler/index
 
diff --git a/Documentation/scsi/53c700.txt b/Documentation/scsi/53c700.rst
index e31aceb6df15..53a0e9f9c198 100644
--- a/Documentation/scsi/53c700.txt
+++ b/Documentation/scsi/53c700.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+The 53c700 Driver Notes
+=======================
+
 General Description
 ===================
 
@@ -16,9 +22,9 @@ fill in to get the driver working.
 Compile Time Flags
 ==================
 
-A compile time flag is:
+A compile time flag is::
 
-CONFIG_53C700_LE_ON_BE
+	CONFIG_53C700_LE_ON_BE
 
 define if the chipset must be supported in little endian mode on a big
 endian architecture (used for the 700 on parisc).
@@ -51,9 +57,11 @@ consistent with the best operation of the chip (although some choose
 to drive it off the CPU or bus clock rather than going to the expense
 of an extra clock chip).  The best operation clock speeds are:
 
-53c700 - 25MHz
-53c700-66 - 50MHz
-53c710 - 40Mhz
+=========  =====
+53c700     25MHz
+53c700-66  50MHz
+53c710     40Mhz
+=========  =====
 
 Writing Your Glue Driver
 ========================
@@ -69,7 +77,7 @@ parameters that matter to you (see below), plumb the NCR_700_intr
 routine into the interrupt line and call NCR_700_detect with the host
 template and the new parameters as arguments.  You should also call
 the relevant request_*_region function and place the register base
-address into the `base' pointer of the host parameters.
+address into the 'base' pointer of the host parameters.
 
 In the release routine, you must free the NCR_700_Host_Parameters that
 you allocated, call the corresponding release_*_region and free the
@@ -78,7 +86,7 @@ interrupt.
 Handling Interrupts
 -------------------
 
-In general, you should just plumb the card's interrupt line in with 
+In general, you should just plumb the card's interrupt line in with
 
 request_irq(irq, NCR_700_intr, <irq flags>, <driver name>, host);
 
@@ -95,41 +103,32 @@ Settable NCR_700_Host_Parameters
 The following are a list of the user settable parameters:
 
 clock: (MANDATORY)
-
-Set to the clock speed of the chip in MHz.
+  Set to the clock speed of the chip in MHz.
 
 base: (MANDATORY)
-
-set to the base of the io or mem region for the register set. On 64
-bit architectures this is only 32 bits wide, so the registers must be
-mapped into the low 32 bits of memory.
+  Set to the base of the io or mem region for the register set. On 64
+  bit architectures this is only 32 bits wide, so the registers must be
+  mapped into the low 32 bits of memory.
 
 pci_dev: (OPTIONAL)
-
-set to the PCI board device.  Leave NULL for a non-pci board.  This is
-used for the pci_alloc_consistent() and pci_map_*() functions.
+  Set to the PCI board device.  Leave NULL for a non-pci board.  This is
+  used for the pci_alloc_consistent() and pci_map_*() functions.
 
 dmode_extra: (OPTIONAL, 53c710 only)
-
-extra flags for the DMODE register.  These are used to control bus
-output pins on the 710.  The settings should be a combination of
-DMODE_FC1 and DMODE_FC2.  What these pins actually do is entirely up
-to the board designer.  Usually it is safe to ignore this setting.
+  Extra flags for the DMODE register.  These are used to control bus
+  output pins on the 710.  The settings should be a combination of
+  DMODE_FC1 and DMODE_FC2.  What these pins actually do is entirely up
+  to the board designer.  Usually it is safe to ignore this setting.
 
 differential: (OPTIONAL)
-
-set to 1 if the chip drives a differential bus.
+  Set to 1 if the chip drives a differential bus.
 
 force_le_on_be: (OPTIONAL, only if CONFIG_53C700_LE_ON_BE is set)
-
-set to 1 if the chip is operating in little endian mode on a big
-endian architecture.
+  Set to 1 if the chip is operating in little endian mode on a big
+  endian architecture.
 
 chip710: (OPTIONAL)
-
-set to 1 if the chip is a 53c710.
+  Set to 1 if the chip is a 53c710.
 
 burst_disable: (OPTIONAL, 53c710 only)
-
-disable 8 byte bursting for DMA transfers.
-
+  Disable 8 byte bursting for DMA transfers.
diff --git a/Documentation/scsi/BusLogic.txt b/Documentation/scsi/BusLogic.rst
index 48e982cd6fe7..b60169812358 100644
--- a/Documentation/scsi/BusLogic.txt
+++ b/Documentation/scsi/BusLogic.rst
@@ -1,6 +1,11 @@
-	   BusLogic MultiMaster and FlashPoint SCSI Driver for Linux
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================================================
+BusLogic MultiMaster and FlashPoint SCSI Driver for Linux
+=========================================================
 
 			 Version 2.0.15 for Linux 2.0
+
 			 Version 2.1.15 for Linux 2.1
 
 			      PRODUCTION RELEASE
@@ -8,13 +13,16 @@
 				17 August 1998
 
 			       Leonard N. Zubkoff
+
 			       Dandelion Digital
+
 			       lnz@dandelion.com
 
 	 Copyright 1995-1998 by Leonard N. Zubkoff <lnz@dandelion.com>
 
 
-				 INTRODUCTION
+Introduction
+============
 
 BusLogic, Inc. designed and manufactured a variety of high performance SCSI
 host adapters which share a common programming interface across a diverse
@@ -86,9 +94,11 @@ Contact information for offices in Europe and Japan is available on the Web
 site.
 
 
-				DRIVER FEATURES
+Driver Features
+===============
 
-o Configuration Reporting and Testing
+Configuration Reporting and Testing
+-----------------------------------
 
   During system initialization, the driver reports extensively on the host
   adapter hardware configuration, including the synchronous transfer parameters
@@ -130,7 +140,8 @@ o Configuration Reporting and Testing
     The status of Wide Negotiation, Disconnect/Reconnect, and Tagged Queuing
     are reported as "Enabled", Disabled", or a sequence of "Y" and "N" letters.
 
-o Performance Features
+Performance Features
+--------------------
 
   BusLogic SCSI Host Adapters directly implement SCSI-2 Tagged Queuing, and so
   support has been included in the driver to utilize tagged queuing with any
@@ -150,7 +161,8 @@ o Performance Features
   queue depth of 1 is selected.  Tagged queuing is also disabled for individual
   target devices if disconnect/reconnect is disabled for that device.
 
-o Robustness Features
+Robustness Features
+-------------------
 
   The driver implements extensive error recovery procedures.  When the higher
   level parts of the SCSI subsystem request that a timed out command be reset,
@@ -174,7 +186,8 @@ o Robustness Features
   lock up or crash, and thereby allowing a clean shutdown and restart after the
   offending component is removed.
 
-o PCI Configuration Support
+PCI Configuration Support
+-------------------------
 
   On PCI systems running kernels compiled with PCI BIOS support enabled, this
   driver will interrogate the PCI configuration space and use the I/O port
@@ -184,19 +197,22 @@ o PCI Configuration Support
   used to disable the ISA compatible I/O port entirely as it is not necessary.
   The ISA compatible I/O port is disabled by default on the BT-948/958/958D.
 
-o /proc File System Support
+/proc File System Support
+-------------------------
 
   Copies of the host adapter configuration information together with updated
   data transfer and error recovery statistics are available through the
   /proc/scsi/BusLogic/<N> interface.
 
-o Shared Interrupts Support
+Shared Interrupts Support
+-------------------------
 
   On systems that support shared interrupts, any number of BusLogic Host
   Adapters may share the same interrupt request channel.
 
 
-			    SUPPORTED HOST ADAPTERS
+Supported Host Adapters
+=======================
 
 The following list comprises the supported BusLogic SCSI Host Adapters as of
 the date of this document.  It is recommended that anyone purchasing a BusLogic
@@ -205,6 +221,7 @@ that it is or will be supported.
 
 FlashPoint Series PCI Host Adapters:
 
+=======================	=============================================
 FlashPoint LT (BT-930)	Ultra SCSI-3
 FlashPoint LT (BT-930R)	Ultra SCSI-3 with RAIDPlus
 FlashPoint LT (BT-920)	Ultra SCSI-3 (BT-930 without BIOS)
@@ -214,15 +231,19 @@ FlashPoint LW (BT-950)	Wide Ultra SCSI-3
 FlashPoint LW (BT-950R)	Wide Ultra SCSI-3 with RAIDPlus
 FlashPoint DW (BT-952)	Dual Channel Wide Ultra SCSI-3
 FlashPoint DW (BT-952R)	Dual Channel Wide Ultra SCSI-3 with RAIDPlus
+=======================	=============================================
 
 MultiMaster "W" Series Host Adapters:
 
+=======     ===		==============================
 BT-948	    PCI		Ultra SCSI-3
 BT-958	    PCI		Wide Ultra SCSI-3
 BT-958D	    PCI		Wide Differential Ultra SCSI-3
+=======     ===		==============================
 
 MultiMaster "C" Series Host Adapters:
 
+========    ====	==============================
 BT-946C	    PCI		Fast SCSI-2
 BT-956C	    PCI		Wide Fast SCSI-2
 BT-956CD    PCI		Wide Differential Fast SCSI-2
@@ -232,9 +253,11 @@ BT-757C	    EISA	Wide Fast SCSI-2
 BT-757CD    EISA	Wide Differential Fast SCSI-2
 BT-545C	    ISA		Fast SCSI-2
 BT-540CF    ISA		Fast SCSI-2
+========    ====	==============================
 
 MultiMaster "S" Series Host Adapters:
 
+=======     ====	==============================
 BT-445S	    VLB		Fast SCSI-2
 BT-747S	    EISA	Fast SCSI-2
 BT-747D	    EISA	Differential Fast SCSI-2
@@ -244,11 +267,14 @@ BT-545S	    ISA		Fast SCSI-2
 BT-542D	    ISA		Differential Fast SCSI-2
 BT-742A	    EISA	SCSI-2 (742A revision H)
 BT-542B	    ISA		SCSI-2 (542B revision H)
+=======     ====	==============================
 
 MultiMaster "A" Series Host Adapters:
 
+=======     ====	==============================
 BT-742A	    EISA	SCSI-2 (742A revisions A - G)
 BT-542B	    ISA		SCSI-2 (542B revisions A - G)
+=======     ====	==============================
 
 AMI FastDisk Host Adapters that are true BusLogic MultiMaster clones are also
 supported by this driver.
@@ -260,9 +286,11 @@ list.  The retail kit includes the bare board and manual as well as cabling and
 driver media and documentation that are not provided with bare boards.
 
 
-			 FLASHPOINT INSTALLATION NOTES
+FlashPoint Installation Notes
+=============================
 
-o RAIDPlus Support
+RAIDPlus Support
+----------------
 
   FlashPoint Host Adapters now include RAIDPlus, Mylex's bootable software
   RAID.  RAIDPlus is not supported on Linux, and there are no plans to support
@@ -273,7 +301,8 @@ o RAIDPlus Support
   than RAIDPlus, so there is little impetus to include RAIDPlus support in the
   BusLogic driver.
 
-o Enabling UltraSCSI Transfers
+Enabling UltraSCSI Transfers
+----------------------------
 
   FlashPoint Host Adapters ship with their configuration set to "Factory
   Default" settings that are conservative and do not allow for UltraSCSI speed
@@ -287,12 +316,14 @@ o Enabling UltraSCSI Transfers
   the "Optimum Performance" settings are loaded.
 
 
-		      BT-948/958/958D INSTALLATION NOTES
+BT-948/958/958D Installation Notes
+==================================
 
 The BT-948/958/958D PCI Ultra SCSI Host Adapters have some features which may
 require attention in some circumstances when installing Linux.
 
-o PCI I/O Port Assignments
+PCI I/O Port Assignments
+------------------------
 
   When configured to factory default settings, the BT-948/958/958D will only
   recognize the PCI I/O port assignments made by the motherboard's PCI BIOS.
@@ -312,7 +343,8 @@ o PCI I/O Port Assignments
   possible future I/O port conflicts.  The older BT-946C/956C/956CD also have
   this configuration option, but the factory default setting is "Primary".
 
-o PCI Slot Scanning Order
+PCI Slot Scanning Order
+-----------------------
 
   In systems with multiple BusLogic PCI Host Adapters, the order in which the
   PCI slots are scanned may appear reversed with the BT-948/958/958D as
@@ -339,7 +371,8 @@ o PCI Slot Scanning Order
   so as to recognize the host adapters in the same order as they are enumerated
   by the host adapter's BIOS.
 
-o Enabling UltraSCSI Transfers
+Enabling UltraSCSI Transfers
+----------------------------
 
   The BT-948/958/958D ship with their configuration set to "Factory Default"
   settings that are conservative and do not allow for UltraSCSI speed to be
@@ -353,7 +386,8 @@ o Enabling UltraSCSI Transfers
   "Optimum Performance" settings are loaded.
 
 
-				DRIVER OPTIONS
+Driver Options
+==============
 
 BusLogic Driver Options may be specified either via the Linux Kernel Command
 Line or via the Loadable Kernel Module Installation Facility.  Driver Options
@@ -520,30 +554,34 @@ The following examples demonstrate setting the Queue Depth for Target Devices
 Devices on the second host adapter to 31, and the Bus Settle Time on the
 second host adapter to 30 seconds.
 
-Linux Kernel Command Line:
+Linux Kernel Command Line::
 
   linux BusLogic=QueueDepth:[,7,15];QueueDepth:31,BusSettleTime:30
 
-LILO Linux Boot Loader (in /etc/lilo.conf):
+LILO Linux Boot Loader (in /etc/lilo.conf)::
 
   append = "BusLogic=QueueDepth:[,7,15];QueueDepth:31,BusSettleTime:30"
 
-INSMOD Loadable Kernel Module Installation Facility:
+INSMOD Loadable Kernel Module Installation Facility::
 
   insmod BusLogic.o \
       'BusLogic="QueueDepth:[,7,15];QueueDepth:31,BusSettleTime:30"'
 
-NOTE: Module Utilities 2.1.71 or later is required for correct parsing
+
+.. Note::
+
+      Module Utilities 2.1.71 or later is required for correct parsing
       of driver options containing commas.
 
 
-			      DRIVER INSTALLATION
+Driver Installation
+===================
 
 This distribution was prepared for Linux kernel version 2.0.35, but should be
 compatible with 2.0.4 or any later 2.0 series kernel.
 
 To install the new BusLogic SCSI driver, you may use the following commands,
-replacing "/usr/src" with wherever you keep your Linux kernel source tree:
+replacing "/usr/src" with wherever you keep your Linux kernel source tree::
 
   cd /usr/src
   tar -xvzf BusLogic-2.0.15.tar.gz
@@ -557,7 +595,8 @@ Then install "arch/x86/boot/zImage" as your standard kernel, run lilo if
 appropriate, and reboot.
 
 
-		      BUSLOGIC ANNOUNCEMENTS MAILING LIST
+BusLogic Announcements Mailing List
+===================================
 
 The BusLogic Announcements Mailing List provides a forum for informing Linux
 users of new driver releases and other announcements regarding Linux support
diff --git a/Documentation/scsi/FlashPoint.rst b/Documentation/scsi/FlashPoint.rst
new file mode 100644
index 000000000000..ef3c07e94ad6
--- /dev/null
+++ b/Documentation/scsi/FlashPoint.rst
@@ -0,0 +1,176 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+The BusLogic FlashPoint SCSI Driver
+===================================
+
+The BusLogic FlashPoint SCSI Host Adapters are now fully supported on Linux.
+The upgrade program described below has been officially terminated effective
+31 March 1997 since it is no longer needed.
+
+::
+
+  	  MYLEX INTRODUCES LINUX OPERATING SYSTEM SUPPORT FOR ITS
+  	      BUSLOGIC FLASHPOINT LINE OF SCSI HOST ADAPTERS
+
+
+  FREMONT, CA, -- October 8, 1996 -- Mylex Corporation has expanded Linux
+  operating system support to its BusLogic brand of FlashPoint Ultra SCSI
+  host adapters.  All of BusLogic's other SCSI host adapters, including the
+  MultiMaster line, currently support the Linux operating system.  Linux
+  drivers and information will be available on October 15th at
+  http://sourceforge.net/projects/dandelion/.
+
+  "Mylex is committed to supporting the Linux community," says Peter Shambora,
+  vice president of marketing for Mylex.  "We have supported Linux driver
+  development and provided technical support for our host adapters for several
+  years, and are pleased to now make our FlashPoint products available to this
+  user base."
+
+The Linux Operating System
+==========================
+
+Linux is a freely-distributed implementation of UNIX for Intel x86, Sun
+SPARC, SGI MIPS, Motorola 68k, Digital Alpha AXP and Motorola PowerPC
+machines.  It supports a wide range of software, including the X Window
+System, Emacs, and TCP/IP networking.  Further information is available at
+http://www.linux.org and http://www.ssc.com/.
+
+FlashPoint Host Adapters
+========================
+
+The FlashPoint family of Ultra SCSI host adapters, designed for workstation
+and file server environments, are available in narrow, wide, dual channel,
+and dual channel wide versions.  These adapters feature SeqEngine
+automation technology, which minimizes SCSI command overhead and reduces
+the number of interrupts generated to the CPU.
+
+About Mylex
+===========
+
+Mylex Corporation (NASDAQ/NM SYMBOL: MYLX), founded in 1983, is a leading
+producer of RAID technology and network management products.  The company
+produces high performance disk array (RAID) controllers, and complementary
+computer products for network servers, mass storage systems, workstations
+and system boards.  Through its wide range of RAID controllers and its
+BusLogic line of Ultra SCSI host adapter products, Mylex provides enabling
+intelligent I/O technologies that increase network management control,
+enhance CPU utilization, optimize I/O performance, and ensure data security
+and availability.  Products are sold globally through a network of OEMs,
+major distributors, VARs, and system integrators.  Mylex Corporation is
+headquartered at 34551 Ardenwood Blvd., Fremont, CA.
+
+Contact:
+========
+
+::
+
+  Peter Shambora
+  Vice President of Marketing
+  Mylex Corp.
+  510/796-6100
+  peters@mylex.com
+
+
+::
+
+			       ANNOUNCEMENT
+	       BusLogic FlashPoint LT/BT-948 Upgrade Program
+			      1 February 1996
+
+			  ADDITIONAL ANNOUNCEMENT
+	       BusLogic FlashPoint LW/BT-958 Upgrade Program
+			       14 June 1996
+
+  Ever since its introduction last October, the BusLogic FlashPoint LT has
+  been problematic for members of the Linux community, in that no Linux
+  drivers have been available for this new Ultra SCSI product.  Despite its
+  officially being positioned as a desktop workstation product, and not being
+  particularly well suited for a high performance multitasking operating
+  system like Linux, the FlashPoint LT has been touted by computer system
+  vendors as the latest thing, and has been sold even on many of their high
+  end systems, to the exclusion of the older MultiMaster products.  This has
+  caused grief for many people who inadvertently purchased a system expecting
+  that all BusLogic SCSI Host Adapters were supported by Linux, only to
+  discover that the FlashPoint was not supported and would not be for quite
+  some time, if ever.
+
+  After this problem was identified, BusLogic contacted its major OEM
+  customers to make sure the BT-946C/956C MultiMaster cards would still be
+  made available, and that Linux users who mistakenly ordered systems with
+  the FlashPoint would be able to upgrade to the BT-946C.  While this helped
+  many purchasers of new systems, it was only a partial solution to the
+  overall problem of FlashPoint support for Linux users.  It did nothing to
+  assist the people who initially purchased a FlashPoint for a supported
+  operating system and then later decided to run Linux, or those who had
+  ended up with a FlashPoint LT, believing it was supported, and were unable
+  to return it.
+
+  In the middle of December, I asked to meet with BusLogic's senior
+  management to discuss the issues related to Linux and free software support
+  for the FlashPoint.  Rumors of varying accuracy had been circulating
+  publicly about BusLogic's attitude toward the Linux community, and I felt
+  it was best that these issues be addressed directly.  I sent an email
+  message after 11pm one evening, and the meeting took place the next
+  afternoon.  Unfortunately, corporate wheels sometimes grind slowly,
+  especially when a company is being acquired, and so it's taken until now
+  before the details were completely determined and a public statement could
+  be made.
+
+  BusLogic is not prepared at this time to release the information necessary
+  for third parties to write drivers for the FlashPoint.  The only existing
+  FlashPoint drivers have been written directly by BusLogic Engineering, and
+  there is no FlashPoint documentation sufficiently detailed to allow outside
+  developers to write a driver without substantial assistance.  While there
+  are people at BusLogic who would rather not release the details of the
+  FlashPoint architecture at all, that debate has not yet been settled either
+  way.  In any event, even if documentation were available today it would
+  take quite a while for a usable driver to be written, especially since I'm
+  not convinced that the effort required would be worthwhile.
+
+  However, BusLogic does remain committed to providing a high performance
+  SCSI solution for the Linux community, and does not want to see anyone left
+  unable to run Linux because they have a Flashpoint LT.  Therefore, BusLogic
+  has put in place a direct upgrade program to allow any Linux user worldwide
+  to trade in their FlashPoint LT for the new BT-948 MultiMaster PCI Ultra
+  SCSI Host Adapter.  The BT-948 is the Ultra SCSI successor to the BT-946C
+  and has all the best features of both the BT-946C and FlashPoint LT,
+  including smart termination and a flash PROM for easy firmware updates, and
+  is of course compatible with the present Linux driver.  The price for this
+  upgrade has been set at US $45 plus shipping and handling, and the upgrade
+  program will be administered through BusLogic Technical Support, which can
+  be reached by electronic mail at techsup@buslogic.com, by Voice at +1 408
+  654-0760, or by FAX at +1 408 492-1542.
+
+  As of 14 June 1996, the original BusLogic FlashPoint LT to BT-948 upgrade
+  program has now been extended to encompass the FlashPoint LW Wide Ultra
+  SCSI Host Adapter.  Any Linux user worldwide may trade in their FlashPoint
+  LW (BT-950) for a BT-958 MultiMaster PCI Ultra SCSI Host Adapter.  The
+  price for this upgrade has been set at US $65 plus shipping and handling.
+
+  I was a beta test site for the BT-948/958, and versions 1.2.1 and 1.3.1 of
+  my BusLogic driver already included latent support for the BT-948/958.
+  Additional cosmetic support for the Ultra SCSI MultiMaster cards was added
+  subsequent releases.  As a result of this cooperative testing process,
+  several firmware bugs were found and corrected.  My heavily loaded Linux
+  test system provided an ideal environment for testing error recovery
+  processes that are much more rarely exercised in production systems, but
+  are crucial to overall system stability.  It was especially convenient
+  being able to work directly with their firmware engineer in demonstrating
+  the problems under control of the firmware debugging environment; things
+  sure have come a long way since the last time I worked on firmware for an
+  embedded system.  I am presently working on some performance testing and
+  expect to have some data to report in the not too distant future.
+
+  BusLogic asked me to send this announcement since a large percentage of the
+  questions regarding support for the FlashPoint have either been sent to me
+  directly via email, or have appeared in the Linux newsgroups in which I
+  participate.  To summarize, BusLogic is offering Linux users an upgrade
+  from the unsupported FlashPoint LT (BT-930) to the supported BT-948 for US
+  $45 plus shipping and handling, or from the unsupported FlashPoint LW
+  (BT-950) to the supported BT-958 for $65 plus shipping and handling.
+  Contact BusLogic Technical Support at techsup@buslogic.com or +1 408
+  654-0760 to take advantage of their offer.
+
+  		Leonard N. Zubkoff
+  		lnz@dandelion.com
diff --git a/Documentation/scsi/FlashPoint.txt b/Documentation/scsi/FlashPoint.txt
deleted file mode 100644
index 5b5f29cb9f8b..000000000000
--- a/Documentation/scsi/FlashPoint.txt
+++ /dev/null
@@ -1,163 +0,0 @@
-The BusLogic FlashPoint SCSI Host Adapters are now fully supported on Linux.
-The upgrade program described below has been officially terminated effective
-31 March 1997 since it is no longer needed.
-
-
-
-	  MYLEX INTRODUCES LINUX OPERATING SYSTEM SUPPORT FOR ITS
-	      BUSLOGIC FLASHPOINT LINE OF SCSI HOST ADAPTERS
-
-
-FREMONT, CA, -- October 8, 1996 -- Mylex Corporation has expanded Linux
-operating system support to its BusLogic brand of FlashPoint Ultra SCSI
-host adapters.  All of BusLogic's other SCSI host adapters, including the
-MultiMaster line, currently support the Linux operating system.  Linux
-drivers and information will be available on October 15th at
-http://sourceforge.net/projects/dandelion/.
-
-"Mylex is committed to supporting the Linux community," says Peter Shambora,
-vice president of marketing for Mylex.  "We have supported Linux driver
-development and provided technical support for our host adapters for several
-years, and are pleased to now make our FlashPoint products available to this
-user base."
-
-The Linux Operating System
-
-Linux is a freely-distributed implementation of UNIX for Intel x86, Sun
-SPARC, SGI MIPS, Motorola 68k, Digital Alpha AXP and Motorola PowerPC
-machines.  It supports a wide range of software, including the X Window
-System, Emacs, and TCP/IP networking.  Further information is available at
-http://www.linux.org and http://www.ssc.com/.
-
-FlashPoint Host Adapters
-
-The FlashPoint family of Ultra SCSI host adapters, designed for workstation
-and file server environments, are available in narrow, wide, dual channel,
-and dual channel wide versions.  These adapters feature SeqEngine
-automation technology, which minimizes SCSI command overhead and reduces
-the number of interrupts generated to the CPU.
-
-About Mylex
-
-Mylex Corporation (NASDAQ/NM SYMBOL: MYLX), founded in 1983, is a leading
-producer of RAID technology and network management products.  The company
-produces high performance disk array (RAID) controllers, and complementary
-computer products for network servers, mass storage systems, workstations
-and system boards.  Through its wide range of RAID controllers and its
-BusLogic line of Ultra SCSI host adapter products, Mylex provides enabling
-intelligent I/O technologies that increase network management control,
-enhance CPU utilization, optimize I/O performance, and ensure data security
-and availability.  Products are sold globally through a network of OEMs,
-major distributors, VARs, and system integrators.  Mylex Corporation is
-headquartered at 34551 Ardenwood Blvd., Fremont, CA.
-
-				   ####
-
-Contact:
-
-Peter Shambora
-Vice President of Marketing
-Mylex Corp.
-510/796-6100
-peters@mylex.com
-
-			       ANNOUNCEMENT
-	       BusLogic FlashPoint LT/BT-948 Upgrade Program
-			      1 February 1996
-
-			  ADDITIONAL ANNOUNCEMENT
-	       BusLogic FlashPoint LW/BT-958 Upgrade Program
-			       14 June 1996
-
-Ever since its introduction last October, the BusLogic FlashPoint LT has
-been problematic for members of the Linux community, in that no Linux
-drivers have been available for this new Ultra SCSI product.  Despite its
-officially being positioned as a desktop workstation product, and not being
-particularly well suited for a high performance multitasking operating
-system like Linux, the FlashPoint LT has been touted by computer system
-vendors as the latest thing, and has been sold even on many of their high
-end systems, to the exclusion of the older MultiMaster products.  This has
-caused grief for many people who inadvertently purchased a system expecting
-that all BusLogic SCSI Host Adapters were supported by Linux, only to
-discover that the FlashPoint was not supported and would not be for quite
-some time, if ever.
-
-After this problem was identified, BusLogic contacted its major OEM
-customers to make sure the BT-946C/956C MultiMaster cards would still be
-made available, and that Linux users who mistakenly ordered systems with
-the FlashPoint would be able to upgrade to the BT-946C.  While this helped
-many purchasers of new systems, it was only a partial solution to the
-overall problem of FlashPoint support for Linux users.  It did nothing to
-assist the people who initially purchased a FlashPoint for a supported
-operating system and then later decided to run Linux, or those who had
-ended up with a FlashPoint LT, believing it was supported, and were unable
-to return it.
-
-In the middle of December, I asked to meet with BusLogic's senior
-management to discuss the issues related to Linux and free software support
-for the FlashPoint.  Rumors of varying accuracy had been circulating
-publicly about BusLogic's attitude toward the Linux community, and I felt
-it was best that these issues be addressed directly.  I sent an email
-message after 11pm one evening, and the meeting took place the next
-afternoon.  Unfortunately, corporate wheels sometimes grind slowly,
-especially when a company is being acquired, and so it's taken until now
-before the details were completely determined and a public statement could
-be made.
-
-BusLogic is not prepared at this time to release the information necessary
-for third parties to write drivers for the FlashPoint.  The only existing
-FlashPoint drivers have been written directly by BusLogic Engineering, and
-there is no FlashPoint documentation sufficiently detailed to allow outside
-developers to write a driver without substantial assistance.  While there
-are people at BusLogic who would rather not release the details of the
-FlashPoint architecture at all, that debate has not yet been settled either
-way.  In any event, even if documentation were available today it would
-take quite a while for a usable driver to be written, especially since I'm
-not convinced that the effort required would be worthwhile.
-
-However, BusLogic does remain committed to providing a high performance
-SCSI solution for the Linux community, and does not want to see anyone left
-unable to run Linux because they have a Flashpoint LT.  Therefore, BusLogic
-has put in place a direct upgrade program to allow any Linux user worldwide
-to trade in their FlashPoint LT for the new BT-948 MultiMaster PCI Ultra
-SCSI Host Adapter.  The BT-948 is the Ultra SCSI successor to the BT-946C
-and has all the best features of both the BT-946C and FlashPoint LT,
-including smart termination and a flash PROM for easy firmware updates, and
-is of course compatible with the present Linux driver.  The price for this
-upgrade has been set at US $45 plus shipping and handling, and the upgrade
-program will be administered through BusLogic Technical Support, which can
-be reached by electronic mail at techsup@buslogic.com, by Voice at +1 408
-654-0760, or by FAX at +1 408 492-1542.
-
-As of 14 June 1996, the original BusLogic FlashPoint LT to BT-948 upgrade
-program has now been extended to encompass the FlashPoint LW Wide Ultra
-SCSI Host Adapter.  Any Linux user worldwide may trade in their FlashPoint
-LW (BT-950) for a BT-958 MultiMaster PCI Ultra SCSI Host Adapter.  The
-price for this upgrade has been set at US $65 plus shipping and handling.
-
-I was a beta test site for the BT-948/958, and versions 1.2.1 and 1.3.1 of
-my BusLogic driver already included latent support for the BT-948/958.
-Additional cosmetic support for the Ultra SCSI MultiMaster cards was added
-subsequent releases.  As a result of this cooperative testing process,
-several firmware bugs were found and corrected.  My heavily loaded Linux
-test system provided an ideal environment for testing error recovery
-processes that are much more rarely exercised in production systems, but
-are crucial to overall system stability.  It was especially convenient
-being able to work directly with their firmware engineer in demonstrating
-the problems under control of the firmware debugging environment; things
-sure have come a long way since the last time I worked on firmware for an
-embedded system.  I am presently working on some performance testing and
-expect to have some data to report in the not too distant future.
-
-BusLogic asked me to send this announcement since a large percentage of the
-questions regarding support for the FlashPoint have either been sent to me
-directly via email, or have appeared in the Linux newsgroups in which I
-participate.  To summarize, BusLogic is offering Linux users an upgrade
-from the unsupported FlashPoint LT (BT-930) to the supported BT-948 for US
-$45 plus shipping and handling, or from the unsupported FlashPoint LW
-(BT-950) to the supported BT-958 for $65 plus shipping and handling.
-Contact BusLogic Technical Support at techsup@buslogic.com or +1 408
-654-0760 to take advantage of their offer.
-
-		Leonard N. Zubkoff
-		lnz@dandelion.com
diff --git a/Documentation/scsi/NinjaSCSI.rst b/Documentation/scsi/NinjaSCSI.rst
new file mode 100644
index 000000000000..999a6ed5bf7e
--- /dev/null
+++ b/Documentation/scsi/NinjaSCSI.rst
@@ -0,0 +1,164 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================================
+WorkBiT NinjaSCSI-3/32Bi driver for Linux
+=========================================
+
+1. Comment
+==========
+
+This is Workbit corp.'s(http://www.workbit.co.jp/) NinjaSCSI-3
+for Linux.
+
+2. My Linux environment
+=======================
+
+:Linux kernel: 2.4.7 / 2.2.19
+:pcmcia-cs:    3.1.27
+:gcc:          gcc-2.95.4
+:PC card:      I-O data PCSC-F (NinjaSCSI-3),
+               I-O data CBSC-II in 16 bit mode (NinjaSCSI-32Bi)
+:SCSI device:  I-O data CDPS-PX24 (CD-ROM drive),
+               Media Intelligent MMO-640GT (Optical disk drive)
+
+3. Install
+==========
+
+(a) Check your PC card is true "NinjaSCSI-3" card.
+
+    If you installed pcmcia-cs already, pcmcia reports your card as UNKNOWN
+    card, and write ["WBT", "NinjaSCSI-3", "R1.0"] or some other string to
+    your console or log file.
+
+    You can also use "cardctl" program (this program is in pcmcia-cs source
+    code) to get more info.
+
+    ::
+
+	# cat /var/log/messages
+	...
+	Jan  2 03:45:06 lindberg cardmgr[78]: unsupported card in socket 1
+	Jan  2 03:45:06 lindberg cardmgr[78]:   product info: "WBT", "NinjaSCSI-3", "R1.0"
+	...
+	# cardctl ident
+	Socket 0:
+	  no product info available
+	Socket 1:
+	  product info: "IO DATA", "CBSC16       ", "1"
+
+
+(b) Get the Linux kernel source, and extract it to /usr/src.
+    Because the NinjaSCSI driver requires some SCSI header files in Linux 
+    kernel source, I recommend rebuilding your kernel; this eliminates 
+    some versioning problems.
+
+    ::
+
+	$ cd /usr/src
+	$ tar -zxvf linux-x.x.x.tar.gz
+	$ cd linux
+	$ make config
+	...
+
+(c) If you use this driver with Kernel 2.2, unpack pcmcia-cs in some directory
+    and make & install. This driver requires the pcmcia-cs header file.
+
+    ::
+
+	$ cd /usr/src
+	$ tar zxvf cs-pcmcia-cs-3.x.x.tar.gz
+	...
+
+(d) Extract this driver's archive somewhere, and edit Makefile, then do make::
+
+	$ tar -zxvf nsp_cs-x.x.tar.gz
+	$ cd nsp_cs-x.x
+	$ emacs Makefile
+	...
+	$ make
+
+(e) Copy nsp_cs.ko to suitable place, like /lib/modules/<Kernel version>/pcmcia/ .
+
+(f) Add these lines to /etc/pcmcia/config .
+
+    If you use pcmcia-cs-3.1.8 or later, we can use "nsp_cs.conf" file.
+    So, you don't need to edit file. Just copy to /etc/pcmcia/ .
+
+    ::
+
+	device "nsp_cs"
+	  class "scsi" module "nsp_cs"
+
+	card "WorkBit NinjaSCSI-3"
+	  version "WBT", "NinjaSCSI-3", "R1.0"
+	  bind "nsp_cs"
+
+	card "WorkBit NinjaSCSI-32Bi (16bit)"
+	  version "WORKBIT", "UltraNinja-16", "1"
+	  bind "nsp_cs"
+
+	# OEM
+	card "WorkBit NinjaSCSI-32Bi (16bit) / IO-DATA"
+	  version "IO DATA", "CBSC16       ", "1"
+	  bind "nsp_cs"
+
+	# OEM
+	card "WorkBit NinjaSCSI-32Bi (16bit) / KME-1"
+	  version "KME    ", "SCSI-CARD-001", "1"
+	  bind "nsp_cs"
+	card "WorkBit NinjaSCSI-32Bi (16bit) / KME-2"
+	  version "KME    ", "SCSI-CARD-002", "1"
+	  bind "nsp_cs"
+	card "WorkBit NinjaSCSI-32Bi (16bit) / KME-3"
+	  version "KME    ", "SCSI-CARD-003", "1"
+	  bind "nsp_cs"
+	card "WorkBit NinjaSCSI-32Bi (16bit) / KME-4"
+	  version "KME    ", "SCSI-CARD-004", "1"
+	  bind "nsp_cs"
+
+(f) Start (or restart) pcmcia-cs::
+
+	# /etc/rc.d/rc.pcmcia start        (BSD style)
+
+    or::
+
+	# /etc/init.d/pcmcia start         (SYSV style)
+
+
+4. History
+==========
+
+See README.nin_cs .
+
+5. Caution
+==========
+
+If you eject card when doing some operation for your SCSI device or suspend
+your computer, you encount some *BAD* error like disk crash.
+
+It works good when I using this driver right way. But I'm not guarantee
+your data. Please backup your data when you use this driver.
+
+6. Known Bugs
+=============
+
+In 2.4 kernel, you can't use 640MB Optical disk. This error comes from
+high level SCSI driver.
+
+7. Testing
+==========
+
+Please send me some reports(bug reports etc..) of this software.
+When you send report, please tell me these or more.
+
+	- card name
+	- kernel version
+	- your SCSI device name(hard drive, CD-ROM, etc...)
+
+8. Copyright
+============
+
+ See GPL.
+
+
+2001/08/08 yokota@netlab.is.tsukuba.ac.jp <YOKOTA Hiroshi>
diff --git a/Documentation/scsi/NinjaSCSI.txt b/Documentation/scsi/NinjaSCSI.txt
deleted file mode 100644
index ac8db8ceec77..000000000000
--- a/Documentation/scsi/NinjaSCSI.txt
+++ /dev/null
@@ -1,128 +0,0 @@
-
-         WorkBiT NinjaSCSI-3/32Bi driver for Linux
-
-1. Comment
- This is Workbit corp.'s(http://www.workbit.co.jp/) NinjaSCSI-3
-for Linux.
-
-2. My Linux environment
-Linux kernel: 2.4.7 / 2.2.19
-pcmcia-cs:    3.1.27
-gcc:          gcc-2.95.4
-PC card:      I-O data PCSC-F (NinjaSCSI-3)
-              I-O data CBSC-II in 16 bit mode (NinjaSCSI-32Bi)
-SCSI device:  I-O data CDPS-PX24 (CD-ROM drive)
-              Media Intelligent MMO-640GT (Optical disk drive)
-
-3. Install
-[1] Check your PC card is true "NinjaSCSI-3" card.
-    If you installed pcmcia-cs already, pcmcia reports your card as UNKNOWN
-    card, and write ["WBT", "NinjaSCSI-3", "R1.0"] or some other string to
-    your console or log file.
-    You can also use "cardctl" program (this program is in pcmcia-cs source
-    code) to get more info.
-
-# cat /var/log/messages
-...
-Jan  2 03:45:06 lindberg cardmgr[78]: unsupported card in socket 1
-Jan  2 03:45:06 lindberg cardmgr[78]:   product info: "WBT", "NinjaSCSI-3", "R1.0"
-...
-# cardctl ident
-Socket 0:
-  no product info available
-Socket 1:
-  product info: "IO DATA", "CBSC16       ", "1"
-
-
-[2] Get the Linux kernel source, and extract it to /usr/src.
-    Because the NinjaSCSI driver requires some SCSI header files in Linux 
-    kernel source, I recommend rebuilding your kernel; this eliminates 
-    some versioning problems.
-$ cd /usr/src
-$ tar -zxvf linux-x.x.x.tar.gz
-$ cd linux
-$ make config
-...
-
-[3] If you use this driver with Kernel 2.2, unpack pcmcia-cs in some directory
-    and make & install. This driver requires the pcmcia-cs header file.
-$ cd /usr/src
-$ tar zxvf cs-pcmcia-cs-3.x.x.tar.gz
-...
-
-[4] Extract this driver's archive somewhere, and edit Makefile, then do make.
-$ tar -zxvf nsp_cs-x.x.tar.gz
-$ cd nsp_cs-x.x
-$ emacs Makefile
-...
-$ make
-
-[5] Copy nsp_cs.ko to suitable place, like /lib/modules/<Kernel version>/pcmcia/ .
-
-[6] Add these lines to /etc/pcmcia/config .
-    If you use pcmcia-cs-3.1.8 or later, we can use "nsp_cs.conf" file.
-    So, you don't need to edit file. Just copy to /etc/pcmcia/ .
-
--------------------------------------
-device "nsp_cs"
-  class "scsi" module "nsp_cs"
-
-card "WorkBit NinjaSCSI-3"
-  version "WBT", "NinjaSCSI-3", "R1.0"
-  bind "nsp_cs"
-
-card "WorkBit NinjaSCSI-32Bi (16bit)"
-  version "WORKBIT", "UltraNinja-16", "1"
-  bind "nsp_cs"
-
-# OEM
-card "WorkBit NinjaSCSI-32Bi (16bit) / IO-DATA"
-  version "IO DATA", "CBSC16       ", "1"
-  bind "nsp_cs"
-
-# OEM
-card "WorkBit NinjaSCSI-32Bi (16bit) / KME-1"
-  version "KME    ", "SCSI-CARD-001", "1"
-  bind "nsp_cs"
-card "WorkBit NinjaSCSI-32Bi (16bit) / KME-2"
-  version "KME    ", "SCSI-CARD-002", "1"
-  bind "nsp_cs"
-card "WorkBit NinjaSCSI-32Bi (16bit) / KME-3"
-  version "KME    ", "SCSI-CARD-003", "1"
-  bind "nsp_cs"
-card "WorkBit NinjaSCSI-32Bi (16bit) / KME-4"
-  version "KME    ", "SCSI-CARD-004", "1"
-  bind "nsp_cs"
--------------------------------------
-
-[7] Start (or restart) pcmcia-cs.
-# /etc/rc.d/rc.pcmcia start        (BSD style)
-or
-# /etc/init.d/pcmcia start         (SYSV style)
-
-
-4. History
-See README.nin_cs .
-
-5. Caution
- If you eject card when doing some operation for your SCSI device or suspend
-your computer, you encount some *BAD* error like disk crash.
- It works good when I using this driver right way. But I'm not guarantee
-your data. Please backup your data when you use this driver.
-
-6. Known Bugs
- In 2.4 kernel, you can't use 640MB Optical disk. This error comes from
-high level SCSI driver.
-
-7. Testing
- Please send me some reports(bug reports etc..) of this software.
-When you send report, please tell me these or more.
-	card name
-	kernel version
-	your SCSI device name(hard drive, CD-ROM, etc...)
-
-8. Copyright
- See GPL.
-
-
-2001/08/08 yokota@netlab.is.tsukuba.ac.jp <YOKOTA Hiroshi>
diff --git a/Documentation/scsi/aacraid.txt b/Documentation/scsi/aacraid.rst
index 30f643f611b2..1904674b94f3 100644
--- a/Documentation/scsi/aacraid.txt
+++ b/Documentation/scsi/aacraid.rst
@@ -1,7 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
 AACRAID Driver for Linux (take two)
+===================================
 
 Introduction
--------------------------
+============
 The aacraid driver adds support for Adaptec (http://www.adaptec.com)
 RAID controllers. This is a major rewrite from the original
 Adaptec supplied driver. It has significantly cleaned up both the code
@@ -9,8 +13,11 @@ and the running binary size (the module is less than half the size of
 the original).
 
 Supported Cards/Chipsets
--------------------------
+========================
+
+	===================	=======	=======================================
 	PCI ID (pci.ids)	OEM	Product
+	===================	=======	=======================================
 	9005:0285:9005:0285	Adaptec	2200S (Vulcan)
 	9005:0285:9005:0286	Adaptec	2120S (Crusader)
 	9005:0285:9005:0287	Adaptec	2200S (Vulcan-2m)
@@ -117,34 +124,54 @@ Supported Cards/Chipsets
 	9005:0285:108e:0286	SUN	STK RAID INT (Cougar)
 	9005:0285:108e:0287	SUN	STK RAID EXT (Prometheus)
 	9005:0285:108e:7aae	SUN	STK RAID EM (Narvi)
+	===================	=======	=======================================
 
 People
--------------------------
+======
+
 Alan Cox <alan@lxorguk.ukuu.org.uk>
-Christoph Hellwig <hch@infradead.org>	(updates for new-style PCI probing and SCSI host registration,
-					 small cleanups/fixes)
-Matt Domsch <matt_domsch@dell.com>	(revision ioctl, adapter messages)
-Deanna Bonds                            (non-DASD support, PAE fibs and 64 bit, added new adaptec controllers
-					 added new ioctls, changed scsi interface to use new error handler,
-					 increased the number of fibs and outstanding commands to a container)
-
-					(fixed 64bit and 64G memory model, changed confusing naming convention
-					 where fibs that go to the hardware are consistently called hw_fibs and
-					 not just fibs like the name of the driver tracking structure)
-Mark Salyzyn <Mark_Salyzyn@adaptec.com> Fixed panic issues and added some new product ids for upcoming hbas. Performance tuning, card failover and bug mitigations.
+
+Christoph Hellwig <hch@infradead.org>
+
+- updates for new-style PCI probing and SCSI host registration,
+  small cleanups/fixes
+
+Matt Domsch <matt_domsch@dell.com>
+
+- revision ioctl, adapter messages
+
+Deanna Bonds
+
+- non-DASD support, PAE fibs and 64 bit, added new adaptec controllers
+  added new ioctls, changed scsi interface to use new error handler,
+  increased the number of fibs and outstanding commands to a container
+- fixed 64bit and 64G memory model, changed confusing naming convention
+  where fibs that go to the hardware are consistently called hw_fibs and
+  not just fibs like the name of the driver tracking structure
+
+Mark Salyzyn <Mark_Salyzyn@adaptec.com>
+
+- Fixed panic issues and added some new product ids for upcoming hbas.
+- Performance tuning, card failover and bug mitigations.
+
 Achim Leubner <Achim_Leubner@adaptec.com>
 
-Original Driver
+- Original Driver
+
 -------------------------
+
 Adaptec Unix OEM Product Group
 
 Mailing List
--------------------------
+============
+
 linux-scsi@vger.kernel.org (Interested parties troll here)
 Also note this is very different to Brian's original driver
 so don't expect him to support it.
+
 Adaptec does support this driver.  Contact Adaptec tech support or
 aacraid@adaptec.com
 
 Original by Brian Boerner February 2001
+
 Rewritten by Alan Cox, November 2001
diff --git a/Documentation/scsi/advansys.txt b/Documentation/scsi/advansys.rst
index 4a3db62b7424..e0367e179696 100644
--- a/Documentation/scsi/advansys.txt
+++ b/Documentation/scsi/advansys.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=====================
+AdvanSys Driver Notes
+=====================
+
 AdvanSys (Advanced System Products, Inc.) manufactures the following
 RISC-based, Bus-Mastering, Fast (10 Mhz) and Ultra (20 Mhz) Narrow
 (8-bit transfer) SCSI Host Adapters for the ISA, EISA, VL, and PCI
@@ -12,50 +18,51 @@ adapter detected. The number of CDBs used by the driver can be
 lowered in the BIOS by changing the 'Host Queue Size' adapter setting.
 
 Laptop Products:
-   ABP-480 - Bus-Master CardBus (16 CDB)
+  - ABP-480 - Bus-Master CardBus (16 CDB)
 
 Connectivity Products:
-   ABP510/5150 - Bus-Master ISA (240 CDB)
-   ABP5140 - Bus-Master ISA PnP (16 CDB)
-   ABP5142 - Bus-Master ISA PnP with floppy (16 CDB)
-   ABP902/3902 - Bus-Master PCI (16 CDB)
-   ABP3905 - Bus-Master PCI (16 CDB)
-   ABP915 - Bus-Master PCI (16 CDB)
-   ABP920 - Bus-Master PCI (16 CDB)
-   ABP3922 - Bus-Master PCI (16 CDB)
-   ABP3925 - Bus-Master PCI (16 CDB)
-   ABP930 - Bus-Master PCI (16 CDB)
-   ABP930U - Bus-Master PCI Ultra (16 CDB)
-   ABP930UA - Bus-Master PCI Ultra (16 CDB)
-   ABP960 - Bus-Master PCI MAC/PC (16 CDB)
-   ABP960U - Bus-Master PCI MAC/PC Ultra (16 CDB)
+   - ABP510/5150 - Bus-Master ISA (240 CDB)
+   - ABP5140 - Bus-Master ISA PnP (16 CDB)
+   - ABP5142 - Bus-Master ISA PnP with floppy (16 CDB)
+   - ABP902/3902 - Bus-Master PCI (16 CDB)
+   - ABP3905 - Bus-Master PCI (16 CDB)
+   - ABP915 - Bus-Master PCI (16 CDB)
+   - ABP920 - Bus-Master PCI (16 CDB)
+   - ABP3922 - Bus-Master PCI (16 CDB)
+   - ABP3925 - Bus-Master PCI (16 CDB)
+   - ABP930 - Bus-Master PCI (16 CDB)
+   - ABP930U - Bus-Master PCI Ultra (16 CDB)
+   - ABP930UA - Bus-Master PCI Ultra (16 CDB)
+   - ABP960 - Bus-Master PCI MAC/PC (16 CDB)
+   - ABP960U - Bus-Master PCI MAC/PC Ultra (16 CDB)
 
 Single Channel Products:
-   ABP542 - Bus-Master ISA with floppy (240 CDB)
-   ABP742 - Bus-Master EISA (240 CDB)
-   ABP842 - Bus-Master VL (240 CDB)
-   ABP940 - Bus-Master PCI (240 CDB)
-   ABP940U - Bus-Master PCI Ultra (240 CDB)
-   ABP940UA/3940UA - Bus-Master PCI Ultra (240 CDB)
-   ABP970 - Bus-Master PCI MAC/PC (240 CDB)
-   ABP970U - Bus-Master PCI MAC/PC Ultra (240 CDB)
-   ABP3960UA - Bus-Master PCI MAC/PC Ultra (240 CDB)
-   ABP940UW/3940UW - Bus-Master PCI Ultra-Wide (253 CDB)
-   ABP970UW - Bus-Master PCI MAC/PC Ultra-Wide (253 CDB)
-   ABP3940U2W - Bus-Master PCI LVD/Ultra2-Wide (253 CDB)
+   - ABP542 - Bus-Master ISA with floppy (240 CDB)
+   - ABP742 - Bus-Master EISA (240 CDB)
+   - ABP842 - Bus-Master VL (240 CDB)
+   - ABP940 - Bus-Master PCI (240 CDB)
+   - ABP940U - Bus-Master PCI Ultra (240 CDB)
+   - ABP940UA/3940UA - Bus-Master PCI Ultra (240 CDB)
+   - ABP970 - Bus-Master PCI MAC/PC (240 CDB)
+   - ABP970U - Bus-Master PCI MAC/PC Ultra (240 CDB)
+   - ABP3960UA - Bus-Master PCI MAC/PC Ultra (240 CDB)
+   - ABP940UW/3940UW - Bus-Master PCI Ultra-Wide (253 CDB)
+   - ABP970UW - Bus-Master PCI MAC/PC Ultra-Wide (253 CDB)
+   - ABP3940U2W - Bus-Master PCI LVD/Ultra2-Wide (253 CDB)
 
 Multi-Channel Products:
-   ABP752 - Dual Channel Bus-Master EISA (240 CDB Per Channel)
-   ABP852 - Dual Channel Bus-Master VL (240 CDB Per Channel)
-   ABP950 - Dual Channel Bus-Master PCI (240 CDB Per Channel)
-   ABP950UW - Dual Channel Bus-Master PCI Ultra-Wide (253 CDB Per Channel)
-   ABP980 - Four Channel Bus-Master PCI (240 CDB Per Channel)
-   ABP980U - Four Channel Bus-Master PCI Ultra (240 CDB Per Channel)
-   ABP980UA/3980UA - Four Channel Bus-Master PCI Ultra (16 CDB Per Chan.)
-   ABP3950U2W - Bus-Master PCI LVD/Ultra2-Wide and Ultra-Wide (253 CDB)
-   ABP3950U3W - Bus-Master PCI Dual LVD2/Ultra3-Wide (253 CDB)
+   - ABP752 - Dual Channel Bus-Master EISA (240 CDB Per Channel)
+   - ABP852 - Dual Channel Bus-Master VL (240 CDB Per Channel)
+   - ABP950 - Dual Channel Bus-Master PCI (240 CDB Per Channel)
+   - ABP950UW - Dual Channel Bus-Master PCI Ultra-Wide (253 CDB Per Channel)
+   - ABP980 - Four Channel Bus-Master PCI (240 CDB Per Channel)
+   - ABP980U - Four Channel Bus-Master PCI Ultra (240 CDB Per Channel)
+   - ABP980UA/3980UA - Four Channel Bus-Master PCI Ultra (16 CDB Per Chan.)
+   - ABP3950U2W - Bus-Master PCI LVD/Ultra2-Wide and Ultra-Wide (253 CDB)
+   - ABP3950U3W - Bus-Master PCI Dual LVD2/Ultra3-Wide (253 CDB)
 
 Driver Compile Time Options and Debugging
+=========================================
 
 The following constants can be defined in the source file.
 
@@ -88,26 +95,30 @@ The following constants can be defined in the source file.
    first three hex digits of the pseudo I/O Port must be set to
    'deb' and the fourth hex digit specifies the debug level: 0 - F.
    The following command line will look for an adapter at 0x330
-   and set the debug level to 2.
+   and set the debug level to 2::
 
       linux advansys=0x330,0,0,0,0xdeb2
 
    If the driver is built as a loadable module this variable can be
    defined when the driver is loaded. The following insmod command
-   will set the debug level to one.
+   will set the debug level to one::
 
       insmod advansys.o asc_dbglvl=1
 
    Debugging Message Levels:
-      0: Errors Only
-      1: High-Level Tracing
-      2-N: Verbose Tracing
+
+
+      ==== ==================
+      0    Errors Only
+      1    High-Level Tracing
+      2-N  Verbose Tracing
+      ==== ==================
 
    To enable debug output to console, please make sure that:
 
    a. System and kernel logging is enabled (syslogd, klogd running).
    b. Kernel messages are routed to console output. Check
-      /etc/syslog.conf for an entry similar to this:
+      /etc/syslog.conf for an entry similar to this::
 
            kern.*                  /dev/console
 
@@ -120,8 +131,11 @@ The following constants can be defined in the source file.
 
    Alternatively you can enable printk() to console with this
    program. However, this is not the 'official' way to do this.
+
    Debug output is logged in /var/log/messages.
 
+   ::
+
      main()
      {
              syscall(103, 7, 0, 0);
@@ -144,11 +158,11 @@ The following constants can be defined in the source file.
    Statistics are only available for kernels greater than or equal
    to v1.3.0 with the CONFIG_PROC_FS (/proc) file system configured.
 
-   AdvanSys SCSI adapter files have the following path name format:
+   AdvanSys SCSI adapter files have the following path name format::
 
       /proc/scsi/advansys/{0,1,2,3,...}
 
-   This information can be displayed with cat. For example:
+   This information can be displayed with cat. For example::
 
       cat /proc/scsi/advansys/0
 
@@ -156,6 +170,7 @@ The following constants can be defined in the source file.
    contain adapter and device configuration information.
 
 Driver LILO Option
+==================
 
 If init/main.c is modified as described in the 'Directions for Adding
 the AdvanSys Driver to Linux' section (B.4.) above, the driver will
@@ -167,17 +182,30 @@ affects searching for ISA and VL boards.
 
 Examples:
   1. Eliminate I/O port scanning:
-       boot: linux advansys=
-         or
-       boot: linux advansys=0x0
+
+     boot::
+
+	linux advansys=
+
+     or::
+
+	boot: linux advansys=0x0
+
   2. Limit I/O port scanning to one I/O port:
-       boot: linux advansys=0x110
+
+     boot::
+
+	linux advansys=0x110
+
   3. Limit I/O port scanning to four I/O ports:
-       boot: linux advansys=0x110,0x210,0x230,0x330
+
+     boot::
+
+	linux advansys=0x110,0x210,0x230,0x330
 
 For a loadable module the same effect can be achieved by setting
 the 'asc_iopflag' variable and 'asc_ioport' array when loading
-the driver, e.g.
+the driver, e.g.::
 
       insmod advansys.o asc_iopflag=1 asc_ioport=0x110,0x330
 
@@ -187,6 +215,7 @@ the 'Driver Compile Time Options and Debugging' section above for
 more information.
 
 Credits (Chronological Order)
+=============================
 
 Bob Frey <bfrey@turbolinux.com.cn> wrote the AdvanSys SCSI driver
 and maintained it up to 3.3F. He continues to answer questions
diff --git a/Documentation/scsi/aha152x.txt b/Documentation/scsi/aha152x.rst
index 94848734ac66..7012b5c46d5d 100644
--- a/Documentation/scsi/aha152x.txt
+++ b/Documentation/scsi/aha152x.rst
@@ -1,7 +1,12 @@
-$Id: README.aha152x,v 1.2 1999/12/25 15:32:30 fischer Exp fischer $
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+=====================================================
 Adaptec AHA-1520/1522 SCSI driver for Linux (aha152x)
+=====================================================
+
+Copyright |copy| 1993-1999 Jürgen Fischer <fischer@norbit.de>
 
-Copyright 1993-1999 Jürgen Fischer <fischer@norbit.de>
 TC1550 patches by Luuk van Dijk (ldz@xs4all.nl)
 
 
@@ -14,8 +19,10 @@ less polling loops), has slightly higher throughput (at
 least on my ancient test box; a i486/33Mhz/20MB).
 
 
-CONFIGURATION ARGUMENTS:
+Configuration Arguments
+=======================
 
+============  ========================================  ======================
 IOPORT        base io address                           (0x340/0x140)
 IRQ           interrupt level                           (9-12; default 11)
 SCSI_ID       scsi id of controller                     (0-7; default 7)
@@ -25,31 +32,38 @@ SYNCHRONOUS   enable synchronous transfers              (0/1; default 1 [on])
 DELAY:        bus reset delay                           (default 100)
 EXT_TRANS:    enable extended translation               (0/1: default 0 [off])
               (see NOTES)
+============  ========================================  ======================
+
+Compile Time Configuration
+==========================
+
+(go into AHA152X in drivers/scsi/Makefile):
 
-COMPILE TIME CONFIGURATION (go into AHA152X in drivers/scsi/Makefile):
+- DAUTOCONF
+    use configuration the controller reports (AHA-152x only)
 
--DAUTOCONF
- use configuration the controller reports (AHA-152x only)
+- DSKIP_BIOSTEST
+    Don't test for BIOS signature (AHA-1510 or disabled BIOS)
 
--DSKIP_BIOSTEST
- Don't test for BIOS signature (AHA-1510 or disabled BIOS)
+- DSETUP0="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+    override for the first controller
 
--DSETUP0="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the first controller 
+- DSETUP1="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+    override for the second controller
 
--DSETUP1="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the second controller
+- DAHA152X_DEBUG
+    enable debugging output
 
--DAHA152X_DEBUG
- enable debugging output
+- DAHA152X_STAT
+    enable some statistics
 
--DAHA152X_STAT
- enable some statistics
 
+LILO Command Line Options
+=========================
 
-LILO COMMAND LINE OPTIONS:
+ ::
 
-aha152x=<IOPORT>[,<IRQ>[,<SCSI-ID>[,<RECONNECT>[,<PARITY>[,<SYNCHRONOUS>[,<DELAY> [,<EXT_TRANS]]]]]]]
+    aha152x=<IOPORT>[,<IRQ>[,<SCSI-ID>[,<RECONNECT>[,<PARITY>[,<SYNCHRONOUS>[,<DELAY> [,<EXT_TRANS]]]]]]]
 
  The normal configuration can be overridden by specifying a command line.
  When you do this, the BIOS test is skipped. Entered values have to be
@@ -58,17 +72,21 @@ aha152x=<IOPORT>[,<IRQ>[,<SCSI-ID>[,<RECONNECT>[,<PARITY>[,<SYNCHRONOUS>[,<DELAY
  For two controllers use the aha152x statement twice.
 
 
-SYMBOLS FOR MODULE CONFIGURATION:
+Symbols for Module Configuration
+================================
 
 Choose from 2 alternatives:
 
-1. specify everything (old)
+1. specify everything (old)::
+
+    aha152x=IOPORT,IRQ,SCSI_ID,RECONNECT,PARITY,SYNCHRONOUS,DELAY,EXT_TRANS
 
-aha152x=IOPORT,IRQ,SCSI_ID,RECONNECT,PARITY,SYNCHRONOUS,DELAY,EXT_TRANS
   configuration override for first controller
 
+  ::
+
+    aha152x1=IOPORT,IRQ,SCSI_ID,RECONNECT,PARITY,SYNCHRONOUS,DELAY,EXT_TRANS
 
-aha152x1=IOPORT,IRQ,SCSI_ID,RECONNECT,PARITY,SYNCHRONOUS,DELAY,EXT_TRANS
   configuration override for second controller
 
 2. specify only what you need to (irq or io is required; new)
@@ -101,7 +119,8 @@ exttrans=EXTTRANS0[,EXTTRANS1]
 If you use both alternatives the first will be taken.
 
 
-NOTES ON EXT_TRANS: 
+Notes on EXT_TRANS
+==================
 
 SCSI uses block numbers to address blocks/sectors on a device.
 The BIOS uses a cylinder/head/sector addressing scheme (C/H/S)
@@ -150,8 +169,9 @@ geometry right in most cases:
 - for disks<1GB: use default translation (C/32/64)
 
 - for disks>1GB:
+
   - take current geometry from the partition table
-    (using scsicam_bios_param and accept only `valid' geometries,
+    (using scsicam_bios_param and accept only 'valid' geometries,
     ie. either (C/32/64) or (C/63/255)).  This can be extended translation
     even if it's not enabled in the driver.
 
@@ -161,7 +181,8 @@ geometry right in most cases:
     disks.
 
 
-REFERENCES USED:
+References Used
+===============
 
  "AIC-6260 SCSI Chip Specification", Adaptec Corporation.
 
@@ -177,7 +198,7 @@ REFERENCES USED:
 
  Drew Eckhardt (drew@cs.colorado.edu)
 
- Eric Youngdale (eric@andante.org) 
+ Eric Youngdale (eric@andante.org)
 
  special thanks to Eric Youngdale for the free(!) supplying the
  documentation on the chip.
diff --git a/Documentation/scsi/aic79xx.rst b/Documentation/scsi/aic79xx.rst
new file mode 100644
index 000000000000..071ff5111a4f
--- /dev/null
+++ b/Documentation/scsi/aic79xx.rst
@@ -0,0 +1,593 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+===================================
+Adaptec Ultra320 Family Manager Set
+===================================
+
+README for The Linux Operating System
+
+.. The following information is available in this file:
+
+  1. Supported Hardware
+  2. Version History
+  3. Command Line Options
+  4. Additional Notes
+  5. Contacting Adaptec
+
+
+1. Supported Hardware
+=====================
+
+   The following Adaptec SCSI Host Adapters are supported by this
+   driver set.
+
+   =============              =========================================
+   Ultra320 ASIC              Description
+   =============              =========================================
+   AIC-7901A                  Single Channel 64-bit PCI-X 133MHz to
+                              Ultra320 SCSI ASIC
+   AIC-7901B                  Single Channel 64-bit PCI-X 133MHz to
+                              Ultra320 SCSI ASIC with Retained Training
+   AIC-7902A4                 Dual Channel 64-bit PCI-X 133MHz to
+                              Ultra320 SCSI ASIC
+   AIC-7902B                  Dual Channel 64-bit PCI-X 133MHz to
+                              Ultra320 SCSI ASIC with Retained Training
+   =============              =========================================
+
+   ========================== ===================================== ============
+   Ultra320 Adapters          Description                              ASIC
+   ========================== ===================================== ============
+   Adaptec SCSI Card 39320    Dual Channel 64-bit PCI-X 133MHz to   7902A4/7902B
+                              Ultra320 SCSI Card (one external
+                              68-pin, two internal 68-pin)
+   Adaptec SCSI Card 39320A   Dual Channel 64-bit PCI-X 133MHz to      7902B
+                              Ultra320 SCSI Card (one external
+                              68-pin, two internal 68-pin)
+   Adaptec SCSI Card 39320D   Dual Channel 64-bit PCI-X 133MHz to      7902A4
+                              Ultra320 SCSI Card (two external VHDC
+                              and one internal 68-pin)
+   Adaptec SCSI Card 39320D   Dual Channel 64-bit PCI-X 133MHz to      7902A4
+                              Ultra320 SCSI Card (two external VHDC
+                              and one internal 68-pin) based on the
+                              AIC-7902B ASIC
+   Adaptec SCSI Card 29320    Single Channel 64-bit PCI-X 133MHz to    7901A
+                              Ultra320 SCSI Card (one external
+                              68-pin, two internal 68-pin, one
+                              internal 50-pin)
+   Adaptec SCSI Card 29320A   Single Channel 64-bit PCI-X 133MHz to    7901B
+                              Ultra320 SCSI Card (one external
+                              68-pin, two internal 68-pin, one
+                              internal 50-pin)
+   Adaptec SCSI Card 29320LP  Single Channel 64-bit Low Profile        7901A
+                              PCI-X 133MHz to Ultra320 SCSI Card
+                              (One external VHDC, one internal
+                              68-pin)
+   Adaptec SCSI Card 29320ALP Single Channel 64-bit Low Profile        7901B
+                              PCI-X 133MHz to Ultra320 SCSI Card
+                              (One external VHDC, one internal
+                              68-pin)
+   ========================== ===================================== ============
+
+2. Version History
+==================
+
+
+ * 3.0	  (December 1st, 2005)
+	- Updated driver to use SCSI transport class infrastructure
+	- Upported sequencer and core fixes from adaptec released
+	  version 2.0.15 of the driver.
+
+ * 1.3.11 (July 11, 2003)
+        - Fix several deadlock issues.
+        - Add 29320ALP and 39320B Id's.
+
+ * 1.3.10 (June 3rd, 2003)
+        - Align the SCB_TAG field on a 16byte boundary.  This avoids
+          SCB corruption on some PCI-33 busses.
+        - Correct non-zero luns on Rev B. hardware.
+        - Update for change in 2.5.X SCSI proc FS interface.
+        - When negotiation async via an 8bit WDTR message, send
+          an SDTR with an offset of 0 to be sure the target
+          knows we are async.  This works around a firmware defect
+          in the Quantum Atlas 10K.
+        - Implement controller suspend and resume.
+        - Clear PCI error state during driver attach so that we
+          don't disable memory mapped I/O due to a stray write
+          by some other driver probe that occurred before we
+          claimed the controller.
+
+ * 1.3.9 (May 22nd, 2003)
+        - Fix compiler errors.
+        - Remove S/G splitting for segments that cross a 4GB boundary.
+          This is guaranteed not to happen in Linux.
+        - Add support for scsi_report_device_reset() found in
+          2.5.X kernels.
+        - Add 7901B support.
+        - Simplify handling of the packetized lun Rev A workaround.
+        - Correct and simplify handling of the ignore wide residue
+          message.  The previous code would fail to report a residual
+          if the transaction data length was even and we received
+          an IWR message.
+
+ * 1.3.8 (April 29th, 2003)
+        - Fix types accessed via the command line interface code.
+        - Perform a few firmware optimizations.
+        - Fix "Unexpected PKT busfree" errors.
+        - Use a sequencer interrupt to notify the host of
+          commands with bad status.  We defer the notification
+          until there are no outstanding selections to ensure
+          that the host is interrupted for as short a time as
+          possible.
+        - Remove pre-2.2.X support.
+        - Add support for new 2.5.X interrupt API.
+        - Correct big-endian architecture support.
+
+ * 1.3.7 (April 16th, 2003)
+        - Use del_timer_sync() to ensure that no timeouts
+          are pending during controller shutdown.
+        - For pre-2.5.X kernels, carefully adjust our segment
+          list size to avoid SCSI malloc pool fragmentation.
+        - Cleanup channel display in our /proc output.
+        - Workaround duplicate device entries in the mid-layer
+          device list during add-single-device.
+
+ * 1.3.6 (March 28th, 2003)
+        - Correct a double free in the Domain Validation code.
+        - Correct a reference to free'ed memory during controller
+          shutdown.
+        - Reset the bus on an SE->LVD change.  This is required
+          to reset our transceivers.
+
+ * 1.3.5 (March 24th, 2003)
+        - Fix a few register window mode bugs.
+        - Include read streaming in the PPR flags we display in
+          diagnostics as well as /proc.
+        - Add PCI hot plug support for 2.5.X kernels.
+        - Correct default precompensation value for RevA hardware.
+        - Fix Domain Validation thread shutdown.
+        - Add a firmware workaround to make the LED blink
+          brighter during packetized operations on the H2A4.
+        - Correct /proc display of user read streaming settings.
+        - Simplify driver locking by releasing the io_request_lock
+          upon driver entry from the mid-layer.
+        - Cleanup command line parsing and move much of this code
+          to aiclib.
+
+ * 1.3.4 (February 28th, 2003)
+        - Correct a race condition in our error recovery handler.
+        - Allow Test Unit Ready commands to take a full 5 seconds
+          during Domain Validation.
+
+ * 1.3.2 (February 19th, 2003)
+        - Correct a Rev B. regression due to the GEM318
+          compatibility fix included in 1.3.1.
+
+ * 1.3.1 (February 11th, 2003)
+        - Add support for the 39320A.
+        - Improve recovery for certain PCI-X errors.
+        - Fix handling of LQ/DATA/LQ/DATA for the
+          same write transaction that can occur without
+          interveining training.
+        - Correct compatibility issues with the GEM318
+          enclosure services device.
+        - Correct data corruption issue that occurred under
+          high tag depth write loads.
+        - Adapt to a change in the 2.5.X daemonize() API.
+        - Correct a "Missing case in ahd_handle_scsiint" panic.
+
+ * 1.3.0 (January 21st, 2003)
+        - Full regression testing for all U320 products completed.
+        - Added abort and target/lun reset error recovery handler and
+          interrupt coalescing.
+
+ * 1.2.0 (November 14th, 2002)
+        - Added support for Domain Validation
+        - Add support for the Hewlett-Packard version of the 39320D
+          and AIC-7902 adapters.
+
+        Support for previous adapters has not been fully tested and should
+        only be used at the customer's own risk.
+
+ * 1.1.1 (September 24th, 2002)
+        - Added support for the Linux 2.5.X kernel series
+
+ * 1.1.0 (September 17th, 2002)
+        - Added support for four additional SCSI products:
+          ASC-39320, ASC-29320, ASC-29320LP, AIC-7901.
+
+ * 1.0.0 (May 30th, 2002)
+        - Initial driver release.
+
+ * 2.1. Software/Hardware Features
+        - Support for the SPI-4 "Ultra320" standard:
+          - 320MB/s transfer rates
+          - Packetized SCSI Protocol at 160MB/s and 320MB/s
+          - Quick Arbitration Selection (QAS)
+          - Retained Training Information (Rev B. ASIC only)
+        - Interrupt Coalescing
+        - Initiator Mode (target mode not currently
+          supported)
+        - Support for the PCI-X standard up to 133MHz
+        - Support for the PCI v2.2 standard
+        - Domain Validation
+
+ * 2.2. Operating System Support:
+        - Redhat Linux 7.2, 7.3, 8.0, Advanced Server 2.1
+        - SuSE Linux 7.3, 8.0, 8.1, Enterprise Server 7
+        - only Intel and AMD x86 supported at this time
+        - >4GB memory configurations supported.
+
+     Refer to the User's Guide for more details on this.
+
+3. Command Line Options
+=======================
+
+    .. Warning::
+
+	         ALTERING OR ADDING THESE DRIVER PARAMETERS
+                 INCORRECTLY CAN RENDER YOUR SYSTEM INOPERABLE.
+                 USE THEM WITH CAUTION.
+
+   Put a .conf file in the /etc/modprobe.d/ directory and add/edit a
+   line containing ``options aic79xx aic79xx=[command[,command...]]`` where
+   ``command`` is one or more of the following:
+
+
+verbose
+    :Definition: enable additional informative messages during driver operation.
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+debug:[value]
+    :Definition: Enables various levels of debugging information
+                 The bit definitions for the debugging mask can
+                 be found in drivers/scsi/aic7xxx/aic79xx.h under
+                 the "Debug" heading.
+    :Possible Values: 0x0000 = no debugging, 0xffff = full debugging
+    :Default Value: 0x0000
+
+no_reset
+    :Definition: Do not reset the bus during the initial probe
+                 phase
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+extended
+    :Definition: Force extended translation on the controller
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+periodic_otag
+    :Definition: Send an ordered tag periodically to prevent
+                 tag starvation.  Needed for some older devices
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+reverse_scan
+    :Definition: Probe the scsi bus in reverse order, starting with target 15
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+global_tag_depth
+    :Definition: Global tag depth for all targets on all busses.
+		 This option sets the default tag depth which
+		 may be selectively overridden vi the tag_info
+		 option.
+
+    :Possible Values: 1 - 253
+    :Default Value: 32
+
+tag_info:{{value[,value...]}[,{value[,value...]}...]}
+    :Definition: Set the per-target tagged queue depth on a
+                 per controller basis.  Both controllers and targets
+                 may be omitted indicating that they should retain
+                 the default tag depth.
+
+    :Possible Values: 1 - 253
+    :Default Value: 32
+
+    Examples:
+
+
+	::
+
+	    tag_info:{{16,32,32,64,8,8,,32,32,32,32,32,32,32,32,32}
+
+	On Controller 0
+
+	    - specifies a tag depth of 16 for target 0
+	    - specifies a tag depth of 64 for target 3
+	    - specifies a tag depth of 8 for targets 4 and 5
+	    - leaves target 6 at the default
+	    - specifies a tag depth of 32 for targets 1,2,7-15
+
+	All other targets retain the default depth.
+
+	::
+
+	    tag_info:{{},{32,,32}}
+
+	On Controller 1
+
+	    - specifies a tag depth of 32 for targets 0 and 2
+
+	All other targets retain the default depth.
+
+
+rd_strm: {rd_strm_bitmask[,rd_strm_bitmask...]}
+    :Definition: Enable read streaming on a per target basis.
+		 The rd_strm_bitmask is a 16 bit hex value in which
+		 each bit represents a target.  Setting the target's
+		 bit to '1' enables read streaming for that
+		 target.  Controllers may be omitted indicating that
+		 they should retain the default read streaming setting.
+
+    Examples:
+
+	    ::
+
+		rd_strm:{0x0041}
+
+	    On Controller 0
+
+		- enables read streaming for targets 0 and 6.
+		- disables read streaming for targets 1-5,7-15.
+
+	    All other targets retain the default read
+	    streaming setting.
+
+	    ::
+
+		rd_strm:{0x0023,,0xFFFF}
+
+	    On Controller 0
+
+		- enables read streaming for targets 1,2, and 5.
+		- disables read streaming for targets 3,4,6-15.
+
+	    On Controller 2
+
+		- enables read streaming for all targets.
+
+	    All other targets retain the default read
+	    streaming setting.
+
+    :Possible Values: 0x0000 - 0xffff
+    :Default Value: 0x0000
+
+dv: {value[,value...]}
+    :Definition: Set Domain Validation Policy on a per-controller basis.
+                 Controllers may be omitted indicating that
+                 they should retain the default read streaming setting.
+
+     :Possible Values:
+
+		      ==== ===============================
+		       < 0 Use setting from serial EEPROM.
+                         0 Disable DV
+		       > 0 Enable DV
+		      ==== ===============================
+
+    :Default Value: DV Serial EEPROM configuration setting.
+
+    Example:
+
+	::
+
+	    dv:{-1,0,,1,1,0}
+
+	- On Controller 0 leave DV at its default setting.
+	- On Controller 1 disable DV.
+	- Skip configuration on Controller 2.
+	- On Controllers 3 and 4 enable DV.
+	- On Controller 5 disable DV.
+
+seltime:[value]
+    :Definition: Specifies the selection timeout value
+    :Possible Values: 0 = 256ms, 1 = 128ms, 2 = 64ms, 3 = 32ms
+    :Default Value: 0
+
+.. Warning:
+
+    The following three options should only be changed at
+    the direction of a technical support representative.
+
+
+precomp: {value[,value...]}
+    :Definition: Set IO Cell precompensation value on a per-controller basis.
+                 Controllers may be omitted indicating that
+                 they should retain the default precompensation setting.
+
+    :Possible Values: 0 - 7
+    :Default Value: Varies based on chip revision
+
+    Examples:
+
+	::
+
+	    precomp:{0x1}
+
+	On Controller 0 set precompensation to 1.
+
+	::
+
+	    precomp:{1,,7}
+
+	- On Controller 0 set precompensation to 1.
+	- On Controller 2 set precompensation to 8.
+
+slewrate: {value[,value...]}
+    :Definition: Set IO Cell slew rate on a per-controller basis.
+                      Controllers may be omitted indicating that
+                      they should retain the default slew rate setting.
+
+    :Possible Values: 0 - 15
+    :Default Value: Varies based on chip revision
+
+    Examples:
+
+	::
+
+	    slewrate:{0x1}
+
+	- On Controller 0 set slew rate to 1.
+
+	::
+
+	    slewrate :{1,,8}
+
+	- On Controller 0 set slew rate to 1.
+	- On Controller 2 set slew rate to 8.
+
+amplitude: {value[,value...]}
+    :Definition: Set IO Cell signal amplitude on a per-controller basis.
+                 Controllers may be omitted indicating that
+                 they should retain the default read streaming setting.
+
+    :Possible Values: 1 - 7
+    :Default Value: Varies based on chip revision
+
+    Examples:
+
+    ::
+
+	amplitude:{0x1}
+
+    On Controller 0 set amplitude to 1.
+
+    ::
+
+	amplitude :{1,,7}
+
+    - On Controller 0 set amplitude to 1.
+    - On Controller 2 set amplitude to 7.
+
+Example::
+
+    options aic79xx aic79xx=verbose,rd_strm:{{0x0041}}
+
+enables verbose output in the driver and turns read streaming on
+for targets 0 and 6 of Controller 0.
+
+4. Additional Notes
+===================
+
+4.1. Known/Unresolved or FYI Issues
+-----------------------------------
+
+        * Under SuSE Linux Enterprise 7, the driver may fail to operate
+          correctly due to a problem with PCI interrupt routing in the
+          Linux kernel.  Please contact SuSE for an updated Linux
+          kernel.
+
+4.2. Third-Party Compatibility Issues
+-------------------------------------
+
+        * Adaptec only supports Ultra320 hard drives running
+          the latest firmware available. Please check with
+          your hard drive manufacturer to ensure you have the
+          latest version.
+
+4.3. Operating System or Technology Limitations
+-----------------------------------------------
+
+        * PCI Hot Plug is untested and may cause the operating system
+          to stop responding.
+        * Luns that are not numbered contiguously starting with 0 might not
+          be automatically probed during system startup.  This is a limitation
+          of the OS.  Please contact your Linux vendor for instructions on
+          manually probing non-contiguous luns.
+        * Using the Driver Update Disk version of this package during OS
+          installation under RedHat might result in two versions of this
+          driver being installed into the system module directory.  This
+          might cause problems with the /sbin/mkinitrd program and/or
+          other RPM packages that try to install system modules.  The best
+          way to correct this once the system is running is to install
+          the latest RPM package version of this driver, available from
+          http://www.adaptec.com.
+
+
+5. Adaptec Customer Support
+===========================
+
+   A Technical Support Identification (TSID) Number is required for
+   Adaptec technical support.
+
+    - The 12-digit TSID can be found on the white barcode-type label
+      included inside the box with your product.  The TSID helps us
+      provide more efficient service by accurately identifying your
+      product and support status.
+
+   Support Options
+    - Search the Adaptec Support Knowledgebase (ASK) at
+      http://ask.adaptec.com for articles, troubleshooting tips, and
+      frequently asked questions about your product.
+    - For support via Email, submit your question to Adaptec's
+      Technical Support Specialists at http://ask.adaptec.com/.
+
+   North America
+    - Visit our Web site at http://www.adaptec.com/.
+    - For information about Adaptec's support options, call
+      408-957-2550, 24 hours a day, 7 days a week.
+    - To speak with a Technical Support Specialist,
+
+      * For hardware products, call 408-934-7274,
+        Monday to Friday, 3:00 am to 5:00 pm, PDT.
+      * For RAID and Fibre Channel products, call 321-207-2000,
+        Monday to Friday, 3:00 am to 5:00 pm, PDT.
+
+      To expedite your service, have your computer with you.
+    - To order Adaptec products, including accessories and cables,
+      call 408-957-7274.  To order cables online go to
+      http://www.adaptec.com/buy-cables/.
+
+   Europe
+    - Visit our Web site at http://www.adaptec.com/en-US/_common/world_index.
+    - To speak with a Technical Support Specialist, call, or email,
+
+      * German:  +49 89 4366 5522, Monday-Friday, 9:00-17:00 CET,
+        http://ask-de.adaptec.com/.
+      * French:  +49 89 4366 5533, Monday-Friday, 9:00-17:00 CET,
+	http://ask-fr.adaptec.com/.
+      * English: +49 89 4366 5544, Monday-Friday, 9:00-17:00 GMT,
+	http://ask.adaptec.com/.
+
+    - You can order Adaptec cables online at
+      http://www.adaptec.com/buy-cables/.
+
+   Japan
+    - Visit our web site at http://www.adaptec.co.jp/.
+    - To speak with a Technical Support Specialist, call
+      +81 3 5308 6120, Monday-Friday, 9:00 a.m. to 12:00 p.m.,
+      1:00 p.m. to 6:00 p.m.
+
+Copyright |copy| 2003 Adaptec Inc. 691 S. Milpitas Blvd., Milpitas CA 95035 USA.
+All rights reserved.
+
+You are permitted to redistribute, use and modify this README file in whole
+or in part in conjunction with redistribution of software governed by the
+General Public License, provided that the following conditions are met:
+
+1. Redistributions of README file must retain the above copyright
+   notice, this list of conditions, and the following disclaimer,
+   without modification.
+2. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+3. Modifications or new contributions must be attributed in a copyright
+   notice identifying the author ("Contributor") and added below the
+   original copyright notice. The copyright notice is for purposes of
+   identifying contributors and should not be deemed as permission to alter
+   the permissions given by Adaptec.
+
+THIS README FILE IS PROVIDED BY ADAPTEC AND CONTRIBUTORS ``AS IS`` AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY
+WARRANTIES OF NON-INFRINGEMENT OR THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+ADAPTEC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS README
+FILE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/Documentation/scsi/aic79xx.txt b/Documentation/scsi/aic79xx.txt
deleted file mode 100644
index e2d3273000d4..000000000000
--- a/Documentation/scsi/aic79xx.txt
+++ /dev/null
@@ -1,497 +0,0 @@
-====================================================================
-=             Adaptec Ultra320 Family Manager Set                  =
-=                                                                  =
-=                            README for                            =
-=                    The Linux Operating System                    =
-====================================================================
-
-The following information is available in this file:
-
-  1. Supported Hardware
-  2. Version History
-  3. Command Line Options
-  4. Additional Notes
-  5. Contacting Adaptec
-
-
-1. Supported Hardware
-
-   The following Adaptec SCSI Host Adapters are supported by this 
-   driver set. 
-
-   Ultra320 ASIC              Description
-   ----------------------------------------------------------------
-   AIC-7901A                  Single Channel 64-bit PCI-X 133MHz to 
-                              Ultra320 SCSI ASIC
-   AIC-7901B                  Single Channel 64-bit PCI-X 133MHz to 
-                              Ultra320 SCSI ASIC with Retained Training
-   AIC-7902A4                 Dual Channel 64-bit PCI-X 133MHz to 
-                              Ultra320 SCSI ASIC
-   AIC-7902B                  Dual Channel 64-bit PCI-X 133MHz to
-                              Ultra320 SCSI ASIC with Retained Training
-
-   Ultra320 Adapters          Description                              ASIC
-   --------------------------------------------------------------------------
-   Adaptec SCSI Card 39320    Dual Channel 64-bit PCI-X 133MHz to   7902A4/7902B
-                              Ultra320 SCSI Card (one external 
-                              68-pin, two internal 68-pin)
-   Adaptec SCSI Card 39320A   Dual Channel 64-bit PCI-X 133MHz to      7902B
-                              Ultra320 SCSI Card (one external 
-                              68-pin, two internal 68-pin)
-   Adaptec SCSI Card 39320D   Dual Channel 64-bit PCI-X 133MHz to      7902A4
-                              Ultra320 SCSI Card (two external VHDC
-                              and one internal 68-pin)
-   Adaptec SCSI Card 39320D   Dual Channel 64-bit PCI-X 133MHz to      7902A4
-                              Ultra320 SCSI Card (two external VHDC
-                              and one internal 68-pin) based on the
-                              AIC-7902B ASIC
-   Adaptec SCSI Card 29320    Single Channel 64-bit PCI-X 133MHz to    7901A
-                              Ultra320 SCSI Card (one external 
-                              68-pin, two internal 68-pin, one
-                              internal 50-pin)
-   Adaptec SCSI Card 29320A   Single Channel 64-bit PCI-X 133MHz to    7901B
-                              Ultra320 SCSI Card (one external 
-                              68-pin, two internal 68-pin, one
-                              internal 50-pin)
-   Adaptec SCSI Card 29320LP  Single Channel 64-bit Low Profile        7901A
-                              PCI-X 133MHz to Ultra320 SCSI Card
-                              (One external VHDC, one internal
-                              68-pin)
-   Adaptec SCSI Card 29320ALP Single Channel 64-bit Low Profile        7901B
-                              PCI-X 133MHz to Ultra320 SCSI Card
-                              (One external VHDC, one internal
-                              68-pin)
-2. Version History
-
-   3.0	  (December 1st, 2005)
-	- Updated driver to use SCSI transport class infrastructure
-	- Upported sequencer and core fixes from adaptec released
-	  version 2.0.15 of the driver.
-
-   1.3.11 (July 11, 2003)
-        - Fix several deadlock issues.
-        - Add 29320ALP and 39320B Id's.
-
-   1.3.10 (June 3rd, 2003)
-        - Align the SCB_TAG field on a 16byte boundary.  This avoids
-          SCB corruption on some PCI-33 busses.
-        - Correct non-zero luns on Rev B. hardware.
-        - Update for change in 2.5.X SCSI proc FS interface.
-        - When negotiation async via an 8bit WDTR message, send
-          an SDTR with an offset of 0 to be sure the target
-          knows we are async.  This works around a firmware defect
-          in the Quantum Atlas 10K.
-        - Implement controller suspend and resume.
-        - Clear PCI error state during driver attach so that we
-          don't disable memory mapped I/O due to a stray write
-          by some other driver probe that occurred before we
-          claimed the controller.
-
-   1.3.9 (May 22nd, 2003)
-        - Fix compiler errors.
-        - Remove S/G splitting for segments that cross a 4GB boundary.
-          This is guaranteed not to happen in Linux.
-        - Add support for scsi_report_device_reset() found in
-          2.5.X kernels.
-        - Add 7901B support.
-        - Simplify handling of the packetized lun Rev A workaround.
-        - Correct and simplify handling of the ignore wide residue
-          message.  The previous code would fail to report a residual
-          if the transaction data length was even and we received
-          an IWR message.
-
-   1.3.8 (April 29th, 2003)
-        - Fix types accessed via the command line interface code.
-        - Perform a few firmware optimizations.
-        - Fix "Unexpected PKT busfree" errors.
-        - Use a sequencer interrupt to notify the host of
-          commands with bad status.  We defer the notification
-          until there are no outstanding selections to ensure
-          that the host is interrupted for as short a time as
-          possible.
-        - Remove pre-2.2.X support.
-        - Add support for new 2.5.X interrupt API.
-        - Correct big-endian architecture support.
-
-   1.3.7 (April 16th, 2003)
-        - Use del_timer_sync() to ensure that no timeouts
-          are pending during controller shutdown.
-        - For pre-2.5.X kernels, carefully adjust our segment
-          list size to avoid SCSI malloc pool fragmentation.
-        - Cleanup channel display in our /proc output.
-        - Workaround duplicate device entries in the mid-layer
-          device list during add-single-device.
-
-   1.3.6 (March 28th, 2003)
-        - Correct a double free in the Domain Validation code.
-        - Correct a reference to free'ed memory during controller
-          shutdown.
-        - Reset the bus on an SE->LVD change.  This is required
-          to reset our transceivers.
-
-   1.3.5 (March 24th, 2003)
-        - Fix a few register window mode bugs.
-        - Include read streaming in the PPR flags we display in
-          diagnostics as well as /proc.
-        - Add PCI hot plug support for 2.5.X kernels.
-        - Correct default precompensation value for RevA hardware.
-        - Fix Domain Validation thread shutdown.
-        - Add a firmware workaround to make the LED blink
-          brighter during packetized operations on the H2A4.
-        - Correct /proc display of user read streaming settings.
-        - Simplify driver locking by releasing the io_request_lock
-          upon driver entry from the mid-layer.
-        - Cleanup command line parsing and move much of this code
-          to aiclib.
-
-   1.3.4 (February 28th, 2003)
-        - Correct a race condition in our error recovery handler.
-        - Allow Test Unit Ready commands to take a full 5 seconds
-          during Domain Validation.
-
-   1.3.2 (February 19th, 2003)
-        - Correct a Rev B. regression due to the GEM318
-          compatibility fix included in 1.3.1.
-          
-   1.3.1 (February 11th, 2003)
-        - Add support for the 39320A.
-        - Improve recovery for certain PCI-X errors.
-        - Fix handling of LQ/DATA/LQ/DATA for the
-          same write transaction that can occur without
-          interveining training.
-        - Correct compatibility issues with the GEM318
-          enclosure services device.
-        - Correct data corruption issue that occurred under
-          high tag depth write loads.
-        - Adapt to a change in the 2.5.X daemonize() API.
-        - Correct a "Missing case in ahd_handle_scsiint" panic.
-
-   1.3.0 (January 21st, 2003)
-        - Full regression testing for all U320 products completed.
-        - Added abort and target/lun reset error recovery handler and
-          interrupt coalescing.
-
-   1.2.0 (November 14th, 2002)
-        - Added support for Domain Validation
-        - Add support for the Hewlett-Packard version of the 39320D
-          and AIC-7902 adapters.
-        Support for previous adapters has not been fully tested and should
-        only be used at the customer's own risk.
-
-   1.1.1 (September 24th, 2002)
-        - Added support for the Linux 2.5.X kernel series
-
-   1.1.0 (September 17th, 2002)
-        - Added support for four additional SCSI products:
-          ASC-39320, ASC-29320, ASC-29320LP, AIC-7901.
-
-   1.0.0 (May 30th, 2002)
-        - Initial driver release.
-
-   2.1. Software/Hardware Features
-        - Support for the SPI-4 "Ultra320" standard:
-          - 320MB/s transfer rates
-          - Packetized SCSI Protocol at 160MB/s and 320MB/s
-          - Quick Arbitration Selection (QAS)
-          - Retained Training Information (Rev B. ASIC only)
-        - Interrupt Coalescing
-        - Initiator Mode (target mode not currently 
-          supported)
-        - Support for the PCI-X standard up to 133MHz
-        - Support for the PCI v2.2 standard
-        - Domain Validation
-
-   2.2. Operating System Support:
-        - Redhat Linux 7.2, 7.3, 8.0, Advanced Server 2.1
-        - SuSE Linux 7.3, 8.0, 8.1, Enterprise Server 7
-        - only Intel and AMD x86 supported at this time
-        - >4GB memory configurations supported.
-
-     Refer to the User's Guide for more details on this.
-
-3. Command Line Options
-
-        WARNING: ALTERING OR ADDING THESE DRIVER PARAMETERS
-                 INCORRECTLY CAN RENDER YOUR SYSTEM INOPERABLE.
-                 USE THEM WITH CAUTION. 
-
-   Put a .conf file in the /etc/modprobe.d/ directory and add/edit a
-   line containing 'options aic79xx aic79xx=[command[,command...]]' where
-   'command' is one or more of the following:
-   -----------------------------------------------------------------
-              Option: verbose
-          Definition: enable additional informative messages during
-                      driver operation.
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: debug:[value]
-          Definition: Enables various levels of debugging information
-                      The bit definitions for the debugging mask can
-                      be found in drivers/scsi/aic7xxx/aic79xx.h under
-                      the "Debug" heading.
-     Possible Values: 0x0000 = no debugging, 0xffff = full debugging
-       Default Value: 0x0000
-   -----------------------------------------------------------------
-              Option: no_reset
-          Definition: Do not reset the bus during the initial probe
-                      phase
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: extended
-          Definition: Force extended translation on the controller
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: periodic_otag
-          Definition: Send an ordered tag periodically to prevent
-                      tag starvation.  Needed for some older devices
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: reverse_scan
-          Definition: Probe the scsi bus in reverse order, starting
-                      with target 15
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: global_tag_depth
-          Definition: Global tag depth for all targets on all busses.
-                      This option sets the default tag depth which
-                      may be selectively overridden vi the tag_info
-                      option.
-     Possible Values: 1 - 253
-       Default Value: 32
-   -----------------------------------------------------------------
-              Option: tag_info:{{value[,value...]}[,{value[,value...]}...]}
-          Definition: Set the per-target tagged queue depth on a
-                      per controller basis.  Both controllers and targets
-                      may be omitted indicating that they should retain
-                      the default tag depth.
-            Examples: tag_info:{{16,32,32,64,8,8,,32,32,32,32,32,32,32,32,32}
-                        On Controller 0
-                          specifies a tag depth of 16 for target 0
-                          specifies a tag depth of 64 for target 3
-                          specifies a tag depth of 8 for targets 4 and 5
-                          leaves target 6 at the default
-                          specifies a tag depth of 32 for targets 1,2,7-15
-                        All other targets retain the default depth.
-
-                      tag_info:{{},{32,,32}}
-                        On Controller 1
-                          specifies a tag depth of 32 for targets 0 and 2
-                        All other targets retain the default depth.
-                        
-     Possible Values: 1 - 253
-       Default Value: 32
-   -----------------------------------------------------------------
-              Option: rd_strm: {rd_strm_bitmask[,rd_strm_bitmask...]}
-          Definition: Enable read streaming on a per target basis.
-                      The rd_strm_bitmask is a 16 bit hex value in which
-                      each bit represents a target.  Setting the target's
-                      bit to '1' enables read streaming for that
-                      target.  Controllers may be omitted indicating that
-                      they should retain the default read streaming setting.
-             Example: rd_strm:{0x0041}
-                        On Controller 0
-                          enables read streaming for targets 0 and 6.
-                          disables read streaming for targets 1-5,7-15.
-                        All other targets retain the default read
-                        streaming setting.
-             Example: rd_strm:{0x0023,,0xFFFF}
-                        On Controller 0
-                          enables read streaming for targets 1,2, and 5.
-                          disables read streaming for targets 3,4,6-15.
-                        On Controller 2
-                          enables read streaming for all targets.
-                        All other targets retain the default read
-                        streaming setting.
-                      
-     Possible Values: 0x0000 - 0xffff
-       Default Value: 0x0000
-   -----------------------------------------------------------------
-              Option: dv: {value[,value...]}
-          Definition: Set Domain Validation Policy on a per-controller basis.
-                      Controllers may be omitted indicating that
-                      they should retain the default read streaming setting.
-             Example: dv:{-1,0,,1,1,0}
-                        On Controller 0 leave DV at its default setting.
-                        On Controller 1 disable DV.
-                        Skip configuration on Controller 2.
-                        On Controllers 3 and 4 enable DV.
-                        On Controller 5 disable DV.
-
-     Possible Values: < 0 Use setting from serial EEPROM.
-                      0 Disable DV
-                      > 0 Enable DV
-       Default Value: DV Serial EEPROM configuration setting.
-   -----------------------------------------------------------------
-              Option: seltime:[value]
-          Definition: Specifies the selection timeout value
-     Possible Values: 0 = 256ms, 1 = 128ms, 2 = 64ms, 3 = 32ms
-       Default Value: 0
-   -----------------------------------------------------------------
-
-   *** The following three options should only be changed at ***
-   *** the direction of a technical support representative.  ***
-
-   -----------------------------------------------------------------
-              Option: precomp: {value[,value...]}
-          Definition: Set IO Cell precompensation value on a per-controller
-                      basis.
-                      Controllers may be omitted indicating that
-                      they should retain the default precompensation setting.
-             Example: precomp:{0x1}
-                        On Controller 0 set precompensation to 1.
-             Example: precomp:{1,,7}
-                        On Controller 0 set precompensation to 1.
-                        On Controller 2 set precompensation to 8.
-                      
-     Possible Values: 0 - 7
-       Default Value: Varies based on chip revision
-   -----------------------------------------------------------------
-              Option: slewrate: {value[,value...]}
-          Definition: Set IO Cell slew rate on a per-controller basis.
-                      Controllers may be omitted indicating that
-                      they should retain the default slew rate setting.
-             Example: slewrate:{0x1}
-                        On Controller 0 set slew rate to 1.
-             Example: slewrate :{1,,8}
-                        On Controller 0 set slew rate to 1.
-                        On Controller 2 set slew rate to 8.
-                      
-     Possible Values: 0 - 15
-       Default Value: Varies based on chip revision
-   -----------------------------------------------------------------
-              Option: amplitude: {value[,value...]}
-          Definition: Set IO Cell signal amplitude on a per-controller basis.
-                      Controllers may be omitted indicating that
-                      they should retain the default read streaming setting.
-             Example: amplitude:{0x1}
-                        On Controller 0 set amplitude to 1.
-             Example: amplitude :{1,,7}
-                        On Controller 0 set amplitude to 1.
-                        On Controller 2 set amplitude to 7.
-                      
-     Possible Values: 1 - 7
-       Default Value: Varies based on chip revision
-   -----------------------------------------------------------------
-
-   Example: 'options aic79xx aic79xx=verbose,rd_strm:{{0x0041}}'
-        enables verbose output in the driver and turns read streaming on
-        for targets 0 and 6 of Controller 0.
-
-4. Additional Notes
-
-   4.1. Known/Unresolved or FYI Issues
-
-        * Under SuSE Linux Enterprise 7, the driver may fail to operate
-          correctly due to a problem with PCI interrupt routing in the
-          Linux kernel.  Please contact SuSE for an updated Linux
-          kernel.
-
-   4.2. Third-Party Compatibility Issues
-
-        * Adaptec only supports Ultra320 hard drives running
-          the latest firmware available. Please check with
-          your hard drive manufacturer to ensure you have the
-          latest version.
-
-   4.3. Operating System or Technology Limitations
-        
-        * PCI Hot Plug is untested and may cause the operating system 
-          to stop responding.
-        * Luns that are not numbered contiguously starting with 0 might not
-          be automatically probed during system startup.  This is a limitation
-          of the OS.  Please contact your Linux vendor for instructions on
-          manually probing non-contiguous luns.
-        * Using the Driver Update Disk version of this package during OS
-          installation under RedHat might result in two versions of this
-          driver being installed into the system module directory.  This
-          might cause problems with the /sbin/mkinitrd program and/or
-          other RPM packages that try to install system modules.  The best
-          way to correct this once the system is running is to install
-          the latest RPM package version of this driver, available from
-          http://www.adaptec.com.
-
-
-5. Adaptec Customer Support
-
-   A Technical Support Identification (TSID) Number is required for 
-   Adaptec technical support.
-    - The 12-digit TSID can be found on the white barcode-type label
-      included inside the box with your product.  The TSID helps us 
-      provide more efficient service by accurately identifying your 
-      product and support status.
-
-   Support Options
-    - Search the Adaptec Support Knowledgebase (ASK) at
-      http://ask.adaptec.com for articles, troubleshooting tips, and
-      frequently asked questions about your product.
-    - For support via Email, submit your question to Adaptec's 
-      Technical Support Specialists at http://ask.adaptec.com/.
-     
-   North America
-    - Visit our Web site at http://www.adaptec.com/.
-    - For information about Adaptec's support options, call
-      408-957-2550, 24 hours a day, 7 days a week.
-    - To speak with a Technical Support Specialist,
-      * For hardware products, call 408-934-7274,
-        Monday to Friday, 3:00 am to 5:00 pm, PDT.
-      * For RAID and Fibre Channel products, call 321-207-2000,
-        Monday to Friday, 3:00 am to 5:00 pm, PDT.
-      To expedite your service, have your computer with you.
-    - To order Adaptec products, including accessories and cables,
-      call 408-957-7274.  To order cables online go to
-      http://www.adaptec.com/buy-cables/.
-
-   Europe
-    - Visit our Web site at http://www.adaptec.com/en-US/_common/world_index.
-    - To speak with a Technical Support Specialist, call, or email,
-      * German:  +49 89 4366 5522, Monday-Friday, 9:00-17:00 CET,
-        http://ask-de.adaptec.com/.
-      * French:  +49 89 4366 5533, Monday-Friday, 9:00-17:00 CET,
-	http://ask-fr.adaptec.com/.
-      * English: +49 89 4366 5544, Monday-Friday, 9:00-17:00 GMT,
-	http://ask.adaptec.com/.
-    - You can order Adaptec cables online at
-      http://www.adaptec.com/buy-cables/.
-
-   Japan
-    - Visit our web site at http://www.adaptec.co.jp/.
-    - To speak with a Technical Support Specialist, call 
-      +81 3 5308 6120, Monday-Friday, 9:00 a.m. to 12:00 p.m.,
-      1:00 p.m. to 6:00 p.m.
-
--------------------------------------------------------------------
-/*
- * Copyright (c) 2003 Adaptec Inc. 691 S. Milpitas Blvd., Milpitas CA 95035 USA.
- * All rights reserved.
- *
- * You are permitted to redistribute, use and modify this README file in whole
- * or in part in conjunction with redistribution of software governed by the
- * General Public License, provided that the following conditions are met:
- * 1. Redistributions of README file must retain the above copyright
- *    notice, this list of conditions, and the following disclaimer,
- *    without modification.
- * 2. The name of the author may not be used to endorse or promote products
- *    derived from this software without specific prior written permission.
- * 3. Modifications or new contributions must be attributed in a copyright
- *    notice identifying the author ("Contributor") and added below the
- *    original copyright notice. The copyright notice is for purposes of
- *    identifying contributors and should not be deemed as permission to alter
- *    the permissions given by Adaptec.
- *
- * THIS README FILE IS PROVIDED BY ADAPTEC AND CONTRIBUTORS ``AS IS'' AND
- * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY
- * WARRANTIES OF NON-INFRINGEMENT OR THE IMPLIED WARRANTIES OF MERCHANTABILITY
- * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
- * ADAPTEC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
- * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS README
- * FILE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
diff --git a/Documentation/scsi/aic7xxx.rst b/Documentation/scsi/aic7xxx.rst
new file mode 100644
index 000000000000..bad0e5567b21
--- /dev/null
+++ b/Documentation/scsi/aic7xxx.rst
@@ -0,0 +1,458 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+========================================================
+Adaptec Aic7xxx Fast -> Ultra160 Family Manager Set v7.0
+========================================================
+
+README for The Linux Operating System
+
+The following information is available in this file:
+
+  1. Supported Hardware
+  2. Version History
+  3. Command Line Options
+  4. Contacting Adaptec
+
+1. Supported Hardware
+=====================
+
+   The following Adaptec SCSI Chips and Host Adapters are supported by
+   the aic7xxx driver.
+
+   ======== ===== ========= ======== ========= ===== ===============
+   Chip     MIPS  Host Bus  MaxSync  MaxWidth  SCBs  Notes
+   ======== ===== ========= ======== ========= ===== ===============
+   aic7770  10    EISA/VL   10MHz    16Bit      4    1
+   aic7850  10    PCI/32    10MHz    8Bit       3
+   aic7855  10    PCI/32    10MHz    8Bit       3
+   aic7856  10    PCI/32    10MHz    8Bit       3
+   aic7859  10    PCI/32    20MHz    8Bit       3
+   aic7860  10    PCI/32    20MHz    8Bit       3
+   aic7870  10    PCI/32    10MHz    16Bit      16
+   aic7880  10    PCI/32    20MHz    16Bit      16
+   aic7890  20    PCI/32    40MHz    16Bit      16      3 4 5 6 7 8
+   aic7891  20    PCI/64    40MHz    16Bit      16      3 4 5 6 7 8
+   aic7892  20    PCI/64-66 80MHz    16Bit      16      3 4 5 6 7 8
+   aic7895  15    PCI/32    20MHz    16Bit      16    2 3 4 5
+   aic7895C 15    PCI/32    20MHz    16Bit      16    2 3 4 5     8
+   aic7896  20    PCI/32    40MHz    16Bit      16    2 3 4 5 6 7 8
+   aic7897  20    PCI/64    40MHz    16Bit      16    2 3 4 5 6 7 8
+   aic7899  20    PCI/64-66 80MHz    16Bit      16    2 3 4 5 6 7 8
+   ======== ===== ========= ======== ========= ===== ===============
+
+   1.   Multiplexed Twin Channel Device - One controller servicing two
+        busses.
+   2.   Multi-function Twin Channel Device - Two controllers on one chip.
+   3.   Command Channel Secondary DMA Engine - Allows scatter gather list
+        and SCB prefetch.
+   4.   64 Byte SCB Support - Allows disconnected, untagged request table
+        for all possible target/lun combinations.
+   5.   Block Move Instruction Support - Doubles the speed of certain
+        sequencer operations.
+   6.   'Bayonet' style Scatter Gather Engine - Improves S/G prefetch
+        performance.
+   7.   Queuing Registers - Allows queuing of new transactions without
+        pausing the sequencer.
+   8.   Multiple Target IDs - Allows the controller to respond to selection
+        as a target on multiple SCSI IDs.
+
+   ============== ======= =========== =============== =============== =========
+   Controller      Chip   Host-Bus    Int-Connectors  Ext-Connectors  Notes
+   ============== ======= =========== =============== =============== =========
+   AHA-274X[A]    aic7770   EISA         SE-50M         SE-HD50F
+   AHA-274X[A]W   aic7770   EISA         SE-HD68F       SE-HD68F
+                                         SE-50M
+   AHA-274X[A]T   aic7770   EISA       2 X SE-50M       SE-HD50F
+   AHA-2842       aic7770    VL          SE-50M         SE-HD50F
+   AHA-2940AU     aic7860   PCI/32       SE-50M         SE-HD50F
+   AVA-2902I      aic7860   PCI/32       SE-50M
+   AVA-2902E      aic7860   PCI/32       SE-50M
+   AVA-2906       aic7856   PCI/32       SE-50M         SE-DB25F
+   APC-7850       aic7850   PCI/32       SE-50M                       1
+   AVA-2940       aic7860   PCI/32       SE-50M
+   AHA-2920B      aic7860   PCI/32       SE-50M
+   AHA-2930B      aic7860   PCI/32       SE-50M
+   AHA-2920C      aic7856   PCI/32       SE-50M         SE-HD50F
+   AHA-2930C      aic7860   PCI/32       SE-50M
+   AHA-2930C      aic7860   PCI/32       SE-50M
+   AHA-2910C      aic7860   PCI/32       SE-50M
+   AHA-2915C      aic7860   PCI/32       SE-50M
+   AHA-2940AU/CN  aic7860   PCI/32       SE-50M         SE-HD50F
+   AHA-2944W      aic7870   PCI/32     HVD-HD68F        HVD-HD68F
+                                       HVD-50M
+   AHA-3940W      aic7870   PCI/32     2 X SE-HD68F     SE-HD68F        2
+   AHA-2940UW     aic7880   PCI/32       SE-HD68F
+                                         SE-50M         SE-HD68F
+   AHA-2940U      aic7880   PCI/32       SE-50M         SE-HD50F
+   AHA-2940D      aic7880   PCI/32
+   aHA-2940 A/T   aic7880   PCI/32
+   AHA-2940D A/T  aic7880   PCI/32
+   AHA-3940UW     aic7880   PCI/32     2 X SE-HD68F     SE-HD68F          3
+   AHA-3940UWD    aic7880   PCI/32     2 X SE-HD68F   2 X SE-VHD68F       3
+   AHA-3940U      aic7880   PCI/32     2 X SE-50M       SE-HD50F          3
+   AHA-2944UW     aic7880   PCI/32      HVD-HD68F       HVD-HD68F
+                                        HVD-50M
+   AHA-3944UWD    aic7880   PCI/32     2 X HVD-HD68F  2 X HVD-VHD68F      3
+   AHA-4944UW     aic7880   PCI/32
+   AHA-2930UW     aic7880   PCI/32
+   AHA-2940UW Pro aic7880   PCI/32      SE-HD68F        SE-HD68F            4
+                                        SE-50M
+   AHA-2940UW/CN  aic7880   PCI/32
+   AHA-2940UDual  aic7895   PCI/32
+   AHA-2940UWDual aic7895   PCI/32
+   AHA-3940UWD    aic7895   PCI/32
+   AHA-3940AUW    aic7895   PCI/32
+   AHA-3940AUWD   aic7895   PCI/32
+   AHA-3940AU     aic7895   PCI/32
+   AHA-3944AUWD   aic7895   PCI/32     2 X HVD-HD68F  2 X HVD-VHD68F
+   AHA-2940U2B    aic7890   PCI/32      LVD-HD68F       LVD-HD68F
+   AHA-2940U2 OEM aic7891   PCI/64
+   AHA-2940U2W    aic7890   PCI/32      LVD-HD68F       LVD-HD68F
+                                        SE-HD68F
+                                        SE-50M
+   AHA-2950U2B    aic7891   PCI/64      LVD-HD68F       LVD-HD68F
+   AHA-2930U2     aic7890   PCI/32      LVD-HD68F       SE-HD50F
+                                        SE-50M
+   AHA-3950U2B    aic7897   PCI/64
+   AHA-3950U2D    aic7897   PCI/64
+   AHA-29160      aic7892   PCI/64-66
+   AHA-29160 CPQ  aic7892   PCI/64-66
+   AHA-29160N     aic7892   PCI/32      LVD-HD68F       SE-HD50F
+                                        SE-50M
+   AHA-29160LP    aic7892   PCI/64-66
+   AHA-19160      aic7892   PCI/64-66
+   AHA-29150LP    aic7892   PCI/64-66
+   AHA-29130LP    aic7892   PCI/64-66
+   AHA-3960D      aic7899   PCI/64-66  2 X LVD-HD68F  2 X LVD-VHD68F
+                                       LVD-50M
+   AHA-3960D CPQ  aic7899   PCI/64-66  2 X LVD-HD68F  2 X LVD-VHD68F
+                                       LVD-50M
+   AHA-39160      aic7899   PCI/64-66  2 X LVD-HD68F  2 X LVD-VHD68F
+                                       LVD-50M
+   ============== ======= =========== =============== =============== =========
+
+   1. No BIOS support
+   2. DEC21050 PCI-PCI bridge with multiple controller chips on secondary bus
+   3. DEC2115X PCI-PCI bridge with multiple controller chips on secondary bus
+   4. All three SCSI connectors may be used simultaneously without
+      SCSI "stub" effects.
+
+2. Version History
+==================
+
+   * 7.0	  (4th August, 2005)
+	- Updated driver to use SCSI transport class infrastructure
+	- Upported sequencer and core fixes from last adaptec released
+	  version of the driver.
+
+   * 6.2.36 (June 3rd, 2003)
+        - Correct code that disables PCI parity error checking.
+        - Correct and simplify handling of the ignore wide residue
+          message.  The previous code would fail to report a residual
+          if the transaction data length was even and we received
+          an IWR message.
+        - Add support for the 2.5.X EISA framework.
+        - Update for change in 2.5.X SCSI proc FS interface.
+        - Correct Domain Validation command-line option parsing.
+        - When negotiation async via an 8bit WDTR message, send
+          an SDTR with an offset of 0 to be sure the target
+          knows we are async.  This works around a firmware defect
+          in the Quantum Atlas 10K.
+        - Clear PCI error state during driver attach so that we
+          don't disable memory mapped I/O due to a stray write
+          by some other driver probe that occurred before we
+          claimed the controller.
+
+   * 6.2.35 (May 14th, 2003)
+        - Fix a few GCC 3.3 compiler warnings.
+        - Correct operation on EISA Twin Channel controller.
+        - Add support for 2.5.X's scsi_report_device_reset().
+
+   * 6.2.34 (May 5th, 2003)
+        - Fix locking regression introduced in 6.2.29 that
+          could cause a lock order reversal between the io_request_lock
+          and our per-softc lock.  This was only possible on RH9,
+          SuSE, and kernel.org 2.4.X kernels.
+
+   * 6.2.33 (April 30th, 2003)
+        - Dynamically disable PCI parity error reporting after
+          10 errors are reported to the user.  These errors are
+          the result of some other device issuing PCI transactions
+          with bad parity.  Once the user has been informed of the
+          problem, continuing to report the errors just degrades
+          our performance.
+
+   * 6.2.32 (March 28th, 2003)
+        - Dynamically sized S/G lists to avoid SCSI malloc
+          pool fragmentation and SCSI mid-layer deadlock.
+
+   * 6.2.28 (January 20th, 2003)
+        - Domain Validation Fixes
+        - Add ability to disable PCI parity error checking.
+        - Enhanced Memory Mapped I/O probe
+
+   * 6.2.20 (November 7th, 2002)
+        - Added Domain Validation.
+
+3. Command Line Options
+=======================
+
+
+    .. Warning::
+
+                 ALTERING OR ADDING THESE DRIVER PARAMETERS
+                 INCORRECTLY CAN RENDER YOUR SYSTEM INOPERABLE.
+                 USE THEM WITH CAUTION.
+
+   Put a .conf file in the /etc/modprobe.d directory and add/edit a
+   line containing ``options aic7xxx aic7xxx=[command[,command...]]`` where
+   ``command`` is one or more of the following:
+
+verbose
+
+    :Definition: enable additional informative messages during driver operation.
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+
+debug:[value]
+
+    :Definition: Enables various levels of debugging information
+    :Possible Values: 0x0000 = no debugging, 0xffff = full debugging
+    :Default Value: 0x0000
+
+no_probe
+
+probe_eisa_vl
+
+    :Definition: Do not probe for EISA/VLB controllers.
+		 This is a toggle.  If the driver is compiled
+		 to not probe EISA/VLB controllers by default,
+		 specifying "no_probe" will enable this probing.
+		 If the driver is compiled to probe EISA/VLB
+		 controllers by default, specifying "no_probe"
+		 will disable this probing.
+
+    :Possible Values: This option is a toggle
+    :Default Value: EISA/VLB probing is disabled by default.
+
+pci_parity
+
+    :Definition: Toggles the detection of PCI parity errors.
+		 On many motherboards with VIA chipsets,
+		 PCI parity is not generated correctly on the
+		 PCI bus.  It is impossible for the hardware to
+		 differentiate between these "spurious" parity
+		 errors and real parity errors.  The symptom of
+		 this problem is a stream of the message::
+
+		    "scsi0:	Data Parity Error Detected during address or write data phase"
+
+		 output by the driver.
+
+    :Possible Values: This option is a toggle
+    :Default Value: PCI Parity Error reporting is disabled
+
+no_reset
+
+    :Definition: Do not reset the bus during the initial probe
+		 phase
+
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+extended
+
+    :Definition: Force extended translation on the controller
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+periodic_otag
+
+    :Definition: Send an ordered tag periodically to prevent
+		 tag starvation.  Needed for some older devices
+
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+reverse_scan
+
+    :Definition: Probe the scsi bus in reverse order, starting
+		with target 15
+
+    :Possible Values: This option is a flag
+    :Default Value: disabled
+
+global_tag_depth:[value]
+
+    :Definition: Global tag depth for all targets on all busses.
+		 This option sets the default tag depth which
+		 may be selectively overridden vi the tag_info
+		 option.
+
+    :Possible Values: 1 - 253
+    :Default Value: 32
+
+tag_info:{{value[,value...]}[,{value[,value...]}...]}
+
+    :Definition: Set the per-target tagged queue depth on a
+		 per controller basis.  Both controllers and targets
+		 may be omitted indicating that they should retain
+		 the default tag depth.
+
+    :Possible Values: 1 - 253
+    :Default Value: 32
+
+    Examples:
+
+	    ::
+
+	        tag_info:{{16,32,32,64,8,8,,32,32,32,32,32,32,32,32,32}
+
+	    On Controller 0:
+
+		- specifies a tag depth of 16 for target 0
+		- specifies a tag depth of 64 for target 3
+		- specifies a tag depth of 8 for targets 4 and 5
+		- leaves target 6 at the default
+		- specifies a tag depth of 32 for targets 1,2,7-15
+		- All other targets retain the default depth.
+
+	    ::
+
+                tag_info:{{},{32,,32}}
+
+	    On Controller 1:
+
+		- specifies a tag depth of 32 for targets 0 and 2
+		- All other targets retain the default depth.
+
+seltime:[value]
+
+    :Definition: Specifies the selection timeout value
+    :Possible Values: 0 = 256ms, 1 = 128ms, 2 = 64ms, 3 = 32ms
+    :Default Value: 0
+
+dv: {value[,value...]}
+
+    :Definition: Set Domain Validation Policy on a per-controller basis.
+		 Controllers may be omitted indicating that
+		 they should retain the default read streaming setting.
+
+    :Possible Values:
+
+		      ==== ===============================
+		       < 0 Use setting from serial EEPROM.
+                         0 Disable DV
+		       > 0 Enable DV
+		      ==== ===============================
+
+
+    :Default Value: SCSI-Select setting on controllers with a SCSI Select
+		    option for DV.  Otherwise, on for controllers supporting
+		    U160 speeds and off for all other controller types.
+
+    Example:
+
+	    ::
+
+		dv:{-1,0,,1,1,0}
+
+	   - On Controller 0 leave DV at its default setting.
+	   - On Controller 1 disable DV.
+	   - Skip configuration on Controller 2.
+	   - On Controllers 3 and 4 enable DV.
+	   - On Controller 5 disable DV.
+
+Example::
+
+    options aic7xxx aic7xxx=verbose,no_probe,tag_info:{{},{,,10}},seltime:1
+
+enables verbose logging, Disable EISA/VLB probing,
+and set tag depth on Controller 1/Target 2 to 10 tags.
+
+4. Adaptec Customer Support
+===========================
+
+   A Technical Support Identification (TSID) Number is required for
+   Adaptec technical support.
+
+    - The 12-digit TSID can be found on the white barcode-type label
+      included inside the box with your product.  The TSID helps us
+      provide more efficient service by accurately identifying your
+      product and support status.
+
+   Support Options
+    - Search the Adaptec Support Knowledgebase (ASK) at
+      http://ask.adaptec.com for articles, troubleshooting tips, and
+      frequently asked questions about your product.
+    - For support via Email, submit your question to Adaptec's
+      Technical Support Specialists at http://ask.adaptec.com/.
+
+   North America
+    - Visit our Web site at http://www.adaptec.com/.
+    - For information about Adaptec's support options, call
+      408-957-2550, 24 hours a day, 7 days a week.
+    - To speak with a Technical Support Specialist,
+
+      * For hardware products, call 408-934-7274,
+        Monday to Friday, 3:00 am to 5:00 pm, PDT.
+      * For RAID and Fibre Channel products, call 321-207-2000,
+        Monday to Friday, 3:00 am to 5:00 pm, PDT.
+
+      To expedite your service, have your computer with you.
+    - To order Adaptec products, including accessories and cables,
+      call 408-957-7274.  To order cables online go to
+      http://www.adaptec.com/buy-cables/.
+
+   Europe
+    - Visit our Web site at http://www.adaptec.com/en-US/_common/world_index.
+    - To speak with a Technical Support Specialist, call, or email,
+
+      * German:  +49 89 4366 5522, Monday-Friday, 9:00-17:00 CET,
+        http://ask-de.adaptec.com/.
+      * French:  +49 89 4366 5533, Monday-Friday, 9:00-17:00 CET,
+	http://ask-fr.adaptec.com/.
+      * English: +49 89 4366 5544, Monday-Friday, 9:00-17:00 GMT,
+	http://ask.adaptec.com/.
+
+    - You can order Adaptec cables online at
+      http://www.adaptec.com/buy-cables/.
+
+   Japan
+    - Visit our web site at http://www.adaptec.co.jp/.
+    - To speak with a Technical Support Specialist, call
+      +81 3 5308 6120, Monday-Friday, 9:00 a.m. to 12:00 p.m.,
+      1:00 p.m. to 6:00 p.m.
+
+Copyright |copy| 2003 Adaptec Inc. 691 S. Milpitas Blvd., Milpitas CA 95035 USA.
+
+All rights reserved.
+
+You are permitted to redistribute, use and modify this README file in whole
+or in part in conjunction with redistribution of software governed by the
+General Public License, provided that the following conditions are met:
+
+1. Redistributions of README file must retain the above copyright
+   notice, this list of conditions, and the following disclaimer,
+   without modification.
+2. The name of the author may not be used to endorse or promote products
+   derived from this software without specific prior written permission.
+3. Modifications or new contributions must be attributed in a copyright
+   notice identifying the author ("Contributor") and added below the
+   original copyright notice. The copyright notice is for purposes of
+   identifying contributors and should not be deemed as permission to alter
+   the permissions given by Adaptec.
+
+THIS README FILE IS PROVIDED BY ADAPTEC AND CONTRIBUTORS ``AS IS`` AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY
+WARRANTIES OF NON-INFRINGEMENT OR THE IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
+ADAPTEC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
+TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS README
+FILE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
diff --git a/Documentation/scsi/aic7xxx.txt b/Documentation/scsi/aic7xxx.txt
deleted file mode 100644
index 7c5d0223d444..000000000000
--- a/Documentation/scsi/aic7xxx.txt
+++ /dev/null
@@ -1,394 +0,0 @@
-====================================================================
-=    Adaptec Aic7xxx Fast -> Ultra160 Family Manager Set v7.0      =
-=                            README for                            =
-=                     The Linux Operating System                   =
-====================================================================
-
-The following information is available in this file:
-
-  1. Supported Hardware
-  2. Version History
-  3. Command Line Options
-  4. Contacting Adaptec
-
-1. Supported Hardware
-
-   The following Adaptec SCSI Chips and Host Adapters are supported by
-   the aic7xxx driver. 
-
-   Chip    MIPS  Host Bus  MaxSync  MaxWidth  SCBs  Notes
-   ---------------------------------------------------------------
-   aic7770  10    EISA/VL   10MHz    16Bit      4   1
-   aic7850  10    PCI/32    10MHz    8Bit       3
-   aic7855  10    PCI/32    10MHz    8Bit       3
-   aic7856  10    PCI/32    10MHz    8Bit       3
-   aic7859  10    PCI/32    20MHz    8Bit       3
-   aic7860  10    PCI/32    20MHz    8Bit       3
-   aic7870  10    PCI/32    10MHz    16Bit      16
-   aic7880  10    PCI/32    20MHz    16Bit      16
-   aic7890  20    PCI/32    40MHz    16Bit      16      3 4 5 6 7 8
-   aic7891  20    PCI/64    40MHz    16Bit      16      3 4 5 6 7 8
-   aic7892  20   PCI/64-66  80MHz    16Bit      16      3 4 5 6 7 8
-   aic7895  15    PCI/32    20MHz    16Bit      16    2 3 4 5
-   aic7895C 15    PCI/32    20MHz    16Bit      16    2 3 4 5     8
-   aic7896  20    PCI/32    40MHz    16Bit      16    2 3 4 5 6 7 8
-   aic7897  20    PCI/64    40MHz    16Bit      16    2 3 4 5 6 7 8
-   aic7899  20   PCI/64-66  80MHz    16Bit      16    2 3 4 5 6 7 8
-
-   1.   Multiplexed Twin Channel Device - One controller servicing two
-        busses.
-   2.   Multi-function Twin Channel Device - Two controllers on one chip.
-   3.   Command Channel Secondary DMA Engine - Allows scatter gather list
-        and SCB prefetch.
-   4.   64 Byte SCB Support - Allows disconnected, untagged request table
-        for all possible target/lun combinations.
-   5.   Block Move Instruction Support - Doubles the speed of certain
-        sequencer operations.
-   6.   `Bayonet' style Scatter Gather Engine - Improves S/G prefetch
-        performance.
-   7.   Queuing Registers - Allows queuing of new transactions without
-        pausing the sequencer.
-   8.   Multiple Target IDs - Allows the controller to respond to selection
-        as a target on multiple SCSI IDs.
-
-   Controller      Chip   Host-Bus    Int-Connectors  Ext-Connectors  Notes
-   --------------------------------------------------------------------------
-   AHA-274X[A]    aic7770   EISA         SE-50M         SE-HD50F
-   AHA-274X[A]W   aic7770   EISA         SE-HD68F       SE-HD68F
-                                         SE-50M
-   AHA-274X[A]T   aic7770   EISA       2 X SE-50M       SE-HD50F
-   AHA-2842       aic7770    VL          SE-50M         SE-HD50F
-   AHA-2940AU     aic7860   PCI/32       SE-50M         SE-HD50F
-   AVA-2902I      aic7860   PCI/32       SE-50M
-   AVA-2902E      aic7860   PCI/32       SE-50M
-   AVA-2906       aic7856   PCI/32       SE-50M         SE-DB25F
-   APC-7850       aic7850   PCI/32       SE-50M                       1
-   AVA-2940       aic7860   PCI/32       SE-50M
-   AHA-2920B      aic7860   PCI/32       SE-50M
-   AHA-2930B      aic7860   PCI/32       SE-50M
-   AHA-2920C      aic7856   PCI/32       SE-50M         SE-HD50F
-   AHA-2930C      aic7860   PCI/32       SE-50M
-   AHA-2930C      aic7860   PCI/32       SE-50M
-   AHA-2910C      aic7860   PCI/32       SE-50M
-   AHA-2915C      aic7860   PCI/32       SE-50M
-   AHA-2940AU/CN  aic7860   PCI/32       SE-50M         SE-HD50F
-   AHA-2944W      aic7870   PCI/32     HVD-HD68F        HVD-HD68F
-                                        HVD-50M
-   AHA-3940W      aic7870   PCI/32     2 X SE-HD68F     SE-HD68F        2
-   AHA-2940UW     aic7880   PCI/32       SE-HD68F
-                                         SE-50M         SE-HD68F
-   AHA-2940U      aic7880   PCI/32       SE-50M         SE-HD50F
-   AHA-2940D      aic7880   PCI/32
-   aHA-2940 A/T   aic7880   PCI/32
-   AHA-2940D A/T  aic7880   PCI/32
-   AHA-3940UW     aic7880   PCI/32     2 X SE-HD68F     SE-HD68F          3
-   AHA-3940UWD    aic7880   PCI/32     2 X SE-HD68F   2 X SE-VHD68F       3
-   AHA-3940U      aic7880   PCI/32     2 X SE-50M       SE-HD50F          3
-   AHA-2944UW     aic7880   PCI/32      HVD-HD68F       HVD-HD68F
-                                         HVD-50M
-   AHA-3944UWD    aic7880   PCI/32     2 X HVD-HD68F  2 X HVD-VHD68F      3
-   AHA-4944UW     aic7880   PCI/32
-   AHA-2930UW     aic7880   PCI/32
-   AHA-2940UW Pro aic7880   PCI/32      SE-HD68F        SE-HD68F            4
-                                         SE-50M
-   AHA-2940UW/CN  aic7880   PCI/32
-   AHA-2940UDual  aic7895   PCI/32
-   AHA-2940UWDual aic7895   PCI/32
-   AHA-3940UWD    aic7895   PCI/32
-   AHA-3940AUW    aic7895   PCI/32
-   AHA-3940AUWD   aic7895   PCI/32
-   AHA-3940AU     aic7895   PCI/32
-   AHA-3944AUWD   aic7895   PCI/32     2 X HVD-HD68F  2 X HVD-VHD68F
-   AHA-2940U2B    aic7890   PCI/32      LVD-HD68F       LVD-HD68F
-   AHA-2940U2 OEM aic7891   PCI/64
-   AHA-2940U2W    aic7890   PCI/32      LVD-HD68F       LVD-HD68F
-                                        SE-HD68F 
-                                         SE-50M
-   AHA-2950U2B    aic7891   PCI/64      LVD-HD68F       LVD-HD68F
-   AHA-2930U2     aic7890   PCI/32      LVD-HD68F       SE-HD50F
-                                         SE-50M 
-   AHA-3950U2B    aic7897   PCI/64
-   AHA-3950U2D    aic7897   PCI/64
-   AHA-29160      aic7892   PCI/64-66
-   AHA-29160 CPQ  aic7892   PCI/64-66
-   AHA-29160N     aic7892   PCI/32      LVD-HD68F       SE-HD50F
-                                         SE-50M
-   AHA-29160LP    aic7892   PCI/64-66
-   AHA-19160      aic7892   PCI/64-66
-   AHA-29150LP    aic7892   PCI/64-66
-   AHA-29130LP    aic7892   PCI/64-66
-   AHA-3960D      aic7899   PCI/64-66  2 X LVD-HD68F  2 X LVD-VHD68F
-                                         LVD-50M
-   AHA-3960D CPQ  aic7899   PCI/64-66  2 X LVD-HD68F  2 X LVD-VHD68F
-                                         LVD-50M
-   AHA-39160      aic7899   PCI/64-66  2 X LVD-HD68F  2 X LVD-VHD68F
-                                         LVD-50M
-
-   1. No BIOS support
-   2. DEC21050 PCI-PCI bridge with multiple controller chips on secondary bus
-   3. DEC2115X PCI-PCI bridge with multiple controller chips on secondary bus
-   4. All three SCSI connectors may be used simultaneously without
-      SCSI "stub" effects.
-
-2. Version History
-   7.0	  (4th August, 2005)
-	- Updated driver to use SCSI transport class infrastructure
-	- Upported sequencer and core fixes from last adaptec released
-	  version of the driver.
-   6.2.36 (June 3rd, 2003)
-        - Correct code that disables PCI parity error checking.
-        - Correct and simplify handling of the ignore wide residue
-          message.  The previous code would fail to report a residual
-          if the transaction data length was even and we received
-          an IWR message.
-        - Add support for the 2.5.X EISA framework.
-        - Update for change in 2.5.X SCSI proc FS interface.
-        - Correct Domain Validation command-line option parsing.
-        - When negotiation async via an 8bit WDTR message, send
-          an SDTR with an offset of 0 to be sure the target
-          knows we are async.  This works around a firmware defect
-          in the Quantum Atlas 10K.
-        - Clear PCI error state during driver attach so that we
-          don't disable memory mapped I/O due to a stray write
-          by some other driver probe that occurred before we
-          claimed the controller.
-
-   6.2.35 (May 14th, 2003)
-        - Fix a few GCC 3.3 compiler warnings.
-        - Correct operation on EISA Twin Channel controller.
-        - Add support for 2.5.X's scsi_report_device_reset().
-
-   6.2.34 (May 5th, 2003)
-        - Fix locking regression introduced in 6.2.29 that
-          could cause a lock order reversal between the io_request_lock
-          and our per-softc lock.  This was only possible on RH9,
-          SuSE, and kernel.org 2.4.X kernels.
-
-   6.2.33 (April 30th, 2003)
-        - Dynamically disable PCI parity error reporting after
-          10 errors are reported to the user.  These errors are
-          the result of some other device issuing PCI transactions
-          with bad parity.  Once the user has been informed of the
-          problem, continuing to report the errors just degrades
-          our performance.
-
-   6.2.32 (March 28th, 2003)
-        - Dynamically sized S/G lists to avoid SCSI malloc
-          pool fragmentation and SCSI mid-layer deadlock.
-
-   6.2.28 (January 20th, 2003)
-        - Domain Validation Fixes
-        - Add ability to disable PCI parity error checking.
-        - Enhanced Memory Mapped I/O probe
-
-   6.2.20 (November 7th, 2002)
-        - Added Domain Validation.
-
-3. Command Line Options
-
-        WARNING: ALTERING OR ADDING THESE DRIVER PARAMETERS
-                 INCORRECTLY CAN RENDER YOUR SYSTEM INOPERABLE.
-                 USE THEM WITH CAUTION. 
-
-   Put a .conf file in the /etc/modprobe.d directory and add/edit a
-   line containing 'options aic7xxx aic7xxx=[command[,command...]]' where
-   'command' is one or more of the following:
-   -----------------------------------------------------------------
-              Option: verbose
-          Definition: enable additional informative messages during
-                      driver operation.
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: debug:[value]
-          Definition: Enables various levels of debugging information
-     Possible Values: 0x0000 = no debugging, 0xffff = full debugging
-       Default Value: 0x0000
-   -----------------------------------------------------------------
-              Option: no_probe
-              Option: probe_eisa_vl
-          Definition: Do not probe for EISA/VLB controllers.
-                      This is a toggle.  If the driver is compiled
-                      to not probe EISA/VLB controllers by default,
-                      specifying "no_probe" will enable this probing.
-                      If the driver is compiled to probe EISA/VLB
-                      controllers by default, specifying "no_probe"
-                      will disable this probing.
-     Possible Values: This option is a toggle
-       Default Value: EISA/VLB probing is disabled by default.
-   -----------------------------------------------------------------
-              Option: pci_parity
-          Definition: Toggles the detection of PCI parity errors.
-                      On many motherboards with VIA chipsets,
-                      PCI parity is not generated correctly on the
-                      PCI bus.  It is impossible for the hardware to
-                      differentiate between these "spurious" parity
-                      errors and real parity errors.  The symptom of
-                      this problem is a stream of the message:
-    "scsi0: Data Parity Error Detected during address or write data phase"
-                      output by the driver.
-     Possible Values: This option is a toggle
-       Default Value: PCI Parity Error reporting is disabled
-   -----------------------------------------------------------------
-              Option: no_reset
-          Definition: Do not reset the bus during the initial probe
-                      phase
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: extended
-          Definition: Force extended translation on the controller
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: periodic_otag
-          Definition: Send an ordered tag periodically to prevent
-                      tag starvation.  Needed for some older devices
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: reverse_scan
-          Definition: Probe the scsi bus in reverse order, starting
-                      with target 15
-     Possible Values: This option is a flag
-       Default Value: disabled
-   -----------------------------------------------------------------
-              Option: global_tag_depth:[value]
-          Definition: Global tag depth for all targets on all busses.
-                      This option sets the default tag depth which
-                      may be selectively overridden vi the tag_info
-                      option.
-     Possible Values: 1 - 253
-       Default Value: 32
-   -----------------------------------------------------------------
-              Option: tag_info:{{value[,value...]}[,{value[,value...]}...]}
-          Definition: Set the per-target tagged queue depth on a
-                      per controller basis.  Both controllers and targets
-                      may be omitted indicating that they should retain
-                      the default tag depth.
-            Examples: tag_info:{{16,32,32,64,8,8,,32,32,32,32,32,32,32,32,32}
-                        On Controller 0
-                          specifies a tag depth of 16 for target 0
-                          specifies a tag depth of 64 for target 3
-                          specifies a tag depth of 8 for targets 4 and 5
-                          leaves target 6 at the default
-                          specifies a tag depth of 32 for targets 1,2,7-15
-                        All other targets retain the default depth.
-
-                      tag_info:{{},{32,,32}}
-                        On Controller 1
-                          specifies a tag depth of 32 for targets 0 and 2
-                        All other targets retain the default depth.
-                        
-     Possible Values: 1 - 253
-       Default Value: 32
-   -----------------------------------------------------------------
-              Option: seltime:[value]
-          Definition: Specifies the selection timeout value
-     Possible Values: 0 = 256ms, 1 = 128ms, 2 = 64ms, 3 = 32ms
-       Default Value: 0
-   -----------------------------------------------------------------
-              Option: dv: {value[,value...]} 
-          Definition: Set Domain Validation Policy on a per-controller basis.
-                      Controllers may be omitted indicating that
-                      they should retain the default read streaming setting.
-             Example: dv:{-1,0,,1,1,0}
-                        On Controller 0 leave DV at its default setting.
-                        On Controller 1 disable DV.
-                        Skip configuration on Controller 2.
-                        On Controllers 3 and 4 enable DV.
-                        On Controller 5 disable DV.
-
-     Possible Values: < 0 Use setting from serial EEPROM.
-                      0 Disable DV
-                      > 0 Enable DV
-
-       Default Value: SCSI-Select setting on controllers with a SCSI Select
-                      option for DV.  Otherwise, on for controllers supporting
-                      U160 speeds and off for all other controller types.
-   -----------------------------------------------------------------
-
-   Example:
-   'options aic7xxx aic7xxx=verbose,no_probe,tag_info:{{},{,,10}},seltime:1'
-        enables verbose logging, Disable EISA/VLB probing,
-        and set tag depth on Controller 1/Target 2 to 10 tags.
-
-4. Adaptec Customer Support
-
-   A Technical Support Identification (TSID) Number is required for 
-   Adaptec technical support.
-    - The 12-digit TSID can be found on the white barcode-type label
-      included inside the box with your product.  The TSID helps us 
-      provide more efficient service by accurately identifying your 
-      product and support status.
-
-   Support Options
-    - Search the Adaptec Support Knowledgebase (ASK) at
-      http://ask.adaptec.com for articles, troubleshooting tips, and
-      frequently asked questions about your product.
-    - For support via Email, submit your question to Adaptec's 
-      Technical Support Specialists at http://ask.adaptec.com/.
-     
-   North America
-    - Visit our Web site at http://www.adaptec.com/.
-    - For information about Adaptec's support options, call
-      408-957-2550, 24 hours a day, 7 days a week.
-    - To speak with a Technical Support Specialist,
-      * For hardware products, call 408-934-7274,
-        Monday to Friday, 3:00 am to 5:00 pm, PDT.
-      * For RAID and Fibre Channel products, call 321-207-2000,
-        Monday to Friday, 3:00 am to 5:00 pm, PDT.
-      To expedite your service, have your computer with you.
-    - To order Adaptec products, including accessories and cables,
-      call 408-957-7274.  To order cables online go to
-      http://www.adaptec.com/buy-cables/.
-
-   Europe
-    - Visit our Web site at http://www.adaptec.com/en-US/_common/world_index.
-    - To speak with a Technical Support Specialist, call, or email,
-      * German:  +49 89 4366 5522, Monday-Friday, 9:00-17:00 CET,
-        http://ask-de.adaptec.com/.
-      * French:  +49 89 4366 5533, Monday-Friday, 9:00-17:00 CET,
-	http://ask-fr.adaptec.com/.
-      * English: +49 89 4366 5544, Monday-Friday, 9:00-17:00 GMT,
-	http://ask.adaptec.com/.
-    - You can order Adaptec cables online at
-      http://www.adaptec.com/buy-cables/.
-
-   Japan
-    - Visit our web site at http://www.adaptec.co.jp/.
-    - To speak with a Technical Support Specialist, call 
-      +81 3 5308 6120, Monday-Friday, 9:00 a.m. to 12:00 p.m.,
-      1:00 p.m. to 6:00 p.m.
-
--------------------------------------------------------------------
-/*
- * Copyright (c) 2003 Adaptec Inc. 691 S. Milpitas Blvd., Milpitas CA 95035 USA.
- * All rights reserved.
- *
- * You are permitted to redistribute, use and modify this README file in whole
- * or in part in conjunction with redistribution of software governed by the
- * General Public License, provided that the following conditions are met:
- * 1. Redistributions of README file must retain the above copyright
- *    notice, this list of conditions, and the following disclaimer,
- *    without modification.
- * 2. The name of the author may not be used to endorse or promote products
- *    derived from this software without specific prior written permission.
- * 3. Modifications or new contributions must be attributed in a copyright
- *    notice identifying the author ("Contributor") and added below the
- *    original copyright notice. The copyright notice is for purposes of
- *    identifying contributors and should not be deemed as permission to alter
- *    the permissions given by Adaptec.
- *
- * THIS README FILE IS PROVIDED BY ADAPTEC AND CONTRIBUTORS ``AS IS'' AND
- * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, ANY
- * WARRANTIES OF NON-INFRINGEMENT OR THE IMPLIED WARRANTIES OF MERCHANTABILITY
- * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
- * ADAPTEC OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
- * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
- * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
- * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
- * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS README
- * FILE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
- */
diff --git a/Documentation/scsi/arcmsr_spec.rst b/Documentation/scsi/arcmsr_spec.rst
new file mode 100644
index 000000000000..83dd53bcff78
--- /dev/null
+++ b/Documentation/scsi/arcmsr_spec.rst
@@ -0,0 +1,907 @@
+ARECA FIRMWARE SPEC
+===================
+
+Usage of IOP331 adapter
+=======================
+
+(All In/Out is in IOP331's view)
+
+1. Message 0
+------------
+
+- InitThread message and return code
+
+2. Doorbell is used for RS-232 emulation
+----------------------------------------
+
+inDoorBell
+    bit0
+	data in ready
+	zDRIVER DATA WRITE OK)
+    bit1
+	data out has been read
+	(DRIVER DATA READ OK)
+
+outDooeBell:
+    bit0
+	data out ready
+	(IOP331 DATA WRITE OK)
+    bit1
+	data in has been read
+	(IOP331 DATA READ OK)
+
+3. Index Memory Usage
+---------------------
+
+============   ==========================================
+offset 0xf00   for RS232 out (request buffer)
+offset 0xe00   for RS232 in  (scratch buffer)
+offset 0xa00   for inbound message code message_rwbuffer
+	       (driver send to IOP331)
+offset 0xa00   for outbound message code message_rwbuffer
+	       (IOP331 send to driver)
+============   ==========================================
+
+4. RS-232 emulation
+-------------------
+
+Currently 128 byte buffer is used:
+
+============   =====================
+1st uint32_t   Data length (1--124)
+Byte 4--127    Max 124 bytes of data
+============   =====================
+
+5. PostQ
+--------
+
+All SCSI Command must be sent through postQ:
+
+    (inbound queue port)
+	Request frame must be 32 bytes aligned:
+
+	    #bit27--bit31
+		flag for post ccb
+	    #bit0--bit26
+		real address (bit27--bit31) of post arcmsr_cdb
+
+		=====   ===================
+		bit31   ==  ===============
+			0   256 bytes frame
+			1   512 bytes frame
+			==  ===============
+		bit30   ==  ==============
+			0   normal request
+			1   BIOS request
+			==  ==============
+		bit29   reserved
+		bit28   reserved
+		bit27   reserved
+		=====   ===================
+
+    (outbount queue port)
+	Request reply:
+
+	    #bit27--bit31
+		    flag for reply
+	    #bit0--bit26
+		    real address (bit27--bit31) of reply arcmsr_cdb
+
+		    =====   =======================================================
+		    bit31   must be 0 (for this type of reply)
+		    bit30   reserved for BIOS handshake
+		    bit29   reserved
+		    bit28   ==  ===================================================
+			    0   no error, ignore AdapStatus/DevStatus/SenseData
+			    1   Error, error code in AdapStatus/DevStatus/SenseData
+			    ==  ===================================================
+		    bit27   reserved
+		    =====   =======================================================
+
+6. BIOS request
+---------------
+
+All BIOS request is the same with request from PostQ
+
+Except:
+
+Request frame is sent from configuration space:
+
+	============   ==========================
+	offset: 0x78   Request Frame (bit30 == 1)
+	offset: 0x18   writeonly to generate
+		       IRQ to IOP331
+	============   ==========================
+
+Completion of request::
+
+	(bit30 == 0, bit28==err flag)
+
+7. Definition of SGL entry (structure)
+--------------------------------------
+
+8. Message1 Out - Diag Status Code (????)
+-----------------------------------------
+
+9. Message0 message code
+------------------------
+
+======  =================================================================
+0x00    NOP
+0x01    Get Config
+	->offset 0xa00 :for outbound message code message_rwbuffer
+	(IOP331 send to driver)
+
+	===================== ==========================================
+	Signature             0x87974060(4)
+	Request len           0x00000200(4)
+	numbers of queue      0x00000100(4)
+	SDRAM Size            0x00000100(4)-->256 MB
+	IDE Channels          0x00000008(4)
+	vendor                40 bytes char
+	model                 8 bytes char
+	FirmVer               16 bytes char
+	Device Map            16 bytes char
+	FirmwareVersion       DWORD
+
+			      - Added for checking of
+				new firmware capability
+	===================== ==========================================
+0x02    Set Config
+	->offset 0xa00 :for inbound message code message_rwbuffer
+	(driver send to IOP331)
+
+	========================= ==================
+	Signature                 0x87974063(4)
+	UPPER32 of Request Frame  (4)-->Driver Only
+	========================= ==================
+0x03    Reset (Abort all queued Command)
+0x04    Stop Background Activity
+0x05    Flush Cache
+0x06    Start Background Activity
+	(re-start if background is halted)
+0x07    Check If Host Command Pending
+	(Novell May Need This Function)
+0x08    Set controller time
+	->offset 0xa00   for inbound message code message_rwbuffer
+	(driver to IOP331)
+
+	======   ==================
+	byte 0   0xaa <-- signature
+	byte 1   0x55 <-- signature
+	byte 2   year (04)
+	byte 3   month (1..12)
+	byte 4   date (1..31)
+	byte 5   hour (0..23)
+	byte 6   minute (0..59)
+	byte 7   second (0..59)
+	======   ==================
+======  =================================================================
+
+
+RS-232 Interface for Areca Raid Controller
+==========================================
+
+      The low level command interface is exclusive with VT100 terminal
+
+1. Sequence of command execution
+--------------------------------
+
+	(A) Header
+		3 bytes sequence (0x5E, 0x01, 0x61)
+
+	(B) Command block
+		variable length of data including length,
+		command code, data and checksum byte
+
+	(C) Return data
+		variable length of data
+
+2. Command block
+----------------
+
+	(A) 1st byte
+		command block length (low byte)
+
+	(B) 2nd byte
+		command block length (high byte)
+
+		.. Note:: command block length shouldn't > 2040 bytes,
+			  length excludes these two bytes
+
+	(C) 3rd byte
+		command code
+
+	(D) 4th and following bytes
+		variable length data bytes
+
+	    depends on command code
+
+	(E) last byte
+	    checksum byte (sum of 1st byte until last data byte)
+
+3. Command code and associated data
+-----------------------------------
+
+The following are command code defined in raid controller Command
+code 0x10--0x1? are used for system level management,
+no password checking is needed and should be implemented in separate
+well controlled utility and not for end user access.
+Command code 0x20--0x?? always check the password,
+password must be entered to enable these command::
+
+	enum
+	{
+		GUI_SET_SERIAL=0x10,
+		GUI_SET_VENDOR,
+		GUI_SET_MODEL,
+		GUI_IDENTIFY,
+		GUI_CHECK_PASSWORD,
+		GUI_LOGOUT,
+		GUI_HTTP,
+		GUI_SET_ETHERNET_ADDR,
+		GUI_SET_LOGO,
+		GUI_POLL_EVENT,
+		GUI_GET_EVENT,
+		GUI_GET_HW_MONITOR,
+		//    GUI_QUICK_CREATE=0x20, (function removed)
+		GUI_GET_INFO_R=0x20,
+		GUI_GET_INFO_V,
+		GUI_GET_INFO_P,
+		GUI_GET_INFO_S,
+		GUI_CLEAR_EVENT,
+		GUI_MUTE_BEEPER=0x30,
+		GUI_BEEPER_SETTING,
+		GUI_SET_PASSWORD,
+		GUI_HOST_INTERFACE_MODE,
+		GUI_REBUILD_PRIORITY,
+		GUI_MAX_ATA_MODE,
+		GUI_RESET_CONTROLLER,
+		GUI_COM_PORT_SETTING,
+		GUI_NO_OPERATION,
+		GUI_DHCP_IP,
+		GUI_CREATE_PASS_THROUGH=0x40,
+		GUI_MODIFY_PASS_THROUGH,
+		GUI_DELETE_PASS_THROUGH,
+		GUI_IDENTIFY_DEVICE,
+		GUI_CREATE_RAIDSET=0x50,
+		GUI_DELETE_RAIDSET,
+		GUI_EXPAND_RAIDSET,
+		GUI_ACTIVATE_RAIDSET,
+		GUI_CREATE_HOT_SPARE,
+		GUI_DELETE_HOT_SPARE,
+		GUI_CREATE_VOLUME=0x60,
+		GUI_MODIFY_VOLUME,
+		GUI_DELETE_VOLUME,
+		GUI_START_CHECK_VOLUME,
+		GUI_STOP_CHECK_VOLUME
+	};
+
+Command description
+^^^^^^^^^^^^^^^^^^^
+
+GUI_SET_SERIAL
+	Set the controller serial#
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x10
+	byte 3            password length (should be 0x0f)
+	byte 4-0x13       should be "ArEcATecHnoLogY"
+	byte 0x14--0x23   Serial number string (must be 16 bytes)
+	================  =============================================
+
+GUI_SET_VENDOR
+	Set vendor string for the controller
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x11
+	byte 3            password length (should be 0x08)
+	byte 4-0x13       should be "ArEcAvAr"
+	byte 0x14--0x3B   vendor string (must be 40 bytes)
+	================  =============================================
+
+GUI_SET_MODEL
+	Set the model name of the controller
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x12
+	byte 3            password length (should be 0x08)
+	byte 4-0x13       should be "ArEcAvAr"
+	byte 0x14--0x1B   model string (must be 8 bytes)
+	================  =============================================
+
+GUI_IDENTIFY
+	Identify device
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x13
+			    return "Areca RAID Subsystem "
+	================  =============================================
+
+GUI_CHECK_PASSWORD
+	Verify password
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x14
+	byte 3            password length
+	byte 4-0x??       user password to be checked
+	================  =============================================
+
+GUI_LOGOUT
+	Logout GUI (force password checking on next command)
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x15
+	================  =============================================
+
+GUI_HTTP
+	HTTP interface (reserved for Http proxy service)(0x16)
+
+GUI_SET_ETHERNET_ADDR
+	Set the ethernet MAC address
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x17
+	byte 3            password length (should be 0x08)
+	byte 4-0x13       should be "ArEcAvAr"
+	byte 0x14--0x19   Ethernet MAC address (must be 6 bytes)
+	================  =============================================
+
+GUI_SET_LOGO
+	Set logo in HTTP
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x18
+	byte 3            Page# (0/1/2/3) (0xff --> clear OEM logo)
+	byte 4/5/6/7      0x55/0xaa/0xa5/0x5a
+	byte 8            TITLE.JPG data (each page must be 2000 bytes)
+
+			  .. Note:: page0 1st 2 byte must be
+				    actual length of the JPG file
+	================  =============================================
+
+GUI_POLL_EVENT
+	Poll If Event Log Changed
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x19
+	================  =============================================
+
+GUI_GET_EVENT
+	Read Event
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x1a
+	byte 3            Event Page (0:1st page/1/2/3:last page)
+	================  =============================================
+
+GUI_GET_HW_MONITOR
+	Get HW monitor data
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x1b
+	byte 3 		  # of FANs(example 2)
+	byte 4 		  # of Voltage sensor(example 3)
+	byte 5 		  # of temperature sensor(example 2)
+	byte 6 		  # of power
+	byte 7/8          Fan#0 (RPM)
+	byte 9/10         Fan#1
+	byte 11/12 	  Voltage#0 original value in ``*1000``
+	byte 13/14 	  Voltage#0 value
+	byte 15/16 	  Voltage#1 org
+	byte 17/18 	  Voltage#1
+	byte 19/20 	  Voltage#2 org
+	byte 21/22 	  Voltage#2
+	byte 23 	  Temp#0
+	byte 24 	  Temp#1
+	byte 25 	  Power indicator (bit0   power#0,
+			  bit1   power#1)
+	byte 26 	  UPS indicator
+	================  =============================================
+
+GUI_QUICK_CREATE
+	Quick create raid/volume set
+
+	================  ==============================================
+	byte 0,1       	  length
+	byte 2         	  command code 0x20
+	byte 3/4/5/6   	  raw capacity
+	byte 7 		  raid level
+	byte 8 		  stripe size
+	byte 9 		  spare
+	byte 10/11/12/13  device mask (the devices to create raid/volume)
+	================  ==============================================
+
+    This function is removed, application like
+    to implement quick create function
+
+    need to use GUI_CREATE_RAIDSET and GUI_CREATE_VOLUMESET function.
+
+GUI_GET_INFO_R
+	Get Raid Set Information
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x20
+	byte 3            raidset#
+	================  =============================================
+
+	::
+
+	    typedef struct sGUI_RAIDSET
+	    {
+		    BYTE grsRaidSetName[16];
+		    DWORD grsCapacity;
+		    DWORD grsCapacityX;
+		    DWORD grsFailMask;
+		    BYTE grsDevArray[32];
+		    BYTE grsMemberDevices;
+		    BYTE grsNewMemberDevices;
+		    BYTE grsRaidState;
+		    BYTE grsVolumes;
+		    BYTE grsVolumeList[16];
+		    BYTE grsRes1;
+		    BYTE grsRes2;
+		    BYTE grsRes3;
+		    BYTE grsFreeSegments;
+		    DWORD grsRawStripes[8];
+		    DWORD grsRes4;
+		    DWORD grsRes5; //     Total to 128 bytes
+		    DWORD grsRes6; //     Total to 128 bytes
+	    } sGUI_RAIDSET, *pGUI_RAIDSET;
+
+GUI_GET_INFO_V
+	Get Volume Set Information
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x21
+	byte 3            volumeset#
+	================  =============================================
+
+	::
+
+	    typedef struct sGUI_VOLUMESET
+	    {
+		    BYTE gvsVolumeName[16]; //     16
+		    DWORD gvsCapacity;
+		    DWORD gvsCapacityX;
+		    DWORD gvsFailMask;
+		    DWORD gvsStripeSize;
+		    DWORD gvsNewFailMask;
+		    DWORD gvsNewStripeSize;
+		    DWORD gvsVolumeStatus;
+		    DWORD gvsProgress; //     32
+		    sSCSI_ATTR gvsScsi;
+		    BYTE gvsMemberDisks;
+		    BYTE gvsRaidLevel; //     8
+		    BYTE gvsNewMemberDisks;
+		    BYTE gvsNewRaidLevel;
+		    BYTE gvsRaidSetNumber;
+		    BYTE gvsRes0; //     4
+		    BYTE gvsRes1[4]; //     64 bytes
+	    } sGUI_VOLUMESET, *pGUI_VOLUMESET;
+
+GUI_GET_INFO_P
+	Get Physical Drive Information
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x22
+	byte 3            drive # (from 0 to max-channels - 1)
+	================  =============================================
+
+	::
+
+	    typedef struct sGUI_PHY_DRV
+	    {
+		    BYTE gpdModelName[40];
+		    BYTE gpdSerialNumber[20];
+		    BYTE gpdFirmRev[8];
+		    DWORD gpdCapacity;
+		    DWORD gpdCapacityX; //     Reserved for expansion
+		    BYTE gpdDeviceState;
+		    BYTE gpdPioMode;
+		    BYTE gpdCurrentUdmaMode;
+		    BYTE gpdUdmaMode;
+		    BYTE gpdDriveSelect;
+		    BYTE gpdRaidNumber; //     0xff if not belongs to a raid set
+		    sSCSI_ATTR gpdScsi;
+		    BYTE gpdReserved[40]; //     Total to 128 bytes
+	    } sGUI_PHY_DRV, *pGUI_PHY_DRV;
+
+GUI_GET_INFO_S
+	Get System Information
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x23
+	================  =============================================
+
+	::
+
+	    typedef struct sCOM_ATTR
+	    {
+		    BYTE comBaudRate;
+		    BYTE comDataBits;
+		    BYTE comStopBits;
+		    BYTE comParity;
+		    BYTE comFlowControl;
+	    } sCOM_ATTR, *pCOM_ATTR;
+	    typedef struct sSYSTEM_INFO
+	    {
+		    BYTE gsiVendorName[40];
+		    BYTE gsiSerialNumber[16];
+		    BYTE gsiFirmVersion[16];
+		    BYTE gsiBootVersion[16];
+		    BYTE gsiMbVersion[16];
+		    BYTE gsiModelName[8];
+		    BYTE gsiLocalIp[4];
+		    BYTE gsiCurrentIp[4];
+		    DWORD gsiTimeTick;
+		    DWORD gsiCpuSpeed;
+		    DWORD gsiICache;
+		    DWORD gsiDCache;
+		    DWORD gsiScache;
+		    DWORD gsiMemorySize;
+		    DWORD gsiMemorySpeed;
+		    DWORD gsiEvents;
+		    BYTE gsiMacAddress[6];
+		    BYTE gsiDhcp;
+		    BYTE gsiBeeper;
+		    BYTE gsiChannelUsage;
+		    BYTE gsiMaxAtaMode;
+		    BYTE gsiSdramEcc; //     1:if ECC enabled
+		    BYTE gsiRebuildPriority;
+		    sCOM_ATTR gsiComA; //     5 bytes
+		    sCOM_ATTR gsiComB; //     5 bytes
+		    BYTE gsiIdeChannels;
+		    BYTE gsiScsiHostChannels;
+		    BYTE gsiIdeHostChannels;
+		    BYTE gsiMaxVolumeSet;
+		    BYTE gsiMaxRaidSet;
+		    BYTE gsiEtherPort; //     1:if ether net port supported
+		    BYTE gsiRaid6Engine; //     1:Raid6 engine supported
+		    BYTE gsiRes[75];
+	    } sSYSTEM_INFO, *pSYSTEM_INFO;
+
+GUI_CLEAR_EVENT
+	Clear System Event
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x24
+	================  =============================================
+
+GUI_MUTE_BEEPER
+	Mute current beeper
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x30
+	================  =============================================
+GUI_BEEPER_SETTING
+	Disable beeper
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x31
+	byte 3            0->disable, 1->enable
+	================  =============================================
+
+GUI_SET_PASSWORD
+	Change password
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x32
+	byte 3 		  pass word length ( must <= 15 )
+	byte 4 		  password (must be alpha-numerical)
+	================  =============================================
+
+GUI_HOST_INTERFACE_MODE
+	Set host interface mode
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x33
+	byte 3 		  0->Independent, 1->cluster
+	================  =============================================
+
+GUI_REBUILD_PRIORITY
+	Set rebuild priority
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x34
+	byte 3 		  0/1/2/3 (low->high)
+	================  =============================================
+
+GUI_MAX_ATA_MODE
+	Set maximum ATA mode to be used
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x35
+	byte 3 		  0/1/2/3 (133/100/66/33)
+	================  =============================================
+
+GUI_RESET_CONTROLLER
+	Reset Controller
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x36
+			  * Response with VT100 screen (discard it)
+	================  =============================================
+
+GUI_COM_PORT_SETTING
+	COM port setting
+
+	================  =================================================
+	byte 0,1	  length
+	byte 2 		  command code 0x37
+	byte 3 		  0->COMA (term port),
+			  1->COMB (debug port)
+	byte 4 		  0/1/2/3/4/5/6/7
+			  (1200/2400/4800/9600/19200/38400/57600/115200)
+	byte 5 		  data bit
+			  (0:7 bit, 1:8 bit   must be 8 bit)
+	byte 6 		  stop bit (0:1, 1:2 stop bits)
+	byte 7 		  parity (0:none, 1:off, 2:even)
+	byte 8 		  flow control
+			  (0:none, 1:xon/xoff, 2:hardware => must use none)
+	================  =================================================
+
+GUI_NO_OPERATION
+	No operation
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x38
+	================  =============================================
+
+GUI_DHCP_IP
+	Set DHCP option and local IP address
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x39
+	byte 3            0:dhcp disabled, 1:dhcp enabled
+	byte 4/5/6/7      IP address
+	================  =============================================
+
+GUI_CREATE_PASS_THROUGH
+	Create pass through disk
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x40
+	byte 3 		  device #
+	byte 4 		  scsi channel (0/1)
+	byte 5 		  scsi id (0-->15)
+	byte 6 		  scsi lun (0-->7)
+	byte 7 		  tagged queue (1   enabled)
+	byte 8 		  cache mode (1   enabled)
+	byte 9 		  max speed (0/1/2/3/4,
+			  async/20/40/80/160 for scsi)
+			  (0/1/2/3/4, 33/66/100/133/150 for ide  )
+	================  =============================================
+
+GUI_MODIFY_PASS_THROUGH
+	Modify pass through disk
+
+	================  =============================================
+	byte 0,1          length
+	byte 2 		  command code 0x41
+	byte 3 		  device #
+	byte 4 		  scsi channel (0/1)
+	byte 5 		  scsi id (0-->15)
+	byte 6 		  scsi lun (0-->7)
+	byte 7 		  tagged queue (1   enabled)
+	byte 8 		  cache mode (1   enabled)
+	byte 9 		  max speed (0/1/2/3/4,
+			  async/20/40/80/160 for scsi)
+			  (0/1/2/3/4, 33/66/100/133/150 for ide  )
+	================  =============================================
+
+GUI_DELETE_PASS_THROUGH
+	Delete pass through disk
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x42
+	byte 3            device# to be deleted
+	================  =============================================
+GUI_IDENTIFY_DEVICE
+	Identify Device
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x43
+	byte 3            Flash Method
+			  (0:flash selected, 1:flash not selected)
+	byte 4/5/6/7      IDE device mask to be flashed
+			  .. Note:: no response data available
+	================  =============================================
+
+GUI_CREATE_RAIDSET
+	Create Raid Set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x50
+	byte 3/4/5/6      device mask
+	byte 7-22         raidset name (if byte 7 == 0:use default)
+	================  =============================================
+
+GUI_DELETE_RAIDSET
+	Delete Raid Set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x51
+	byte 3            raidset#
+	================  =============================================
+
+GUI_EXPAND_RAIDSET
+	Expand Raid Set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x52
+	byte 3            raidset#
+	byte 4/5/6/7      device mask for expansion
+	byte 8/9/10       (8:0 no change, 1 change, 0xff:terminate,
+			  9:new raid level,
+			  10:new stripe size
+			  0/1/2/3/4/5->4/8/16/32/64/128K )
+	byte 11/12/13     repeat for each volume in the raidset
+	================  =============================================
+
+GUI_ACTIVATE_RAIDSET
+	Activate incomplete raid set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x53
+	byte 3            raidset#
+	================  =============================================
+
+GUI_CREATE_HOT_SPARE
+	Create hot spare disk
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x54
+	byte 3/4/5/6      device mask for hot spare creation
+	================  =============================================
+
+GUI_DELETE_HOT_SPARE
+	Delete hot spare disk
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x55
+	byte 3/4/5/6      device mask for hot spare deletion
+	================  =============================================
+
+GUI_CREATE_VOLUME
+	Create volume set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x60
+	byte 3            raidset#
+	byte 4-19         volume set name
+			  (if byte4 == 0, use default)
+	byte 20-27        volume capacity (blocks)
+	byte 28 	  raid level
+	byte 29 	  stripe size
+			  (0/1/2/3/4/5->4/8/16/32/64/128K)
+	byte 30 	  channel
+	byte 31 	  ID
+	byte 32 	  LUN
+	byte 33 	  1 enable tag
+	byte 34 	  1 enable cache
+	byte 35 	  speed
+			  (0/1/2/3/4->async/20/40/80/160 for scsi)
+			  (0/1/2/3/4->33/66/100/133/150 for IDE  )
+	byte 36 	  1 to select quick init
+	================  =============================================
+
+GUI_MODIFY_VOLUME
+	Modify volume Set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x61
+	byte 3            volumeset#
+	byte 4-19         new volume set name
+			  (if byte4 == 0, not change)
+	byte 20-27        new volume capacity (reserved)
+	byte 28 	  new raid level
+	byte 29 	  new stripe size
+			  (0/1/2/3/4/5->4/8/16/32/64/128K)
+	byte 30 	  new channel
+	byte 31 	  new ID
+	byte 32 	  new LUN
+	byte 33 	  1 enable tag
+	byte 34 	  1 enable cache
+	byte 35 	  speed
+			  (0/1/2/3/4->async/20/40/80/160 for scsi)
+			  (0/1/2/3/4->33/66/100/133/150 for IDE  )
+	================  =============================================
+
+GUI_DELETE_VOLUME
+	Delete volume set
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x62
+	byte 3            volumeset#
+	================  =============================================
+
+GUI_START_CHECK_VOLUME
+	Start volume consistency check
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x63
+	byte 3            volumeset#
+	================  =============================================
+
+GUI_STOP_CHECK_VOLUME
+	Stop volume consistency check
+
+	================  =============================================
+	byte 0,1          length
+	byte 2            command code 0x64
+	================  =============================================
+
+4. Returned data
+----------------
+
+(A) Header
+    3 bytes sequence (0x5E, 0x01, 0x61)
+(B) Length
+    2 bytes
+    (low byte 1st, excludes length and checksum byte)
+(C)
+    status or data:
+
+	1) If length == 1 ==> 1 byte status code::
+
+		#define GUI_OK                    0x41
+		#define GUI_RAIDSET_NOT_NORMAL    0x42
+		#define GUI_VOLUMESET_NOT_NORMAL  0x43
+		#define GUI_NO_RAIDSET            0x44
+		#define GUI_NO_VOLUMESET          0x45
+		#define GUI_NO_PHYSICAL_DRIVE     0x46
+		#define GUI_PARAMETER_ERROR       0x47
+		#define GUI_UNSUPPORTED_COMMAND   0x48
+		#define GUI_DISK_CONFIG_CHANGED   0x49
+		#define GUI_INVALID_PASSWORD      0x4a
+		#define GUI_NO_DISK_SPACE         0x4b
+		#define GUI_CHECKSUM_ERROR        0x4c
+		#define GUI_PASSWORD_REQUIRED     0x4d
+
+	2) If length > 1:
+
+		data block returned from controller
+		and the contents depends on the command code
+
+(E) Checksum
+    checksum of length and status or data byte
+
diff --git a/Documentation/scsi/arcmsr_spec.txt b/Documentation/scsi/arcmsr_spec.txt
deleted file mode 100644
index 45d9482c1517..000000000000
--- a/Documentation/scsi/arcmsr_spec.txt
+++ /dev/null
@@ -1,574 +0,0 @@
-*******************************************************************************
-**                            ARECA FIRMWARE SPEC
-*******************************************************************************
-**	Usage of IOP331 adapter
-**	(All In/Out is in IOP331's view)
-**	1. Message 0 --> InitThread message and return code
-**	2. Doorbell is used for RS-232 emulation
-**		inDoorBell :    bit0 -- data in ready
-**			(DRIVER DATA WRITE OK)
-**				bit1 -- data out has been read
-**			(DRIVER DATA READ OK)
-**		outDooeBell:    bit0 -- data out ready
-**			(IOP331 DATA WRITE OK)
-**				bit1 -- data in has been read
-**			(IOP331 DATA READ OK)
-**	3. Index Memory Usage
-**	offset 0xf00 : for RS232 out (request buffer)
-**	offset 0xe00 : for RS232 in  (scratch buffer)
-**	offset 0xa00 : for inbound message code message_rwbuffer
-**			(driver send to IOP331)
-**	offset 0xa00 : for outbound message code message_rwbuffer
-**			(IOP331 send to driver)
-**	4. RS-232 emulation
-**		Currently 128 byte buffer is used
-**			1st uint32_t : Data length (1--124)
-**			Byte 4--127  : Max 124 bytes of data
-**	5. PostQ
-**	All SCSI Command must be sent through postQ:
-**	(inbound queue port)	Request frame must be 32 bytes aligned
-**	#bit27--bit31 => flag for post ccb
-**	#bit0--bit26  => real address (bit27--bit31) of post arcmsr_cdb
-**		bit31 :
-**			0 : 256 bytes frame
-**			1 : 512 bytes frame
-**		bit30 :
-**			0 : normal request
-**			1 : BIOS request
-**		bit29 : reserved
-**		bit28 : reserved
-**		bit27 : reserved
-**  ---------------------------------------------------------------------------
-**	(outbount queue port)	Request reply
-**	#bit27--bit31
-**		=> flag for reply
-**	#bit0--bit26
-**		=> real address (bit27--bit31) of reply arcmsr_cdb
-**			bit31 : must be 0 (for this type of reply)
-**			bit30 : reserved for BIOS handshake
-**			bit29 : reserved
-**			bit28 :
-**			0 : no error, ignore AdapStatus/DevStatus/SenseData
-**			1 : Error, error code in AdapStatus/DevStatus/SenseData
-**			bit27 : reserved
-**	6. BIOS request
-**		All BIOS request is the same with request from PostQ
-**		Except :
-**			Request frame is sent from configuration space
-**		offset: 0x78 : Request Frame (bit30 == 1)
-**		offset: 0x18 : writeonly to generate
-**					IRQ to IOP331
-**		Completion of request:
-**			(bit30 == 0, bit28==err flag)
-**	7. Definition of SGL entry (structure)
-**	8. Message1 Out - Diag Status Code (????)
-**	9. Message0 message code :
-**		0x00 : NOP
-**		0x01 : Get Config
-**		->offset 0xa00 :for outbound message code message_rwbuffer
-**		(IOP331 send to driver)
-**		Signature             0x87974060(4)
-**		Request len           0x00000200(4)
-**		numbers of queue      0x00000100(4)
-**		SDRAM Size            0x00000100(4)-->256 MB
-**		IDE Channels          0x00000008(4)
-**		vendor                40 bytes char
-**		model                  8 bytes char
-**		FirmVer               16 bytes char
-**		Device Map            16 bytes char
-**		FirmwareVersion DWORD <== Added for checking of
-**						new firmware capability
-**		0x02 : Set Config
-**		->offset 0xa00 :for inbound message code message_rwbuffer
-**		(driver send to IOP331)
-**		Signature             0x87974063(4)
-**		UPPER32 of Request Frame  (4)-->Driver Only
-**		0x03 : Reset (Abort all queued Command)
-**		0x04 : Stop Background Activity
-**		0x05 : Flush Cache
-**		0x06 : Start Background Activity
-**			(re-start if background is halted)
-**		0x07 : Check If Host Command Pending
-**			(Novell May Need This Function)
-**		0x08 : Set controller time
-**		->offset 0xa00 : for inbound message code message_rwbuffer
-**		(driver to IOP331)
-**		byte 0 : 0xaa <-- signature
-**		byte 1 : 0x55 <-- signature
-**		byte 2 : year (04)
-**		byte 3 : month (1..12)
-**		byte 4 : date (1..31)
-**		byte 5 : hour (0..23)
-**		byte 6 : minute (0..59)
-**		byte 7 : second (0..59)
-*******************************************************************************
-*******************************************************************************
-**      	RS-232 Interface for Areca Raid Controller
-**      The low level command interface is exclusive with VT100 terminal
-**  --------------------------------------------------------------------
-**      1. Sequence of command execution
-**  --------------------------------------------------------------------
-**    	(A) Header : 3 bytes sequence (0x5E, 0x01, 0x61)
-**    	(B) Command block : variable length of data including length,
-**    		command code, data and checksum byte
-**    	(C) Return data : variable length of data
-**  --------------------------------------------------------------------
-**    2. Command block
-**  --------------------------------------------------------------------
-**    	(A) 1st byte : command block length (low byte)
-**    	(B) 2nd byte : command block length (high byte)
-**                note ..command block length shouldn't > 2040 bytes,
-**    		length excludes these two bytes
-**    	(C) 3rd byte : command code
-**    	(D) 4th and following bytes : variable length data bytes
-**    		depends on command code
-**    	(E) last byte : checksum byte (sum of 1st byte until last data byte)
-**  --------------------------------------------------------------------
-**    3. Command code and associated data
-**  --------------------------------------------------------------------
-**    	The following are command code defined in raid controller Command
-**    	code 0x10--0x1? are used for system level management,
-**    	no password checking is needed and should be implemented in separate
-**    	well controlled utility and not for end user access.
-**    	Command code 0x20--0x?? always check the password,
-**    	password must be entered to enable these command.
-**    	enum
-**    	{
-**    		GUI_SET_SERIAL=0x10,
-**    		GUI_SET_VENDOR,
-**    		GUI_SET_MODEL,
-**    		GUI_IDENTIFY,
-**    		GUI_CHECK_PASSWORD,
-**    		GUI_LOGOUT,
-**    		GUI_HTTP,
-**    		GUI_SET_ETHERNET_ADDR,
-**    		GUI_SET_LOGO,
-**    		GUI_POLL_EVENT,
-**    		GUI_GET_EVENT,
-**    		GUI_GET_HW_MONITOR,
-**    		//    GUI_QUICK_CREATE=0x20, (function removed)
-**    		GUI_GET_INFO_R=0x20,
-**    		GUI_GET_INFO_V,
-**    		GUI_GET_INFO_P,
-**    		GUI_GET_INFO_S,
-**    		GUI_CLEAR_EVENT,
-**    		GUI_MUTE_BEEPER=0x30,
-**    		GUI_BEEPER_SETTING,
-**    		GUI_SET_PASSWORD,
-**    		GUI_HOST_INTERFACE_MODE,
-**    		GUI_REBUILD_PRIORITY,
-**    		GUI_MAX_ATA_MODE,
-**    		GUI_RESET_CONTROLLER,
-**    		GUI_COM_PORT_SETTING,
-**    		GUI_NO_OPERATION,
-**    		GUI_DHCP_IP,
-**    		GUI_CREATE_PASS_THROUGH=0x40,
-**    		GUI_MODIFY_PASS_THROUGH,
-**    		GUI_DELETE_PASS_THROUGH,
-**    		GUI_IDENTIFY_DEVICE,
-**    		GUI_CREATE_RAIDSET=0x50,
-**    		GUI_DELETE_RAIDSET,
-**    		GUI_EXPAND_RAIDSET,
-**    		GUI_ACTIVATE_RAIDSET,
-**    		GUI_CREATE_HOT_SPARE,
-**    		GUI_DELETE_HOT_SPARE,
-**    		GUI_CREATE_VOLUME=0x60,
-**    		GUI_MODIFY_VOLUME,
-**    		GUI_DELETE_VOLUME,
-**    		GUI_START_CHECK_VOLUME,
-**    		GUI_STOP_CHECK_VOLUME
-**    	};
-**    Command description :
-**    	GUI_SET_SERIAL : Set the controller serial#
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x10
-**    		byte 3          : password length (should be 0x0f)
-**    		byte 4-0x13     : should be "ArEcATecHnoLogY"
-**    		byte 0x14--0x23 : Serial number string (must be 16 bytes)
-**      GUI_SET_VENDOR : Set vendor string for the controller
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x11
-**    		byte 3          : password length (should be 0x08)
-**    		byte 4-0x13     : should be "ArEcAvAr"
-**    		byte 0x14--0x3B : vendor string (must be 40 bytes)
-**      GUI_SET_MODEL : Set the model name of the controller
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x12
-**    		byte 3          : password length (should be 0x08)
-**    		byte 4-0x13     : should be "ArEcAvAr"
-**    		byte 0x14--0x1B : model string (must be 8 bytes)
-**      GUI_IDENTIFY : Identify device
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x13
-**    		                  return "Areca RAID Subsystem "
-**      GUI_CHECK_PASSWORD : Verify password
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x14
-**    		byte 3          : password length
-**    		byte 4-0x??     : user password to be checked
-**      GUI_LOGOUT : Logout GUI (force password checking on next command)
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x15
-**      GUI_HTTP : HTTP interface (reserved for Http proxy service)(0x16)
-**
-**      GUI_SET_ETHERNET_ADDR : Set the ethernet MAC address
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x17
-**    		byte 3          : password length (should be 0x08)
-**    		byte 4-0x13     : should be "ArEcAvAr"
-**    		byte 0x14--0x19 : Ethernet MAC address (must be 6 bytes)
-**      GUI_SET_LOGO : Set logo in HTTP
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x18
-**    		byte 3          : Page# (0/1/2/3) (0xff --> clear OEM logo)
-**    		byte 4/5/6/7    : 0x55/0xaa/0xa5/0x5a
-**    		byte 8          : TITLE.JPG data (each page must be 2000 bytes)
-**    		                  note page0 1st 2 byte must be
-**    					actual length of the JPG file
-**      GUI_POLL_EVENT : Poll If Event Log Changed
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x19
-**      GUI_GET_EVENT : Read Event
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x1a
-**    		byte 3          : Event Page (0:1st page/1/2/3:last page)
-**      GUI_GET_HW_MONITOR : Get HW monitor data
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x1b
-**    		byte 3 			: # of FANs(example 2)
-**    		byte 4 			: # of Voltage sensor(example 3)
-**    		byte 5 			: # of temperature sensor(example 2)
-**    		byte 6 			: # of power
-**    		byte 7/8        : Fan#0 (RPM)
-**    		byte 9/10       : Fan#1
-**    		byte 11/12 		: Voltage#0 original value in *1000
-**    		byte 13/14 		: Voltage#0 value
-**    		byte 15/16 		: Voltage#1 org
-**    		byte 17/18 		: Voltage#1
-**    		byte 19/20 		: Voltage#2 org
-**    		byte 21/22 		: Voltage#2
-**    		byte 23 		: Temp#0
-**    		byte 24 		: Temp#1
-**    		byte 25 		: Power indicator (bit0 : power#0,
-**    						 bit1 : power#1)
-**    		byte 26 		: UPS indicator
-**      GUI_QUICK_CREATE : Quick create raid/volume set
-**    	    byte 0,1        : length
-**    	    byte 2          : command code 0x20
-**    	    byte 3/4/5/6    : raw capacity
-**    	    byte 7 			: raid level
-**    	    byte 8 			: stripe size
-**    	    byte 9 			: spare
-**    	    byte 10/11/12/13: device mask (the devices to create raid/volume)
-**    		This function is removed, application like
-**    		to implement quick create function
-**    	need to use GUI_CREATE_RAIDSET and GUI_CREATE_VOLUMESET function.
-**      GUI_GET_INFO_R : Get Raid Set Information
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x20
-**    		byte 3          : raidset#
-**    	typedef struct sGUI_RAIDSET
-**    	{
-**    		BYTE grsRaidSetName[16];
-**    		DWORD grsCapacity;
-**    		DWORD grsCapacityX;
-**    		DWORD grsFailMask;
-**    		BYTE grsDevArray[32];
-**    		BYTE grsMemberDevices;
-**    		BYTE grsNewMemberDevices;
-**    		BYTE grsRaidState;
-**    		BYTE grsVolumes;
-**    		BYTE grsVolumeList[16];
-**    		BYTE grsRes1;
-**    		BYTE grsRes2;
-**    		BYTE grsRes3;
-**    		BYTE grsFreeSegments;
-**    		DWORD grsRawStripes[8];
-**    		DWORD grsRes4;
-**    		DWORD grsRes5; //     Total to 128 bytes
-**    		DWORD grsRes6; //     Total to 128 bytes
-**    	} sGUI_RAIDSET, *pGUI_RAIDSET;
-**      GUI_GET_INFO_V : Get Volume Set Information
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x21
-**    		byte 3          : volumeset#
-**    	typedef struct sGUI_VOLUMESET
-**    	{
-**    		BYTE gvsVolumeName[16]; //     16
-**    		DWORD gvsCapacity;
-**    		DWORD gvsCapacityX;
-**    		DWORD gvsFailMask;
-**    		DWORD gvsStripeSize;
-**    		DWORD gvsNewFailMask;
-**    		DWORD gvsNewStripeSize;
-**    		DWORD gvsVolumeStatus;
-**    		DWORD gvsProgress; //     32
-**    		sSCSI_ATTR gvsScsi;
-**    		BYTE gvsMemberDisks;
-**    		BYTE gvsRaidLevel; //     8
-**    		BYTE gvsNewMemberDisks;
-**    		BYTE gvsNewRaidLevel;
-**    		BYTE gvsRaidSetNumber;
-**    		BYTE gvsRes0; //     4
-**    		BYTE gvsRes1[4]; //     64 bytes
-**    	} sGUI_VOLUMESET, *pGUI_VOLUMESET;
-**      GUI_GET_INFO_P : Get Physical Drive Information
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x22
-**    		byte 3          : drive # (from 0 to max-channels - 1)
-**    	typedef struct sGUI_PHY_DRV
-**    	{
-**    		BYTE gpdModelName[40];
-**    		BYTE gpdSerialNumber[20];
-**    		BYTE gpdFirmRev[8];
-**    		DWORD gpdCapacity;
-**    		DWORD gpdCapacityX; //     Reserved for expansion
-**    		BYTE gpdDeviceState;
-**    		BYTE gpdPioMode;
-**    		BYTE gpdCurrentUdmaMode;
-**    		BYTE gpdUdmaMode;
-**    		BYTE gpdDriveSelect;
-**    		BYTE gpdRaidNumber; //     0xff if not belongs to a raid set
-**    		sSCSI_ATTR gpdScsi;
-**    		BYTE gpdReserved[40]; //     Total to 128 bytes
-**    	} sGUI_PHY_DRV, *pGUI_PHY_DRV;
-**    	GUI_GET_INFO_S : Get System Information
-**      	byte 0,1        : length
-**      	byte 2          : command code 0x23
-**    	typedef struct sCOM_ATTR
-**    	{
-**    		BYTE comBaudRate;
-**    		BYTE comDataBits;
-**    		BYTE comStopBits;
-**    		BYTE comParity;
-**    		BYTE comFlowControl;
-**    	} sCOM_ATTR, *pCOM_ATTR;
-**    	typedef struct sSYSTEM_INFO
-**    	{
-**    		BYTE gsiVendorName[40];
-**    		BYTE gsiSerialNumber[16];
-**    		BYTE gsiFirmVersion[16];
-**    		BYTE gsiBootVersion[16];
-**    		BYTE gsiMbVersion[16];
-**    		BYTE gsiModelName[8];
-**    		BYTE gsiLocalIp[4];
-**    		BYTE gsiCurrentIp[4];
-**    		DWORD gsiTimeTick;
-**    		DWORD gsiCpuSpeed;
-**    		DWORD gsiICache;
-**    		DWORD gsiDCache;
-**    		DWORD gsiScache;
-**    		DWORD gsiMemorySize;
-**    		DWORD gsiMemorySpeed;
-**    		DWORD gsiEvents;
-**    		BYTE gsiMacAddress[6];
-**    		BYTE gsiDhcp;
-**    		BYTE gsiBeeper;
-**    		BYTE gsiChannelUsage;
-**    		BYTE gsiMaxAtaMode;
-**    		BYTE gsiSdramEcc; //     1:if ECC enabled
-**    		BYTE gsiRebuildPriority;
-**    		sCOM_ATTR gsiComA; //     5 bytes
-**    		sCOM_ATTR gsiComB; //     5 bytes
-**    		BYTE gsiIdeChannels;
-**    		BYTE gsiScsiHostChannels;
-**    		BYTE gsiIdeHostChannels;
-**    		BYTE gsiMaxVolumeSet;
-**    		BYTE gsiMaxRaidSet;
-**    		BYTE gsiEtherPort; //     1:if ether net port supported
-**    		BYTE gsiRaid6Engine; //     1:Raid6 engine supported
-**    		BYTE gsiRes[75];
-**    	} sSYSTEM_INFO, *pSYSTEM_INFO;
-**    	GUI_CLEAR_EVENT : Clear System Event
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x24
-**      GUI_MUTE_BEEPER : Mute current beeper
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x30
-**      GUI_BEEPER_SETTING : Disable beeper
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x31
-**    		byte 3          : 0->disable, 1->enable
-**      GUI_SET_PASSWORD : Change password
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x32
-**    		byte 3 			: pass word length ( must <= 15 )
-**    		byte 4 			: password (must be alpha-numerical)
-**    	GUI_HOST_INTERFACE_MODE : Set host interface mode
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x33
-**    		byte 3 			: 0->Independent, 1->cluster
-**      GUI_REBUILD_PRIORITY : Set rebuild priority
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x34
-**    		byte 3 			: 0/1/2/3 (low->high)
-**      GUI_MAX_ATA_MODE : Set maximum ATA mode to be used
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x35
-**    		byte 3 			: 0/1/2/3 (133/100/66/33)
-**      GUI_RESET_CONTROLLER : Reset Controller
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x36
-**                            *Response with VT100 screen (discard it)
-**      GUI_COM_PORT_SETTING : COM port setting
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x37
-**    		byte 3 			: 0->COMA (term port),
-**    					  1->COMB (debug port)
-**    		byte 4 			: 0/1/2/3/4/5/6/7
-**    			(1200/2400/4800/9600/19200/38400/57600/115200)
-**    		byte 5 			: data bit
-**    					(0:7 bit, 1:8 bit : must be 8 bit)
-**    		byte 6 			: stop bit (0:1, 1:2 stop bits)
-**    		byte 7 			: parity (0:none, 1:off, 2:even)
-**    		byte 8 			: flow control
-**    			(0:none, 1:xon/xoff, 2:hardware => must use none)
-**      GUI_NO_OPERATION : No operation
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x38
-**      GUI_DHCP_IP : Set DHCP option and local IP address
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x39
-**    		byte 3          : 0:dhcp disabled, 1:dhcp enabled
-**    		byte 4/5/6/7    : IP address
-**      GUI_CREATE_PASS_THROUGH : Create pass through disk
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x40
-**    		byte 3 			: device #
-**    		byte 4 			: scsi channel (0/1)
-**    		byte 5 			: scsi id (0-->15)
-**    		byte 6 			: scsi lun (0-->7)
-**    		byte 7 			: tagged queue (1 : enabled)
-**    		byte 8 			: cache mode (1 : enabled)
-**    		byte 9 			: max speed (0/1/2/3/4,
-**    			async/20/40/80/160 for scsi)
-**    			(0/1/2/3/4, 33/66/100/133/150 for ide  )
-**      GUI_MODIFY_PASS_THROUGH : Modify pass through disk
-**    		byte 0,1        : length
-**    		byte 2 			: command code 0x41
-**    		byte 3 			: device #
-**    		byte 4 			: scsi channel (0/1)
-**    		byte 5 			: scsi id (0-->15)
-**    		byte 6 			: scsi lun (0-->7)
-**    		byte 7 			: tagged queue (1 : enabled)
-**    		byte 8 			: cache mode (1 : enabled)
-**    		byte 9 			: max speed (0/1/2/3/4,
-**    					async/20/40/80/160 for scsi)
-**    			(0/1/2/3/4, 33/66/100/133/150 for ide  )
-**      GUI_DELETE_PASS_THROUGH : Delete pass through disk
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x42
-**    		byte 3          : device# to be deleted
-**      GUI_IDENTIFY_DEVICE : Identify Device
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x43
-**    		byte 3          : Flash Method
-**    				(0:flash selected, 1:flash not selected)
-**    		byte 4/5/6/7    : IDE device mask to be flashed
-**                           note .... no response data available
-**    	GUI_CREATE_RAIDSET : Create Raid Set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x50
-**    		byte 3/4/5/6    : device mask
-**    		byte 7-22       : raidset name (if byte 7 == 0:use default)
-**      GUI_DELETE_RAIDSET : Delete Raid Set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x51
-**    		byte 3          : raidset#
-**    	GUI_EXPAND_RAIDSET : Expand Raid Set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x52
-**    		byte 3          : raidset#
-**    		byte 4/5/6/7    : device mask for expansion
-**    		byte 8/9/10     : (8:0 no change, 1 change, 0xff:terminate,
-**    				9:new raid level,
-**    				10:new stripe size
-**    				0/1/2/3/4/5->4/8/16/32/64/128K )
-**    		byte 11/12/13   : repeat for each volume in the raidset
-**      GUI_ACTIVATE_RAIDSET : Activate incomplete raid set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x53
-**    		byte 3          : raidset#
-**      GUI_CREATE_HOT_SPARE : Create hot spare disk
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x54
-**    		byte 3/4/5/6    : device mask for hot spare creation
-**    	GUI_DELETE_HOT_SPARE : Delete hot spare disk
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x55
-**    		byte 3/4/5/6    : device mask for hot spare deletion
-**    	GUI_CREATE_VOLUME : Create volume set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x60
-**    		byte 3          : raidset#
-**    		byte 4-19       : volume set name
-**    				(if byte4 == 0, use default)
-**    		byte 20-27      : volume capacity (blocks)
-**    		byte 28 		: raid level
-**    		byte 29 		: stripe size
-**    				(0/1/2/3/4/5->4/8/16/32/64/128K)
-**    		byte 30 		: channel
-**    		byte 31 		: ID
-**    		byte 32 		: LUN
-**    		byte 33 		: 1 enable tag
-**    		byte 34 		: 1 enable cache
-**    		byte 35 		: speed
-**    		(0/1/2/3/4->async/20/40/80/160 for scsi)
-**    		(0/1/2/3/4->33/66/100/133/150 for IDE  )
-**    		byte 36 		: 1 to select quick init
-**
-**    	GUI_MODIFY_VOLUME : Modify volume Set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x61
-**    		byte 3          : volumeset#
-**    		byte 4-19       : new volume set name
-**    		(if byte4 == 0, not change)
-**    		byte 20-27      : new volume capacity (reserved)
-**    		byte 28 		: new raid level
-**    		byte 29 		: new stripe size
-**    		(0/1/2/3/4/5->4/8/16/32/64/128K)
-**    		byte 30 		: new channel
-**    		byte 31 		: new ID
-**    		byte 32 		: new LUN
-**    		byte 33 		: 1 enable tag
-**    		byte 34 		: 1 enable cache
-**    		byte 35 		: speed
-**    		(0/1/2/3/4->async/20/40/80/160 for scsi)
-**    		(0/1/2/3/4->33/66/100/133/150 for IDE  )
-**    	GUI_DELETE_VOLUME : Delete volume set
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x62
-**    		byte 3          : volumeset#
-**    	GUI_START_CHECK_VOLUME : Start volume consistency check
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x63
-**    		byte 3          : volumeset#
-**    	GUI_STOP_CHECK_VOLUME : Stop volume consistency check
-**    		byte 0,1        : length
-**    		byte 2          : command code 0x64
-** ---------------------------------------------------------------------
-**    4. Returned data
-** ---------------------------------------------------------------------
-**    	(A) Header          : 3 bytes sequence (0x5E, 0x01, 0x61)
-**    	(B) Length          : 2 bytes
-**    			(low byte 1st, excludes length and checksum byte)
-**    	(C) status or data  :
-**           <1> If length == 1 ==> 1 byte status code
-**    		#define GUI_OK                    0x41
-**    		#define GUI_RAIDSET_NOT_NORMAL    0x42
-**    		#define GUI_VOLUMESET_NOT_NORMAL  0x43
-**    		#define GUI_NO_RAIDSET            0x44
-**    		#define GUI_NO_VOLUMESET          0x45
-**    		#define GUI_NO_PHYSICAL_DRIVE     0x46
-**    		#define GUI_PARAMETER_ERROR       0x47
-**    		#define GUI_UNSUPPORTED_COMMAND   0x48
-**    		#define GUI_DISK_CONFIG_CHANGED   0x49
-**    		#define GUI_INVALID_PASSWORD      0x4a
-**    		#define GUI_NO_DISK_SPACE         0x4b
-**    		#define GUI_CHECKSUM_ERROR        0x4c
-**    		#define GUI_PASSWORD_REQUIRED     0x4d
-**           <2> If length > 1 ==>
-**    		data block returned from controller
-**    		and the contents depends on the command code
-**    	(E) Checksum        : checksum of length and status or data byte
-**************************************************************************
diff --git a/Documentation/scsi/bfa.txt b/Documentation/scsi/bfa.rst
index 3cc4d80d6092..3abc0411857d 100644
--- a/Documentation/scsi/bfa.txt
+++ b/Documentation/scsi/bfa.rst
@@ -1,5 +1,8 @@
-Linux driver for Brocade FC/FCOE adapters
+.. SPDX-License-Identifier: GPL-2.0
 
+=========================================
+Linux driver for Brocade FC/FCOE adapters
+=========================================
 
 Supported Hardware
 ------------------
@@ -7,8 +10,9 @@ Supported Hardware
 bfa 3.0.2.2 driver supports all Brocade FC/FCOE adapters. Below is a list of
 adapter models with corresponding PCIIDs.
 
-	PCIID		  	Model
-
+	===================	===========================================
+	PCIID			Model
+	===================	===========================================
 	1657:0013:1657:0014	425 4Gbps dual port FC HBA
 	1657:0013:1657:0014	825 8Gbps PCIe dual port FC HBA
 	1657:0013:103c:1742	HP 82B 8Gbps PCIedual port FC HBA
@@ -26,6 +30,7 @@ adapter models with corresponding PCIIDs.
 
 	1657:0022:1657:0024	1860 16Gbps FC HBA
 	1657:0022:1657:0022	1860 10Gbps CNA - FCOE
+	===================	===========================================
 
 
 Firmware download
@@ -37,9 +42,11 @@ http://www.brocade.com/services-support/drivers-downloads/adapters/Linux.page
 
 and then click following respective util package link:
 
-	Version			Link
-
+	=========	=======================================================
+	Version		Link
+	=========	=======================================================
 	v3.0.0.0	Linux Adapter Firmware package for RHEL 6.2, SLES 11SP2
+	=========	=======================================================
 
 
 Configuration & Management utility download
@@ -52,9 +59,11 @@ http://www.brocade.com/services-support/drivers-downloads/adapters/Linux.page
 
 and then click following respective util package link
 
-	Version			Link
-
+	=========	=======================================================
+	Version		Link
+	=========	=======================================================
 	v3.0.2.0	Linux Adapter Firmware package for RHEL 6.2, SLES 11SP2
+	=========	=======================================================
 
 
 Documentation
@@ -69,10 +78,11 @@ http://www.brocade.com/services-support/drivers-downloads/adapters/Linux.page
 and use the following inbox and out-of-box driver version mapping to find
 the corresponding documentation:
 
+	=============		==================
 	Inbox Version		Out-of-box Version
-
+	=============		==================
 	v3.0.2.2		v3.0.0.0
-
+	=============		==================
 
 Support
 -------
diff --git a/Documentation/scsi/bnx2fc.txt b/Documentation/scsi/bnx2fc.rst
index 80823556d62f..2fef2dff80c7 100644
--- a/Documentation/scsi/bnx2fc.txt
+++ b/Documentation/scsi/bnx2fc.rst
@@ -1,3 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===========================
 Operating FCoE using bnx2fc
 ===========================
 Broadcom FCoE offload through bnx2fc is full stateful hardware offload that
@@ -24,6 +27,7 @@ Driver Usage Model:
 
 2. Configure the interfaces on which bnx2fc driver has to operate on.
 Here are the steps to configure:
+
 	a. cd /etc/fcoe
 	b. copy cfg-ethx to cfg-eth5 if FCoE has to be enabled on eth5.
 	c. Repeat this for all the interfaces where FCoE has to be enabled.
@@ -39,8 +43,10 @@ discovery and log into the targets.
 
 5. "Symbolic Name" in 'fcoeadm -i' output would display if bnx2fc has claimed
 the interface.
-Eg:
-[root@bh2 ~]# fcoeadm -i
+
+Eg::
+
+ [root@bh2 ~]# fcoeadm -i
     Description:      NetXtreme II BCM57712 10 Gigabit Ethernet
     Revision:         01
     Manufacturer:     Broadcom Corporation
@@ -60,16 +66,16 @@ Eg:
         State:             Online
 
 6. Verify the vlan discovery is performed by running ifconfig and notice
-<INTERFACE>.<VLAN>-fcoe interfaces are automatically created.
+   <INTERFACE>.<VLAN>-fcoe interfaces are automatically created.
 
 Refer to fcoeadm manpage for more information on fcoeadm operations to
 create/destroy interfaces or to display lun/target information.
 
-NOTE:
+NOTE
 ====
 ** Broadcom FCoE capable devices implement a DCBX/LLDP client on-chip. Only one
 LLDP client is allowed per interface. For proper operation all host software
 based DCBX/LLDP clients (e.g. lldpad) must be disabled. To disable lldpad on a
-given interface, run the following command:
+given interface, run the following command::
 
-lldptool set-lldp -i <interface_name> adminStatus=disabled
+	lldptool set-lldp -i <interface_name> adminStatus=disabled
diff --git a/Documentation/scsi/cxgb3i.txt b/Documentation/scsi/cxgb3i.rst
index 7ac8032ee9b2..e01f18fbfa9f 100644
--- a/Documentation/scsi/cxgb3i.txt
+++ b/Documentation/scsi/cxgb3i.rst
@@ -1,4 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
 Chelsio S3 iSCSI Driver for Linux
+=================================
 
 Introduction
 ============
@@ -49,7 +53,8 @@ The following steps need to be taken to accelerates the open-iscsi initiator:
 
    The cxgb3i module registers a new transport class "cxgb3i" with open-iscsi.
 
-   * in the case of recompiling the kernel, the cxgb3i selection is located at
+   * in the case of recompiling the kernel, the cxgb3i selection is located at::
+
 	Device Drivers
 		SCSI device support --->
 			[*] SCSI low-level drivers  --->
@@ -58,25 +63,26 @@ The following steps need to be taken to accelerates the open-iscsi initiator:
 2. Create an interface file located under /etc/iscsi/ifaces/ for the new
    transport class "cxgb3i".
 
-   The content of the file should be in the following format:
+   The content of the file should be in the following format::
+
 	iface.transport_name = cxgb3i
 	iface.net_ifacename = <ethX>
 	iface.ipaddress = <iscsi ip address>
 
    * if iface.ipaddress is specified, <iscsi ip address> needs to be either the
-	same as the ethX's ip address or an address on the same subnet. Make
-	sure the ip address is unique in the network.
+     same as the ethX's ip address or an address on the same subnet. Make
+     sure the ip address is unique in the network.
 
 3. edit /etc/iscsi/iscsid.conf
    The default setting for MaxRecvDataSegmentLength (131072) is too big;
-   replace with a value no bigger than 15360 (for example 8192):
+   replace with a value no bigger than 15360 (for example 8192)::
 
 	node.conn[0].iscsi.MaxRecvDataSegmentLength = 8192
 
    * The login would fail for a normal session if MaxRecvDataSegmentLength is
-	too big.  A error message in the format of
-	"cxgb3i: ERR! MaxRecvSegmentLength <X> too big. Need to be <= <Y>."
-	would be logged to dmesg.
+     too big.  A error message in the format of
+     "cxgb3i: ERR! MaxRecvSegmentLength <X> too big. Need to be <= <Y>."
+     would be logged to dmesg.
 
 4. To direct open-iscsi traffic to go through cxgb3i's accelerated path,
    "-I <iface file name>" option needs to be specified with most of the
diff --git a/Documentation/scsi/dc395x.txt b/Documentation/scsi/dc395x.rst
index 88219f96633d..d779e782b1cb 100644
--- a/Documentation/scsi/dc395x.txt
+++ b/Documentation/scsi/dc395x.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
 README file for the dc395x SCSI driver
-==========================================
+======================================
 
 Status
 ------
@@ -18,14 +21,14 @@ http://lists.twibble.org/mailman/listinfo/dc395x/
 
 Parameters
 ----------
-The driver uses the settings from the EEPROM set in the SCSI BIOS 
+The driver uses the settings from the EEPROM set in the SCSI BIOS
 setup. If there is no EEPROM, the driver uses default values.
 Both can be overridden by command line parameters (module or kernel
 parameters).
 
 The following parameters are available:
 
- - safe
+safe
    Default: 0, Acceptable values: 0 or 1
 
    If safe is set to 1 then the adapter will use conservative
@@ -33,52 +36,63 @@ The following parameters are available:
 
 		shortcut for dc395x=7,4,9,15,2,10
 
- - adapter_id
+adapter_id
    Default: 7, Acceptable values: 0 to 15
 
    Sets the host adapter SCSI ID.
 
- - max_speed
+max_speed
    Default: 1, Acceptable value: 0 to 7
-   0 = 20   Mhz
-   1 = 12.2 Mhz
-   2 = 10   Mhz
-   3 = 8    Mhz
-   4 = 6.7  Mhz
-   5 = 5.8  Hhz
-   6 = 5    Mhz
-   7 = 4    Mhz
-
- - dev_mode
+
+   ==  ========
+   0   20   Mhz
+   1   12.2 Mhz
+   2   10   Mhz
+   3   8    Mhz
+   4   6.7  Mhz
+   5   5.8  Hhz
+   6   5    Mhz
+   7   4    Mhz
+   ==  ========
+
+dev_mode
    Bitmap for device configuration
 
    DevMode bit definition:
+
+      === ======== ========  =========================================
       Bit Val(hex) Val(dec)  Meaning
-      *0    0x01       1     Parity check
-      *1    0x02       2     Synchronous Negotiation
-      *2    0x04       4     Disconnection
-      *3    0x08       8     Send Start command on startup. (Not used)
-      *4    0x10      16     Tagged Command Queueing
-      *5    0x20      32     Wide Negotiation
-
- - adapter_mode
+      === ======== ========  =========================================
+       0    0x01       1     Parity check
+       1    0x02       2     Synchronous Negotiation
+       2    0x04       4     Disconnection
+       3    0x08       8     Send Start command on startup. (Not used)
+       4    0x10      16     Tagged Command Queueing
+       5    0x20      32     Wide Negotiation
+      === ======== ========  =========================================
+
+adapter_mode
    Bitmap for adapter configuration
 
    AdaptMode bit definition
+
+    ===== ======== ========  ====================================================
       Bit Val(hex) Val(dec)  Meaning
-      *0    0x01       1     Support more than two drives. (Not used)
-      *1    0x02       2     Use DOS compatible mapping for HDs greater than 1GB.
-      *2    0x04       4     Reset SCSI Bus on startup.
-      *3    0x08       8     Active Negation: Improves SCSI Bus noise immunity.
+    ===== ======== ========  ====================================================
+       0    0x01       1     Support more than two drives. (Not used)
+       1    0x02       2     Use DOS compatible mapping for HDs greater than 1GB.
+       2    0x04       4     Reset SCSI Bus on startup.
+       3    0x08       8     Active Negation: Improves SCSI Bus noise immunity.
        4    0x10      16     Immediate return on BIOS seek command. (Not used)
     (*)5    0x20      32     Check for LUNs >= 1.
+    ===== ======== ========  ====================================================
 
- - tags
+tags
    Default: 3, Acceptable values: 0-5
-   
+
    The number of tags is 1<<x, if x has been specified
 
- - reset_delay
+reset_delay
    Default: 1, Acceptable values: 0-180
 
    The seconds to not accept commands after a SCSI Reset
@@ -95,8 +109,9 @@ License (GPL). Please read it, before using this driver. It should be
 included in your kernel sources and with your distribution. It carries the
 filename COPYING. If you don't have it, please ask me to send you one by
 email.
-Note: The GNU GPL says also something about warranty and liability. 
+
+Note: The GNU GPL says also something about warranty and liability.
 Please be aware the following: While we do my best to provide a working and
-reliable driver, there is a chance, that it will kill your valuable data. 
+reliable driver, there is a chance, that it will kill your valuable data.
 We refuse to take any responsibility for that. The driver is provided as-is
 and YOU USE IT AT YOUR OWN RESPONSIBILITY.
diff --git a/Documentation/scsi/dpti.rst b/Documentation/scsi/dpti.rst
new file mode 100644
index 000000000000..0496919d87d3
--- /dev/null
+++ b/Documentation/scsi/dpti.rst
@@ -0,0 +1,92 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================
+Adaptec dpti driver
+===================
+
+Redistribution and use in source form, with or without modification, are
+permitted provided that redistributions of source code must retain the
+above copyright notice, this list of conditions and the following disclaimer.
+
+This software is provided ``as is`` by Adaptec and
+any express or implied warranties, including, but not limited to, the
+implied warranties of merchantability and fitness for a particular purpose,
+are disclaimed. In no event shall Adaptec be
+liable for any direct, indirect, incidental, special, exemplary or
+consequential damages (including, but not limited to, procurement of
+substitute goods or services; loss of use, data, or profits; or business
+interruptions) however caused and on any theory of liability, whether in
+contract, strict liability, or tort (including negligence or otherwise)
+arising in any way out of the use of this driver software, even if advised
+of the possibility of such damage.
+
+This driver supports the Adaptec I2O RAID and DPT SmartRAID V I2O boards.
+
+Credits
+=======
+
+The original linux driver was ported to Linux by Karen White while at
+Dell Computer.  It was ported from Bob Pasteur's (of DPT) original
+non-Linux driver.  Mark Salyzyn and Bob Pasteur consulted on the original
+driver.
+
+2.0 version of the driver by Deanna Bonds and Mark Salyzyn.
+
+History
+=======
+
+The driver was originally ported to linux version 2.0.34
+
+==== ==========================================================================
+V2.0 Rewrite of driver.  Re-architectured based on i2o subsystem.
+     This was the first full GPL version since the last version used
+     i2osig headers which were not GPL.  Developer Testing version.
+V2.1 Internal testing
+V2.2 First released version
+
+V2.3 Changes:
+
+     - Added Raptor Support
+     - Fixed bug causing system to hang under extreme load with
+     - management utilities running (removed GFP_DMA from kmalloc flags)
+
+V2.4 First version ready to be submitted to be embedded in the kernel
+
+     Changes:
+
+     - Implemented suggestions from Alan Cox
+     - Added calculation of resid for sg layer
+     - Better error handling
+     - Added checking underflow conditions
+     - Added DATAPROTECT checking
+     - Changed error return codes
+     - Fixed pointer bug in bus reset routine
+     - Enabled hba reset from ioctls (allows a FW flash to reboot and use
+       the new FW without having to reboot)
+     - Changed proc output
+==== ==========================================================================
+
+TODO
+====
+- Add 64 bit Scatter Gather when compiled on 64 bit architectures
+- Add sparse lun scanning
+- Add code that checks if a device that had been taken offline is
+  now online (at the FW level) when test unit ready or inquiry
+  command from scsi-core
+- Add proc read interface
+- busrescan command
+- rescan command
+- Add code to rescan routine that notifies scsi-core about new devices
+- Add support for C-PCI (hotplug stuff)
+- Add ioctl passthru error recovery
+
+Notes
+=====
+The DPT card optimizes the order of processing commands.  Consequently,
+a command may take up to 6 minutes to complete after it has been sent
+to the board.
+
+The files dpti_ioctl.h dptsig.h osd_defs.h osd_util.h sys_info.h are part of the
+interface files for Adaptec's management routines.  These define the structures used
+in the ioctls.  They are written to be portable.  They are hard to read, but I need
+to use them 'as is' or I can miss changes in the interface.
diff --git a/Documentation/scsi/dpti.txt b/Documentation/scsi/dpti.txt
deleted file mode 100644
index f36dc0e7c8da..000000000000
--- a/Documentation/scsi/dpti.txt
+++ /dev/null
@@ -1,83 +0,0 @@
- /* TERMS AND CONDITIONS OF USE
- * 
- * Redistribution and use in source form, with or without modification, are
- * permitted provided that redistributions of source code must retain the
- * above copyright notice, this list of conditions and the following disclaimer.
- * 
- * This software is provided `as is' by Adaptec and
- * any express or implied warranties, including, but not limited to, the
- * implied warranties of merchantability and fitness for a particular purpose,
- * are disclaimed. In no event shall Adaptec be
- * liable for any direct, indirect, incidental, special, exemplary or
- * consequential damages (including, but not limited to, procurement of
- * substitute goods or services; loss of use, data, or profits; or business
- * interruptions) however caused and on any theory of liability, whether in
- * contract, strict liability, or tort (including negligence or otherwise)
- * arising in any way out of the use of this driver software, even if advised
- * of the possibility of such damage.
- * 
- ****************************************************************
- * This driver supports the Adaptec I2O RAID and DPT SmartRAID V I2O boards.
- *
- * CREDITS:
- * The original linux driver was ported to Linux by Karen White while at 
- * Dell Computer.  It was ported from Bob Pasteur's (of DPT) original 
- * non-Linux driver.  Mark Salyzyn and Bob Pasteur consulted on the original
- * driver. 
- * 
- * 2.0 version of the driver by Deanna Bonds and Mark Salyzyn.
- *
- * HISTORY:
- * The driver was originally ported to linux version 2.0.34 
- *
- * V2.0 Rewrite of driver.  Re-architectured based on i2o subsystem.
- *   This was the first full GPL version since the last version used
- *   i2osig headers which were not GPL.  Developer Testing version.
- * V2.1 Internal testing
- * V2.2 First released version
- *
- * V2.3 
- *   Changes:
- *      Added Raptor Support
- *      Fixed bug causing system to hang under extreme load with 
- *         management utilities running (removed GFP_DMA from kmalloc flags)
- *
- *
- * V2.4 First version ready to be submitted to be embedded in the kernel
- *   Changes: 
- *      Implemented suggestions from Alan Cox
- *      Added calculation of resid for sg layer
- *      Better error handling
- *         Added checking underflow conditions 
- *         Added DATAPROTECT checking
- *         Changed error return codes
- *         Fixed pointer bug in bus reset routine
- *      Enabled hba reset from ioctls (allows a FW flash to reboot and use the new
- *         FW without having to reboot)
- *      Changed proc output
- *
- * TODO:
- *      Add 64 bit Scatter Gather when compiled on 64 bit architectures
- *      Add sparse lun scanning 
- *      Add code that checks if a device that had been taken offline is
- *         now online (at the FW level) when test unit ready or inquiry 
- *         command from scsi-core
- *      Add proc read interface
- *         busrescan command
- *         rescan command
- *      Add code to rescan routine that notifies scsi-core about new devices
- *      Add support for C-PCI (hotplug stuff)
- *      Add ioctl passthru error recovery
- *
- * NOTES:
- * The DPT card optimizes the order of processing commands.  Consequently,
- * a command may take up to 6 minutes to complete after it has been sent
- * to the board.  
- *
- * The files dpti_ioctl.h dptsig.h osd_defs.h osd_util.h sys_info.h are part of the
- * interface files for Adaptec's management routines.  These define the structures used
- * in the ioctls.  They are written to be portable.  They are hard to read, but I need
- * to use them 'as is' or I can miss changes in the interface.
- *
- */
-
diff --git a/Documentation/scsi/g_NCR5380.rst b/Documentation/scsi/g_NCR5380.rst
new file mode 100644
index 000000000000..a282059fec43
--- /dev/null
+++ b/Documentation/scsi/g_NCR5380.rst
@@ -0,0 +1,93 @@
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+==========================================
+README file for the Linux g_NCR5380 driver
+==========================================
+
+Copyright |copy| 1993 Drew Eckhard
+
+NCR53c400 extensions Copyright |copy| 1994,1995,1996 Kevin Lentin
+
+This file documents the NCR53c400 extensions by Kevin Lentin and some
+enhancements to the NCR5380 core.
+
+This driver supports NCR5380 and NCR53c400 and compatible cards in port or
+memory mapped modes.
+
+Use of an interrupt is recommended, if supported by the board, as this will
+allow targets to disconnect and thereby improve SCSI bus utilization.
+
+If the irq parameter is 254 or is omitted entirely, the driver will probe
+for the correct IRQ line automatically. If the irq parameter is 0 or 255
+then no IRQ will be used.
+
+The NCR53c400 does not support DMA but it does have Pseudo-DMA which is
+supported by the driver.
+
+This driver provides some information on what it has detected in
+/proc/scsi/g_NCR5380/x where x is the scsi card number as detected at boot
+time. More info to come in the future.
+
+This driver works as a module.
+When included as a module, parameters can be passed on the insmod/modprobe
+command line:
+
+  ============= ===============================================================
+  irq=xx[,...]	the interrupt(s)
+  base=xx[,...]	the port or base address(es) (for port or memory mapped, resp.)
+  card=xx[,...]	card type(s):
+
+		==  ======================================
+		0   NCR5380,
+		1   NCR53C400,
+		2   NCR53C400A,
+		3   Domex Technology Corp 3181E (DTC3181E)
+		4   Hewlett Packard C2502
+		==  ======================================
+  ============= ===============================================================
+
+These old-style parameters can support only one card:
+
+  ============= =================================================
+  ncr_irq=xx    the interrupt
+  ncr_addr=xx   the port or base address (for port or memory
+                mapped, resp.)
+  ncr_5380=1    to set up for a NCR5380 board
+  ncr_53c400=1  to set up for a NCR53C400 board
+  ncr_53c400a=1 to set up for a NCR53C400A board
+  dtc_3181e=1   to set up for a Domex Technology Corp 3181E board
+  hp_c2502=1    to set up for a Hewlett Packard C2502 board
+  ============= =================================================
+
+E.g. Trantor T130B in its default configuration::
+
+	modprobe g_NCR5380 irq=5 base=0x350 card=1
+
+or alternatively, using the old syntax::
+
+	modprobe g_NCR5380 ncr_irq=5 ncr_addr=0x350 ncr_53c400=1
+
+E.g. a port mapped NCR5380 board, driver to probe for IRQ::
+
+	modprobe g_NCR5380 base=0x350 card=0
+
+or alternatively::
+
+	modprobe g_NCR5380 ncr_addr=0x350 ncr_5380=1
+
+E.g. a memory mapped NCR53C400 board with no IRQ::
+
+	modprobe g_NCR5380 irq=255 base=0xc8000 card=1
+
+or alternatively::
+
+	modprobe g_NCR5380 ncr_irq=255 ncr_addr=0xc8000 ncr_53c400=1
+
+E.g. two cards, DTC3181 (in non-PnP mode) at 0x240 with no IRQ
+and HP C2502 at 0x300 with IRQ 7::
+
+	modprobe g_NCR5380 irq=0,7 base=0x240,0x300 card=3,4
+
+Kevin Lentin
+K.Lentin@cs.monash.edu.au
diff --git a/Documentation/scsi/g_NCR5380.txt b/Documentation/scsi/g_NCR5380.txt
deleted file mode 100644
index 37b1967a00a9..000000000000
--- a/Documentation/scsi/g_NCR5380.txt
+++ /dev/null
@@ -1,68 +0,0 @@
-README file for the Linux g_NCR5380 driver.
-
-(c) 1993 Drew Eckhard
-NCR53c400 extensions (c) 1994,1995,1996 Kevin Lentin
-
-This file documents the NCR53c400 extensions by Kevin Lentin and some
-enhancements to the NCR5380 core.
-
-This driver supports NCR5380 and NCR53c400 and compatible cards in port or
-memory mapped modes.
-
-Use of an interrupt is recommended, if supported by the board, as this will
-allow targets to disconnect and thereby improve SCSI bus utilization.
-
-If the irq parameter is 254 or is omitted entirely, the driver will probe
-for the correct IRQ line automatically. If the irq parameter is 0 or 255
-then no IRQ will be used.
-
-The NCR53c400 does not support DMA but it does have Pseudo-DMA which is
-supported by the driver.
-
-This driver provides some information on what it has detected in
-/proc/scsi/g_NCR5380/x where x is the scsi card number as detected at boot
-time. More info to come in the future.
-
-This driver works as a module.
-When included as a module, parameters can be passed on the insmod/modprobe
-command line:
-  irq=xx[,...]	the interrupt(s)
-  base=xx[,...]	the port or base address(es) (for port or memory mapped, resp.)
-  card=xx[,...]	card type(s):
-		0 = NCR5380,
-		1 = NCR53C400,
-		2 = NCR53C400A,
-		3 = Domex Technology Corp 3181E (DTC3181E)
-		4 = Hewlett Packard C2502
-
-These old-style parameters can support only one card:
-  ncr_irq=xx   the interrupt
-  ncr_addr=xx  the port or base address (for port or memory
-               mapped, resp.)
-  ncr_5380=1   to set up for a NCR5380 board
-  ncr_53c400=1 to set up for a NCR53C400 board
-  ncr_53c400a=1 to set up for a NCR53C400A board
-  dtc_3181e=1  to set up for a Domex Technology Corp 3181E board
-  hp_c2502=1   to set up for a Hewlett Packard C2502 board
-
-E.g. Trantor T130B in its default configuration:
-modprobe g_NCR5380 irq=5 base=0x350 card=1
-or alternatively, using the old syntax,
-modprobe g_NCR5380 ncr_irq=5 ncr_addr=0x350 ncr_53c400=1
-
-E.g. a port mapped NCR5380 board, driver to probe for IRQ:
-modprobe g_NCR5380 base=0x350 card=0
-or alternatively,
-modprobe g_NCR5380 ncr_addr=0x350 ncr_5380=1
-
-E.g. a memory mapped NCR53C400 board with no IRQ:
-modprobe g_NCR5380 irq=255 base=0xc8000 card=1
-or alternatively,
-modprobe g_NCR5380 ncr_irq=255 ncr_addr=0xc8000 ncr_53c400=1
-
-E.g. two cards, DTC3181 (in non-PnP mode) at 0x240 with no IRQ
-and HP C2502 at 0x300 with IRQ 7:
-modprobe g_NCR5380 irq=0,7 base=0x240,0x300 card=3,4
-
-Kevin Lentin
-K.Lentin@cs.monash.edu.au
diff --git a/Documentation/scsi/hpsa.txt b/Documentation/scsi/hpsa.rst
index 891435a72fce..340e10c6e35f 100644
--- a/Documentation/scsi/hpsa.txt
+++ b/Documentation/scsi/hpsa.rst
@@ -1,6 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
 
+=========================================
 HPSA - Hewlett Packard Smart Array driver
------------------------------------------
+=========================================
 
 This file describes the hpsa SCSI driver for HP Smart Array controllers.
 The hpsa driver is intended to supplant the cciss driver for newer
@@ -11,17 +13,17 @@ driver (for logical drives) AND a SCSI driver (for tape drives). This
 complexity and eliminating that complexity is one of the reasons
 for hpsa to exist.
 
-Supported devices:
-------------------
+Supported devices
+=================
 
-Smart Array P212
-Smart Array P410
-Smart Array P410i
-Smart Array P411
-Smart Array P812
-Smart Array P712m
-Smart Array P711m
-StorageWorks P1210m
+- Smart Array P212
+- Smart Array P410
+- Smart Array P410i
+- Smart Array P411
+- Smart Array P812
+- Smart Array P712m
+- Smart Array P711m
+- StorageWorks P1210m
 
 Additionally, older Smart Arrays may work with the hpsa driver if the kernel
 boot parameter "hpsa_allow_any=1" is specified, however these are not tested
@@ -35,18 +37,20 @@ mode, each command completion requires an interrupt, while with "performant mode
 command completions indicated by a single interrupt.
 
 HPSA specific entries in /sys
------------------------------
+=============================
 
   In addition to the generic SCSI attributes available in /sys, hpsa supports
   the following attributes:
 
-  HPSA specific host attributes:
-  ------------------------------
+HPSA specific host attributes
+=============================
+
+  ::
 
-  /sys/class/scsi_host/host*/rescan
-  /sys/class/scsi_host/host*/firmware_revision
-  /sys/class/scsi_host/host*/resettable
-  /sys/class/scsi_host/host*/transport_mode
+    /sys/class/scsi_host/host*/rescan
+    /sys/class/scsi_host/host*/firmware_revision
+    /sys/class/scsi_host/host*/resettable
+    /sys/class/scsi_host/host*/transport_mode
 
   the host "rescan" attribute is a write only attribute.  Writing to this
   attribute will cause the driver to scan for new, changed, or removed devices
@@ -58,7 +62,7 @@ HPSA specific entries in /sys
   tape drives, or entire storage boxes containing pre-configured logical drives.
 
   The "firmware_revision" attribute contains the firmware version of the Smart Array.
-  For example:
+  For example::
 
 	root@host:/sys/class/scsi_host/host4# cat firmware_revision
 	7.14
@@ -78,16 +82,18 @@ HPSA specific entries in /sys
   kexec tools to warn the user if they attempt to designate a device which is
   unable to honor the reset_devices kernel parameter as a dump device.
 
-  HPSA specific disk attributes:
-  ------------------------------
+HPSA specific disk attributes
+-----------------------------
+
+  ::
 
-  /sys/class/scsi_disk/c:b:t:l/device/unique_id
-  /sys/class/scsi_disk/c:b:t:l/device/raid_level
-  /sys/class/scsi_disk/c:b:t:l/device/lunid
+    /sys/class/scsi_disk/c:b:t:l/device/unique_id
+    /sys/class/scsi_disk/c:b:t:l/device/raid_level
+    /sys/class/scsi_disk/c:b:t:l/device/lunid
 
   (where c:b:t:l are the controller, bus, target and lun of the device)
 
-  For example:
+  For example::
 
 	root@host:/sys/class/scsi_disk/4:0:0:0/device# cat unique_id
 	600508B1001044395355323037570F77
@@ -96,35 +102,28 @@ HPSA specific entries in /sys
 	root@host:/sys/class/scsi_disk/4:0:0:0/device# cat raid_level
 	RAID 0
 
-HPSA specific ioctls:
----------------------
+HPSA specific ioctls
+====================
 
   For compatibility with applications written for the cciss driver, many, but
   not all of the ioctls supported by the cciss driver are also supported by the
   hpsa driver.  The data structures used by these are described in
   include/linux/cciss_ioctl.h
 
-  CCISS_DEREGDISK
-  CCISS_REGNEWDISK
-  CCISS_REGNEWD
-
-  The above three ioctls all do exactly the same thing, which is to cause the driver
-  to rescan for new devices.  This does exactly the same thing as writing to the
-  hpsa specific host "rescan" attribute.
+  CCISS_DEREGDISK, CCISS_REGNEWDISK, CCISS_REGNEWD
+	The above three ioctls all do exactly the same thing, which is to cause the driver
+	to rescan for new devices.  This does exactly the same thing as writing to the
+	hpsa specific host "rescan" attribute.
 
   CCISS_GETPCIINFO
-
 	Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID).
 
   CCISS_GETDRIVVER
+	Returns driver version in three bytes encoded as::
 
-	Returns driver version in three bytes encoded as:
 		(major_version << 16) | (minor_version << 8) | (subminor_version)
 
-  CCISS_PASSTHRU
-  CCISS_BIG_PASSTHRU
-
+  CCISS_PASSTHRU, CCISS_BIG_PASSTHRU
 	Allows "BMIC" and "CISS" commands to be passed through to the Smart Array.
 	These are used extensively by the HP Array Configuration Utility, SNMP storage
 	agents, etc.  See cciss_vol_status at http://cciss.sf.net for some examples.
-
diff --git a/Documentation/scsi/hptiop.txt b/Documentation/scsi/hptiop.rst
index 12ecfd308e55..23ae7ae36971 100644
--- a/Documentation/scsi/hptiop.txt
+++ b/Documentation/scsi/hptiop.rst
@@ -1,15 +1,25 @@
-HIGHPOINT ROCKETRAID 3xxx/4xxx ADAPTER DRIVER (hptiop)
+.. SPDX-License-Identifier: GPL-2.0
+.. include:: <isonum.txt>
+
+======================================================
+Highpoint RocketRAID 3xxx/4xxx Adapter Driver (hptiop)
+======================================================
 
 Controller Register Map
--------------------------
+-----------------------
 
-For RR44xx Intel IOP based adapters, the controller IOP is accessed via PCI BAR0 and BAR2:
+For RR44xx Intel IOP based adapters, the controller IOP is accessed via PCI BAR0 and BAR2
 
+     ============== ==================================
      BAR0 offset    Register
+     ============== ==================================
             0x11C5C Link Interface IRQ Set
             0x11C60 Link Interface IRQ Clear
+     ============== ==================================
 
+     ============== ==================================
      BAR2 offset    Register
+     ============== ==================================
             0x10    Inbound Message Register 0
             0x14    Inbound Message Register 1
             0x18    Outbound Message Register 0
@@ -21,10 +31,13 @@ For RR44xx Intel IOP based adapters, the controller IOP is accessed via PCI BAR0
             0x34    Outbound Interrupt Mask Register
             0x40    Inbound Queue Port
             0x44    Outbound Queue Port
+     ============== ==================================
 
 For Intel IOP based adapters, the controller IOP is accessed via PCI BAR0:
 
+     ============== ==================================
      BAR0 offset    Register
+     ============== ==================================
             0x10    Inbound Message Register 0
             0x14    Inbound Message Register 1
             0x18    Outbound Message Register 0
@@ -36,16 +49,22 @@ For Intel IOP based adapters, the controller IOP is accessed via PCI BAR0:
             0x34    Outbound Interrupt Mask Register
             0x40    Inbound Queue Port
             0x44    Outbound Queue Port
+     ============== ==================================
 
 For Marvell not Frey IOP based adapters, the IOP is accessed via PCI BAR0 and BAR1:
 
+     ============== ==================================
      BAR0 offset    Register
+     ============== ==================================
          0x20400    Inbound Doorbell Register
          0x20404    Inbound Interrupt Mask Register
          0x20408    Outbound Doorbell Register
          0x2040C    Outbound Interrupt Mask Register
+     ============== ==================================
 
+     ============== ==================================
      BAR1 offset    Register
+     ============== ==================================
              0x0    Inbound Queue Head Pointer
              0x4    Inbound Queue Tail Pointer
              0x8    Outbound Queue Head Pointer
@@ -53,14 +72,20 @@ For Marvell not Frey IOP based adapters, the IOP is accessed via PCI BAR0 and BA
             0x10    Inbound Message Register
             0x14    Outbound Message Register
      0x40-0x1040    Inbound Queue
-   0x1040-0x2040    Outbound Queue
+     0x1040-0x2040  Outbound Queue
+     ============== ==================================
 
 For Marvell Frey IOP based adapters, the IOP is accessed via PCI BAR0 and BAR1:
 
+     ============== ==================================
      BAR0 offset    Register
+     ============== ==================================
              0x0    IOP configuration information.
+     ============== ==================================
 
+     ============== ===================================================
      BAR1 offset    Register
+     ============== ===================================================
           0x4000    Inbound List Base Address Low
           0x4004    Inbound List Base Address High
           0x4018    Inbound List Write Pointer
@@ -76,10 +101,11 @@ For Marvell Frey IOP based adapters, the IOP is accessed via PCI BAR0 and BAR1:
          0x10420    CPU to PCIe Function 0 Message A
          0x10480    CPU to PCIe Function 0 Doorbell
          0x10484    CPU to PCIe Function 0 Doorbell Enable
+     ============== ===================================================
 
 
 I/O Request Workflow of Not Marvell Frey
-------------------------------------------
+----------------------------------------
 
 All queued requests are handled via inbound/outbound queue port.
 A request packet can be allocated in either IOP or host memory.
@@ -124,7 +150,7 @@ of an inbound message.
 
 
 I/O Request Workflow of Marvell Frey
---------------------------------------
+------------------------------------
 
 All queued requests are handled via inbound/outbound list.
 
@@ -167,13 +193,17 @@ User-level Interface
 
 The driver exposes following sysfs attributes:
 
+     ==================   ===    ========================
      NAME                 R/W    Description
+     ==================   ===    ========================
      driver-version        R     driver version string
      firmware-version      R     firmware version string
+     ==================   ===    ========================
 
 
 -----------------------------------------------------------------------------
-Copyright (C) 2006-2012 HighPoint Technologies, Inc. All Rights Reserved.
+
+Copyright |copy| 2006-2012 HighPoint Technologies, Inc. All Rights Reserved.
 
   This file is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
@@ -181,4 +211,5 @@ Copyright (C) 2006-2012 HighPoint Technologies, Inc. All Rights Reserved.
   GNU General Public License for more details.
 
   linux@highpoint-tech.com
+
   http://www.highpoint-tech.com
diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst
new file mode 100644
index 000000000000..7c5f5f8f614e
--- /dev/null
+++ b/Documentation/scsi/index.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+Linux SCSI Subsystem
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   53c700
+   aacraid
+   advansys
+   aha152x
+   aic79xx
+   aic7xxx
+   arcmsr_spec
+   bfa
+   bnx2fc
+   BusLogic
+   cxgb3i
+   dc395x
+   dpti
+   FlashPoint
+   g_NCR5380
+   hpsa
+   hptiop
+   libsas
+   link_power_management_policy
+   lpfc
+   megaraid
+   ncr53c8xx
+   NinjaSCSI
+   ppa
+   qlogicfas
+   scsi-changer
+   scsi_eh
+   scsi_fc_transport
+   scsi-generic
+   scsi_mid_low_api
+   scsi-parameters
+   scsi
+   sd-parameters
+   smartpqi
+   st
+   sym53c500_cs
+   sym53c8xx_2
+   tcm_qla2xxx
+   ufs
+   wd719x
+
+   scsi_transport_srp/figures
diff --git a/Documentation/scsi/libsas.txt b/Documentation/scsi/libsas.rst
index 8cac6492aade..7216b5d25800 100644
--- a/Documentation/scsi/libsas.txt
+++ b/Documentation/scsi/libsas.rst
@@ -1,5 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========
 SAS Layer
----------
+=========
 
 The SAS Layer is a management infrastructure which manages
 SAS LLDDs.  It sits between SCSI Core and SAS LLDDs.  The
@@ -37,16 +40,21 @@ It will then return.  Then you enable your phys to actually
 start OOB (at which point your driver will start calling the
 notify_* event callbacks).
 
-Structure descriptions:
+Structure descriptions
+======================
+
+``struct sas_phy``
+------------------
 
-struct sas_phy --------------------
 Normally this is statically embedded to your driver's
-phy structure:
-	struct my_phy {
-	       blah;
-	       struct sas_phy sas_phy;
-	       bleh;
-	};
+phy structure::
+
+    struct my_phy {
+	    blah;
+	    struct sas_phy sas_phy;
+	    bleh;
+    };
+
 And then all the phys are an array of my_phy in your HA
 struct (shown below).
 
@@ -63,94 +71,122 @@ There is a scheme where the LLDD can RW certain fields,
 and the SAS layer can only read such ones, and vice versa.
 The idea is to avoid unnecessary locking.
 
-enabled -- must be set (0/1)
-id -- must be set [0,MAX_PHYS)
-class, proto, type, role, oob_mode, linkrate -- must be set
-oob_mode --  you set this when OOB has finished and then notify
-the SAS Layer.
-
-sas_addr -- this normally points to an array holding the sas
-address of the phy, possibly somewhere in your my_phy
-struct.
-
-attached_sas_addr -- set this when you (LLDD) receive an
-IDENTIFY frame or a FIS frame, _before_ notifying the SAS
-layer.  The idea is that sometimes the LLDD may want to fake
-or provide a different SAS address on that phy/port and this
-allows it to do this.  At best you should copy the sas
-address from the IDENTIFY frame or maybe generate a SAS
-address for SATA directly attached devices.  The Discover
-process may later change this.
-
-frame_rcvd -- this is where you copy the IDENTIFY/FIS frame
-when you get it; you lock, copy, set frame_rcvd_size and
-unlock the lock, and then call the event.  It is a pointer
-since there's no way to know your hw frame size _exactly_,
-so you define the actual array in your phy struct and let
-this pointer point to it.  You copy the frame from your
-DMAable memory to that area holding the lock.
-
-sas_prim -- this is where primitives go when they're
-received.  See sas.h. Grab the lock, set the primitive,
-release the lock, notify.
-
-port -- this points to the sas_port if the phy belongs
-to a port -- the LLDD only reads this. It points to the
-sas_port this phy is part of.  Set by the SAS Layer.
-
-ha -- may be set; the SAS layer sets it anyway.
-
-lldd_phy -- you should set this to point to your phy so you
-can find your way around faster when the SAS layer calls one
-of your callbacks and passes you a phy.  If the sas_phy is
-embedded you can also use container_of -- whatever you
-prefer.
-
-
-struct sas_port --------------------
+enabled
+    - must be set (0/1)
+
+id
+    - must be set [0,MAX_PHYS)]
+
+class, proto, type, role, oob_mode, linkrate
+    - must be set
+
+oob_mode
+    - you set this when OOB has finished and then notify
+      the SAS Layer.
+
+sas_addr
+    - this normally points to an array holding the sas
+      address of the phy, possibly somewhere in your my_phy
+      struct.
+
+attached_sas_addr
+    - set this when you (LLDD) receive an
+      IDENTIFY frame or a FIS frame, _before_ notifying the SAS
+      layer.  The idea is that sometimes the LLDD may want to fake
+      or provide a different SAS address on that phy/port and this
+      allows it to do this.  At best you should copy the sas
+      address from the IDENTIFY frame or maybe generate a SAS
+      address for SATA directly attached devices.  The Discover
+      process may later change this.
+
+frame_rcvd
+    - this is where you copy the IDENTIFY/FIS frame
+      when you get it; you lock, copy, set frame_rcvd_size and
+      unlock the lock, and then call the event.  It is a pointer
+      since there's no way to know your hw frame size _exactly_,
+      so you define the actual array in your phy struct and let
+      this pointer point to it.  You copy the frame from your
+      DMAable memory to that area holding the lock.
+
+sas_prim
+    - this is where primitives go when they're
+      received.  See sas.h. Grab the lock, set the primitive,
+      release the lock, notify.
+
+port
+    - this points to the sas_port if the phy belongs
+      to a port -- the LLDD only reads this. It points to the
+      sas_port this phy is part of.  Set by the SAS Layer.
+
+ha
+    - may be set; the SAS layer sets it anyway.
+
+lldd_phy
+    - you should set this to point to your phy so you
+      can find your way around faster when the SAS layer calls one
+      of your callbacks and passes you a phy.  If the sas_phy is
+      embedded you can also use container_of -- whatever you
+      prefer.
+
+
+``struct sas_port``
+-------------------
+
 The LLDD doesn't set any fields of this struct -- it only
 reads them.  They should be self explanatory.
 
 phy_mask is 32 bit, this should be enough for now, as I
 haven't heard of a HA having more than 8 phys.
 
-lldd_port -- I haven't found use for that -- maybe other
-LLDD who wish to have internal port representation can make
-use of this.
+lldd_port
+    - I haven't found use for that -- maybe other
+      LLDD who wish to have internal port representation can make
+      use of this.
 
+``struct sas_ha_struct``
+------------------------
 
-struct sas_ha_struct --------------------
 It normally is statically declared in your own LLDD
-structure describing your adapter:
-struct my_sas_ha {
-       blah;
-       struct sas_ha_struct sas_ha;
-       struct my_phy phys[MAX_PHYS];
-       struct sas_port sas_ports[MAX_PHYS]; /* (1) */
-       bleh;
-};
+structure describing your adapter::
+
+    struct my_sas_ha {
+	blah;
+	struct sas_ha_struct sas_ha;
+	struct my_phy phys[MAX_PHYS];
+	struct sas_port sas_ports[MAX_PHYS]; /* (1) */
+	bleh;
+    };
 
-(1) If your LLDD doesn't have its own port representation.
+    (1) If your LLDD doesn't have its own port representation.
 
 What needs to be initialized (sample function given below).
 
 pcidev
-sas_addr -- since the SAS layer doesn't want to mess with
+^^^^^^
+
+sas_addr
+       - since the SAS layer doesn't want to mess with
 	 memory allocation, etc, this points to statically
 	 allocated array somewhere (say in your host adapter
 	 structure) and holds the SAS address of the host
 	 adapter as given by you or the manufacturer, etc.
+
 sas_port
-sas_phy -- an array of pointers to structures. (see
+^^^^^^^^
+
+sas_phy
+      - an array of pointers to structures. (see
 	note above on sas_addr).
 	These must be set.  See more notes below.
-num_phys -- the number of phys present in the sas_phy array,
+
+num_phys
+       - the number of phys present in the sas_phy array,
 	 and the number of ports present in the sas_port
 	 array.  There can be a maximum num_phys ports (one per
 	 port) so we drop the num_ports, and only use
 	 num_phys.
 
-The event interface:
+The event interface::
 
 	/* LLDD calls these to notify the class of an event. */
 	void (*notify_ha_event)(struct sas_ha_struct *, enum ha_event);
@@ -161,7 +197,7 @@ When sas_register_ha() returns, those are set and can be
 called by the LLDD to notify the SAS layer of such events
 the SAS layer.
 
-The port notification:
+The port notification::
 
 	/* The class calls these to notify the LLDD of an event. */
 	void (*lldd_port_formed)(struct sas_phy *);
@@ -171,7 +207,7 @@ If the LLDD wants notification when a port has been formed
 or deformed it sets those to a function satisfying the type.
 
 A SAS LLDD should also implement at least one of the Task
-Management Functions (TMFs) described in SAM:
+Management Functions (TMFs) described in SAM::
 
 	/* Task Management Functions. Must be called from process context. */
 	int (*lldd_abort_task)(struct sas_task *);
@@ -184,7 +220,7 @@ Management Functions (TMFs) described in SAM:
 
 For more information please read SAM from T10.org.
 
-Port and Adapter management:
+Port and Adapter management::
 
 	/* Port and Adapter management */
 	int (*lldd_clear_nexus_port)(struct sas_port *);
@@ -192,75 +228,78 @@ Port and Adapter management:
 
 A SAS LLDD should implement at least one of those.
 
-Phy management:
+Phy management::
 
 	/* Phy management */
 	int (*lldd_control_phy)(struct sas_phy *, enum phy_func);
 
-lldd_ha -- set this to point to your HA struct. You can also
-use container_of if you embedded it as shown above.
+lldd_ha
+    - set this to point to your HA struct. You can also
+      use container_of if you embedded it as shown above.
 
 A sample initialization and registration function
 can look like this (called last thing from probe())
-*but* before you enable the phys to do OOB:
+*but* before you enable the phys to do OOB::
 
-static int register_sas_ha(struct my_sas_ha *my_ha)
-{
-	int i;
-	static struct sas_phy   *sas_phys[MAX_PHYS];
-	static struct sas_port  *sas_ports[MAX_PHYS];
+    static int register_sas_ha(struct my_sas_ha *my_ha)
+    {
+	    int i;
+	    static struct sas_phy   *sas_phys[MAX_PHYS];
+	    static struct sas_port  *sas_ports[MAX_PHYS];
 
-	my_ha->sas_ha.sas_addr = &my_ha->sas_addr[0];
+	    my_ha->sas_ha.sas_addr = &my_ha->sas_addr[0];
 
-	for (i = 0; i < MAX_PHYS; i++) {
-		sas_phys[i] = &my_ha->phys[i].sas_phy;
-		sas_ports[i] = &my_ha->sas_ports[i];
-	}
+	    for (i = 0; i < MAX_PHYS; i++) {
+		    sas_phys[i] = &my_ha->phys[i].sas_phy;
+		    sas_ports[i] = &my_ha->sas_ports[i];
+	    }
 
-	my_ha->sas_ha.sas_phy  = sas_phys;
-	my_ha->sas_ha.sas_port = sas_ports;
-	my_ha->sas_ha.num_phys = MAX_PHYS;
+	    my_ha->sas_ha.sas_phy  = sas_phys;
+	    my_ha->sas_ha.sas_port = sas_ports;
+	    my_ha->sas_ha.num_phys = MAX_PHYS;
 
-	my_ha->sas_ha.lldd_port_formed = my_port_formed;
+	    my_ha->sas_ha.lldd_port_formed = my_port_formed;
 
-	my_ha->sas_ha.lldd_dev_found = my_dev_found;
-	my_ha->sas_ha.lldd_dev_gone = my_dev_gone;
+	    my_ha->sas_ha.lldd_dev_found = my_dev_found;
+	    my_ha->sas_ha.lldd_dev_gone = my_dev_gone;
 
-	my_ha->sas_ha.lldd_execute_task = my_execute_task;
+	    my_ha->sas_ha.lldd_execute_task = my_execute_task;
 
-	my_ha->sas_ha.lldd_abort_task     = my_abort_task;
-	my_ha->sas_ha.lldd_abort_task_set = my_abort_task_set;
-	my_ha->sas_ha.lldd_clear_aca      = my_clear_aca;
-	my_ha->sas_ha.lldd_clear_task_set = my_clear_task_set;
-	my_ha->sas_ha.lldd_I_T_nexus_reset= NULL; (2)
-	my_ha->sas_ha.lldd_lu_reset       = my_lu_reset;
-	my_ha->sas_ha.lldd_query_task     = my_query_task;
+	    my_ha->sas_ha.lldd_abort_task     = my_abort_task;
+	    my_ha->sas_ha.lldd_abort_task_set = my_abort_task_set;
+	    my_ha->sas_ha.lldd_clear_aca      = my_clear_aca;
+	    my_ha->sas_ha.lldd_clear_task_set = my_clear_task_set;
+	    my_ha->sas_ha.lldd_I_T_nexus_reset= NULL; (2)
+	    my_ha->sas_ha.lldd_lu_reset       = my_lu_reset;
+	    my_ha->sas_ha.lldd_query_task     = my_query_task;
 
-	my_ha->sas_ha.lldd_clear_nexus_port = my_clear_nexus_port;
-	my_ha->sas_ha.lldd_clear_nexus_ha = my_clear_nexus_ha;
+	    my_ha->sas_ha.lldd_clear_nexus_port = my_clear_nexus_port;
+	    my_ha->sas_ha.lldd_clear_nexus_ha = my_clear_nexus_ha;
 
-	my_ha->sas_ha.lldd_control_phy = my_control_phy;
+	    my_ha->sas_ha.lldd_control_phy = my_control_phy;
 
-	return sas_register_ha(&my_ha->sas_ha);
-}
+	    return sas_register_ha(&my_ha->sas_ha);
+    }
 
 (2) SAS 1.1 does not define I_T Nexus Reset TMF.
 
 Events
-------
+======
 
-Events are _the only way_ a SAS LLDD notifies the SAS layer
+Events are **the only way** a SAS LLDD notifies the SAS layer
 of anything.  There is no other method or way a LLDD to tell
 the SAS layer of anything happening internally or in the SAS
 domain.
 
-Phy events:
+Phy events::
+
 	PHYE_LOSS_OF_SIGNAL, (C)
 	PHYE_OOB_DONE,
 	PHYE_OOB_ERROR,      (C)
 	PHYE_SPINUP_HOLD.
 
-Port events, passed on a _phy_:
+Port events, passed on a _phy_::
+
 	PORTE_BYTES_DMAED,      (M)
 	PORTE_BROADCAST_RCVD,   (E)
 	PORTE_LINK_RESET_ERR,   (C)
@@ -271,6 +310,7 @@ Host Adapter event:
 	HAE_RESET
 
 A SAS LLDD should be able to generate
+
 	- at least one event from group C (choice),
 	- events marked M (mandatory) are mandatory (only one),
 	- events marked E (expander) if it wants the SAS layer
@@ -279,26 +319,42 @@ A SAS LLDD should be able to generate
 
 Meaning:
 
-HAE_RESET -- when your HA got internal error and was reset.
+HAE_RESET
+    - when your HA got internal error and was reset.
+
+PORTE_BYTES_DMAED
+    - on receiving an IDENTIFY/FIS frame
+
+PORTE_BROADCAST_RCVD
+    - on receiving a primitive
+
+PORTE_LINK_RESET_ERR
+    - timer expired, loss of signal, loss of DWS, etc. [1]_
 
-PORTE_BYTES_DMAED -- on receiving an IDENTIFY/FIS frame
-PORTE_BROADCAST_RCVD -- on receiving a primitive
-PORTE_LINK_RESET_ERR -- timer expired, loss of signal, loss
-of DWS, etc. (*)
-PORTE_TIMER_EVENT -- DWS reset timeout timer expired (*)
-PORTE_HARD_RESET -- Hard Reset primitive received.
+PORTE_TIMER_EVENT
+    - DWS reset timeout timer expired [1]_
 
-PHYE_LOSS_OF_SIGNAL -- the device is gone (*)
-PHYE_OOB_DONE -- OOB went fine and oob_mode is valid
-PHYE_OOB_ERROR -- Error while doing OOB, the device probably
-got disconnected. (*)
-PHYE_SPINUP_HOLD -- SATA is present, COMWAKE not sent.
+PORTE_HARD_RESET
+    - Hard Reset primitive received.
 
-(*) should set/clear the appropriate fields in the phy,
-    or alternatively call the inlined sas_phy_disconnected()
-    which is just a helper, from their tasklet.
+PHYE_LOSS_OF_SIGNAL
+    - the device is gone [1]_
 
-The Execute Command SCSI RPC:
+PHYE_OOB_DONE
+    - OOB went fine and oob_mode is valid
+
+PHYE_OOB_ERROR
+    - Error while doing OOB, the device probably
+      got disconnected. [1]_
+
+PHYE_SPINUP_HOLD
+    - SATA is present, COMWAKE not sent.
+
+.. [1] should set/clear the appropriate fields in the phy,
+       or alternatively call the inlined sas_phy_disconnected()
+       which is just a helper, from their tasklet.
+
+The Execute Command SCSI RPC::
 
 	int (*lldd_execute_task)(struct sas_task *, gfp_t gfp_flags);
 
@@ -311,23 +367,28 @@ That is, when lldd_execute_task() is called, the command
 go out on the transport *immediately*.  There is *no*
 queuing of any sort and at any level in a SAS LLDD.
 
-Returns: -SAS_QUEUE_FULL, -ENOMEM, nothing was queued;
-	 0, the task(s) were queued.
+Returns:
 
-struct sas_task {
-	dev -- the device this task is destined to
-	task_proto -- _one_ of enum sas_proto
-	scatter -- pointer to scatter gather list array
-	num_scatter -- number of elements in scatter
-	total_xfer_len -- total number of bytes expected to be transferred
-	data_dir -- PCI_DMA_...
-	task_done -- callback when the task has finished execution
-};
+   * -SAS_QUEUE_FULL, -ENOMEM, nothing was queued;
+   * 0, the task(s) were queued.
 
-DISCOVERY
----------
+::
+
+    struct sas_task {
+	    dev -- the device this task is destined to
+	    task_proto -- _one_ of enum sas_proto
+	    scatter -- pointer to scatter gather list array
+	    num_scatter -- number of elements in scatter
+	    total_xfer_len -- total number of bytes expected to be transferred
+	    data_dir -- PCI_DMA_...
+	    task_done -- callback when the task has finished execution
+    };
+
+Discovery
+=========
 
 The sysfs tree has the following purposes:
+
     a) It shows you the physical layout of the SAS domain at
        the current time, i.e. how the domain looks in the
        physical world right now.
@@ -336,6 +397,7 @@ The sysfs tree has the following purposes:
 This is a link to the tree(1) program, very useful in
 viewing the SAS domain:
 ftp://mama.indstate.edu/linux/tree/
+
 I expect user space applications to actually create a
 graphical interface of this.
 
@@ -359,7 +421,7 @@ contents of the domain_device structure, but it never creates
 or destroys one.
 
 Expander management from User Space
------------------------------------
+===================================
 
 In each expander directory in sysfs, there is a file called
 "smp_portal".  It is a binary sysfs attribute file, which
@@ -371,15 +433,23 @@ Functionality is deceptively simple:
 
 1. Build the SMP frame you want to send. The format and layout
    is described in the SAS spec.  Leave the CRC field equal 0.
+
 open(2)
+
 2. Open the expander's SMP portal sysfs file in RW mode.
+
 write(2)
+
 3. Write the frame you built in 1.
+
 read(2)
+
 4. Read the amount of data you expect to receive for the frame you built.
    If you receive different amount of data you expected to receive,
    then there was some kind of error.
+
 close(2)
+
 All this process is shown in detail in the function do_smp_func()
 and its callers, in the file "expander_conf.c".
 
diff --git a/Documentation/scsi/link_power_management_policy.txt b/Documentation/scsi/link_power_management_policy.rst
index d18993d01884..64288dcf10f6 100644
--- a/Documentation/scsi/link_power_management_policy.txt
+++ b/Documentation/scsi/link_power_management_policy.rst
@@ -1,8 +1,15 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==========================
+Link Power Managent Policy
+==========================
+
 This parameter allows the user to set the link (interface) power management.
 There are 3 possible options:
 
+=====================   =====================================================
 Value			Effect
-----------------------------------------------------------------------------
+=====================   =====================================================
 min_power		Tell the controller to try to make the link use the
 			least possible power when possible.  This may
 			sacrifice some performance due to increased latency
@@ -15,5 +22,4 @@ max_performance		Generally, this means no power management.  Tell
 medium_power		Tell the controller to enter a lower power state
 			when possible, but do not enter the lowest power
 			state, thus improving latency over min_power setting.
-
-
+=====================   =====================================================
diff --git a/Documentation/scsi/lpfc.txt b/Documentation/scsi/lpfc.rst
index 5741ea8aa88a..6e217e82b9b9 100644
--- a/Documentation/scsi/lpfc.txt
+++ b/Documentation/scsi/lpfc.rst
@@ -1,10 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
 
-LPFC Driver Release Notes:
+=========================
+LPFC Driver Release Notes
+=========================
 
-=============================================================================
 
-
-                               IMPORTANT:
+.. important::
 
   Starting in the 8.0.17 release, the driver began to be targeted strictly
   toward the upstream kernel. As such, we removed #ifdefs for older kernels
@@ -22,9 +23,6 @@ LPFC Driver Release Notes:
   Please heed these dependencies....
 
 
-   ********************************************************************
-
-
 The following information is provided for additional background on the
 history of the driver as we push for upstream acceptance.
 
@@ -64,6 +62,7 @@ Cable pull and temporary device Loss:
 
 
 Kernel Support
+==============
 
   This source package is targeted for the upstream kernel only. (See notes
   at the top of this file). It relies on interfaces that are slowing
@@ -77,7 +76,6 @@ Kernel Support
 
 
 Patches
+=======
 
   Thankfully, at this time, patches are not needed.
-
-
diff --git a/Documentation/scsi/megaraid.txt b/Documentation/scsi/megaraid.rst
index 3c7cea51e687..22b75a86ba72 100644
--- a/Documentation/scsi/megaraid.txt
+++ b/Documentation/scsi/megaraid.rst
@@ -1,7 +1,10 @@
-			Notes on Management Module
-			~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. SPDX-License-Identifier: GPL-2.0
 
-Overview:
+==========================
+Notes on Management Module
+==========================
+
+Overview
 --------
 
 Different classes of controllers from LSI Logic accept and respond to the
@@ -25,28 +28,32 @@ ioctl commands. But this module is envisioned to handle all user space level
 interactions. So any 'proc', 'sysfs' implementations will be localized in this
 common module.
 
-Credits:
+Credits
 -------
 
-"Shared code in a third module, a "library module", is an acceptable
-solution. modprobe automatically loads dependent modules, so users
-running "modprobe driver1" or "modprobe driver2" would automatically
-load the shared library module."
+::
+
+	"Shared code in a third module, a "library module", is an acceptable
+	solution. modprobe automatically loads dependent modules, so users
+	running "modprobe driver1" or "modprobe driver2" would automatically
+	load the shared library module."
+
+- Jeff Garzik (jgarzik@pobox.com), 02.25.2004 LKML
 
-		- Jeff Garzik (jgarzik@pobox.com), 02.25.2004 LKML
+::
 
-"As Jeff hinted, if your userspace<->driver API is consistent between
-your new MPT-based RAID controllers and your existing megaraid driver,
-then perhaps you need a single small helper module (lsiioctl or some
-better name), loaded by both mptraid and megaraid automatically, which
-handles registering the /dev/megaraid node dynamically. In this case,
-both mptraid and megaraid would register with lsiioctl for each
-adapter discovered, and lsiioctl would essentially be a switch,
-redirecting userspace tool ioctls to the appropriate driver."
+	"As Jeff hinted, if your userspace<->driver API is consistent between
+	your new MPT-based RAID controllers and your existing megaraid driver,
+	then perhaps you need a single small helper module (lsiioctl or some
+	better name), loaded by both mptraid and megaraid automatically, which
+	handles registering the /dev/megaraid node dynamically. In this case,
+	both mptraid and megaraid would register with lsiioctl for each
+	adapter discovered, and lsiioctl would essentially be a switch,
+	redirecting userspace tool ioctls to the appropriate driver."
 
-		- Matt Domsch, (Matt_Domsch@dell.com), 02.25.2004 LKML
+- Matt Domsch, (Matt_Domsch@dell.com), 02.25.2004 LKML
 
-Design:
+Design
 ------
 
 The Common Management Module is implemented in megaraid_mm.[ch] files. This
@@ -61,7 +68,7 @@ uioc_t. The management module converts the older ioctl packets from the older
 applications into uioc_t. After driver handles the uioc_t, the common module
 will convert that back into the old format before returning to applications.
 
-As new applications evolve and replace the old ones, the old packet format 
+As new applications evolve and replace the old ones, the old packet format
 will be retired.
 
 Common module dedicates one uioc_t packet to each controller registered. This
diff --git a/Documentation/scsi/ncr53c8xx.txt b/Documentation/scsi/ncr53c8xx.rst
index 8586efff1e99..c41cec99f07c 100644
--- a/Documentation/scsi/ncr53c8xx.txt
+++ b/Documentation/scsi/ncr53c8xx.rst
@@ -1,106 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================================
 The Linux NCR53C8XX/SYM53C8XX drivers README file
+=================================================
 
 Written by Gerard Roudier <groudier@free.fr>
+
 21 Rue Carnot
+
 95170 DEUIL LA BARRE - FRANCE
 
 29 May 1999
-===============================================================================
-
-1.  Introduction
-2.  Supported chips and SCSI features
-3.  Advantages of the enhanced 896 driver
-      3.1 Optimized SCSI SCRIPTS
-      3.2 New features of the SYM53C896 (64 bit PCI dual LVD SCSI controller)
-4.  Memory mapped I/O versus normal I/O
-5.  Tagged command queueing
-6.  Parity checking
-7.  Profiling information
-8.  Control commands
-      8.1  Set minimum synchronous period
-      8.2  Set wide size
-      8.3  Set maximum number of concurrent tagged commands
-      8.4  Set order type for tagged command
-      8.5  Set debug mode
-      8.6  Clear profile counters
-      8.7  Set flag (no_disc)
-      8.8  Set verbose level
-      8.9  Reset all logical units of a target
-      8.10 Abort all tasks of all logical units of a target
-9.  Configuration parameters
-10. Boot setup commands
-      10.1 Syntax
-      10.2 Available arguments
-             10.2.1  Master parity checking
-             10.2.2  Scsi parity checking
-             10.2.3  Scsi disconnections
-             10.2.4  Special features
-             10.2.5  Ultra SCSI support
-             10.2.6  Default number of tagged commands
-             10.2.7  Default synchronous period factor
-             10.2.8  Negotiate synchronous with all devices
-             10.2.9  Verbosity level
-             10.2.10 Debug mode
-             10.2.11 Burst max
-             10.2.12 LED support
-             10.2.13 Max wide
-             10.2.14 Differential mode
-             10.2.15 IRQ mode
-             10.2.16 Reverse probe
-             10.2.17 Fix up PCI configuration space
-             10.2.18 Serial NVRAM
-             10.2.19 Check SCSI BUS 
-             10.2.20 Exclude a host from being attached
-             10.2.21 Suggest a default SCSI id for hosts
-             10.2.22 Enable use of IMMEDIATE ARBITRATION
-      10.3 Advised boot setup commands
-      10.4 PCI configuration fix-up boot option
-      10.5 Serial NVRAM support boot option
-      10.6 SCSI BUS checking boot option
-      10.7 IMMEDIATE ARBITRATION boot option
-11. Some constants and flags of the ncr53c8xx.h header file
-12. Installation
-13. Architecture dependent features
-14. Known problems
-      14.1 Tagged commands with Iomega Jaz device
-      14.2 Device names change when another controller is added
-      14.3 Using only 8 bit devices with a WIDE SCSI controller.
-      14.4 Possible data corruption during a Memory Write and Invalidate
-      14.5 IRQ sharing problems
-15. SCSI problem troubleshooting
-      15.1 Problem tracking
-      15.2 Understanding hardware error reports
-16. Synchronous transfer negotiation tables
-      16.1 Synchronous timings for 53C875 and 53C860 Ultra-SCSI controllers
-      16.2 Synchronous timings for fast SCSI-2 53C8XX controllers
-17. Serial NVRAM support (by Richard Waltham)
-      17.1 Features
-      17.2 Symbios NVRAM layout
-      17.3 Tekram  NVRAM layout
-18. Support for Big Endian
-      18.1 Big Endian CPU
-      18.2 NCR chip in Big Endian mode of operations
 
-===============================================================================
+.. Contents:
+
+   1.  Introduction
+   2.  Supported chips and SCSI features
+   3.  Advantages of the enhanced 896 driver
+         3.1 Optimized SCSI SCRIPTS
+         3.2 New features of the SYM53C896 (64 bit PCI dual LVD SCSI controller)
+   4.  Memory mapped I/O versus normal I/O
+   5.  Tagged command queueing
+   6.  Parity checking
+   7.  Profiling information
+   8.  Control commands
+         8.1  Set minimum synchronous period
+         8.2  Set wide size
+         8.3  Set maximum number of concurrent tagged commands
+         8.4  Set order type for tagged command
+         8.5  Set debug mode
+         8.6  Clear profile counters
+         8.7  Set flag (no_disc)
+         8.8  Set verbose level
+         8.9  Reset all logical units of a target
+         8.10 Abort all tasks of all logical units of a target
+   9.  Configuration parameters
+   10. Boot setup commands
+         10.1 Syntax
+         10.2 Available arguments
+                10.2.1  Master parity checking
+                10.2.2  Scsi parity checking
+                10.2.3  Scsi disconnections
+                10.2.4  Special features
+                10.2.5  Ultra SCSI support
+                10.2.6  Default number of tagged commands
+                10.2.7  Default synchronous period factor
+                10.2.8  Negotiate synchronous with all devices
+                10.2.9  Verbosity level
+                10.2.10 Debug mode
+                10.2.11 Burst max
+                10.2.12 LED support
+                10.2.13 Max wide
+                10.2.14 Differential mode
+                10.2.15 IRQ mode
+                10.2.16 Reverse probe
+                10.2.17 Fix up PCI configuration space
+                10.2.18 Serial NVRAM
+                10.2.19 Check SCSI BUS
+                10.2.20 Exclude a host from being attached
+                10.2.21 Suggest a default SCSI id for hosts
+                10.2.22 Enable use of IMMEDIATE ARBITRATION
+         10.3 Advised boot setup commands
+         10.4 PCI configuration fix-up boot option
+         10.5 Serial NVRAM support boot option
+         10.6 SCSI BUS checking boot option
+         10.7 IMMEDIATE ARBITRATION boot option
+   11. Some constants and flags of the ncr53c8xx.h header file
+   12. Installation
+   13. Architecture dependent features
+   14. Known problems
+         14.1 Tagged commands with Iomega Jaz device
+         14.2 Device names change when another controller is added
+         14.3 Using only 8 bit devices with a WIDE SCSI controller.
+         14.4 Possible data corruption during a Memory Write and Invalidate
+         14.5 IRQ sharing problems
+   15. SCSI problem troubleshooting
+         15.1 Problem tracking
+         15.2 Understanding hardware error reports
+   16. Synchronous transfer negotiation tables
+         16.1 Synchronous timings for 53C875 and 53C860 Ultra-SCSI controllers
+         16.2 Synchronous timings for fast SCSI-2 53C8XX controllers
+   17. Serial NVRAM support (by Richard Waltham)
+         17.1 Features
+         17.2 Symbios NVRAM layout
+         17.3 Tekram  NVRAM layout
+   18. Support for Big Endian
+         18.1 Big Endian CPU
+         18.2 NCR chip in Big Endian mode of operations
 
 1. Introduction
+===============
 
-The initial Linux ncr53c8xx driver has been a port of the ncr driver from 
+The initial Linux ncr53c8xx driver has been a port of the ncr driver from
 FreeBSD that has been achieved in November 1995 by:
-          Gerard Roudier              <groudier@free.fr>
+
+	- Gerard Roudier              <groudier@free.fr>
 
 The original driver has been written for 386bsd and FreeBSD by:
-          Wolfgang Stanglmeier        <wolf@cologne.de>
-          Stefan Esser                <se@mi.Uni-Koeln.de>
+
+        - Wolfgang Stanglmeier        <wolf@cologne.de>
+        - Stefan Esser                <se@mi.Uni-Koeln.de>
 
 It is now available as a bundle of 2 drivers:
 
-- ncr53c8xx generic driver that supports all the SYM53C8XX family including 
+- ncr53c8xx generic driver that supports all the SYM53C8XX family including
   the earliest 810 rev. 1, the latest 896 (2 channel LVD SCSI controller) and
   the new 895A (1 channel LVD SCSI controller).
-- sym53c8xx enhanced driver (a.k.a. 896 drivers) that drops support of oldest 
-  chips in order to gain advantage of new features, as LOAD/STORE instructions 
-  available since the 810A and hardware phase mismatch available with the 
+- sym53c8xx enhanced driver (a.k.a. 896 drivers) that drops support of oldest
+  chips in order to gain advantage of new features, as LOAD/STORE instructions
+  available since the 810A and hardware phase mismatch available with the
   896 and the 895A.
 
 You can find technical information about the NCR 8xx family in the
@@ -109,119 +117,145 @@ Drew Eckhardt.
 
 Information about new chips is available at LSILOGIC web server:
 
-          http://www.lsilogic.com/
+          - http://www.lsilogic.com/
 
 SCSI standard documentations are available at SYMBIOS ftp server:
 
-          ftp://ftp.symbios.com/
+          - ftp://ftp.symbios.com/
 
 Useful SCSI tools written by Eric Youngdale are available at tsx-11:
 
-          ftp://tsx-11.mit.edu/pub/linux/ALPHA/scsi/scsiinfo-X.Y.tar.gz
-          ftp://tsx-11.mit.edu/pub/linux/ALPHA/scsi/scsidev-X.Y.tar.gz
+          - ftp://tsx-11.mit.edu/pub/linux/ALPHA/scsi/scsiinfo-X.Y.tar.gz
+          - ftp://tsx-11.mit.edu/pub/linux/ALPHA/scsi/scsidev-X.Y.tar.gz
 
 These tools are not ALPHA but quite clean and work quite well.
 It is essential you have the 'scsiinfo' package.
 
 This short documentation describes the features of the generic and enhanced
-drivers, configuration parameters and control commands available through 
+drivers, configuration parameters and control commands available through
 the proc SCSI file system read / write operations.
 
 This driver has been tested OK with linux/i386, Linux/Alpha and Linux/PPC.
 
 Latest driver version and patches are available at:
 
-          ftp://ftp.tux.org/pub/people/gerard-roudier
+          - ftp://ftp.tux.org/pub/people/gerard-roudier
+
 or
-          ftp://ftp.symbios.com/mirror/ftp.tux.org/pub/tux/roudier/drivers
+
+          - ftp://ftp.symbios.com/mirror/ftp.tux.org/pub/tux/roudier/drivers
 
 I am not a native speaker of English and there are probably lots of
 mistakes in this README file. Any help will be welcome.
 
 
 2. Supported chips and SCSI features
+====================================
 
 The following features are supported for all chips:
 
-	Synchronous negotiation
-	Disconnection
-	Tagged command queuing
-	SCSI parity checking
-	Master parity checking
+	- Synchronous negotiation
+	- Disconnection
+	- Tagged command queuing
+	- SCSI parity checking
+	- Master parity checking
 
 "Wide negotiation" is supported for chips that allow it.  The
-following table shows some characteristics of NCR 8xx family chips 
+following table shows some characteristics of NCR 8xx family chips
 and what drivers support them.
 
-                                                  Supported by   Supported by
-       On board                                   the generic    the enhanced 
-Chip   SDMS BIOS   Wide   SCSI std.   Max. sync   driver         driver
-----   ---------   ----   ---------   ----------  ------------   -------------
-810        N         N      FAST10    10 MB/s        Y             N
-810A       N         N      FAST10    10 MB/s        Y             Y
-815        Y         N      FAST10    10 MB/s        Y             N
-825        Y         Y      FAST10    20 MB/s        Y             N
-825A       Y         Y      FAST10    20 MB/s        Y             Y
-860        N         N      FAST20    20 MB/s        Y             Y
-875        Y         Y      FAST20    40 MB/s        Y             Y
-876        Y         Y      FAST20    40 MB/s        Y             Y
-895        Y         Y      FAST40    80 MB/s        Y             Y
-895A       Y         Y      FAST40    80 MB/s        Y             Y
-896        Y         Y      FAST40    80 MB/s        Y             Y
-897        Y         Y      FAST40    80 MB/s        Y             Y
-1510D      Y         Y      FAST40    80 MB/s        Y             Y
-1010       Y         Y      FAST80   160 MB/s        N             Y
-1010_66*   Y         Y      FAST80   160 MB/s        N             Y
-
-* Chip supports 33MHz and 66MHz PCI buses.
++--------+-----------+-----+-----------+------------+------------+------------+
+|        |           |     |           |            |Supported by|Supported by|
+|        |On board   |     |           |            |the generic |the enhanced|
+|Chip    |SDMS BIOS  |Wide |SCSI std.  | Max. sync  |driver      |driver      |
++--------+-----------+-----+-----------+------------+------------+------------+
+|810     |  N        | N   |  FAST10   | 10 MB/s    |    Y       |    N       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|810A    |  N        | N   |  FAST10   | 10 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|815     |  Y        | N   |  FAST10   | 10 MB/s    |    Y       |    N       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|825     |  Y        | Y   |  FAST10   | 20 MB/s    |    Y       |    N       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|825A    |  Y        | Y   |  FAST10   | 20 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|860     |  N        | N   |  FAST20   | 20 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|875     |  Y        | Y   |  FAST20   | 40 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|876     |  Y        | Y   |  FAST20   | 40 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|895     |  Y        | Y   |  FAST40   | 80 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|895A    |  Y        | Y   |  FAST40   | 80 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|896     |  Y        | Y   |  FAST40   | 80 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|897     |  Y        | Y   |  FAST40   | 80 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|1510D   |  Y        | Y   |  FAST40   | 80 MB/s    |    Y       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|1010    |  Y        | Y   |  FAST80   |160 MB/s    |    N       |    Y       |
++--------+-----------+-----+-----------+------------+------------+------------+
+|1010_66 |  Y        | Y   |  FAST80   |160 MB/s    |    N       |    Y       |
+|[1]_    |           |     |           |            |            |            |
++--------+-----------+-----+-----------+------------+------------+------------+
+
+.. [1] Chip supports 33MHz and 66MHz PCI buses.
 
 
 Summary of other supported features:
 
-Module:                allow to load the driver
-Memory mapped I/O:     increases performance
-Profiling information: read operations from the proc SCSI file system
-Control commands:      write operations to the proc SCSI file system
-Debugging information: written to syslog (expert only)
-Scatter / gather
-Shared interrupt
-Boot setup commands
-Serial NVRAM:          Symbios and Tekram formats
+:Module:                allow to load the driver
+:Memory mapped I/O:     increases performance
+:Profiling information: read operations from the proc SCSI file system
+:Control commands:      write operations to the proc SCSI file system
+:Debugging information: written to syslog (expert only)
+:Serial NVRAM:          Symbios and Tekram formats
+
+- Scatter / gather
+- Shared interrupt
+- Boot setup commands
 
 
 3. Advantages of the enhanced 896 driver
+========================================
 
-3.1 Optimized SCSI SCRIPTS.
+3.1 Optimized SCSI SCRIPTS
+--------------------------
 
-The 810A, 825A, 875, 895, 896 and 895A support new SCSI SCRIPTS instructions 
-named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register 
-to/from memory much faster that the MOVE MEMORY instruction that is supported 
+The 810A, 825A, 875, 895, 896 and 895A support new SCSI SCRIPTS instructions
+named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register
+to/from memory much faster that the MOVE MEMORY instruction that is supported
 by the 53c7xx and 53c8xx family.
-The LOAD/STORE instructions support absolute and DSA relative addressing 
-modes.  The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead 
+The LOAD/STORE instructions support absolute and DSA relative addressing
+modes.  The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead
 of MOVE MEMORY instructions.
 
 3.2 New features of the SYM53C896 (64 bit PCI dual LVD SCSI controller)
+-----------------------------------------------------------------------
 
-The 896 and the 895A allows handling of the phase mismatch context from 
-SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor 
+The 896 and the 895A allows handling of the phase mismatch context from
+SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor
 until the C code has saved the context of the transfer).
-Implementing this without using LOAD/STORE instructions would be painful 
+Implementing this without using LOAD/STORE instructions would be painful
 and I didn't even want to try it.
 
-The 896 chip supports 64 bit PCI transactions and addressing, while the 
+The 896 chip supports 64 bit PCI transactions and addressing, while the
 895A supports 32 bit PCI transactions and 64 bit addressing.
-The SCRIPTS processor of these chips is not true 64 bit, but uses segment 
-registers for bit 32-63. Another interesting feature is that LOAD/STORE 
+The SCRIPTS processor of these chips is not true 64 bit, but uses segment
+registers for bit 32-63. Another interesting feature is that LOAD/STORE
 instructions that address the on-chip RAM (8k) remain internal to the chip.
 
-Due to the use of LOAD/STORE SCRIPTS instructions, this driver does not 
+Due to the use of LOAD/STORE SCRIPTS instructions, this driver does not
 support the following chips:
+
 - SYM53C810 revision < 0x10 (16)
 - SYM53C815 all revisions
 - SYM53C825 revision < 0x10 (16)
 
 4. Memory mapped I/O versus normal I/O
+======================================
 
 Memory mapped I/O has less latency than normal I/O.  Since
 linux-1.3.x, memory mapped I/O is used rather than normal I/O.  Memory
@@ -233,17 +267,18 @@ driver to use normal I/O in all cases.
 
 
 5. Tagged command queueing
+==========================
 
-Queuing more than 1 command at a time to a device allows it to perform 
-optimizations based on actual head positions and its mechanical 
+Queuing more than 1 command at a time to a device allows it to perform
+optimizations based on actual head positions and its mechanical
 characteristics. This feature may also reduce average command latency.
-In order to really gain advantage of this feature, devices must have 
-a reasonable cache size (No miracle is to be expected for a low-end 
+In order to really gain advantage of this feature, devices must have
+a reasonable cache size (No miracle is to be expected for a low-end
 hard disk with 128 KB or less).
 Some known SCSI devices do not properly support tagged command queuing.
-Generally, firmware revisions that fix this kind of problems are available 
+Generally, firmware revisions that fix this kind of problems are available
 at respective vendor web/ftp sites.
-All I can say is that the hard disks I use on my machines behave well with 
+All I can say is that the hard disks I use on my machines behave well with
 this driver with tagged command queuing enabled:
 
 - IBM S12 0662
@@ -251,9 +286,9 @@ this driver with tagged command queuing enabled:
 - Quantum Atlas I
 - Quantum Atlas II
 
-If your controller has NVRAM, you can configure this feature per target 
-from the user setup tool. The Tekram Setup program allows to tune the 
-maximum number of queued commands up to 32. The Symbios Setup only allows 
+If your controller has NVRAM, you can configure this feature per target
+from the user setup tool. The Tekram Setup program allows to tune the
+maximum number of queued commands up to 32. The Symbios Setup only allows
 to enable or disable this feature.
 
 The maximum number of simultaneous tagged commands queued to a device
@@ -261,16 +296,16 @@ is currently set to 8 by default.  This value is suitable for most SCSI
 disks.  With large SCSI disks (>= 2GB, cache >= 512KB, average seek time
 <= 10 ms), using a larger value may give better performances.
 
-The sym53c8xx driver supports up to 255 commands per device, and the 
-generic ncr53c8xx driver supports up to 64, but using more than 32 is 
-generally not worth-while, unless you are using a very large disk or disk 
-array. It is noticeable that most of recent hard disks seem not to accept 
-more than 64 simultaneous commands. So, using more than 64 queued commands 
+The sym53c8xx driver supports up to 255 commands per device, and the
+generic ncr53c8xx driver supports up to 64, but using more than 32 is
+generally not worth-while, unless you are using a very large disk or disk
+array. It is noticeable that most of recent hard disks seem not to accept
+more than 64 simultaneous commands. So, using more than 64 queued commands
 is probably just resource wasting.
 
-If your controller does not have NVRAM or if it is managed by the SDMS 
-BIOS/SETUP, you can configure tagged queueing feature and device queue 
-depths from the boot command-line. For example:
+If your controller does not have NVRAM or if it is managed by the SDMS
+BIOS/SETUP, you can configure tagged queueing feature and device queue
+depths from the boot command-line. For example::
 
   ncr53c8xx=tags:4/t2t3q15-t4q7/t1u0q32
 
@@ -286,80 +321,85 @@ In some special conditions, some SCSI disk firmwares may return a
 QUEUE FULL status for a SCSI command. This behaviour is managed by the
 driver using the following heuristic:
 
-- Each time a QUEUE FULL status is returned, tagged queue depth is reduced 
-  to the actual number of disconnected commands. 
+- Each time a QUEUE FULL status is returned, tagged queue depth is reduced
+  to the actual number of disconnected commands.
 
 - Every 1000 successfully completed SCSI commands, if allowed by the
   current limit, the maximum number of queueable commands is incremented.
 
-Since QUEUE FULL status reception and handling is resource wasting, the 
-driver notifies by default this problem to user by indicating the actual 
-number of commands used and their status, as well as its decision on the 
+Since QUEUE FULL status reception and handling is resource wasting, the
+driver notifies by default this problem to user by indicating the actual
+number of commands used and their status, as well as its decision on the
 device queue depth change.
-The heuristic used by the driver in handling QUEUE FULL ensures that the 
-impact on performances is not too bad. You can get rid of the messages by 
+The heuristic used by the driver in handling QUEUE FULL ensures that the
+impact on performances is not too bad. You can get rid of the messages by
 setting verbose level to zero, as follow:
 
-1st method: boot your system using 'ncr53c8xx=verb:0' option.
-2nd method: apply "setverbose 0" control command to the proc fs entry 
+1st method:
+	    boot your system using 'ncr53c8xx=verb:0' option.
+
+2nd method:
+	    apply "setverbose 0" control command to the proc fs entry
             corresponding to your controller after boot-up.
 
 6. Parity checking
+==================
 
 The driver supports SCSI parity checking and PCI bus master parity
 checking.  These features must be enabled in order to ensure safe data
 transfers.  However, some flawed devices or mother boards will have
-problems with parity. You can disable either PCI parity or SCSI parity 
+problems with parity. You can disable either PCI parity or SCSI parity
 checking by entering appropriate options from the boot command line.
 (See 10: Boot setup commands).
 
 7. Profiling information
+========================
 
 Profiling information is available through the proc SCSI file system.
-Since gathering profiling information may impact performances, this 
-feature is disabled by default and requires a compilation configuration 
+Since gathering profiling information may impact performances, this
+feature is disabled by default and requires a compilation configuration
 option to be set to Y.
 
-The device associated with a host has the following pathname:
+The device associated with a host has the following pathname::
 
           /proc/scsi/ncr53c8xx/N     (N=0,1,2 ....)
 
-Generally, only 1 board is used on hardware configuration, and that device is:
+Generally, only 1 board is used on hardware configuration, and that device is::
+
           /proc/scsi/ncr53c8xx/0
 
 However, if the driver has been made as module, the number of the
 hosts is incremented each time the driver is loaded.
 
-In order to display profiling information, just enter:
+In order to display profiling information, just enter::
 
          cat /proc/scsi/ncr53c8xx/0
 
-and you will get something like the following text:
-
--------------------------------------------------------
-General information:
-  Chip NCR53C810, device id 0x1, revision id 0x2
-  IO port address 0x6000, IRQ number 10
-  Using memory mapped IO at virtual address 0x282c000
-  Synchronous transfer period 25, max commands per lun 4
-Profiling information:
-  num_trans    = 18014
-  num_kbytes   = 671314
-  num_disc     = 25763
-  num_break    = 1673
-  num_int      = 1685
-  num_fly      = 18038
-  ms_setup     = 4940
-  ms_data      = 369940
-  ms_disc      = 183090
-  ms_post      = 1320
--------------------------------------------------------
+and you will get something like the following text::
+
+    General information:
+    Chip NCR53C810, device id 0x1, revision id 0x2
+    IO port address 0x6000, IRQ number 10
+    Using memory mapped IO at virtual address 0x282c000
+    Synchronous transfer period 25, max commands per lun 4
+    Profiling information:
+    num_trans    = 18014
+    num_kbytes   = 671314
+    num_disc     = 25763
+    num_break    = 1673
+    num_int      = 1685
+    num_fly      = 18038
+    ms_setup     = 4940
+    ms_data      = 369940
+    ms_disc      = 183090
+    ms_post      = 1320
 
 General information is easy to understand. The device ID and the
 revision ID identify the SCSI chip as follows:
 
+======= ============= ===========
 Chip    Device id     Revision Id
-----    ---------     -----------
+======= ============= ===========
 810       0x1            <  0x10
 810A      0x1            >= 0x10
 815       0x4
@@ -368,6 +408,7 @@ Chip    Device id     Revision Id
 825A      0x3            >= 0x10
 875       0xf
 895       0xc
+======= ============= ===========
 
 The profiling information is updated upon completion of SCSI commands.
 A data structure is allocated and zeroed when the host adapter is
@@ -425,15 +466,16 @@ Due to the 1/100 second tick of the system clock, "ms_post" time may
 be wrong.
 
 In the example above, we got 18038 interrupts "on the fly" and only
-1673 script breaks generally due to disconnections inside a segment 
+1673 script breaks generally due to disconnections inside a segment
 of the scatter list.
 
 
 8. Control commands
+===================
 
 Control commands can be sent to the driver with write operations to
 the proc SCSI file system. The generic command syntax is the
-following:
+following::
 
       echo "<verb> <parameters>" >/proc/scsi/ncr53c8xx/0
       (assumes controller number is 0)
@@ -444,66 +486,81 @@ apply to all targets of the SCSI chain (except the controller).
 Available commands:
 
 8.1 Set minimum synchronous period factor
+-----------------------------------------
 
     setsync <target> <period factor>
 
-    target:    target number
-    period:    minimum synchronous period.
+    :target:   target number
+    :period:   minimum synchronous period.
                Maximum speed = 1000/(4*period factor) except for special
                cases below.
 
     Specify a period of 255, to force asynchronous transfer mode.
 
-      10 means 25 nano-seconds synchronous period
-      11 means 30 nano-seconds synchronous period
-      12 means 50 nano-seconds synchronous period
+      - 10 means 25 nano-seconds synchronous period
+      - 11 means 30 nano-seconds synchronous period
+      - 12 means 50 nano-seconds synchronous period
 
 8.2 Set wide size
+-----------------
 
     setwide <target> <size>
 
-    target:    target number
-    size:      0=8 bits, 1=16bits
+    :target:   target number
+    :size:     0=8 bits, 1=16bits
 
 8.3 Set maximum number of concurrent tagged commands
- 
+----------------------------------------------------
+
     settags <target> <tags>
 
-    target:    target number
-    tags:      number of concurrent tagged commands
+    :target:   target number
+    :tags:     number of concurrent tagged commands
                must not be greater than SCSI_NCR_MAX_TAGS (default: 8)
 
 8.4 Set order type for tagged command
+-------------------------------------
 
     setorder <order>
 
-    order:     3 possible values:
-               simple: use SIMPLE TAG for all operations (read and write)
-               ordered: use ORDERED TAG for all operations
-               default: use default tag type,
+    :order:    3 possible values:
+
+               simple:
+			use SIMPLE TAG for all operations (read and write)
+
+               ordered:
+			use ORDERED TAG for all operations
+
+               default:
+			use default tag type,
                         SIMPLE  TAG for read  operations
                         ORDERED TAG for write operations
 
 
 8.5 Set debug mode
+------------------
 
     setdebug <list of debug flags>
 
     Available debug flags:
-        alloc:   print info about memory allocations (ccb, lcb)
-        queue:   print info about insertions into the command start queue
-        result:  print sense data on CHECK CONDITION status
-        scatter: print info about the scatter process
-        scripts: print info about the script binding process
-	tiny:    print minimal debugging information
-	timing:  print timing information of the NCR chip
-	nego:    print information about SCSI negotiations
-	phase:   print information on script interruptions
+
+	======== ========================================================
+        alloc    print info about memory allocations (ccb, lcb)
+        queue    print info about insertions into the command start queue
+        result   print sense data on CHECK CONDITION status
+        scatter  print info about the scatter process
+        scripts  print info about the script binding process
+	tiny     print minimal debugging information
+	timing   print timing information of the NCR chip
+	nego     print information about SCSI negotiations
+	phase    print information on script interruptions
+	======== ========================================================
 
     Use "setdebug" with no argument to reset debug flags.
 
 
 8.6 Clear profile counters
+--------------------------
 
     clearprof
 
@@ -513,7 +570,8 @@ Available commands:
 
 
 8.7 Set flag (no_disc)
- 
+----------------------
+
     setflag <target> <flag>
 
     target:    target number
@@ -523,38 +581,47 @@ Available commands:
         no_disc:   not allow target to disconnect.
 
     Do not specify any flag in order to reset the flag. For example:
-    - setflag 4
+
+    setflag 4
       will reset no_disc flag for target 4, so will allow it disconnections.
-    - setflag all
+
+    setflag all
       will allow disconnection for all devices on the SCSI bus.
 
 
 8.8 Set verbose level
+---------------------
 
     setverbose #level
 
-    The driver default verbose level is 1. This command allows to change 
+    The driver default verbose level is 1. This command allows to change
     th driver verbose level after boot-up.
 
 8.9 Reset all logical units of a target
+---------------------------------------
 
     resetdev <target>
 
-    target:    target number
+    :target:   target number
+
     The driver will try to send a BUS DEVICE RESET message to the target.
     (Only supported by the SYM53C8XX driver and provided for test purpose)
 
 8.10 Abort all tasks of all logical units of a target
+-----------------------------------------------------
 
     cleardev <target>
 
-    target:    target number
-    The driver will try to send a ABORT message to all the logical units 
+    :target:   target number
+
+    The driver will try to send a ABORT message to all the logical units
     of the target.
+
     (Only supported by the SYM53C8XX driver and provided for test purpose)
 
 
 9. Configuration parameters
+===========================
 
 If the firmware of all your devices is perfect enough, all the
 features supported by the driver can be enabled at start-up.  However,
@@ -564,6 +631,7 @@ this feature after boot-up only for devices that support it safely.
 
 CONFIG_SCSI_NCR53C8XX_IOMAPPED       (default answer: n)
     Answer "y" if you suspect your mother board to not allow memory mapped I/O.
+
     May slow down performance a little.  This option is required by
     Linux/PPC and is used no matter what you select here.  Linux/PPC
     suffers no performance loss with this option since all IO is memory
@@ -573,35 +641,37 @@ CONFIG_SCSI_NCR53C8XX_DEFAULT_TAGS    (default answer: 8)
     Default tagged command queue depth.
 
 CONFIG_SCSI_NCR53C8XX_MAX_TAGS         (default answer: 8)
-    This option allows you to specify the maximum number of tagged commands 
+    This option allows you to specify the maximum number of tagged commands
     that can be queued to a device. The maximum supported value is 32.
 
 CONFIG_SCSI_NCR53C8XX_SYNC            (default answer: 5)
-    This option allows you to specify the frequency in MHz the driver 
+    This option allows you to specify the frequency in MHz the driver
     will use at boot time for synchronous data transfer negotiations.
     This frequency can be changed later with the "setsync" control command.
     0 means "asynchronous data transfers".
 
 CONFIG_SCSI_NCR53C8XX_FORCE_SYNC_NEGO (default answer: n)
     Force synchronous negotiation for all SCSI-2 devices.
-    Some SCSI-2 devices do not report this feature in byte 7 of inquiry 
+
+    Some SCSI-2 devices do not report this feature in byte 7 of inquiry
     response but do support it properly (TAMARACK scanners for example).
 
 CONFIG_SCSI_NCR53C8XX_NO_DISCONNECT   (default and only reasonable answer: n)
     If you suspect a device of yours does not properly support disconnections,
-    you can answer "y". Then, all SCSI devices will never disconnect the bus 
+    you can answer "y". Then, all SCSI devices will never disconnect the bus
     even while performing long SCSI operations.
 
 CONFIG_SCSI_NCR53C8XX_SYMBIOS_COMPAT
-    Genuine SYMBIOS boards use GPIO0 in output for controller LED and GPIO3 
+    Genuine SYMBIOS boards use GPIO0 in output for controller LED and GPIO3
     bit as a flag indicating singled-ended/differential interface.
     If all the boards of your system are genuine SYMBIOS boards or use
     BIOS and drivers from SYMBIOS, you would want to enable this option.
-    This option must NOT be enabled if your system has at least one 53C8XX 
+
+    This option must NOT be enabled if your system has at least one 53C8XX
     based scsi board with a vendor-specific BIOS.
-    For example, Tekram DC-390/U, DC-390/W and DC-390/F scsi controllers 
-    use a vendor-specific BIOS and are known to not use SYMBIOS compatible 
-    GPIO wiring. So, this option must not be enabled if your system has 
+    For example, Tekram DC-390/U, DC-390/W and DC-390/F scsi controllers
+    use a vendor-specific BIOS and are known to not use SYMBIOS compatible
+    GPIO wiring. So, this option must not be enabled if your system has
     such a board installed.
 
 CONFIG_SCSI_NCR53C8XX_NVRAM_DETECT
@@ -610,7 +680,7 @@ CONFIG_SCSI_NCR53C8XX_NVRAM_DETECT
     systems with more than one Symbios compatible controller where at least
     one has a serial NVRAM, or for a system with a mixture of Symbios and
     Tekram cards. Enables setting the boot order of host adaptors
-    to something other than the default order or "reverse probe" order. 
+    to something other than the default order or "reverse probe" order.
     Also enables Symbios and Tekram cards to be distinguished so
     CONFIG_SCSI_NCR53C8XX_SYMBIOS_COMPAT may be set in a system with a
     mixture of Symbios and Tekram cards so the Symbios cards can make use of
@@ -618,243 +688,364 @@ CONFIG_SCSI_NCR53C8XX_NVRAM_DETECT
     causing problems for the Tekram card(s).
 
 10. Boot setup commands
+=======================
 
 10.1 Syntax
+-----------
 
-Setup commands can be passed to the driver either at boot time or as a 
+Setup commands can be passed to the driver either at boot time or as a
 string variable using 'insmod'.
 
-A boot setup command for the ncr53c8xx (sym53c8xx) driver begins with the 
-driver name "ncr53c8xx="(sym53c8xx). The kernel syntax parser then expects 
-an optional list of integers separated with comma followed by an optional 
-list of comma-separated strings. Example of boot setup command under lilo 
-prompt:
+A boot setup command for the ncr53c8xx (sym53c8xx) driver begins with the
+driver name "ncr53c8xx="(sym53c8xx). The kernel syntax parser then expects
+an optional list of integers separated with comma followed by an optional
+list of comma-separated strings. Example of boot setup command under lilo
+prompt::
 
-lilo: linux root=/dev/hda2 ncr53c8xx=tags:4,sync:10,debug:0x200
+    lilo: linux root=/dev/hda2 ncr53c8xx=tags:4,sync:10,debug:0x200
 
 - enable tagged commands, up to 4 tagged commands queued.
 - set synchronous negotiation speed to 10 Mega-transfers / second.
 - set DEBUG_NEGO flag.
 
-Since comma seems not to be allowed when defining a string variable using  
-'insmod', the driver also accepts <space> as option separator. 
-The following command will install driver module with the same options as 
-above.
+Since comma seems not to be allowed when defining a string variable using
+'insmod', the driver also accepts <space> as option separator.
+The following command will install driver module with the same options as
+above::
 
     insmod ncr53c8xx.o ncr53c8xx="tags:4 sync:10 debug:0x200"
 
-For the moment, the integer list of arguments is discarded by the driver. 
+For the moment, the integer list of arguments is discarded by the driver.
 It will be used in the future in order to allow a per controller setup.
 
-Each string argument must be specified as "keyword:value". Only lower-case 
+Each string argument must be specified as "keyword:value". Only lower-case
 characters and digits are allowed.
 
-In a system that contains multiple 53C8xx adapters insmod will install the 
+In a system that contains multiple 53C8xx adapters insmod will install the
 specified driver on each adapter. To exclude a chip use the 'excl' keyword.
 
-The sequence of commands, 
+The sequence of commands::
 
     insmod sym53c8xx sym53c8xx=excl:0x1400
     insmod ncr53c8xx
 
-installs the sym53c8xx driver on all adapters except the one at IO port 
-address 0x1400 and then installs the ncr53c8xx driver to the adapter at IO 
+installs the sym53c8xx driver on all adapters except the one at IO port
+address 0x1400 and then installs the ncr53c8xx driver to the adapter at IO
 port address 0x1400.
 
 
 10.2 Available arguments
+------------------------
 
 10.2.1  Master parity checking
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	======     ========
         mpar:y     enabled
         mpar:n     disabled
+	======     ========
 
 10.2.2  Scsi parity checking
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	======     ========
         spar:y     enabled
         spar:n     disabled
+	======     ========
 
 10.2.3  Scsi disconnections
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	======     ========
         disc:y     enabled
         disc:n     disabled
- 
+	======     ========
+
 10.2.4  Special features
+^^^^^^^^^^^^^^^^^^^^^^^^
+
    Only apply to 810A, 825A, 860, 875 and 895 controllers.
    Have no effect with other ones.
+
+	=======    =================================================
         specf:y    (or 1) enabled
         specf:n    (or 0) disabled
         specf:3           enabled except Memory Write And Invalidate
-   The default driver setup is 'specf:3'. As a consequence, option 'specf:y' 
-   must be specified in the boot setup command to enable Memory Write And 
+	=======    =================================================
+
+   The default driver setup is 'specf:3'. As a consequence, option 'specf:y'
+   must be specified in the boot setup command to enable Memory Write And
    Invalidate.
 
 10.2.5  Ultra SCSI support
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
    Only apply to 860, 875, 895, 895a, 896, 1010 and 1010_66 controllers.
    Have no effect with other ones.
+
+	=======    ========================
         ultra:n    All ultra speeds enabled
         ultra:2    Ultra2 enabled
         ultra:1    Ultra enabled
         ultra:0    Ultra speeds disabled
+	=======    ========================
 
 10.2.6  Default number of tagged commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	======================= ===============================
         tags:0     (or tags:1 ) tagged command queuing disabled
         tags:#tags (#tags  > 1) tagged command queuing enabled
+	======================= ===============================
+
   #tags will be truncated to the max queued commands configuration parameter.
-  This option also allows to specify a command queue depth for each device 
+  This option also allows to specify a command queue depth for each device
   that support tagged command queueing.
-  Example:
+
+  Example::
+
       ncr53c8xx=tags:10/t2t3q16-t5q24/t1u2q32
-               will set devices queue depth as follow:
+
+  will set devices queue depth as follow:
+
       - controller #0 target #2 and target #3                  -> 16 commands,
       - controller #0 target #5                                -> 24 commands,
       - controller #1 target #1 logical unit #2                -> 32 commands,
       - all other logical units (all targets, all controllers) -> 10 commands.
 
 10.2.7  Default synchronous period factor
-        sync:255     disabled (asynchronous transfer mode)
-        sync:#factor
-  #factor = 10     Ultra-2 SCSI 40 Mega-transfers / second
-  #factor = 11     Ultra-2 SCSI 33 Mega-transfers / second
-  #factor < 25     Ultra   SCSI 20 Mega-transfers / second
-  #factor < 50     Fast    SCSI-2
-
-  In all cases, the driver will use the minimum transfer period supported by 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+============ ========================================================
+sync:255     disabled (asynchronous transfer mode)
+sync:#factor
+	     ============     =======================================
+	     #factor = 10     Ultra-2 SCSI 40 Mega-transfers / second
+	     #factor = 11     Ultra-2 SCSI 33 Mega-transfers / second
+	     #factor < 25     Ultra   SCSI 20 Mega-transfers / second
+	     #factor < 50     Fast    SCSI-2
+	     ============     =======================================
+============ ========================================================
+
+  In all cases, the driver will use the minimum transfer period supported by
   controllers according to NCR53C8XX chip type.
 
 10.2.8  Negotiate synchronous with all devices
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         (force sync nego)
+
+        =====      =========
         fsn:y      enabled
         fsn:n      disabled
+        =====      =========
 
 10.2.9  Verbosity level
+^^^^^^^^^^^^^^^^^^^^^^^
+
+        ======     =========
         verb:0     minimal
         verb:1     normal
         verb:2     too much
+        ======     =========
 
 10.2.10 Debug mode
-        debug:0	 clear debug flags
-        debug:#x   set debug flags
-  #x is an integer value combining the following power-of-2 values:
-  DEBUG_ALLOC       0x1
-  DEBUG_PHASE       0x2
-  DEBUG_POLL        0x4
-  DEBUG_QUEUE       0x8
-  DEBUG_RESULT     0x10
-  DEBUG_SCATTER    0x20
-  DEBUG_SCRIPT     0x40
-  DEBUG_TINY       0x80
-  DEBUG_TIMING    0x100
-  DEBUG_NEGO      0x200
-  DEBUG_TAGS      0x400
-  DEBUG_FREEZE    0x800
-  DEBUG_RESTART  0x1000
-
-  You can play safely with DEBUG_NEGO. However, some of these flags may 
-  generate bunches of syslog messages. 
+^^^^^^^^^^^^^^^^^^
+
+========   ==================================================================
+debug:0    clear debug flags
+debug:#x   set debug flags
+
+	    #x is an integer value combining the following power-of-2 values:
+
+	    =============  ======
+	    DEBUG_ALLOC       0x1
+	    DEBUG_PHASE       0x2
+	    DEBUG_POLL        0x4
+	    DEBUG_QUEUE       0x8
+	    DEBUG_RESULT     0x10
+	    DEBUG_SCATTER    0x20
+	    DEBUG_SCRIPT     0x40
+	    DEBUG_TINY       0x80
+	    DEBUG_TIMING    0x100
+	    DEBUG_NEGO      0x200
+	    DEBUG_TAGS      0x400
+	    DEBUG_FREEZE    0x800
+	    DEBUG_RESTART  0x1000
+	    =============  ======
+========   ==================================================================
+
+  You can play safely with DEBUG_NEGO. However, some of these flags may
+  generate bunches of syslog messages.
 
 10.2.11 Burst max
-        burst:0    burst disabled
-        burst:255  get burst length from initial IO register settings.
-        burst:#x   burst enabled (1<<#x burst transfers max)
-  #x is an integer value which is log base 2 of the burst transfers max.
-  The NCR53C875 and NCR53C825A support up to 128 burst transfers (#x = 7).
-  Other chips only support up to 16 (#x = 4).
-  This is a maximum value. The driver set the burst length according to chip 
-  and revision ids. By default the driver uses the maximum value supported 
-  by the chip.
+^^^^^^^^^^^^^^^^^
+
+=========  ==================================================================
+burst:0    burst disabled
+burst:255  get burst length from initial IO register settings.
+burst:#x   burst enabled (1<<#x burst transfers max)
+
+	   #x is an integer value which is log base 2 of the burst transfers
+	   max.
+
+	   The NCR53C875 and NCR53C825A support up to 128 burst transfers
+	   (#x = 7).
+
+	   Other chips only support up to 16 (#x = 4).
+
+	   This is a maximum value. The driver set the burst length according
+	   to chip and revision ids. By default the driver uses the maximum
+	   value supported by the chip.
+=========  ==================================================================
 
 10.2.12 LED support
+^^^^^^^^^^^^^^^^^^^
+
+        =====      ===================
         led:1      enable  LED support
         led:0      disable LED support
+        =====      ===================
+
   Donnot enable LED support if your scsi board does not use SDMS BIOS.
   (See 'Configuration parameters')
 
 10.2.13 Max wide
+^^^^^^^^^^^^^^^^
+
+        ======     ===================
         wide:1      wide scsi enabled
         wide:0      wide scsi disabled
+        ======     ===================
+
   Some scsi boards use a 875 (ultra wide) and only supply narrow connectors.
-  If you have connected a wide device with a 50 pins to 68 pins cable 
+  If you have connected a wide device with a 50 pins to 68 pins cable
   converter, any accepted wide negotiation will break further data transfers.
-  In such a case, using "wide:0" in the bootup command will be helpful. 
+  In such a case, using "wide:0" in the bootup command will be helpful.
 
 10.2.14 Differential mode
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	======	=================================
         diff:0	never set up diff mode
         diff:1	set up diff mode if BIOS set it
         diff:2	always set up diff mode
         diff:3	set diff mode if GPIO3 is not set
+	======	=================================
 
 10.2.15 IRQ mode
+^^^^^^^^^^^^^^^^
+
+	=========  ========================================================
         irqm:0     always open drain
         irqm:1     same as initial settings (assumed BIOS settings)
         irqm:2     always totem pole
         irqm:0x10  driver will not use IRQF_SHARED flag when requesting irq
+	=========  ========================================================
 
     (Bits 0x10 and 0x20 can be combined with hardware irq mode option)
 
 10.2.16 Reverse probe
+^^^^^^^^^^^^^^^^^^^^^
+
+	=========   ========================================================
         revprob:n   probe chip ids from the PCI configuration in this order:
                     810, 815, 820, 860, 875, 885, 895, 896
         revprob:y   probe chip ids in the reverse order.
+	=========   ========================================================
 
 10.2.17 Fix up PCI configuration space
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         pcifix:<option bits>
 
     Available option bits:
-        0x0:   No attempt to fix PCI configuration space registers values.
-        0x1:   Set PCI cache-line size register if not set.
-        0x2:   Set write and invalidate bit in PCI command register.
-        0x4:   Increase if necessary PCI latency timer according to burst max.
+
+	===    ===============================================================
+        0x0    No attempt to fix PCI configuration space registers values.
+        0x1    Set PCI cache-line size register if not set.
+        0x2    Set write and invalidate bit in PCI command register.
+        0x4    Increase if necessary PCI latency timer according to burst max.
+	===    ===============================================================
 
     Use 'pcifix:7' in order to allow the driver to fix up all PCI features.
 
 10.2.18 Serial NVRAM
+^^^^^^^^^^^^^^^^^^^^
+
+	=======     =========================================
         nvram:n     do not look for serial NVRAM
         nvram:y     test controllers for onboard serial NVRAM
+	=======     =========================================
+
         (alternate binary form)
         mvram=<bits options>
+
+        ====   =================================================================
         0x01   look for NVRAM  (equivalent to nvram=y)
         0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
         0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
         0x08   ignore NVRAM "Scan at boot time" parameter for all devices
         0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)
+        ====   =================================================================
+
+10.2.19 Check SCSI BUS
+^^^^^^^^^^^^^^^^^^^^^^
 
-10.2.19 Check SCSI BUS 
         buschk:<option bits>
 
     Available option bits:
+
+        ====   ================================================
         0x0:   No check.
-        0x1:   Check and do not attach the controller on error.  
+        0x1:   Check and do not attach the controller on error.
         0x2:   Check and just warn on error.
         0x4:   Disable SCSI bus integrity checking.
+        ====   ================================================
 
 10.2.20 Exclude a host from being attached
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
         excl=<io_address>
 
     Prevent host at a given io address from being attached.
-    For example 'ncr53c8xx=excl:0xb400,excl:0xc000' indicate to the 
+    For example 'ncr53c8xx=excl:0xb400,excl:0xc000' indicate to the
     ncr53c8xx driver not to attach hosts at address 0xb400 and 0xc000.
 
 10.2.21 Suggest a default SCSI id for hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	==========	==========================================
         hostid:255	no id suggested.
-        hostid:#x   (0 < x < 7) x suggested for hosts SCSI id.
+        hostid:#x	(0 < x < 7) x suggested for hosts SCSI id.
+	==========	==========================================
 
-    If a host SCSI id is available from the NVRAM, the driver will ignore 
-    any value suggested as boot option. Otherwise, if a suggested value 
-    different from 255 has been supplied, it will use it. Otherwise, it will 
-    try to deduce the value previously set in the hardware and use value 
+    If a host SCSI id is available from the NVRAM, the driver will ignore
+    any value suggested as boot option. Otherwise, if a suggested value
+    different from 255 has been supplied, it will use it. Otherwise, it will
+    try to deduce the value previously set in the hardware and use value
     7 if the hardware value is zero.
 
 10.2.22 Enable use of IMMEDIATE ARBITRATION
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
         (only supported by the sym53c8xx driver. See 10.7 for more details)
-        iarb:0    do not use this feature.
-        iarb:#x   use this feature according to bit fields as follow:
 
-    bit 0 (1) : enable IARB each time the initiator has been reselected 
-                when it arbitrated for the SCSI BUS.
-    (#x >> 4) : maximum number of successive settings of IARB if the initiator 
-                win arbitration and it has other commands to send to a device.
+=======   =================================================================
+iarb:0    do not use this feature.
+iarb:#x   use this feature according to bit fields as follow:
+
+	  ========= =======================================================
+	  bit 0 (1) enable IARB each time the initiator has been reselected
+		    when it arbitrated for the SCSI BUS.
+	  (#x >> 4) maximum number of successive settings of IARB if the
+		    initiator win arbitration and it has other commands
+		    to send to a device.
+	  ========= =======================================================
+=======   =================================================================
 
 Boot fail safe
     safe:y	load the following assumed fail safe initial setup
 
+  ========================	======================	==========
   master parity			disabled		mpar:n
   scsi parity			enabled			spar:y
   disconnections		not allowed		disc:n
@@ -876,189 +1067,222 @@ Boot fail safe
   irq mode			from BIOS settings	irqm:1
   SCSI BUS check		do not attach on error	buschk:1
   immediate arbitration		disabled		iarb:0
+  ========================	======================	==========
 
 10.3 Advised boot setup commands
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If the driver has been configured with default options, the equivalent 
-boot setup is:
+If the driver has been configured with default options, the equivalent
+boot setup is::
 
    ncr53c8xx=mpar:y,spar:y,disc:y,specf:3,fsn:n,ultra:2,fsn:n,revprob:n,verb:1\
              tags:0,sync:50,debug:0,burst:7,led:0,wide:1,settle:2,diff:0,irqm:0
 
 For an installation diskette or a safe but not fast system,
-boot setup can be:
+boot setup can be::
 
     ncr53c8xx=safe:y,mpar:y,disc:y
     ncr53c8xx=safe:y,disc:y
     ncr53c8xx=safe:y,mpar:y
     ncr53c8xx=safe:y
 
-My personal system works flawlessly with the following equivalent setup:
+My personal system works flawlessly with the following equivalent setup::
 
    ncr53c8xx=mpar:y,spar:y,disc:y,specf:1,fsn:n,ultra:2,fsn:n,revprob:n,verb:1\
              tags:32,sync:12,debug:0,burst:7,led:1,wide:1,settle:2,diff:0,irqm:0
 
-The driver prints its actual setup when verbosity level is 2. You can try 
-"ncr53c8xx=verb:2" to get the "static" setup of the driver, or add "verb:2" 
-to your boot setup command in order to check the actual setup the driver is 
+The driver prints its actual setup when verbosity level is 2. You can try
+"ncr53c8xx=verb:2" to get the "static" setup of the driver, or add "verb:2"
+to your boot setup command in order to check the actual setup the driver is
 using.
 
 10.4 PCI configuration fix-up boot option
+-----------------------------------------
 
 pcifix:<option bits>
 
 Available option bits:
-    0x1:     Set PCI cache-line size register if not set.
-    0x2:     Set write and invalidate bit in PCI command register.
+
+    ===      =====================================================
+    0x1      Set PCI cache-line size register if not set.
+    0x2      Set write and invalidate bit in PCI command register.
+    ===      =====================================================
 
 Use 'pcifix:3' in order to allow the driver to fix both PCI features.
 
-These options only apply to new SYMBIOS chips 810A, 825A, 860, 875 
+These options only apply to new SYMBIOS chips 810A, 825A, 860, 875
 and 895 and are only supported for Pentium and 486 class processors.
-Recent SYMBIOS 53C8XX scsi processors are able to use PCI read multiple 
-and PCI write and invalidate commands. These features require the 
-cache line size register to be properly set in the PCI configuration 
-space of the chips. On the other hand, chips will use PCI write and 
-invalidate commands only if the corresponding bit is set to 1 in the 
+Recent SYMBIOS 53C8XX scsi processors are able to use PCI read multiple
+and PCI write and invalidate commands. These features require the
+cache line size register to be properly set in the PCI configuration
+space of the chips. On the other hand, chips will use PCI write and
+invalidate commands only if the corresponding bit is set to 1 in the
 PCI command register.
 
-Not all PCI bioses set the PCI cache line register and the PCI write and 
+Not all PCI bioses set the PCI cache line register and the PCI write and
 invalidate bit in the PCI configuration space of 53C8XX chips.
-Optimized PCI accesses may be broken for some PCI/memory controllers or 
+Optimized PCI accesses may be broken for some PCI/memory controllers or
 make problems with some PCI boards.
 
 This fix-up worked flawlessly on my previous system.
 (MB Triton HX / 53C875 / 53C810A)
-I use these options at my own risks as you will do if you decide to 
+I use these options at my own risks as you will do if you decide to
 use them too.
 
 
 10.5 Serial NVRAM support boot option
+-------------------------------------
 
+=======     =========================================
 nvram:n     do not look for serial NVRAM
 nvram:y     test controllers for onboard serial NVRAM
+=======     =========================================
 
-This option can also been entered as an hexadecimal value that allows 
-to control what information the driver will get from the NVRAM and what 
+This option can also been entered as an hexadecimal value that allows
+to control what information the driver will get from the NVRAM and what
 information it will ignore.
 For details see '17. Serial NVRAM support'.
 
-When this option is enabled, the driver tries to detect all boards using 
+When this option is enabled, the driver tries to detect all boards using
 a Serial NVRAM. This memory is used to hold user set up parameters.
 
-The parameters the driver is able to get from the NVRAM depend on the 
+The parameters the driver is able to get from the NVRAM depend on the
 data format used, as follow:
 
-                                 Tekram format      Symbios format
-General and host parameters
-    Boot order                         N                   Y
-    Host SCSI ID                       Y                   Y
-    SCSI parity checking               Y                   Y
-    Verbose boot messages              N                   Y
-SCSI devices parameters
-    Synchronous transfer speed         Y                   Y
-    Wide 16 / Narrow                   Y                   Y
-    Tagged Command Queuing enabled     Y                   Y
-    Disconnections enabled             Y                   Y
-    Scan at boot time                  N                   Y
-
-In order to speed up the system boot, for each device configured without 
-the "scan at boot time" option, the driver forces an error on the 
++-------------------------------+------------------+--------------+
+|                               |Tekram format     |Symbios format|
++-------------------------------+------------------+--------------+
+|General and host parameters    |                  |              |
++-------------------------------+------------------+--------------+
+|  * Boot order                 |        N         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Host SCSI ID               |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * SCSI parity checking       |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Verbose boot messages      |        N         |       Y      |
++-------------------------------+------------------+--------------+
+|SCSI devices parameters                                          |
++-------------------------------+------------------+--------------+
+|  * Synchronous transfer speed |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Wide 16 / Narrow           |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Tagged Command Queuing     |        Y         |       Y      |
+|    enabled                    |                  |              |
++-------------------------------+------------------+--------------+
+|  * Disconnections enabled     |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Scan at boot time          |        N         |       Y      |
++-------------------------------+------------------+--------------+
+
+In order to speed up the system boot, for each device configured without
+the "scan at boot time" option, the driver forces an error on the
 first TEST UNIT READY command received for this device.
 
-Some SDMS BIOS revisions seem to be unable to boot cleanly with very fast 
-hard disks. In such a situation you cannot configure the NVRAM with 
+Some SDMS BIOS revisions seem to be unable to boot cleanly with very fast
+hard disks. In such a situation you cannot configure the NVRAM with
 optimized parameters value.
 
-The 'nvram' boot option can be entered in hexadecimal form in order 
+The 'nvram' boot option can be entered in hexadecimal form in order
 to ignore some options configured in the NVRAM, as follow:
 
 mvram=<bits options>
+
+      ====   =================================================================
       0x01   look for NVRAM  (equivalent to nvram=y)
       0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
       0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
       0x08   ignore NVRAM "Scan at boot time" parameter for all devices
       0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)
+      ====   =================================================================
 
-Option 0x80 is only supported by the sym53c8xx driver and is disabled by 
-default. Result is that, by default (option not set), the sym53c8xx driver 
+Option 0x80 is only supported by the sym53c8xx driver and is disabled by
+default. Result is that, by default (option not set), the sym53c8xx driver
 will not attach controllers set to OFF in the NVRAM.
 
-The ncr53c8xx always tries to attach all the controllers. Option 0x80 has 
-not been added to the ncr53c8xx driver, since it has been reported to 
-confuse users who use this driver since a long time. If you desire a 
-controller not to be attached by the ncr53c8xx driver at Linux boot, you 
+The ncr53c8xx always tries to attach all the controllers. Option 0x80 has
+not been added to the ncr53c8xx driver, since it has been reported to
+confuse users who use this driver since a long time. If you desire a
+controller not to be attached by the ncr53c8xx driver at Linux boot, you
 must use the 'excl' driver boot option.
 
 10.6 SCSI BUS checking boot option.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-When this option is set to a non-zero value, the driver checks SCSI lines 
+When this option is set to a non-zero value, the driver checks SCSI lines
 logic state, 100 micro-seconds after having asserted the SCSI RESET line.
 The driver just reads SCSI lines and checks all lines read FALSE except RESET.
-Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI 
+Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI
 RESET has been asserted, any signal to TRUE may indicate a SCSI BUS problem.
 Unfortunately, the following common SCSI BUS problems are not detected:
+
 - Only 1 terminator installed.
 - Misplaced terminators.
 - Bad quality terminators.
-On the other hand, either bad cabling, broken devices, not conformant 
+
+On the other hand, either bad cabling, broken devices, not conformant
 devices, ... may cause a SCSI signal to be wrong when te driver reads it.
 
 10.7 IMMEDIATE ARBITRATION boot option
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This option is only supported by the SYM53C8XX driver (not by the NCR53C8XX).
 
-SYMBIOS 53C8XX chips are able to arbitrate for the SCSI BUS as soon as they 
-have detected an expected disconnection (BUS FREE PHASE). For this process 
-to be started, bit 1 of SCNTL1 IO register must be set when the chip is 
+SYMBIOS 53C8XX chips are able to arbitrate for the SCSI BUS as soon as they
+have detected an expected disconnection (BUS FREE PHASE). For this process
+to be started, bit 1 of SCNTL1 IO register must be set when the chip is
 connected to the SCSI BUS.
 
-When this feature has been enabled for the current connection, the chip has 
-every chance to win arbitration if only devices with lower priority are 
-competing for the SCSI BUS. By the way, when the chip is using SCSI id 7, 
+When this feature has been enabled for the current connection, the chip has
+every chance to win arbitration if only devices with lower priority are
+competing for the SCSI BUS. By the way, when the chip is using SCSI id 7,
 then it will for sure win the next SCSI BUS arbitration.
 
-Since, there is no way to know what devices are trying to arbitrate for the 
+Since, there is no way to know what devices are trying to arbitrate for the
 BUS, using this feature can be extremely unfair. So, you are not advised
-to enable it, or at most enable this feature for the case the chip lost 
+to enable it, or at most enable this feature for the case the chip lost
 the previous arbitration (boot option 'iarb:1').
 
 This feature has the following advantages:
 
 a) Allow the initiator with ID 7 to win arbitration when it wants so.
-b) Overlap at least 4 micro-seconds of arbitration time with the execution 
-   of SCRIPTS that deal with the end of the current connection and that 
+b) Overlap at least 4 micro-seconds of arbitration time with the execution
+   of SCRIPTS that deal with the end of the current connection and that
    starts the next job.
 
-Hmmm... But (a) may just prevent other devices from reselecting the initiator, 
-and delay data transfers or status/completions, and (b) may just waste 
+Hmmm... But (a) may just prevent other devices from reselecting the initiator,
+and delay data transfers or status/completions, and (b) may just waste
 SCSI BUS bandwidth if the SCRIPTS execution lasts more than 4 micro-seconds.
 
-The use of IARB needs the SCSI_NCR_IARB_SUPPORT option to have been defined 
-at compile time and the 'iarb' boot option to have been set to a non zero 
-value at boot time. It is not that useful for real work, but can be used 
-to stress SCSI devices or for some applications that can gain advantage of 
-it. By the way, if you experience badnesses like 'unexpected disconnections', 
-'bad reselections', etc... when using IARB on heavy IO load, you should not 
-be surprised, because force-feeding anything and blocking its arse at the 
+The use of IARB needs the SCSI_NCR_IARB_SUPPORT option to have been defined
+at compile time and the 'iarb' boot option to have been set to a non zero
+value at boot time. It is not that useful for real work, but can be used
+to stress SCSI devices or for some applications that can gain advantage of
+it. By the way, if you experience badnesses like 'unexpected disconnections',
+'bad reselections', etc... when using IARB on heavy IO load, you should not
+be surprised, because force-feeding anything and blocking its arse at the
 same time cannot work for a long time. :-))
 
 
 11. Some constants and flags of the ncr53c8xx.h header file
+===========================================================
 
 Some of these are defined from the configuration parameters.  To
 change other "defines", you must edit the header file.  Do that only
 if you know what you are doing.
 
 SCSI_NCR_SETUP_SPECIAL_FEATURES	(default: defined)
-	If defined, the driver will enable some special features according  
+	If defined, the driver will enable some special features according
 	to chip and revision id.
-        For 810A, 860, 825A, 875 and 895 scsi chips, this option enables 
-	support of features that reduce load of PCI bus and memory accesses 
-	during  scsi transfer processing: burst op-code fetch, read multiple, 
-        read line, prefetch, cache line, write and invalidate, 
+
+        For 810A, 860, 825A, 875 and 895 scsi chips, this option enables
+	support of features that reduce load of PCI bus and memory accesses
+	during  scsi transfer processing: burst op-code fetch, read multiple,
+        read line, prefetch, cache line, write and invalidate,
         burst 128 (875 only), large dma fifo (875 only), offset 16 (875 only).
-	Can be changed by the following boot setup command:
+	Can be changed by the following boot setup command::
+
 		ncr53c8xx=specf:n
 
 SCSI_NCR_IOMAPPED		(default: not defined)
@@ -1066,22 +1290,26 @@ SCSI_NCR_IOMAPPED		(default: not defined)
 
 SCSI_NCR_SHARE_IRQ		(default: defined)
 	If defined, request shared IRQ.
-	
+
 SCSI_NCR_MAX_TAGS		(default: 8)
 	Maximum number of simultaneous tagged commands to a device.
+
 	Can be changed by "settags <target> <maxtags>"
 
 SCSI_NCR_SETUP_DEFAULT_SYNC     (default: 50)
-	Transfer period factor the driver will use at boot time for synchronous 
+	Transfer period factor the driver will use at boot time for synchronous
 	negotiation. 0 means asynchronous.
+
 	Can be changed by "setsync <target> <period factor>"
 
 SCSI_NCR_SETUP_DEFAULT_TAGS     (default: 8)
 	Default number of simultaneous tagged commands to a device.
+
 	< 1 means tagged command queuing disabled at start-up.
 
 SCSI_NCR_ALWAYS_SIMPLE_TAG	(default: defined)
 	Use SIMPLE TAG for read and write commands.
+
 	Can be changed by "setorder <ordered|simple|default>"
 
 SCSI_NCR_SETUP_DISCONNECTION	(default: defined)
@@ -1089,6 +1317,7 @@ SCSI_NCR_SETUP_DISCONNECTION	(default: defined)
 
 SCSI_NCR_SETUP_FORCE_SYNC_NEGO	(default: not defined)
 	If defined, synchronous negotiation is tried for all SCSI-2 devices.
+
 	Can be changed by "setsync <target> <period>"
 
 SCSI_NCR_SETUP_MASTER_PARITY	(default: defined)
@@ -1115,6 +1344,7 @@ SCSI_NCR_SETTLE_TIME		(default: 2)
 SCSI_NCR_TIMEOUT_ALERT		(default: 3)
 	If a pending command will time out after this amount of seconds,
 	an ordered tag is used for the next command.
+
 	Avoids timeouts for unordered tagged commands.
 
 SCSI_NCR_CAN_QUEUE		(default: 7*SCSI_NCR_MAX_TAGS)
@@ -1131,34 +1361,38 @@ SCSI_NCR_MAX_LUN	(default: 8)
 
 
 12. Installation
+================
 
 This driver is part of the linux kernel distribution.
-Driver files are located in the sub-directory "drivers/scsi" of the 
+Driver files are located in the sub-directory "drivers/scsi" of the
 kernel source tree.
 
-Driver files:
+Driver files::
 
 	README.ncr53c8xx	: this file
 	ChangeLog.ncr53c8xx	: change log
 	ncr53c8xx.h		: definitions
 	ncr53c8xx.c		: the driver code
 
-New driver versions are made available separately in order to allow testing 
-changes and new features prior to including them into the linux kernel 
-distribution. The following URL provides information on latest available 
-patches: 
+New driver versions are made available separately in order to allow testing
+changes and new features prior to including them into the linux kernel
+distribution. The following URL provides information on latest available
+patches:
 
       ftp://ftp.tux.org/pub/people/gerard-roudier/README
 
 
-13. Architecture dependent features.
+13. Architecture dependent features
+===================================
 
 <Not yet written>
 
 
 14. Known problems
+==================
 
 14.1 Tagged commands with Iomega Jaz device
+-------------------------------------------
 
 I have not tried this device, however it has been reported to me the
 following: This device is capable of Tagged command queuing. However
@@ -1170,14 +1404,15 @@ other problem that may appear is timeouts. The only way to avoid
 timeouts seems to edit linux/drivers/scsi/sd.c and to increase the
 current timeout values.
 
-14.2 Device names change when another controller is added.
+14.2 Device names change when another controller is added
+---------------------------------------------------------
 
-When you add a new NCR53C8XX chip based controller to a system that already 
-has one or more controllers of this family, it may happen that the order 
-the driver registers them to the kernel causes problems due to device 
+When you add a new NCR53C8XX chip based controller to a system that already
+has one or more controllers of this family, it may happen that the order
+the driver registers them to the kernel causes problems due to device
 name changes.
-When at least one controller uses NvRAM, SDMS BIOS version 4 allows you to 
-define the order the BIOS will scan the scsi boards. The driver attaches 
+When at least one controller uses NvRAM, SDMS BIOS version 4 allows you to
+define the order the BIOS will scan the scsi boards. The driver attaches
 controllers according to BIOS information if NvRAM detect option is set.
 
 If your controllers do not have NvRAM, you can:
@@ -1187,52 +1422,58 @@ If your controllers do not have NvRAM, you can:
 - Make appropriate changes in the fstab.
 - Use the 'scsidev' tool from Eric Youngdale.
 
-14.3 Using only 8 bit devices with a WIDE SCSI controller.
+14.3 Using only 8 bit devices with a WIDE SCSI controller
+---------------------------------------------------------
 
-When only 8 bit NARROW devices are connected to a 16 bit WIDE SCSI controller, 
+When only 8 bit NARROW devices are connected to a 16 bit WIDE SCSI controller,
 you must ensure that lines of the wide part of the SCSI BUS are pulled-up.
-This can be achieved by ENABLING the WIDE TERMINATOR portion of the SCSI 
+This can be achieved by ENABLING the WIDE TERMINATOR portion of the SCSI
 controller card.
+
 The TYAN 1365 documentation revision 1.2 is not correct about such settings.
 (page 10, figure 3.3).
 
 14.4 Possible data corruption during a Memory Write and Invalidate
+------------------------------------------------------------------
 
 This problem is described in SYMBIOS DEL 397, Part Number 69-039241, ITEM 4.
 
-In some complex situations, 53C875 chips revision <= 3 may start a PCI 
+In some complex situations, 53C875 chips revision <= 3 may start a PCI
 Write and Invalidate Command at a not cache-line-aligned 4 DWORDS boundary.
 This is only possible when Cache Line Size is 8 DWORDS or greater.
-Pentium systems use a 8 DWORDS cache line size and so are concerned by 
+Pentium systems use a 8 DWORDS cache line size and so are concerned by
 this chip bug, unlike i486 systems that use a 4 DWORDS cache line size.
 
-When this situation occurs, the chip may complete the Write and Invalidate 
-command after having only filled part of the last cache line involved in 
+When this situation occurs, the chip may complete the Write and Invalidate
+command after having only filled part of the last cache line involved in
 the transfer, leaving to data corruption the remainder of this cache line.
 
-Not using Write And Invalidate obviously gets rid of this chip bug, and so 
+Not using Write And Invalidate obviously gets rid of this chip bug, and so
 it is now the default setting of the driver.
-However, for people like me who want to enable this feature, I have added 
-part of a work-around suggested by SYMBIOS. This work-around resets the 
-addressing logic when the DATA IN phase is entered and so prevents the bug 
-from being triggered for the first SCSI MOVE of the phase. This work-around 
+However, for people like me who want to enable this feature, I have added
+part of a work-around suggested by SYMBIOS. This work-around resets the
+addressing logic when the DATA IN phase is entered and so prevents the bug
+from being triggered for the first SCSI MOVE of the phase. This work-around
 should be enough according to the following:
 
-The only driver internal data structure that is greater than 8 DWORDS  and 
-that is moved by the SCRIPTS processor is the 'CCB header' that contains 
-the context of the SCSI transfer. This data structure is aligned on 8 DWORDS 
-boundary (Pentium Cache Line Size), and so is immune to this chip bug, at 
+The only driver internal data structure that is greater than 8 DWORDS  and
+that is moved by the SCRIPTS processor is the 'CCB header' that contains
+the context of the SCSI transfer. This data structure is aligned on 8 DWORDS
+boundary (Pentium Cache Line Size), and so is immune to this chip bug, at
 least on Pentium systems.
-But the conditions of this bug can be met when a SCSI read command is 
+
+But the conditions of this bug can be met when a SCSI read command is
 performed using a buffer that is 4 DWORDS but not cache-line aligned.
-This cannot happen under Linux when scatter/gather lists are used since 
-they only refer to system buffers that are well aligned. So, a work around 
-may only be needed under Linux when a scatter/gather list is not used and 
+This cannot happen under Linux when scatter/gather lists are used since
+they only refer to system buffers that are well aligned. So, a work around
+may only be needed under Linux when a scatter/gather list is not used and
 when the SCSI DATA IN phase is reentered after a phase mismatch.
 
 15. SCSI problem troubleshooting
+================================
 
 15.1 Problem tracking
+---------------------
 
 Most SCSI problems are due to a non conformant SCSI bus or to buggy
 devices.  If unfortunately you have SCSI problems, you can check the
@@ -1267,193 +1508,286 @@ tagged commands queuing.
 
 Try to enable one feature at a time with control commands.  For example:
 
-- echo "setsync all 25" >/proc/scsi/ncr53c8xx/0
-  Will enable fast synchronous data transfer negotiation for all targets.
+::
+
+    echo "setsync all 25" >/proc/scsi/ncr53c8xx/0
+
+Will enable fast synchronous data transfer negotiation for all targets.
+
+::
 
-- echo "setflag 3" >/proc/scsi/ncr53c8xx/0
-  Will reset flags (no_disc) for target 3, and so will allow it to disconnect 
-  the SCSI Bus.
+    echo "setflag 3" >/proc/scsi/ncr53c8xx/0
 
-- echo "settags 3 8" >/proc/scsi/ncr53c8xx/0
-  Will enable tagged command queuing for target 3 if that device supports it.
+Will reset flags (no_disc) for target 3, and so will allow it to disconnect
+the SCSI Bus.
 
-Once you have found the device and the feature that cause problems, just 
+::
+
+    echo "settags 3 8" >/proc/scsi/ncr53c8xx/0
+
+Will enable tagged command queuing for target 3 if that device supports it.
+
+Once you have found the device and the feature that cause problems, just
 disable that feature for that device.
 
 15.2 Understanding hardware error reports
+-----------------------------------------
 
-When the driver detects an unexpected error condition, it may display a 
-message of the following pattern.
+When the driver detects an unexpected error condition, it may display a
+message of the following pattern::
 
-sym53c876-0:1: ERROR (0:48) (1-21-65) (f/95) @ (script 7c0:19000000).
-sym53c876-0: script cmd = 19000000
-sym53c876-0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.
+    sym53c876-0:1: ERROR (0:48) (1-21-65) (f/95) @ (script 7c0:19000000).
+    sym53c876-0: script cmd = 19000000
+    sym53c876-0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.
 
-Some fields in such a message may help you understand the cause of the 
-problem, as follows:
+Some fields in such a message may help you understand the cause of the
+problem, as follows::
 
-sym53c876-0:1: ERROR (0:48) (1-21-65) (f/95) @ (script 7c0:19000000).
-............A.........B.C....D.E..F....G.H.......I.....J...K.......
+    sym53c876-0:1: ERROR (0:48) (1-21-65) (f/95) @ (script 7c0:19000000).
+    ............A.........B.C....D.E..F....G.H.......I.....J...K.......
 
 Field A : target number.
-  SCSI ID of the device the controller was talking with at the moment the 
+  SCSI ID of the device the controller was talking with at the moment the
   error occurs.
 
 Field B : DSTAT io register (DMA STATUS)
-  Bit 0x40 : MDPE Master Data Parity Error
+  ========   =============================================================
+  Bit 0x40   MDPE Master Data Parity Error
              Data parity error detected on the PCI BUS.
-  Bit 0x20 : BF   Bus Fault
+  Bit 0x20   BF   Bus Fault
              PCI bus fault condition detected
-  Bit 0x01 : IID  Illegal Instruction Detected
-             Set by the chip when it detects an Illegal Instruction format 
+  Bit 0x01   IID  Illegal Instruction Detected
+             Set by the chip when it detects an Illegal Instruction format
              on some condition that makes an instruction illegal.
-  Bit 0x80 : DFE Dma Fifo Empty
+  Bit 0x80   DFE Dma Fifo Empty
              Pure status bit that does not indicate an error.
-  If the reported DSTAT value contains a combination of MDPE (0x40), 
+  ========   =============================================================
+
+  If the reported DSTAT value contains a combination of MDPE (0x40),
   BF (0x20), then the cause may be likely due to a PCI BUS problem.
 
 Field C : SIST io register (SCSI Interrupt Status)
-  Bit 0x08 : SGE  SCSI GROSS ERROR
-             Indicates that the chip detected a severe error condition 
+  ========   ==================================================================
+  Bit 0x08   SGE  SCSI GROSS ERROR
+             Indicates that the chip detected a severe error condition
              on the SCSI BUS that prevents the SCSI protocol from functioning
              properly.
-  Bit 0x04 : UDC  Unexpected Disconnection
-             Indicates that the device released the SCSI BUS when the chip 
-             was not expecting this to happen. A device may behave so to 
-             indicate the SCSI initiator that an error condition not reportable              using the SCSI protocol has occurred.
-  Bit 0x02 : RST  SCSI BUS Reset
-             Generally SCSI targets do not reset the SCSI BUS, although any 
+  Bit 0x04   UDC  Unexpected Disconnection
+             Indicates that the device released the SCSI BUS when the chip
+             was not expecting this to happen. A device may behave so to
+             indicate the SCSI initiator that an error condition not reportable
+             using the SCSI protocol has occurred.
+  Bit 0x02   RST  SCSI BUS Reset
+             Generally SCSI targets do not reset the SCSI BUS, although any
              device on the BUS can reset it at any time.
-  Bit 0x01 : PAR  Parity
+  Bit 0x01   PAR  Parity
              SCSI parity error detected.
-  On a faulty SCSI BUS, any error condition among SGE (0x08), UDC (0x04) and 
-  PAR (0x01) may be detected by the chip. If your SCSI system sometimes 
-  encounters such error conditions, especially SCSI GROSS ERROR, then a SCSI 
+  ========   ==================================================================
+
+  On a faulty SCSI BUS, any error condition among SGE (0x08), UDC (0x04) and
+  PAR (0x01) may be detected by the chip. If your SCSI system sometimes
+  encounters such error conditions, especially SCSI GROSS ERROR, then a SCSI
   BUS problem is likely the cause of these errors.
 
-For fields D,E,F,G and H, you may look into the sym53c8xx_defs.h file 
+For fields D,E,F,G and H, you may look into the sym53c8xx_defs.h file
 that contains some minimal comments on IO register bits.
+
 Field D : SOCL  Scsi Output Control Latch
-          This register reflects the state of the SCSI control lines the 
+          This register reflects the state of the SCSI control lines the
           chip want to drive or compare against.
+
 Field E : SBCL  Scsi Bus Control Lines
           Actual value of control lines on the SCSI BUS.
+
 Field F : SBDL  Scsi Bus Data Lines
           Actual value of data lines on the SCSI BUS.
+
 Field G : SXFER  SCSI Transfer
-          Contains the setting of the Synchronous Period for output and 
+          Contains the setting of the Synchronous Period for output and
           the current Synchronous offset (offset 0 means asynchronous).
+
 Field H : SCNTL3 Scsi Control Register 3
-          Contains the setting of timing values for both asynchronous and 
-          synchronous data transfers. 
+          Contains the setting of timing values for both asynchronous and
+          synchronous data transfers.
 
-Understanding Fields I, J, K and dumps requires to have good knowledge of 
+Understanding Fields I, J, K and dumps requires to have good knowledge of
 SCSI standards, chip cores functionnals and internal driver data structures.
-You are not required to decode and understand them, unless you want to help 
+You are not required to decode and understand them, unless you want to help
 maintain the driver code.
 
 16. Synchronous transfer negotiation tables
+===========================================
 
 Tables below have been created by calling the routine the driver uses
 for synchronisation negotiation timing calculation and chip setting.
-The first table corresponds to Ultra chips 53875 and 53C860 with 80 MHz 
+The first table corresponds to Ultra chips 53875 and 53C860 with 80 MHz
 clock and 5 clock divisors.
-The second one has been calculated by setting the scsi clock to 40 Mhz 
-and using 4 clock divisors and so applies to all NCR53C8XX chips in fast 
+The second one has been calculated by setting the scsi clock to 40 Mhz
+and using 4 clock divisors and so applies to all NCR53C8XX chips in fast
 SCSI-2 mode.
 
 Periods are in nano-seconds and speeds are in Mega-transfers per second.
-1 Mega-transfers/second means 1 MB/s with 8 bits SCSI and 2 MB/s with 
+1 Mega-transfers/second means 1 MB/s with 8 bits SCSI and 2 MB/s with
 Wide16 SCSI.
 
 16.1 Synchronous timings for 53C895, 53C875 and 53C860 SCSI controllers
 
- ----------------------------------------------
- Negotiated                     NCR settings
- Factor   Period   Speed        Period   Speed
- ------   ------   ------       ------   ------
- 10       25       40.000       25       40.000   (53C895 only)
- 11       30.2     33.112       31.25    32.000   (53C895 only)
- 12       50       20.000       50       20.000
- 13       52       19.230       62       16.000
- 14       56       17.857       62       16.000
- 15       60       16.666       62       16.000
- 16       64       15.625       75       13.333
- 17       68       14.705       75       13.333
- 18       72       13.888       75       13.333
- 19       76       13.157       87       11.428
- 20       80       12.500       87       11.428
- 21       84       11.904       87       11.428
- 22       88       11.363       93       10.666
- 23       92       10.869       93       10.666
- 24       96       10.416      100       10.000
- 25      100       10.000      100       10.000
- 26      104        9.615      112        8.888
- 27      108        9.259      112        8.888
- 28      112        8.928      112        8.888
- 29      116        8.620      125        8.000
- 30      120        8.333      125        8.000
- 31      124        8.064      125        8.000
- 32      128        7.812      131        7.619
- 33      132        7.575      150        6.666
- 34      136        7.352      150        6.666
- 35      140        7.142      150        6.666
- 36      144        6.944      150        6.666
- 37      148        6.756      150        6.666
- 38      152        6.578      175        5.714
- 39      156        6.410      175        5.714
- 40      160        6.250      175        5.714
- 41      164        6.097      175        5.714
- 42      168        5.952      175        5.714
- 43      172        5.813      175        5.714
- 44      176        5.681      187        5.333
- 45      180        5.555      187        5.333
- 46      184        5.434      187        5.333
- 47      188        5.319      200        5.000
- 48      192        5.208      200        5.000
- 49      196        5.102      200        5.000
-
++-----------------------------+--------+-------+--------------+
+|Negotiated                   |NCR settings    |              |
++-------+--------+------------+--------+-------+              |
+|Factor |Period  |Speed       |Period  |Speed  |              |
++-------+--------+------------+--------+-------+--------------+
+|10     | 25     |40.000      | 25     |40.000 | (53C895 only)|
++-------+--------+------------+--------+-------+--------------+
+|11     | 30.2   |33.112      | 31.25  |32.000 | (53C895 only)|
++-------+--------+------------+--------+-------+--------------+
+|12     | 50     |20.000      | 50     |20.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|13     | 52     |19.230      | 62     |16.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|14     | 56     |17.857      | 62     |16.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|15     | 60     |16.666      | 62     |16.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|16     | 64     |15.625      | 75     |13.333 |              |
++-------+--------+------------+--------+-------+--------------+
+|17     | 68     |14.705      | 75     |13.333 |              |
++-------+--------+------------+--------+-------+--------------+
+|18     | 72     |13.888      | 75     |13.333 |              |
++-------+--------+------------+--------+-------+--------------+
+|19     | 76     |13.157      | 87     |11.428 |              |
++-------+--------+------------+--------+-------+--------------+
+|20     | 80     |12.500      | 87     |11.428 |              |
++-------+--------+------------+--------+-------+--------------+
+|21     | 84     |11.904      | 87     |11.428 |              |
++-------+--------+------------+--------+-------+--------------+
+|22     | 88     |11.363      | 93     |10.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|23     | 92     |10.869      | 93     |10.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|24     | 96     |10.416      |100     |10.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|25     |100     |10.000      |100     |10.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|26     |104     | 9.615      |112     | 8.888 |              |
++-------+--------+------------+--------+-------+--------------+
+|27     |108     | 9.259      |112     | 8.888 |              |
++-------+--------+------------+--------+-------+--------------+
+|28     |112     | 8.928      |112     | 8.888 |              |
++-------+--------+------------+--------+-------+--------------+
+|29     |116     | 8.620      |125     | 8.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|30     |120     | 8.333      |125     | 8.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|31     |124     | 8.064      |125     | 8.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|32     |128     | 7.812      |131     | 7.619 |              |
++-------+--------+------------+--------+-------+--------------+
+|33     |132     | 7.575      |150     | 6.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|34     |136     | 7.352      |150     | 6.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|35     |140     | 7.142      |150     | 6.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|36     |144     | 6.944      |150     | 6.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|37     |148     | 6.756      |150     | 6.666 |              |
++-------+--------+------------+--------+-------+--------------+
+|38     |152     | 6.578      |175     | 5.714 |              |
++-------+--------+------------+--------+-------+--------------+
+|39     |156     | 6.410      |175     | 5.714 |              |
++-------+--------+------------+--------+-------+--------------+
+|40     |160     | 6.250      |175     | 5.714 |              |
++-------+--------+------------+--------+-------+--------------+
+|41     |164     | 6.097      |175     | 5.714 |              |
++-------+--------+------------+--------+-------+--------------+
+|42     |168     | 5.952      |175     | 5.714 |              |
++-------+--------+------------+--------+-------+--------------+
+|43     |172     | 5.813      |175     | 5.714 |              |
++-------+--------+------------+--------+-------+--------------+
+|44     |176     | 5.681      |187     | 5.333 |              |
++-------+--------+------------+--------+-------+--------------+
+|45     |180     | 5.555      |187     | 5.333 |              |
++-------+--------+------------+--------+-------+--------------+
+|46     |184     | 5.434      |187     | 5.333 |              |
++-------+--------+------------+--------+-------+--------------+
+|47     |188     | 5.319      |200     | 5.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|48     |192     | 5.208      |200     | 5.000 |              |
++-------+--------+------------+--------+-------+--------------+
+|49     |196     | 5.102      |200     | 5.000 |              |
++-------+--------+------------+--------+-------+--------------+
 
 16.2 Synchronous timings for fast SCSI-2 53C8XX controllers
 
- ----------------------------------------------
- Negotiated                     NCR settings
- Factor   Period   Speed        Period   Speed
- ------   ------   ------       ------   ------
- 25      100       10.000      100       10.000
- 26      104        9.615      125        8.000
- 27      108        9.259      125        8.000
- 28      112        8.928      125        8.000
- 29      116        8.620      125        8.000
- 30      120        8.333      125        8.000
- 31      124        8.064      125        8.000
- 32      128        7.812      131        7.619
- 33      132        7.575      150        6.666
- 34      136        7.352      150        6.666
- 35      140        7.142      150        6.666
- 36      144        6.944      150        6.666
- 37      148        6.756      150        6.666
- 38      152        6.578      175        5.714
- 39      156        6.410      175        5.714
- 40      160        6.250      175        5.714
- 41      164        6.097      175        5.714
- 42      168        5.952      175        5.714
- 43      172        5.813      175        5.714
- 44      176        5.681      187        5.333
- 45      180        5.555      187        5.333
- 46      184        5.434      187        5.333
- 47      188        5.319      200        5.000
- 48      192        5.208      200        5.000
- 49      196        5.102      200        5.000
-
-
-17. Serial NVRAM (added by Richard Waltham: dormouse@farsrobt.demon.co.uk)
++-----------------------------+----------------+
+|Negotiated                   |NCR settings    |
++-------+--------+------------+--------+-------+
+|Factor |Period  |Speed       |Period  |Speed  |
++-------+--------+------------+--------+-------+
+|25     |100     |10.000      |100     |10.000 |
++-------+--------+------------+--------+-------+
+|26     |104     |9.615       |125     | 8.000 |
++-------+--------+------------+--------+-------+
+|27     |108     |9.259       |125     | 8.000 |
++-------+--------+------------+--------+-------+
+|28     |112     |8.928       |125     | 8.000 |
++-------+--------+------------+--------+-------+
+|29     |116     |8.620       |125     | 8.000 |
++-------+--------+------------+--------+-------+
+|30     |120     |8.333       |125     | 8.000 |
++-------+--------+------------+--------+-------+
+|31     |124     |8.064       |125     | 8.000 |
++-------+--------+------------+--------+-------+
+|32     |128     |7.812       |131     | 7.619 |
++-------+--------+------------+--------+-------+
+|33     |132     |7.575       |150     | 6.666 |
++-------+--------+------------+--------+-------+
+|34     |136     |7.352       |150     | 6.666 |
++-------+--------+------------+--------+-------+
+|35     |140     |7.142       |150     | 6.666 |
++-------+--------+------------+--------+-------+
+|36     |144     |6.944       |150     | 6.666 |
++-------+--------+------------+--------+-------+
+|37     |148     |6.756       |150     | 6.666 |
++-------+--------+------------+--------+-------+
+|38     |152     |6.578       |175     | 5.714 |
++-------+--------+------------+--------+-------+
+|39     |156     |6.410       |175     | 5.714 |
++-------+--------+------------+--------+-------+
+|40     |160     |6.250       |175     | 5.714 |
++-------+--------+------------+--------+-------+
+|41     |164     |6.097       |175     | 5.714 |
++-------+--------+------------+--------+-------+
+|42     |168     |5.952       |175     | 5.714 |
++-------+--------+------------+--------+-------+
+|43     |172     |5.813       |175     | 5.714 |
++-------+--------+------------+--------+-------+
+|44     |176     |5.681       |187     | 5.333 |
++-------+--------+------------+--------+-------+
+|45     |180     |5.555       |187     | 5.333 |
++-------+--------+------------+--------+-------+
+|46     |184     |5.434       |187     | 5.333 |
++-------+--------+------------+--------+-------+
+|47     |188     |5.319       |200     | 5.000 |
++-------+--------+------------+--------+-------+
+|48     |192     |5.208       |200     | 5.000 |
++-------+--------+------------+--------+-------+
+|49     |196     |5.102       |200     | 5.000 |
++-------+--------+------------+--------+-------+
+
+
+17. Serial NVRAM
+================
+
+(added by Richard Waltham: dormouse@farsrobt.demon.co.uk)
 
 17.1 Features
+-------------
 
 Enabling serial NVRAM support enables detection of the serial NVRAM included
-on Symbios and some Symbios compatible host adaptors, and Tekram boards. The 
-serial NVRAM is used by Symbios and Tekram to hold set up parameters for the 
+on Symbios and some Symbios compatible host adaptors, and Tekram boards. The
+serial NVRAM is used by Symbios and Tekram to hold set up parameters for the
 host adaptor and its attached drives.
 
 The Symbios NVRAM also holds data on the boot order of host adaptors in a
@@ -1467,10 +1801,10 @@ NVRAM boot order settings can do this as well as change the order the same
 types of cards are scanned in, something "reverse probe" cannot do.
 
 Tekram boards using Symbios chips, DC390W/F/U, which have NVRAM are detected
-and this is used to distinguish between Symbios compatible and Tekram host 
+and this is used to distinguish between Symbios compatible and Tekram host
 adaptors. This is used to disable the Symbios compatible "diff" setting
-incorrectly set on Tekram boards if the CONFIG_SCSI_53C8XX_SYMBIOS_COMPAT 
-configuration parameter is set enabling both Symbios and Tekram boards to be 
+incorrectly set on Tekram boards if the CONFIG_SCSI_53C8XX_SYMBIOS_COMPAT
+configuration parameter is set enabling both Symbios and Tekram boards to be
 used together with the Symbios cards using all their features, including
 "diff" support. ("led pin" support for Symbios compatible cards can remain
 enabled when using Tekram cards. It does nothing useful for Tekram host
@@ -1478,71 +1812,76 @@ adaptors but does not cause problems either.)
 
 
 17.2 Symbios NVRAM layout
+-------------------------
+
+typical data at NVRAM address 0x100 (53c810a NVRAM)::
+
+    00 00
+    64 01
+    8e 0b
+
+    00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
+
+    04 00 0f 00 00 10 00 50 00 00 01 00 00 62
+    04 00 03 00 00 10 00 58 00 00 01 00 00 63
+    04 00 01 00 00 10 00 48 00 00 01 00 00 61
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+
+    fe fe
+    00 00
+    00 00
 
-typical data at NVRAM address 0x100 (53c810a NVRAM)
------------------------------------------------------------
-00 00
-64 01
-8e 0b
-
-00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00 
-
-04 00 0f 00 00 10 00 50 00 00 01 00 00 62 
-04 00 03 00 00 10 00 58 00 00 01 00 00 63 
-04 00 01 00 00 10 00 48 00 00 01 00 00 61 
-00 00 00 00 00 00 00 00 00 00 00 00 00 00 
-
-0f 00 08 08 64 00 0a 00
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-
-fe fe
-00 00
-00 00
------------------------------------------------------------
 NVRAM layout details
 
-NVRAM Address 0x000-0x0ff not used
-              0x100-0x26f initialised data
-              0x270-0x7ff not used
+=============  ================
+NVRAM Address
+=============  ================
+0x000-0x0ff    not used
+0x100-0x26f    initialised data
+0x270-0x7ff    not used
+=============  ================
 
-general layout
+general layout::
 
         header  -   6 bytes,
         data    - 356 bytes (checksum is byte sum of this data)
@@ -1550,7 +1889,7 @@ general layout
                   ---
         total     368 bytes
 
-data area layout
+data area layout::
 
         controller set up  -  20 bytes
         boot configuration -  56 bytes (4x14 bytes)
@@ -1559,121 +1898,126 @@ data area layout
                              ---
         total                356 bytes
 
------------------------------------------------------------
-header
-
-00 00   - ?? start marker
-64 01   - byte count (lsb/msb excludes header/trailer)
-8e 0b   - checksum (lsb/msb excludes header/trailer)
------------------------------------------------------------
-controller set up
-
-00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
-                   |     |           |     |
-                   |     |           |      -- host ID
-                   |     |           |
-                   |     |            --Removable Media Support
-                   |     |               0x00 = none
-                   |     |               0x01 = Bootable Device
-                   |     |               0x02 = All with Media
-                   |     |
-                   |      --flag bits 2
-                   |        0x00000001= scan order hi->low
-                   |            (default 0x00 - scan low->hi)
-                    --flag bits 1
-                       0x00000001 scam enable
-                       0x00000010 parity enable
-                       0x00000100 verbose boot msgs
+header::
+
+    00 00   - ?? start marker
+    64 01   - byte count (lsb/msb excludes header/trailer)
+    8e 0b   - checksum (lsb/msb excludes header/trailer)
+
+controller set up::
+
+    00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
+		    |     |           |     |
+		    |     |           |      -- host ID
+		    |     |           |
+		    |     |            --Removable Media Support
+		    |     |               0x00 = none
+		    |     |               0x01 = Bootable Device
+		    |     |               0x02 = All with Media
+		    |     |
+		    |      --flag bits 2
+		    |        0x00000001= scan order hi->low
+		    |            (default 0x00 - scan low->hi)
+			--flag bits 1
+			0x00000001 scam enable
+			0x00000010 parity enable
+			0x00000100 verbose boot msgs
 
 remaining bytes unknown - they do not appear to change in my
 current set up for any of the controllers.
 
 default set up is identical for 53c810a and 53c875 NVRAM
 (Removable Media added Symbios BIOS version 4.09)
------------------------------------------------------------
+
 boot configuration
 
-boot order set by order of the devices in this table
+boot order set by order of the devices in this table::
 
-04 00 0f 00 00 10 00 50 00 00 01 00 00 62 -- 1st controller
-04 00 03 00 00 10 00 58 00 00 01 00 00 63    2nd controller
-04 00 01 00 00 10 00 48 00 00 01 00 00 61    3rd controller
-00 00 00 00 00 00 00 00 00 00 00 00 00 00    4th controller
-       |  |  |  |     |        |     |  |
-       |  |  |  |     |        |      ---- PCI io port adr
-       |  |  |  |     |         --0x01 init/scan at boot time
-       |  |  |  |      --PCI device/function number (0xdddddfff)
-       |  |   ----- ?? PCI vendor ID (lsb/msb)
-        ----PCI device ID (lsb/msb)
+    04 00 0f 00 00 10 00 50 00 00 01 00 00 62 -- 1st controller
+    04 00 03 00 00 10 00 58 00 00 01 00 00 63    2nd controller
+    04 00 01 00 00 10 00 48 00 00 01 00 00 61    3rd controller
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00    4th controller
+	|  |  |  |     |        |     |  |
+	|  |  |  |     |        |      ---- PCI io port adr
+	|  |  |  |     |         --0x01 init/scan at boot time
+	|  |  |  |      --PCI device/function number (0xdddddfff)
+	|  |   ----- ?? PCI vendor ID (lsb/msb)
+	    ----PCI device ID (lsb/msb)
 
-?? use of this data is a guess but seems reasonable
+    ?? use of this data is a guess but seems reasonable
 
 remaining bytes unknown - they do not appear to change in my
 current set up
 
 default set up is identical for 53c810a and 53c875 NVRAM
------------------------------------------------------------
-device set up (up to 16 devices - includes controller)
-
-0f 00 08 08 64 00 0a 00 - id 0
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 - id 15
- |     |  |  |     |  |
- |     |  |  |      ----timeout (lsb/msb)
- |     |  |   --synch period (0x?? 40 Mtrans/sec- fast 40) (probably 0x28)
- |     |  |                  (0x30 20 Mtrans/sec- fast 20)
- |     |  |                  (0x64 10 Mtrans/sec- fast )
- |     |  |                  (0xc8  5 Mtrans/sec)
- |     |  |                  (0x00  asynchronous)
- |     |   -- ?? max sync offset (0x08 in NVRAM on 53c810a) 
- |     |                         (0x10 in NVRAM on 53c875)
- |      --device bus width (0x08 narrow)
- |                         (0x10 16 bit wide)
-  --flag bits
-    0x00000001 - disconnect enabled
-    0x00000010 - scan at boot time
-    0x00000100 - scan luns
-    0x00001000 - queue tags enabled
+--------------------------------------------------------
+
+device set up (up to 16 devices - includes controller)::
+
+    0f 00 08 08 64 00 0a 00 - id 0
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00 - id 15
+    |     |  |  |     |  |
+    |     |  |  |      ----timeout (lsb/msb)
+    |     |  |   --synch period (0x?? 40 Mtrans/sec- fast 40) (probably 0x28)
+    |     |  |                  (0x30 20 Mtrans/sec- fast 20)
+    |     |  |                  (0x64 10 Mtrans/sec- fast )
+    |     |  |                  (0xc8  5 Mtrans/sec)
+    |     |  |                  (0x00  asynchronous)
+    |     |   -- ?? max sync offset (0x08 in NVRAM on 53c810a)
+    |     |                         (0x10 in NVRAM on 53c875)
+    |      --device bus width (0x08 narrow)
+    |                         (0x10 16 bit wide)
+    --flag bits
+	0x00000001 - disconnect enabled
+	0x00000010 - scan at boot time
+	0x00000100 - scan luns
+	0x00001000 - queue tags enabled
 
 remaining bytes unknown - they do not appear to change in my
 current set up
 
-?? use of this data is a guess but seems reasonable 
+?? use of this data is a guess but seems reasonable
 (but it could be max bus width)
 
 default set up for 53c810a NVRAM
-default set up for 53c875 NVRAM - bus width     - 0x10
+default set up for 53c875 NVRAM
+
+				- bus width     - 0x10
                                 - sync offset ? - 0x10
                                 - sync period   - 0x30
------------------------------------------------------------
+
 ?? spare device space (32 bit bus ??)
 
-00 00 00 00 00 00 00 00  (19x8bytes)
-.
-.
-00 00 00 00 00 00 00 00
+::
+
+    00 00 00 00 00 00 00 00  (19x8bytes)
+    .
+    .
+    00 00 00 00 00 00 00 00
 
 default set up is identical for 53c810a and 53c875 NVRAM
------------------------------------------------------------
-trailer
+--------------------------------------------------------
 
-fe fe   - ? end marker ?
-00 00
-00 00
+trailer::
+
+    fe fe   - ? end marker ?
+    00 00
+    00 00
 
 default set up is identical for 53c810a and 53c875 NVRAM
 -----------------------------------------------------------
@@ -1681,51 +2025,52 @@ default set up is identical for 53c810a and 53c875 NVRAM
 
 
 17.3 Tekram NVRAM layout
+------------------------
 
 nvram 64x16 (1024 bit)
 
-Drive settings
-
-Drive ID 0-15 (addr 0x0yyyy0 = device setup, yyyy = ID)
-              (addr 0x0yyyy1 = 0x0000)
-
-    x x x x  x x x x  x x x x  x x x x
-               | | |      | |  | | | |
-               | | |      | |  | | |  ----- parity check   0 - off
-               | | |      | |  | | |                       1 - on
-               | | |      | |  | | |
-               | | |      | |  | |  ------- sync neg       0 - off
-               | | |      | |  | |                         1 - on
-               | | |      | |  | |
-               | | |      | |  |  --------- disconnect     0 - off
-               | | |      | |  |                           1 - on
-               | | |      | |  |
-               | | |      | |   ----------- start cmd      0 - off
-               | | |      | |                              1 - on
-               | | |      | |
-               | | |      |  -------------- tagged cmds    0 - off
-               | | |      |                                1 - on
-               | | |      | 
-               | | |       ---------------- wide neg       0 - off
-               | | |                                       1 - on
-               | | |
-                --------------------------- sync rate      0 - 10.0 Mtrans/sec
-                                                           1 -  8.0
-                                                           2 -  6.6
-                                                           3 -  5.7
-                                                           4 -  5.0
-                                                           5 -  4.0
-                                                           6 -  3.0
-                                                           7 -  2.0
-                                                           7 -  2.0
-                                                           8 - 20.0
-                                                           9 - 16.7
-                                                           a - 13.9
-                                                           b - 11.9
+Drive settings::
+
+    Drive ID 0-15 (addr 0x0yyyy0 = device setup, yyyy = ID)
+		(addr 0x0yyyy1 = 0x0000)
+
+	x x x x  x x x x  x x x x  x x x x
+		| | |      | |  | | | |
+		| | |      | |  | | |  ----- parity check   0 - off
+		| | |      | |  | | |                       1 - on
+		| | |      | |  | | |
+		| | |      | |  | |  ------- sync neg       0 - off
+		| | |      | |  | |                         1 - on
+		| | |      | |  | |
+		| | |      | |  |  --------- disconnect     0 - off
+		| | |      | |  |                           1 - on
+		| | |      | |  |
+		| | |      | |   ----------- start cmd      0 - off
+		| | |      | |                              1 - on
+		| | |      | |
+		| | |      |  -------------- tagged cmds    0 - off
+		| | |      |                                1 - on
+		| | |      |
+		| | |       ---------------- wide neg       0 - off
+		| | |                                       1 - on
+		| | |
+		    --------------------------- sync rate      0 - 10.0 Mtrans/sec
+							    1 -  8.0
+							    2 -  6.6
+							    3 -  5.7
+							    4 -  5.0
+							    5 -  4.0
+							    6 -  3.0
+							    7 -  2.0
+							    7 -  2.0
+							    8 - 20.0
+							    9 - 16.7
+							    a - 13.9
+							    b - 11.9
 
 Global settings
 
-Host flags 0 (addr 0x100000, 32) 
+Host flags 0 (addr 0x100000, 32)::
 
     x x x x  x x x x  x x x x  x x x x
     | | | |  | | | |           | | | |
@@ -1733,7 +2078,7 @@ Host flags 0 (addr 0x100000, 32)
     | | | |  | | | |
     | | | |  | | |  ----------------------- support for    0 - off
     | | | |  | | |                          > 2 drives     1 - on
-    | | | |  | | | 
+    | | | |  | | |
     | | | |  | |  ------------------------- support drives 0 - off
     | | | |  | |                            > 1Gbytes      1 - on
     | | | |  | |
@@ -1753,10 +2098,10 @@ Host flags 0 (addr 0x100000, 32)
                                             as BIOS dev    1 - boot device
                                                            2 - all
 
-Host flags 1 (addr 0x100001, 33)
+Host flags 1 (addr 0x100001, 33)::
 
     x x x x  x x x x  x x x x  x x x x
-               | | |             | | | 
+               | | |             | | |
                | | |              --------- boot delay     0 -   3 sec
                | | |                                       1 -   5
                | | |                                       2 -  10
@@ -1771,7 +2116,7 @@ Host flags 1 (addr 0x100001, 33)
                                                            3 - 16
                                                            4 - 32
 
-Host flags 2 (addr 0x100010, 34)
+Host flags 2 (addr 0x100010, 34)::
 
     x x x x  x x x x  x x x x  x x x x
                                      |
@@ -1784,41 +2129,41 @@ checksum = 0x1234 - (sum addr 0-63)
 
 ----------------------------------------------------------------------------
 
-default nvram data:
+default nvram data::
 
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
 
-0x0f07 0x0400 0x0001 0x0000 0x0000 0x0000 0x0000 0x0000
-0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
-0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
-0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0xfbbc
+    0x0f07 0x0400 0x0001 0x0000 0x0000 0x0000 0x0000 0x0000
+    0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
+    0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
+    0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0xfbbc
 
 
 18. Support for Big Endian
+==========================
 
 The PCI local bus has been primarily designed for x86 architecture.
-As a consequence, PCI devices generally expect DWORDS using little endian 
+As a consequence, PCI devices generally expect DWORDS using little endian
 byte ordering.
 
 18.1 Big Endian CPU
+-------------------
 
-In order to support NCR chips on a Big Endian architecture the driver has to 
-perform byte reordering each time it is needed. This feature has been 
-added to the driver by Cort <cort@cs.nmt.edu> and is available in driver 
-version 2.5 and later ones. For the moment Big Endian support has only 
+In order to support NCR chips on a Big Endian architecture the driver has to
+perform byte reordering each time it is needed. This feature has been
+added to the driver by Cort <cort@cs.nmt.edu> and is available in driver
+version 2.5 and later ones. For the moment Big Endian support has only
 been tested on Linux/PPC (PowerPC).
 
 18.2 NCR chip in Big Endian mode of operations
+----------------------------------------------
 
-It can be read in SYMBIOS documentation that some chips support a special 
+It can be read in SYMBIOS documentation that some chips support a special
 Big Endian mode, on paper: 53C815, 53C825A, 53C875, 53C875N, 53C895.
-This mode of operations is not software-selectable, but needs pin named 
-BigLit to be pulled-up. Using this mode, most of byte reorderings should 
+This mode of operations is not software-selectable, but needs pin named
+BigLit to be pulled-up. Using this mode, most of byte reorderings should
 be avoided when the driver is running on a Big Endian CPU.
 Driver version 2.5 is also, in theory, ready for this feature.
-
-===============================================================================
-End of NCR53C8XX driver README file
diff --git a/Documentation/scsi/ppa.rst b/Documentation/scsi/ppa.rst
new file mode 100644
index 000000000000..5fe3859a6892
--- /dev/null
+++ b/Documentation/scsi/ppa.rst
@@ -0,0 +1,18 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+Terse where to get ZIP Drive help info
+======================================
+
+General Iomega ZIP drive page for Linux:
+http://web.archive.org/web/%2E/http://www.torque.net/~campbell/
+
+Driver archive for old drivers:
+http://web.archive.org/web/%2E/http://www.torque.net/~campbell/ppa
+
+Linux Parport page (parallel port)
+http://web.archive.org/web/%2E/http://www.torque.net/parport/
+
+Email list for Linux Parport
+linux-parport@torque.net
+
diff --git a/Documentation/scsi/ppa.txt b/Documentation/scsi/ppa.txt
deleted file mode 100644
index 05ff47dbe8d1..000000000000
--- a/Documentation/scsi/ppa.txt
+++ /dev/null
@@ -1,14 +0,0 @@
--------- Terse where to get ZIP Drive help info --------
-
-General Iomega ZIP drive page for Linux:
-http://web.archive.org/web/*/http://www.torque.net/~campbell/
-
-Driver archive for old drivers:
-http://web.archive.org/web/*/http://www.torque.net/~campbell/ppa
-
-Linux Parport page (parallel port)
-http://web.archive.org/web/*/http://www.torque.net/parport/
-
-Email list for Linux Parport
-linux-parport@torque.net
-
diff --git a/Documentation/scsi/qlogicfas.txt b/Documentation/scsi/qlogicfas.rst
index c211d827fef2..b17f1b3676c3 100644
--- a/Documentation/scsi/qlogicfas.txt
+++ b/Documentation/scsi/qlogicfas.rst
@@ -1,3 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Qlogic FASXXX Family Driver Notes
+=================================
 
 This driver supports the Qlogic FASXXX family of chips.  This driver
 only works with the ISA, VLB, and PCMCIA versions of the Qlogic
@@ -16,7 +21,8 @@ is provided by the qla1280 driver.
 Nor does it support the PCI-Basic, which is supported by the
 'am53c974' driver.
 
-PCMCIA SUPPORT
+PCMCIA Support
+==============
 
 This currently only works if the card is enabled first from DOS.  This
 means you will have to load your socket and card services, and
@@ -31,7 +37,8 @@ it from configuring the card.
 I am working with the PCMCIA group to make it more flexible, but that
 may take a while.
 
-ALL CARDS
+All Cards
+=========
 
 The top of the qlogic.c file has a number of defines that controls
 configuration.  As shipped, it provides a balance between speed and
@@ -46,7 +53,8 @@ command or something.  It comes up faster if this is set to zero, and
 if you have reliable hardware and connections it may be more useful to
 not reset things.
 
-SOME TROUBLESHOOTING TIPS
+Some Troubleshooting Tips
+=========================
 
 Make sure it works properly under DOS.  You should also do an initial FDISK
 on a new drive if you want partitions.
@@ -54,7 +62,8 @@ on a new drive if you want partitions.
 Don't enable all the speedups first.  If anything is wrong, they will make
 any problem worse.
 
-IMPORTANT
+Important
+=========
 
 The best way to test if your cables, termination, etc. are good is to
 copy a very big file (e.g. a doublespace container file, or a very
diff --git a/Documentation/scsi/scsi-changer.txt b/Documentation/scsi/scsi-changer.rst
index ade046ea7c17..ab60e7e61a6c 100644
--- a/Documentation/scsi/scsi-changer.txt
+++ b/Documentation/scsi/scsi-changer.rst
@@ -1,4 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
 
+========================================
 README for the SCSI media changer driver
 ========================================
 
@@ -28,15 +30,17 @@ The SCSI changer model is complex, compared to - for example - IDE-CD
 changers. But it allows to handle nearly all possible cases. It knows
 4 different types of changer elements:
 
-  media transport - this one shuffles around the media, i.e. the
+  ===============   ==================================================
+  media transport   this one shuffles around the media, i.e. the
                     transport arm.  Also known as "picker".
-  storage         - a slot which can hold a media.
-  import/export   - the same as above, but is accessible from outside,
+  storage           a slot which can hold a media.
+  import/export     the same as above, but is accessible from outside,
                     i.e. there the operator (you !) can use this to
                     fill in and remove media from the changer.
 		    Sometimes named "mailslot".
-  data transfer   - this is the device which reads/writes, i.e. the
+  data transfer     this is the device which reads/writes, i.e. the
 		    CD-ROM / Tape / whatever drive.
+  ===============   ==================================================
 
 None of these is limited to one: A huge Jukebox could have slots for
 123 CD-ROM's, 5 CD-ROM readers (and therefore 6 SCSI ID's: the changer
@@ -131,24 +135,23 @@ timeout_init=<seconds>
 timeout_move=<seconds>
 	timeout for all other commands (default: 120).
 
-dt_id=<id1>,<id2>,...
-dt_lun=<lun1>,<lun2>,...
+dt_id=<id1>,<id2>,... / dt_lun=<lun1>,<lun2>,...
 	These two allow to specify the SCSI ID and LUN for the data
 	transfer elements.  You likely don't need this as the jukebox
 	should provide this information.  But some devices don't ...
 
-vendor_firsts=
-vendor_counts=
-vendor_labels=
+vendor_firsts=, vendor_counts=, vendor_labels=
 	These insmod options can be used to tell the driver that there
 	are some vendor-specific element types.  Grundig for example
 	does this.  Some jukeboxes have a printer to label fresh burned
 	CDs, which is addressed as element 0xc000 (type 5).  To tell the
-	driver about this vendor-specific element, use this:
+	driver about this vendor-specific element, use this::
+
 		$ insmod ch			\
 			vendor_firsts=0xc000	\
 			vendor_counts=1		\
 			vendor_labels=printer
+
 	All three insmod options accept up to four comma-separated
 	values, this way you can configure the element types 5-8.
 	You likely need the SCSI specs for the device in question to
@@ -162,13 +165,15 @@ Credits
 I wrote this driver using the famous mailing-patches-around-the-world
 method.  With (more or less) help from:
 
-	Daniel Moehwald <moehwald@hdg.de>
-	Dane Jasper <dane@sonic.net>
-	R. Scott Bailey <sbailey@dsddi.eds.com>
-	Jonathan Corbet <corbet@lwn.net>
+	- Daniel Moehwald <moehwald@hdg.de>
+	- Dane Jasper <dane@sonic.net>
+	- R. Scott Bailey <sbailey@dsddi.eds.com>
+	- Jonathan Corbet <corbet@lwn.net>
 
 Special thanks go to
-	Martin Kuehne <martin.kuehne@bnbt.de>
+
+	- Martin Kuehne <martin.kuehne@bnbt.de>
+
 for a old, second-hand (but full functional) cdrom jukebox which I use
 to develop/test driver and tools now.
 
@@ -176,5 +181,4 @@ Have fun,
 
    Gerd
 
--- 
 Gerd Knorr <kraxel@bytesex.org>
diff --git a/Documentation/scsi/scsi-generic.txt b/Documentation/scsi/scsi-generic.rst
index 51be20a6a14d..258505e557a6 100644
--- a/Documentation/scsi/scsi-generic.txt
+++ b/Documentation/scsi/scsi-generic.rst
@@ -1,6 +1,11 @@
-            Notes on Linux SCSI Generic (sg) driver
-            ---------------------------------------
+.. 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
@@ -18,7 +23,7 @@ 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) . 
+      - 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.
@@ -29,12 +34,16 @@ There are three major versions of sg found in the linux kernel (lk):
 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
+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
+
+- 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
@@ -45,23 +54,27 @@ 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 
+/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 
+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
+
+    =========   ==========================================================
+    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 
+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.
@@ -72,30 +85,34 @@ 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.
+     - 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 
+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
+
+     - 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 .
+version 3.1.22 found in lk 2.4.17.
 
 
 Douglas Gilbert
+
 26th January 2002
+
 dgilbert@interlog.com
diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.rst
index 25a4b4cf04a6..9aba897c97ac 100644
--- a/Documentation/scsi/scsi-parameters.txt
+++ b/Documentation/scsi/scsi-parameters.rst
@@ -1,31 +1,35 @@
-                          SCSI Kernel Parameters
-                          ~~~~~~~~~~~~~~~~~~~~~~
+.. SPDX-License-Identifier: GPL-2.0
+
+======================
+SCSI Kernel Parameters
+======================
 
 See Documentation/admin-guide/kernel-parameters.rst for general information on
 specifying module parameters.
 
 This document may not be entirely up to date and comprehensive. The command
-"modinfo -p ${modulename}" shows a current list of all parameters of a loadable
+``modinfo -p ${modulename}`` shows a current list of all parameters of a loadable
 module. Loadable modules, after being loaded into the running kernel, also
 reveal their parameters in /sys/module/${modulename}/parameters/. Some of these
 parameters may be changed at runtime by the command
-"echo -n ${value} > /sys/module/${modulename}/parameters/${parm}".
+``echo -n ${value} > /sys/module/${modulename}/parameters/${parm}``.
 
+::
 
 	advansys=	[HW,SCSI]
 			See header of drivers/scsi/advansys.c.
 
 	aha152x=	[HW,SCSI]
-			See Documentation/scsi/aha152x.txt.
+			See Documentation/scsi/aha152x.rst.
 
 	aha1542=	[HW,SCSI]
 			Format: <portbase>[,<buson>,<busoff>[,<dmaspeed>]]
 
 	aic7xxx=	[HW,SCSI]
-			See Documentation/scsi/aic7xxx.txt.
+			See Documentation/scsi/aic7xxx.rst.
 
 	aic79xx=	[HW,SCSI]
-			See Documentation/scsi/aic79xx.txt.
+			See Documentation/scsi/aic79xx.rst.
 
 	atascsi=	[HW,SCSI]
 			See drivers/scsi/atari_scsi.c.
@@ -57,19 +61,19 @@ parameters may be changed at runtime by the command
 			See header of drivers/scsi/NCR_D700.c.
 
 	ncr5380=	[HW,SCSI]
-			See Documentation/scsi/g_NCR5380.txt.
+			See Documentation/scsi/g_NCR5380.rst.
 
 	ncr53c400=	[HW,SCSI]
-			See Documentation/scsi/g_NCR5380.txt.
+			See Documentation/scsi/g_NCR5380.rst.
 
 	ncr53c400a=	[HW,SCSI]
-			See Documentation/scsi/g_NCR5380.txt.
+			See Documentation/scsi/g_NCR5380.rst.
 
 	ncr53c8xx=	[HW,SCSI]
 
 	osst=		[HW,SCSI] SCSI Tape Driver
 			Format: <buffer_size>,<write_threshold>
-			See also Documentation/scsi/st.txt.
+			See also Documentation/scsi/st.rst.
 
 	scsi_debug_*=	[SCSI]
 			See drivers/scsi/scsi_debug.c.
@@ -101,7 +105,7 @@ parameters may be changed at runtime by the command
 			See header of drivers/scsi/sim710.c.
 
 	st=		[HW,SCSI] SCSI tape parameters (buffers, etc.)
-			See Documentation/scsi/st.txt.
+			See Documentation/scsi/st.rst.
 
 	wd33c93=	[HW,SCSI]
 			See header of drivers/scsi/wd33c93.c.
diff --git a/Documentation/scsi/scsi.txt b/Documentation/scsi/scsi.rst
index 3d99d38cb62a..276918eb4d74 100644
--- a/Documentation/scsi/scsi.txt
+++ b/Documentation/scsi/scsi.rst
@@ -1,44 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============================
 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
 and multiple page HTML renderings as well as postscript and pdf.
 It can also be found at:
-http://web.archive.org/web/*/http://www.torque.net/scsi/SCSI-2.4-HOWTO
+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 
+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 
+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")
 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 
+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 ** (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, 
+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
 the associated memory).
 
 The lower level drivers are the ones that support the individual cards that
 are supported for the hardware platform that you are running under. Those
 individual cards are often called Host Bus Adapters (HBAs). For example the
-aic7xxx.o driver is used to control all recent SCSI controller cards from 
-Adaptec. Almost all lower level drivers can be built either as modules or 
+aic7xxx.o driver is used to control all recent SCSI controller cards from
+Adaptec. Almost all lower level drivers can be built either as modules or
 built into the kernel.
 
-
-** There is a variant of the st driver for controlling OnStream tape
-   devices. Its module name is osst.o .
+.. [1] There is a variant of the st driver for controlling OnStream tape
+       devices. Its module name is osst.o .
 
diff --git a/Documentation/scsi/scsi_eh.txt b/Documentation/scsi/scsi_eh.rst
index 1b7436932a2b..7d78c2475615 100644
--- a/Documentation/scsi/scsi_eh.txt
+++ b/Documentation/scsi/scsi_eh.rst
@@ -1,35 +1,39 @@
+.. SPDX-License-Identifier: GPL-2.0
 
+=======
 SCSI EH
-======================================
+=======
 
- This document describes SCSI midlayer error handling infrastructure.
-Please refer to Documentation/scsi/scsi_mid_low_api.txt for more
+This document describes SCSI midlayer error handling infrastructure.
+Please refer to Documentation/scsi/scsi_mid_low_api.rst for more
 information regarding SCSI midlayer.
 
-TABLE OF CONTENTS
+.. TABLE OF CONTENTS
 
-[1] How SCSI commands travel through the midlayer and to EH
-    [1-1] struct scsi_cmnd
-    [1-2] How do scmd's get completed?
-	[1-2-1] Completing a scmd w/ scsi_done
-	[1-2-2] Completing a scmd w/ timeout
-    [1-3] How EH takes over
-[2] How SCSI EH works
-    [2-1] EH through fine-grained callbacks
-	[2-1-1] Overview
-	[2-1-2] Flow of scmds through EH
-	[2-1-3] Flow of control
-    [2-2] EH through transportt->eh_strategy_handler()
-	[2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions
-	[2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions
-	[2-2-3] Things to consider
+   [1] How SCSI commands travel through the midlayer and to EH
+       [1-1] struct scsi_cmnd
+       [1-2] How do scmd's get completed?
+   	[1-2-1] Completing a scmd w/ scsi_done
+   	[1-2-2] Completing a scmd w/ timeout
+       [1-3] How EH takes over
+   [2] How SCSI EH works
+       [2-1] EH through fine-grained callbacks
+   	[2-1-1] Overview
+   	[2-1-2] Flow of scmds through EH
+   	[2-1-3] Flow of control
+       [2-2] EH through transportt->eh_strategy_handler()
+   	[2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions
+   	[2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions
+   	[2-2-3] Things to consider
 
 
-[1] How SCSI commands travel through the midlayer and to EH
+1. How SCSI commands travel through the midlayer and to EH
+==========================================================
 
-[1-1] struct scsi_cmnd
+1.1 struct scsi_cmnd
+--------------------
 
- Each SCSI command is represented with struct scsi_cmnd (== scmd).  A
+Each SCSI command is represented with struct scsi_cmnd (== scmd).  A
 scmd has two list_head's to link itself into lists.  The two are
 scmd->list and scmd->eh_entry.  The former is used for free list or
 per-device allocated scmd list and not of much interest to this EH
@@ -38,25 +42,28 @@ otherwise stated scmds are always linked using scmd->eh_entry in this
 discussion.
 
 
-[1-2] How do scmd's get completed?
+1.2 How do scmd's get completed?
+--------------------------------
 
- Once LLDD gets hold of a scmd, either the LLDD will complete the
+Once LLDD gets hold of a scmd, either the LLDD will complete the
 command by calling scsi_done callback passed from midlayer when
 invoking hostt->queuecommand() or the block layer will time it out.
 
 
-[1-2-1] Completing a scmd w/ scsi_done
+1.2.1 Completing a scmd w/ scsi_done
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
- For all non-EH commands, scsi_done() is the completion callback.  It
+For all non-EH commands, scsi_done() is the completion callback.  It
 just calls blk_complete_request() to delete the block layer timer and
 raise SCSI_SOFTIRQ
 
- SCSI_SOFTIRQ handler scsi_softirq calls scsi_decide_disposition() to
+SCSI_SOFTIRQ handler scsi_softirq calls scsi_decide_disposition() to
 determine what to do with the command.  scsi_decide_disposition()
 looks at the scmd->result value and sense data to determine what to do
 with the command.
 
  - SUCCESS
+
 	scsi_finish_command() is invoked for the command.  The
 	function does some maintenance chores and then calls
 	scsi_io_completion() to finish the I/O.
@@ -66,17 +73,21 @@ with the command.
 	of the data in case of an error.
 
  - NEEDS_RETRY
+
  - ADD_TO_MLQUEUE
+
 	scmd is requeued to blk queue.
 
  - otherwise
+
 	scsi_eh_scmd_add(scmd) is invoked for the command.  See
 	[1-3] for details of this function.
 
 
-[1-2-2] Completing a scmd w/ timeout
+1.2.2 Completing a scmd w/ timeout
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
- The timeout handler is scsi_times_out().  When a timeout occurs, this
+The timeout handler is scsi_times_out().  When a timeout occurs, this
 function
 
  1. invokes optional hostt->eh_timed_out() callback.  Return value can
@@ -101,18 +112,21 @@ function
  3. scsi_eh_scmd_add(scmd, SCSI_EH_CANCEL_CMD) is invoked for the
     command.  See [1-4] for more information.
 
-[1-3] Asynchronous command aborts
+1.3 Asynchronous command aborts
+-------------------------------
 
  After a timeout occurs a command abort is scheduled from
  scsi_abort_command(). If the abort is successful the command
  will either be retried (if the number of retries is not exhausted)
  or terminated with DID_TIME_OUT.
+
  Otherwise scsi_eh_scmd_add() is invoked for the command.
  See [1-4] for more information.
 
-[1-4] How EH takes over
+1.4 How EH takes over
+---------------------
 
- scmds enter EH via scsi_eh_scmd_add(), which does the following.
+scmds enter EH via scsi_eh_scmd_add(), which does the following.
 
  1. Links scmd->eh_entry to shost->eh_cmd_q
 
@@ -122,19 +136,19 @@ function
 
  4. Wakes up SCSI EH thread if shost->host_busy == shost->host_failed
 
- As can be seen above, once any scmd is added to shost->eh_cmd_q,
+As can be seen above, once any scmd is added to shost->eh_cmd_q,
 SHOST_RECOVERY shost_state bit is turned on.  This prevents any new
 scmd to be issued from blk queue to the host; eventually, all scmds on
 the host either complete normally, fail and get added to eh_cmd_q, or
 time out and get added to shost->eh_cmd_q.
 
- If all scmds either complete or fail, the number of in-flight scmds
+If all scmds either complete or fail, the number of in-flight scmds
 becomes equal to the number of failed scmds - i.e. shost->host_busy ==
 shost->host_failed.  This wakes up SCSI EH thread.  So, once woken up,
 SCSI EH thread can expect that all in-flight commands have failed and
 are linked on shost->eh_cmd_q.
 
- Note that this does not mean lower layers are quiescent.  If a LLDD
+Note that this does not mean lower layers are quiescent.  If a LLDD
 completed a scmd with error status, the LLDD and lower layers are
 assumed to forget about the scmd at that point.  However, if a scmd
 has timed out, unless hostt->eh_timed_out() made lower layers forget
@@ -143,13 +157,14 @@ active as long as lower layers are concerned and completion could
 occur at any time.  Of course, all such completions are ignored as the
 timer has already expired.
 
- We'll talk about how SCSI EH takes actions to abort - make LLDD
+We'll talk about how SCSI EH takes actions to abort - make LLDD
 forget about - timed out scmds later.
 
 
-[2] How SCSI EH works
+2. How SCSI EH works
+====================
 
- LLDD's can implement SCSI EH actions in one of the following two
+LLDD's can implement SCSI EH actions in one of the following two
 ways.
 
  - Fine-grained EH callbacks
@@ -162,7 +177,7 @@ ways.
 	handling.  As such, it should do all chores the SCSI midlayer
 	performs during recovery.  This will be discussed in [2-2].
 
- Once recovery is complete, SCSI EH resumes normal operation by
+Once recovery is complete, SCSI EH resumes normal operation by
 calling scsi_restart_operations(), which
 
  1. Checks if door locking is needed and locks door.
@@ -177,34 +192,38 @@ calling scsi_restart_operations(), which
  4. Kicks queues in all devices on the host in the asses
 
 
-[2-1] EH through fine-grained callbacks
+2.1 EH through fine-grained callbacks
+-------------------------------------
 
-[2-1-1] Overview
+2.1.1 Overview
+^^^^^^^^^^^^^^
 
- If eh_strategy_handler() is not present, SCSI midlayer takes charge
+If eh_strategy_handler() is not present, SCSI midlayer takes charge
 of driving error handling.  EH's goals are two - make LLDD, host and
 device forget about timed out scmds and make them ready for new
 commands.  A scmd is said to be recovered if the scmd is forgotten by
 lower layers and lower layers are ready to process or fail the scmd
 again.
 
- To achieve these goals, EH performs recovery actions with increasing
+To achieve these goals, EH performs recovery actions with increasing
 severity.  Some actions are performed by issuing SCSI commands and
 others are performed by invoking one of the following fine-grained
 hostt EH callbacks.  Callbacks may be omitted and omitted ones are
 considered to fail always.
 
-int (* eh_abort_handler)(struct scsi_cmnd *);
-int (* eh_device_reset_handler)(struct scsi_cmnd *);
-int (* eh_bus_reset_handler)(struct scsi_cmnd *);
-int (* eh_host_reset_handler)(struct scsi_cmnd *);
+::
 
- Higher-severity actions are taken only when lower-severity actions
+    int (* eh_abort_handler)(struct scsi_cmnd *);
+    int (* eh_device_reset_handler)(struct scsi_cmnd *);
+    int (* eh_bus_reset_handler)(struct scsi_cmnd *);
+    int (* eh_host_reset_handler)(struct scsi_cmnd *);
+
+Higher-severity actions are taken only when lower-severity actions
 cannot recover some of failed scmds.  Also, note that failure of the
 highest-severity action means EH failure and results in offlining of
 all unrecovered devices.
 
- During recovery, the following rules are followed
+During recovery, the following rules are followed
 
  - Recovery actions are performed on failed scmds on the to do list,
    eh_work_q.  If a recovery action succeeds for a scmd, recovered
@@ -221,58 +240,72 @@ all unrecovered devices.
    timed-out scmds, SCSI EH ensures that LLDD forgets about a scmd
    before reusing it for EH commands.
 
- When a scmd is recovered, the scmd is moved from eh_work_q to EH
+When a scmd is recovered, the scmd is moved from eh_work_q to EH
 local eh_done_q using scsi_eh_finish_cmd().  After all scmds are
 recovered (eh_work_q is empty), scsi_eh_flush_done_q() is invoked to
 either retry or error-finish (notify upper layer of failure) recovered
 scmds.
 
- scmds are retried iff its sdev is still online (not offlined during
+scmds are retried iff its sdev is still online (not offlined during
 EH), REQ_FAILFAST is not set and ++scmd->retries is less than
 scmd->allowed.
 
 
-[2-1-2] Flow of scmds through EH
+2.1.2 Flow of scmds through EH
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
  1. Error completion / time out
-    ACTION: scsi_eh_scmd_add() is invoked for scmd
+
+    :ACTION: scsi_eh_scmd_add() is invoked for scmd
+
 	- add scmd to shost->eh_cmd_q
 	- set SHOST_RECOVERY
 	- shost->host_failed++
-    LOCKING: shost->host_lock
+
+    :LOCKING: shost->host_lock
 
  2. EH starts
-    ACTION: move all scmds to EH's local eh_work_q.  shost->eh_cmd_q
-	    is cleared.
-    LOCKING: shost->host_lock (not strictly necessary, just for
+
+    :ACTION: move all scmds to EH's local eh_work_q.  shost->eh_cmd_q
+	     is cleared.
+
+    :LOCKING: shost->host_lock (not strictly necessary, just for
              consistency)
 
  3. scmd recovered
-    ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd
+
+    :ACTION: scsi_eh_finish_cmd() is invoked to EH-finish scmd
+
 	- scsi_setup_cmd_retry()
 	- move from local eh_work_q to local eh_done_q
-    LOCKING: none
-    CONCURRENCY: at most one thread per separate eh_work_q to
-		 keep queue manipulation lockless
+
+    :LOCKING: none
+
+    :CONCURRENCY: at most one thread per separate eh_work_q to
+		  keep queue manipulation lockless
 
  4. EH completes
-    ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper
-	    layer of failure. May be called concurrently but must have
-	    a no more than one thread per separate eh_work_q to
-	    manipulate the queue locklessly
-	- scmd is removed from eh_done_q and scmd->eh_entry is cleared
-	- if retry is necessary, scmd is requeued using
-          scsi_queue_insert()
-	- otherwise, scsi_finish_command() is invoked for scmd
-	- zero shost->host_failed
-    LOCKING: queue or finish function performs appropriate locking
 
+    :ACTION: scsi_eh_flush_done_q() retries scmds or notifies upper
+	     layer of failure. May be called concurrently but must have
+	     a no more than one thread per separate eh_work_q to
+	     manipulate the queue locklessly
 
-[2-1-3] Flow of control
+	     - scmd is removed from eh_done_q and scmd->eh_entry is cleared
+	     - if retry is necessary, scmd is requeued using
+	       scsi_queue_insert()
+	     - otherwise, scsi_finish_command() is invoked for scmd
+	     - zero shost->host_failed
+
+    :LOCKING: queue or finish function performs appropriate locking
+
+
+2.1.3 Flow of control
+^^^^^^^^^^^^^^^^^^^^^^
 
  EH through fine-grained callbacks start from scsi_unjam_host().
 
-<<scsi_unjam_host>>
+``scsi_unjam_host``
 
     1. Lock shost->host_lock, splice_init shost->eh_cmd_q into local
        eh_work_q and unlock host_lock.  Note that shost->eh_cmd_q is
@@ -280,7 +313,7 @@ scmd->allowed.
 
     2. Invoke scsi_eh_get_sense.
 
-    <<scsi_eh_get_sense>>
+    ``scsi_eh_get_sense``
 
 	This action is taken for each error-completed
 	(!SCSI_EH_CANCEL_CMD) commands without valid sense data.  Most
@@ -315,7 +348,7 @@ scmd->allowed.
 
     3. If !list_empty(&eh_work_q), invoke scsi_eh_abort_cmds().
 
-    <<scsi_eh_abort_cmds>>
+    ``scsi_eh_abort_cmds``
 
 	This action is taken for each timed out command when
 	no_async_abort is enabled in the host template.
@@ -339,14 +372,14 @@ scmd->allowed.
 
     4. If !list_empty(&eh_work_q), invoke scsi_eh_ready_devs()
 
-    <<scsi_eh_ready_devs>>
+    ``scsi_eh_ready_devs``
 
 	This function takes four increasingly more severe measures to
 	make failed sdevs ready for new commands.
 
 	1. Invoke scsi_eh_stu()
 
-	<<scsi_eh_stu>>
+	``scsi_eh_stu``
 
 	    For each sdev which has failed scmds with valid sense data
 	    of which scsi_check_sense()'s verdict is FAILED,
@@ -369,7 +402,7 @@ scmd->allowed.
 
 	2. If !list_empty(&eh_work_q), invoke scsi_eh_bus_device_reset().
 
-	<<scsi_eh_bus_device_reset>>
+	``scsi_eh_bus_device_reset``
 
 	    This action is very similar to scsi_eh_stu() except that,
 	    instead of issuing STU, hostt->eh_device_reset_handler()
@@ -379,7 +412,7 @@ scmd->allowed.
 
 	3. If !list_empty(&eh_work_q), invoke scsi_eh_bus_reset()
 
-	<<scsi_eh_bus_reset>>
+	``scsi_eh_bus_reset``
 
 	    hostt->eh_bus_reset_handler() is invoked for each channel
 	    with failed scmds.  If bus reset succeeds, all failed
@@ -388,7 +421,7 @@ scmd->allowed.
 
 	4. If !list_empty(&eh_work_q), invoke scsi_eh_host_reset()
 
-	<<scsi_eh_host_reset>>
+	``scsi_eh_host_reset``
 
 	    This is the last resort.  hostt->eh_host_reset_handler()
 	    is invoked.  If host reset succeeds, all failed scmds on
@@ -396,14 +429,14 @@ scmd->allowed.
 
 	5. If !list_empty(&eh_work_q), invoke scsi_eh_offline_sdevs()
 
-	<<scsi_eh_offline_sdevs>>
+	``scsi_eh_offline_sdevs``
 
 	    Take all sdevs which still have unrecovered scmds offline
 	    and EH-finish the scmds.
 
     5. Invoke scsi_eh_flush_done_q().
 
-	<<scsi_eh_flush_done_q>>
+	``scsi_eh_flush_done_q``
 
 	    At this point all scmds are recovered (or given up) and
 	    put on eh_done_q by scsi_eh_finish_cmd().  This function
@@ -411,9 +444,10 @@ scmd->allowed.
 	    layer of failure of the scmds.
 
 
-[2-2] EH through transportt->eh_strategy_handler()
+2.2 EH through transportt->eh_strategy_handler()
+------------------------------------------------
 
- transportt->eh_strategy_handler() is invoked in the place of
+transportt->eh_strategy_handler() is invoked in the place of
 scsi_unjam_host() and it is responsible for whole recovery process.
 On completion, the handler should have made lower layers forget about
 all failed scmds and either ready for new commands or offline.  Also,
@@ -422,7 +456,8 @@ SCSI midlayer.  IOW, of the steps described in [2-1-2], all steps
 except for #1 must be implemented by eh_strategy_handler().
 
 
-[2-2-1] Pre transportt->eh_strategy_handler() SCSI midlayer conditions
+2.2.1 Pre transportt->eh_strategy_handler() SCSI midlayer conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
  The following conditions are true on entry to the handler.
 
@@ -435,7 +470,8 @@ except for #1 must be implemented by eh_strategy_handler().
  - shost->host_failed == shost->host_busy
 
 
-[2-2-2] Post transportt->eh_strategy_handler() SCSI midlayer conditions
+2.2.2 Post transportt->eh_strategy_handler() SCSI midlayer conditions
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
  The following conditions must be true on exit from the handler.
 
@@ -453,7 +489,8 @@ except for #1 must be implemented by eh_strategy_handler().
    ->allowed to limit the number of retries.
 
 
-[2-2-3] Things to consider
+2.2.3 Things to consider
+^^^^^^^^^^^^^^^^^^^^^^^^
 
  - Know that timed out scmds are still active on lower layers.  Make
    lower layers forget about them before doing anything else with
@@ -469,7 +506,7 @@ except for #1 must be implemented by eh_strategy_handler().
    offline.
 
 
---
 Tejun Heo
 htejun@gmail.com
+
 11th September 2005
diff --git a/Documentation/scsi/scsi_fc_transport.txt b/Documentation/scsi/scsi_fc_transport.rst
index f79282fc48d7..176c1862cb9b 100644
--- a/Documentation/scsi/scsi_fc_transport.txt
+++ b/Documentation/scsi/scsi_fc_transport.rst
@@ -1,8 +1,13 @@
-                             SCSI FC Tansport
-                 =============================================
+.. SPDX-License-Identifier: GPL-2.0
+
+================
+SCSI FC Tansport
+================
 
 Date:  11/18/2008
-Kernel Revisions for features:
+
+Kernel Revisions for features::
+
   rports : <<TBS>>
   vports : 2.6.22
   bsg support : 2.6.30 (?TBD?)
@@ -12,25 +17,27 @@ Introduction
 ============
 This file documents the features and components of the SCSI FC Transport.
 It also provides documents the API between the transport and FC LLDDs.
-The FC transport can be found at:
+
+The FC transport can be found at::
+
   drivers/scsi/scsi_transport_fc.c
   include/scsi/scsi_transport_fc.h
   include/scsi/scsi_netlink_fc.h
   include/scsi/scsi_bsg_fc.h
 
-This file is found at Documentation/scsi/scsi_fc_transport.txt
+This file is found at Documentation/scsi/scsi_fc_transport.rst
 
 
 FC Remote Ports (rports)
-========================================================================
+========================
 << To Be Supplied >>
 
 
 FC Virtual Ports (vports)
-========================================================================
+=========================
 
-Overview:
--------------------------------
+Overview
+--------
 
   New FC standards have defined mechanisms which allows for a single physical
   port to appear on as multiple communication ports. Using the N_Port Id
@@ -61,12 +68,14 @@ Overview:
   Thus, whether a FC port is based on a physical port or on a virtual port,
   each will appear as a unique scsi_host with its own target and lun space.
 
-  Note: At this time, the transport is written to create only NPIV-based
+  .. Note::
+    At this time, the transport is written to create only NPIV-based
     vports. However, consideration was given to VF-based vports and it
     should be a minor change to add support if needed.  The remaining
     discussion will concentrate on NPIV.
 
-  Note: World Wide Name assignment (and uniqueness guarantees) are left
+  .. Note::
+    World Wide Name assignment (and uniqueness guarantees) are left
     up to an administrative entity controlling the vport. For example,
     if vports are to be associated with virtual machines, a XEN mgmt
     utility would be responsible for creating wwpn/wwnn's for the vport,
@@ -91,18 +100,29 @@ Device Trees and Vport Objects:
   port's scsi_host.
 
   Here's what to expect in the device tree :
-   The typical Physical Port's Scsi_Host:
+
+   The typical Physical Port's Scsi_Host::
+
      /sys/devices/.../host17/
-   and it has the typical descendant tree:
+
+   and it has the typical descendant tree::
+
      /sys/devices/.../host17/rport-17:0-0/target17:0:0/17:0:0:0:
-   and then the vport is created on the Physical Port:
+
+   and then the vport is created on the Physical Port::
+
      /sys/devices/.../host17/vport-17:0-0
-   and the vport's Scsi_Host is then created:
+
+   and the vport's Scsi_Host is then created::
+
      /sys/devices/.../host17/vport-17:0-0/host18
-   and then the rest of the tree progresses, such as:
+
+   and then the rest of the tree progresses, such as::
+
      /sys/devices/.../host17/vport-17:0-0/host18/rport-18:0-0/target18:0:0/18:0:0:0:
 
-  Here's what to expect in the sysfs tree :
+  Here's what to expect in the sysfs tree::
+
    scsi_hosts:
      /sys/class/scsi_host/host17                physical port's scsi_host
      /sys/class/scsi_host/host18                vport's scsi_host
@@ -116,8 +136,8 @@ Device Trees and Vport Objects:
      /sys/class/fc_remote_ports/rport-18:0-0    rport on the vport
 
 
-Vport Attributes:
--------------------------------
+Vport Attributes
+----------------
 
   The new fc_vport class object has the following attributes
 
@@ -184,16 +204,18 @@ Vport Attributes:
         (e.g. 0x, x, etc).
 
 
-Vport States:
--------------------------------
+Vport States
+------------
 
   Vport instantiation consists of two parts:
+
     - Creation with the kernel and LLDD. This means all transport and
       driver data structures are built up, and device objects created.
       This is equivalent to a driver "attach" on an adapter, which is
       independent of the adapter's link state.
     - Instantiation of the vport on the FC link via ELS traffic, etc.
       This is equivalent to a "link up" and successful link initialization.
+
   Further information can be found in the interfaces section below for
   Vport Creation.
 
@@ -227,6 +249,7 @@ Vport States:
     FC_VPORT_NO_FABRIC_SUPP     - No Fabric Support
       The vport is not operational. One of the following conditions were
       encountered:
+
        - The FC topology is not Point-to-Point
        - The FC port is not connected to an F_Port
        - The F_Port has indicated that NPIV is not supported.
@@ -251,32 +274,53 @@ Vport States:
 
   The following state table indicates the different state transitions:
 
-    State              Event                            New State
-    --------------------------------------------------------------------
-     n/a                Initialization                  Unknown
-    Unknown:            Link Down                       Linkdown
-                        Link Up & Loop                  No Fabric Support
-                        Link Up & no Fabric             No Fabric Support
-                        Link Up & FLOGI response        No Fabric Support
-                          indicates no NPIV support
-                        Link Up & FDISC being sent      Initializing
-                        Disable request                 Disable
-    Linkdown:           Link Up                         Unknown
-    Initializing:       FDISC ACC                       Active
-                        FDISC LS_RJT w/ no resources    No Fabric Resources
-                        FDISC LS_RJT w/ invalid         Fabric Rejected WWN
-                          pname or invalid nport_id
-                        FDISC LS_RJT failed for         Vport Failed
-                          other reasons
-                        Link Down                       Linkdown
-                        Disable request                 Disable
-    Disable:            Enable request                  Unknown
-    Active:             LOGO received from fabric       Fabric Logout
-                        Link Down                       Linkdown
-                        Disable request                 Disable
-    Fabric Logout:      Link still up                   Unknown
+   +------------------+--------------------------------+---------------------+
+   | State            | Event                          | New State           |
+   +==================+================================+=====================+
+   | n/a              | Initialization                 | Unknown             |
+   +------------------+--------------------------------+---------------------+
+   | Unknown:         | Link Down                      | Linkdown            |
+   |                  +--------------------------------+---------------------+
+   |                  | Link Up & Loop                 | No Fabric Support   |
+   |                  +--------------------------------+---------------------+
+   |                  | Link Up & no Fabric            | No Fabric Support   |
+   |                  +--------------------------------+---------------------+
+   |                  | Link Up & FLOGI response       | No Fabric Support   |
+   |                  | indicates no NPIV support      |                     |
+   |                  +--------------------------------+---------------------+
+   |                  | Link Up & FDISC being sent     | Initializing        |
+   |                  +--------------------------------+---------------------+
+   |                  | Disable request                | Disable             |
+   +------------------+--------------------------------+---------------------+
+   | Linkdown:        | Link Up                        | Unknown             |
+   +------------------+--------------------------------+---------------------+
+   | Initializing:    | FDISC ACC                      | Active              |
+   |                  +--------------------------------+---------------------+
+   |                  | FDISC LS_RJT w/ no resources   | No Fabric Resources |
+   |                  +--------------------------------+---------------------+
+   |                  | FDISC LS_RJT w/ invalid        | Fabric Rejected WWN |
+   |		      | pname or invalid nport_id      |                     |
+   |                  +--------------------------------+---------------------+
+   |                  | FDISC LS_RJT failed for        | Vport Failed        |
+   |                  | other reasons                  |                     |
+   |                  +--------------------------------+---------------------+
+   |                  | Link Down                      | Linkdown            |
+   |                  +--------------------------------+---------------------+
+   |                  | Disable request                | Disable             |
+   +------------------+--------------------------------+---------------------+
+   | Disable:         | Enable request                 | Unknown             |
+   +------------------+--------------------------------+---------------------+
+   | Active:          | LOGO received from fabric      | Fabric Logout       |
+   |                  +--------------------------------+---------------------+
+   |                  | Link Down                      | Linkdown            |
+   |                  +--------------------------------+---------------------+
+   |                  | Disable request                | Disable             |
+   +------------------+--------------------------------+---------------------+
+   | Fabric Logout:   | Link still up                  | Unknown             |
+   +------------------+--------------------------------+---------------------+
+
+The following 4 error states all have the same transitions::
 
-         The following 4 error states all have the same transitions:
     No Fabric Support:
     No Fabric Resources:
     Fabric Rejected WWN:
@@ -285,8 +329,8 @@ Vport States:
                         Link goes down                  Linkdown
 
 
-Transport <-> LLDD Interfaces :
--------------------------------
+Transport <-> LLDD Interfaces
+-----------------------------
 
 Vport support by LLDD:
 
@@ -300,14 +344,17 @@ Vport support by LLDD:
 
 Vport Creation:
 
-  The LLDD vport_create() syntax is:
+  The LLDD vport_create() syntax is::
 
       int vport_create(struct fc_vport *vport, bool disable)
 
-    where:
-      vport:    Is the newly allocated vport object
-      disable:  If "true", the vport is to be created in a disabled stated.
+  where:
+
+      =======   ===========================================================
+      vport     Is the newly allocated vport object
+      disable   If "true", the vport is to be created in a disabled stated.
                 If "false", the vport is to be enabled upon creation.
+      =======   ===========================================================
 
   When a request is made to create a new vport (via sgio/netlink, or the
   vport_create fc_host attribute), the transport will validate that the LLDD
@@ -317,6 +364,7 @@ Vport Creation:
   LLDD's vport_create() function with the newly allocated vport object.
 
   As mentioned above, vport creation is divided into two parts:
+
     - Creation with the kernel and LLDD. This means all transport and
       driver data structures are built up, and device objects created.
       This is equivalent to a driver "attach" on an adapter, which is
@@ -329,6 +377,7 @@ Vport Creation:
   infrastructure exists to support NPIV, and complete the first part of
   vport creation (data structure build up) before returning.  We do not
   hinge vport_create() on the link-side operation mainly because:
+
     - The link may be down. It is not a failure if it is. It simply
       means the vport is in an inoperable state until the link comes up.
       This is consistent with the link bouncing post vport creation.
@@ -337,11 +386,15 @@ Vport Creation:
       FC adapter. The vport_create is synonymous with driver attachment
       to the adapter, which is independent of link state.
 
-    Note: special error codes have been defined to delineate infrastructure
+  .. Note::
+
+      special error codes have been defined to delineate infrastructure
       failure cases for quicker resolution.
 
   The expected behavior for the LLDD's vport_create() function is:
+
     - Validate Infrastructure:
+
         - If the driver or adapter cannot support another vport, whether
             due to improper firmware, (a lie about) max_npiv, or a lack of
             some other resource - return VPCERR_UNSUPPORTED.
@@ -349,17 +402,21 @@ Vport Creation:
             the adapter and detects an overlap - return VPCERR_BAD_WWN.
         - If the driver detects the topology is loop, non-fabric, or the
             FLOGI did not support NPIV - return VPCERR_NO_FABRIC_SUPP.
+
     - Allocate data structures. If errors are encountered, such as out
         of memory conditions, return the respective negative Exxx error code.
     - If the role is FCP Initiator, the LLDD is to :
+
         - Call scsi_host_alloc() to allocate a scsi_host for the vport.
         - Call scsi_add_host(new_shost, &vport->dev) to start the scsi_host
           and bind it as a child of the vport device.
         - Initializes the fc_host attribute values.
+
     - Kick of further vport state transitions based on the disable flag and
         link state - and return success (zero).
 
   LLDD Implementers Notes:
+
   - It is suggested that there be a different fc_function_templates for
     the physical port and the virtual port.  The physical port's template
     would have the vport_create, vport_delete, and vport_disable functions,
@@ -373,14 +430,17 @@ Vport Creation:
 
 Vport Disable/Enable:
 
-  The LLDD vport_disable() syntax is:
+  The LLDD vport_disable() syntax is::
 
       int vport_disable(struct fc_vport *vport, bool disable)
 
-    where:
-      vport:    Is vport to be enabled or disabled
-      disable:  If "true", the vport is to be disabled.
+  where:
+
+      =======   =======================================
+      vport     Is vport to be enabled or disabled
+      disable   If "true", the vport is to be disabled.
                 If "false", the vport is to be enabled.
+      =======   =======================================
 
   When a request is made to change the disabled state on a vport, the
   transport will validate the request against the existing vport state.
@@ -401,11 +461,12 @@ Vport Disable/Enable:
 
 Vport Deletion:
 
-  The LLDD vport_delete() syntax is:
+  The LLDD vport_delete() syntax is::
 
       int vport_delete(struct fc_vport *vport)
 
-    where:
+  where:
+
       vport:    Is vport to delete
 
   When a request is made to delete a vport (via sgio/netlink, or via the
@@ -443,39 +504,42 @@ Transport supplied functions
 
 The following functions are supplied by the FC-transport for use by LLDs.
 
-   fc_vport_create - create a vport
-   fc_vport_terminate - detach and remove a vport
-
-Details:
-
-/**
- * fc_vport_create - Admin App or LLDD requests creation of a vport
- * @shost:     scsi host the virtual port is connected to.
- * @ids:       The world wide names, FC4 port roles, etc for
- *              the virtual port.
- *
- * Notes:
- *     This routine assumes no locks are held on entry.
- */
-struct fc_vport *
-fc_vport_create(struct Scsi_Host *shost, struct fc_vport_identifiers *ids)
-
-/**
- * fc_vport_terminate - Admin App or LLDD requests termination of a vport
- * @vport:      fc_vport to be terminated
- *
- * Calls the LLDD vport_delete() function, then deallocates and removes
- * the vport from the shost and object tree.
- *
- * Notes:
- *      This routine assumes no locks are held on entry.
- */
-int
-fc_vport_terminate(struct fc_vport *vport)
+   ==================   =========================
+   fc_vport_create      create a vport
+   fc_vport_terminate   detach and remove a vport
+   ==================   =========================
+
+Details::
+
+    /**
+    * fc_vport_create - Admin App or LLDD requests creation of a vport
+    * @shost:     scsi host the virtual port is connected to.
+    * @ids:       The world wide names, FC4 port roles, etc for
+    *              the virtual port.
+    *
+    * Notes:
+    *     This routine assumes no locks are held on entry.
+    */
+    struct fc_vport *
+    fc_vport_create(struct Scsi_Host *shost, struct fc_vport_identifiers *ids)
+
+    /**
+    * fc_vport_terminate - Admin App or LLDD requests termination of a vport
+    * @vport:      fc_vport to be terminated
+    *
+    * Calls the LLDD vport_delete() function, then deallocates and removes
+    * the vport from the shost and object tree.
+    *
+    * Notes:
+    *      This routine assumes no locks are held on entry.
+    */
+    int
+    fc_vport_terminate(struct fc_vport *vport)
 
 
 FC BSG support (CT & ELS passthru, and more)
-========================================================================
+============================================
+
 << To Be Supplied >>
 
 
diff --git a/Documentation/scsi/scsi_mid_low_api.rst b/Documentation/scsi/scsi_mid_low_api.rst
new file mode 100644
index 000000000000..5358bc10689e
--- /dev/null
+++ b/Documentation/scsi/scsi_mid_low_api.rst
@@ -0,0 +1,1313 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=============================================
+SCSI mid_level - lower_level driver interface
+=============================================
+
+Introduction
+============
+This document outlines the interface between the Linux SCSI mid level and
+SCSI lower level drivers. Lower level drivers (LLDs) are variously called
+host bus adapter (HBA) drivers and host drivers (HD). A "host" in this
+context is a bridge between a computer IO bus (e.g. PCI or ISA) and a
+single SCSI initiator port on a SCSI transport. An "initiator" port
+(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
+to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
+system, but only one per hardware type. Most LLDs can control one or more
+SCSI HBAs. Some HBAs contain multiple hosts.
+
+In some cases the SCSI transport is an external bus that already has
+its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
+SCSI subsystem LLD is a software bridge to the other driver subsystem.
+Examples are the usb-storage driver (found in the drivers/usb/storage
+directory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394
+directory).
+
+For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
+(SPI) controllers based on that company's 7xxx chip series. The aic7xxx
+LLD can be built into the kernel or loaded as a module. There can only be
+one aic7xxx LLD running in a Linux system but it may be controlling many
+HBAs. These HBAs might be either on PCI daughter-boards or built into
+the motherboard (or both). Some aic7xxx based HBAs are dual controllers
+and thus represent two hosts. Like most modern HBAs, each aic7xxx host
+has its own PCI device address. [The one-to-one correspondence between
+a SCSI host and a PCI device is common but not required (e.g. with
+ISA adapters).]
+
+The SCSI mid level isolates an LLD from other layers such as the SCSI
+upper layer drivers and the block layer.
+
+This version of the document roughly matches linux kernel version 2.6.8 .
+
+Documentation
+=============
+There is a SCSI documentation directory within the kernel source tree,
+typically Documentation/scsi . Most documents are in plain
+(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be
+found in that directory. A more recent copy of this document may be found
+at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/.
+Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
+briefly described in scsi.txt which contains a url to a document
+describing the SCSI subsystem in the lk 2.4 series. Two upper level
+drivers have documents in that directory: st.txt (SCSI tape driver) and
+scsi-generic.txt (for the sg driver).
+
+Some documentation (or urls) for LLDs may be found in the C source code
+or in the same directory as the C source code. For example to find a url
+about the USB mass storage driver see the
+/usr/src/linux/drivers/usb/storage directory.
+
+Driver structure
+================
+Traditionally an LLD for the SCSI subsystem has been at least two files in
+the drivers/scsi directory. For example, a driver called "xyz" has a header
+file "xyz.h" and a source file "xyz.c". [Actually there is no good reason
+why this couldn't all be in one file; the header file is superfluous.] Some
+drivers that have been ported to several operating systems have more than
+two files. For example the aic7xxx driver has separate files for generic
+and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
+their own directory under the drivers/scsi directory.
+
+When a new LLD is being added to Linux, the following files (found in the
+drivers/scsi directory) will need some attention: Makefile and Kconfig .
+It is probably best to study how existing LLDs are organized.
+
+As the 2.5 series development kernels evolve into the 2.6 series
+production series, changes are being introduced into this interface. An
+example of this is driver initialization code where there are now 2 models
+available. The older one, similar to what was found in the lk 2.4 series,
+is based on hosts that are detected at HBA driver load time. This will be
+referred to the "passive" initialization model. The newer model allows HBAs
+to be hot plugged (and unplugged) during the lifetime of the LLD and will
+be referred to as the "hotplug" initialization model. The newer model is
+preferred as it can handle both traditional SCSI equipment that is
+permanently connected as well as modern "SCSI" devices (e.g. USB or
+IEEE 1394 connected digital cameras) that are hotplugged. Both
+initialization models are discussed in the following sections.
+
+An LLD interfaces to the SCSI subsystem several ways:
+
+  a) directly invoking functions supplied by the mid level
+  b) passing a set of function pointers to a registration function
+     supplied by the mid level. The mid level will then invoke these
+     functions at some point in the future. The LLD will supply
+     implementations of these functions.
+  c) direct access to instances of well known data structures maintained
+     by the mid level
+
+Those functions in group a) are listed in a section entitled "Mid level
+supplied functions" below.
+
+Those functions in group b) are listed in a section entitled "Interface
+functions" below. Their function pointers are placed in the members of
+"struct scsi_host_template", an instance of which is passed to
+scsi_host_alloc() [#]_.  Those interface functions that the LLD does not
+wish to supply should have NULL placed in the corresponding member of
+struct scsi_host_template.  Defining an instance of struct
+scsi_host_template at file scope will cause NULL to be  placed in function
+pointer members not explicitly initialized.
+
+Those usages in group c) should be handled with care, especially in a
+"hotplug" environment. LLDs should be aware of the lifetime of instances
+that are shared with the mid level and other layers.
+
+All functions defined within an LLD and all data defined at file scope
+should be static. For example the slave_alloc() function in an LLD
+called "xxx" could be defined as
+``static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }``
+
+.. [#] the scsi_host_alloc() function is a replacement for the rather vaguely
+       named scsi_register() function in most situations.
+
+
+Hotplug initialization model
+============================
+In this model an LLD controls when SCSI hosts are introduced and removed
+from the SCSI subsystem. Hosts can be introduced as early as driver
+initialization and removed as late as driver shutdown. Typically a driver
+will respond to a sysfs probe() callback that indicates an HBA has been
+detected. After confirming that the new device is one that the LLD wants
+to control, the LLD will initialize the HBA and then register a new host
+with the SCSI mid level.
+
+During LLD initialization the driver should register itself with the
+appropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus).
+This can probably be done via sysfs. Any driver parameters (especially
+those that are writable after the driver is loaded) could also be
+registered with sysfs at this point. The SCSI mid level first becomes
+aware of an LLD when that LLD registers its first HBA.
+
+At some later time, the LLD becomes aware of an HBA and what follows
+is a typical sequence of calls between the LLD and the mid level.
+This example shows the mid level scanning the newly introduced HBA for 3
+scsi devices of which only the first 2 respond::
+
+	HBA PROBE: assume 2 SCSI devices found in scan
+    LLD                   mid level                    LLD
+    ===-------------------=========--------------------===------
+    scsi_host_alloc()  -->
+    scsi_add_host()  ---->
+    scsi_scan_host()  -------+
+			    |
+			slave_alloc()
+			slave_configure() -->  scsi_change_queue_depth()
+			    |
+			slave_alloc()
+			slave_configure()
+			    |
+			slave_alloc()   ***
+			slave_destroy() ***
+
+
+    *** For scsi devices that the mid level tries to scan but do not
+	respond, a slave_alloc(), slave_destroy() pair is called.
+
+If the LLD wants to adjust the default queue settings, it can invoke
+scsi_change_queue_depth() in its slave_configure() routine.
+
+When an HBA is being removed it could be as part of an orderly shutdown
+associated with the LLD module being unloaded (e.g. with the "rmmod"
+command) or in response to a "hot unplug" indicated by sysfs()'s
+remove() callback being invoked. In either case, the sequence is the
+same::
+
+	    HBA REMOVE: assume 2 SCSI devices attached
+    LLD                      mid level                 LLD
+    ===----------------------=========-----------------===------
+    scsi_remove_host() ---------+
+				|
+			slave_destroy()
+			slave_destroy()
+    scsi_host_put()
+
+It may be useful for a LLD to keep track of struct Scsi_Host instances
+(a pointer is returned by scsi_host_alloc()). Such instances are "owned"
+by the mid-level.  struct Scsi_Host instances are freed from
+scsi_host_put() when the reference count hits zero.
+
+Hot unplugging an HBA that controls a disk which is processing SCSI
+commands on a mounted file system is an interesting situation. Reference
+counting logic is being introduced into the mid level to cope with many
+of the issues involved. See the section on reference counting below.
+
+
+The hotplug concept may be extended to SCSI devices. Currently, when an
+HBA is added, the scsi_scan_host() function causes a scan for SCSI devices
+attached to the HBA's SCSI transport. On newer SCSI transports the HBA
+may become aware of a new SCSI device _after_ the scan has completed.
+An LLD can use this sequence to make the mid level aware of a SCSI device::
+
+		    SCSI DEVICE hotplug
+    LLD                   mid level                    LLD
+    ===-------------------=========--------------------===------
+    scsi_add_device()  ------+
+			    |
+			slave_alloc()
+			slave_configure()   [--> scsi_change_queue_depth()]
+
+In a similar fashion, an LLD may become aware that a SCSI device has been
+removed (unplugged) or the connection to it has been interrupted. Some
+existing SCSI transports (e.g. SPI) may not become aware that a SCSI
+device has been removed until a subsequent SCSI command fails which will
+probably cause that device to be set offline by the mid level. An LLD that
+detects the removal of a SCSI device can instigate its removal from
+upper layers with this sequence::
+
+		    SCSI DEVICE hot unplug
+    LLD                      mid level                 LLD
+    ===----------------------=========-----------------===------
+    scsi_remove_device() -------+
+				|
+			slave_destroy()
+
+It may be useful for an LLD to keep track of struct scsi_device instances
+(a pointer is passed as the parameter to slave_alloc() and
+slave_configure() callbacks). Such instances are "owned" by the mid-level.
+struct scsi_device instances are freed after slave_destroy().
+
+
+Reference Counting
+==================
+The Scsi_Host structure has had reference counting infrastructure added.
+This effectively spreads the ownership of struct Scsi_Host instances
+across the various SCSI layers which use them. Previously such instances
+were exclusively owned by the mid level. LLDs would not usually need to
+directly manipulate these reference counts but there may be some cases
+where they do.
+
+There are 3 reference counting functions of interest associated with
+struct Scsi_Host:
+
+  - scsi_host_alloc():
+	returns a pointer to new instance of struct
+        Scsi_Host which has its reference count ^^ set to 1
+
+  - scsi_host_get():
+	adds 1 to the reference count of the given instance
+
+  - scsi_host_put():
+	decrements 1 from the reference count of the given
+        instance. If the reference count reaches 0 then the given instance
+        is freed
+
+The scsi_device structure has had reference counting infrastructure added.
+This effectively spreads the ownership of struct scsi_device instances
+across the various SCSI layers which use them. Previously such instances
+were exclusively owned by the mid level. See the access functions declared
+towards the end of include/scsi/scsi_device.h . If an LLD wants to keep
+a copy of a pointer to a scsi_device instance it should use scsi_device_get()
+to bump its reference count. When it is finished with the pointer it can
+use scsi_device_put() to decrement its reference count (and potentially
+delete it).
+
+.. Note::
+
+   struct Scsi_Host actually has 2 reference counts which are manipulated
+   in parallel by these functions.
+
+
+Conventions
+===========
+First, Linus Torvalds's thoughts on C coding style can be found in the
+Documentation/process/coding-style.rst file.
+
+Next, there is a movement to "outlaw" typedefs introducing synonyms for
+struct tags. Both can be still found in the SCSI subsystem, but
+the typedefs have been moved to a single file, scsi_typedefs.h to
+make their future removal easier, for example:
+"typedef struct scsi_cmnd Scsi_Cmnd;"
+
+Also, most C99 enhancements are encouraged to the extent they are supported
+by the relevant gcc compilers. So C99 style structure and array
+initializers are encouraged where appropriate. Don't go too far,
+VLAs are not properly supported yet.  An exception to this is the use of
+``//`` style comments; ``/*...*/`` comments are still preferred in Linux.
+
+Well written, tested and documented code, need not be re-formatted to
+comply with the above conventions. For example, the aic7xxx driver
+comes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD
+and Adaptec have their own coding conventions.
+
+
+Mid level supplied functions
+============================
+These functions are supplied by the SCSI mid level for use by LLDs.
+The names (i.e. entry points) of these functions are exported
+so an LLD that is a module can access them. The kernel will
+arrange for the SCSI mid level to be loaded and initialized before any LLD
+is initialized. The functions below are listed alphabetically and their
+names all start with ``scsi_``.
+
+Summary:
+
+  - scsi_add_device - creates new scsi device (lu) instance
+  - scsi_add_host - perform sysfs registration and set up transport class
+  - scsi_change_queue_depth - change the queue depth on a SCSI device
+  - scsi_bios_ptable - return copy of block device's partition table
+  - scsi_block_requests - prevent further commands being queued to given host
+  - scsi_host_alloc - return a new scsi_host instance whose refcount==1
+  - scsi_host_get - increments Scsi_Host instance's refcount
+  - scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
+  - scsi_register - create and register a scsi host adapter instance.
+  - scsi_remove_device - detach and remove a SCSI device
+  - scsi_remove_host - detach and remove all SCSI devices owned by host
+  - scsi_report_bus_reset - report scsi _bus_ reset observed
+  - scsi_scan_host - scan SCSI bus
+  - scsi_track_queue_full - track successive QUEUE_FULL events
+  - scsi_unblock_requests - allow further commands to be queued to given host
+  - scsi_unregister - [calls scsi_host_put()]
+
+
+Details::
+
+    /**
+    * scsi_add_device - creates new scsi device (lu) instance
+    * @shost:   pointer to scsi host instance
+    * @channel: channel number (rarely other than 0)
+    * @id:      target id number
+    * @lun:     logical unit number
+    *
+    *      Returns pointer to new struct scsi_device instance or
+    *      ERR_PTR(-ENODEV) (or some other bent pointer) if something is
+    *      wrong (e.g. no lu responds at given address)
+    *
+    *      Might block: yes
+    *
+    *      Notes: This call is usually performed internally during a scsi
+    *      bus scan when an HBA is added (i.e. scsi_scan_host()). So it
+    *      should only be called if the HBA becomes aware of a new scsi
+    *      device (lu) after scsi_scan_host() has completed. If successful
+    *      this call can lead to slave_alloc() and slave_configure() callbacks
+    *      into the LLD.
+    *
+    *      Defined in: drivers/scsi/scsi_scan.c
+    **/
+    struct scsi_device * scsi_add_device(struct Scsi_Host *shost,
+					unsigned int channel,
+					unsigned int id, unsigned int lun)
+
+
+    /**
+    * scsi_add_host - perform sysfs registration and set up transport class
+    * @shost:   pointer to scsi host instance
+    * @dev:     pointer to struct device of type scsi class
+    *
+    *      Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
+    *
+    *      Might block: no
+    *
+    *      Notes: Only required in "hotplug initialization model" after a
+    *      successful call to scsi_host_alloc().  This function does not
+    *	scan the bus; this can be done by calling scsi_scan_host() or
+    *	in some other transport-specific way.  The LLD must set up
+    *	the transport template before calling this function and may only
+    *	access the transport class data after this function has been called.
+    *
+    *      Defined in: drivers/scsi/hosts.c
+    **/
+    int scsi_add_host(struct Scsi_Host *shost, struct device * dev)
+
+
+    /**
+    * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
+    * @sdev:       pointer to SCSI device to change queue depth on
+    * @tags        Number of tags allowed if tagged queuing enabled,
+    *              or number of commands the LLD can queue up
+    *              in non-tagged mode (as per cmd_per_lun).
+    *
+    *      Returns nothing
+    *
+    *      Might block: no
+    *
+    *      Notes: Can be invoked any time on a SCSI device controlled by this
+    *      LLD. [Specifically during and after slave_configure() and prior to
+    *      slave_destroy().] Can safely be invoked from interrupt code.
+    *
+    *      Defined in: drivers/scsi/scsi.c [see source code for more notes]
+    *
+    **/
+    int scsi_change_queue_depth(struct scsi_device *sdev, int tags)
+
+
+    /**
+    * scsi_bios_ptable - return copy of block device's partition table
+    * @dev:        pointer to block device
+    *
+    *      Returns pointer to partition table, or NULL for failure
+    *
+    *      Might block: yes
+    *
+    *      Notes: Caller owns memory returned (free with kfree() )
+    *
+    *      Defined in: drivers/scsi/scsicam.c
+    **/
+    unsigned char *scsi_bios_ptable(struct block_device *dev)
+
+
+    /**
+    * scsi_block_requests - prevent further commands being queued to given host
+    *
+    * @shost: pointer to host to block commands on
+    *
+    *      Returns nothing
+    *
+    *      Might block: no
+    *
+    *      Notes: There is no timer nor any other means by which the requests
+    *      get unblocked other than the LLD calling scsi_unblock_requests().
+    *
+    *      Defined in: drivers/scsi/scsi_lib.c
+    **/
+    void scsi_block_requests(struct Scsi_Host * shost)
+
+
+    /**
+    * scsi_host_alloc - create a scsi host adapter instance and perform basic
+    *                   initialization.
+    * @sht:        pointer to scsi host template
+    * @privsize:   extra bytes to allocate in hostdata array (which is the
+    *              last member of the returned Scsi_Host instance)
+    *
+    *      Returns pointer to new Scsi_Host instance or NULL on failure
+    *
+    *      Might block: yes
+    *
+    *      Notes: When this call returns to the LLD, the SCSI bus scan on
+    *      this host has _not_ yet been done.
+    *      The hostdata array (by default zero length) is a per host scratch
+    *      area for the LLD's exclusive use.
+    *      Both associated refcounting objects have their refcount set to 1.
+    *      Full registration (in sysfs) and a bus scan are performed later when
+    *      scsi_add_host() and scsi_scan_host() are called.
+    *
+    *      Defined in: drivers/scsi/hosts.c .
+    **/
+    struct Scsi_Host * scsi_host_alloc(struct scsi_host_template * sht,
+				    int privsize)
+
+
+    /**
+    * scsi_host_get - increment Scsi_Host instance refcount
+    * @shost:   pointer to struct Scsi_Host instance
+    *
+    *      Returns nothing
+    *
+    *      Might block: currently may block but may be changed to not block
+    *
+    *      Notes: Actually increments the counts in two sub-objects
+    *
+    *      Defined in: drivers/scsi/hosts.c
+    **/
+    void scsi_host_get(struct Scsi_Host *shost)
+
+
+    /**
+    * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
+    * @shost:   pointer to struct Scsi_Host instance
+    *
+    *      Returns nothing
+    *
+    *      Might block: currently may block but may be changed to not block
+    *
+    *      Notes: Actually decrements the counts in two sub-objects. If the
+    *      latter refcount reaches 0, the Scsi_Host instance is freed.
+    *      The LLD need not worry exactly when the Scsi_Host instance is
+    *      freed, it just shouldn't access the instance after it has balanced
+    *      out its refcount usage.
+    *
+    *      Defined in: drivers/scsi/hosts.c
+    **/
+    void scsi_host_put(struct Scsi_Host *shost)
+
+
+    /**
+    * scsi_register - create and register a scsi host adapter instance.
+    * @sht:        pointer to scsi host template
+    * @privsize:   extra bytes to allocate in hostdata array (which is the
+    *              last member of the returned Scsi_Host instance)
+    *
+    *      Returns pointer to new Scsi_Host instance or NULL on failure
+    *
+    *      Might block: yes
+    *
+    *      Notes: When this call returns to the LLD, the SCSI bus scan on
+    *      this host has _not_ yet been done.
+    *      The hostdata array (by default zero length) is a per host scratch
+    *      area for the LLD.
+    *
+    *      Defined in: drivers/scsi/hosts.c .
+    **/
+    struct Scsi_Host * scsi_register(struct scsi_host_template * sht,
+				    int privsize)
+
+
+    /**
+    * scsi_remove_device - detach and remove a SCSI device
+    * @sdev:      a pointer to a scsi device instance
+    *
+    *      Returns value: 0 on success, -EINVAL if device not attached
+    *
+    *      Might block: yes
+    *
+    *      Notes: If an LLD becomes aware that a scsi device (lu) has
+    *      been removed but its host is still present then it can request
+    *      the removal of that scsi device. If successful this call will
+    *      lead to the slave_destroy() callback being invoked. sdev is an
+    *      invalid pointer after this call.
+    *
+    *      Defined in: drivers/scsi/scsi_sysfs.c .
+    **/
+    int scsi_remove_device(struct scsi_device *sdev)
+
+
+    /**
+    * scsi_remove_host - detach and remove all SCSI devices owned by host
+    * @shost:      a pointer to a scsi host instance
+    *
+    *      Returns value: 0 on success, 1 on failure (e.g. LLD busy ??)
+    *
+    *      Might block: yes
+    *
+    *      Notes: Should only be invoked if the "hotplug initialization
+    *      model" is being used. It should be called _prior_ to
+    *      scsi_unregister().
+    *
+    *      Defined in: drivers/scsi/hosts.c .
+    **/
+    int scsi_remove_host(struct Scsi_Host *shost)
+
+
+    /**
+    * scsi_report_bus_reset - report scsi _bus_ reset observed
+    * @shost: a pointer to a scsi host involved
+    * @channel: channel (within) host on which scsi bus reset occurred
+    *
+    *      Returns nothing
+    *
+    *      Might block: no
+    *
+    *      Notes: This only needs to be called if the reset is one which
+    *      originates from an unknown location.  Resets originated by the
+    *      mid level itself don't need to call this, but there should be
+    *      no harm.  The main purpose of this is to make sure that a
+    *      CHECK_CONDITION is properly treated.
+    *
+    *      Defined in: drivers/scsi/scsi_error.c .
+    **/
+    void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
+
+
+    /**
+    * scsi_scan_host - scan SCSI bus
+    * @shost: a pointer to a scsi host instance
+    *
+    *	Might block: yes
+    *
+    *	Notes: Should be called after scsi_add_host()
+    *
+    *	Defined in: drivers/scsi/scsi_scan.c
+    **/
+    void scsi_scan_host(struct Scsi_Host *shost)
+
+
+    /**
+    * scsi_track_queue_full - track successive QUEUE_FULL events on given
+    *                      device to determine if and when there is a need
+    *                      to adjust the queue depth on the device.
+    * @sdev:  pointer to SCSI device instance
+    * @depth: Current number of outstanding SCSI commands on this device,
+    *         not counting the one returned as QUEUE_FULL.
+    *
+    *      Returns 0  - no change needed
+    *              >0 - adjust queue depth to this new depth
+    *              -1 - drop back to untagged operation using host->cmd_per_lun
+    *                   as the untagged command depth
+    *
+    *      Might block: no
+    *
+    *      Notes: LLDs may call this at any time and we will do "The Right
+    *              Thing"; interrupt context safe.
+    *
+    *      Defined in: drivers/scsi/scsi.c .
+    **/
+    int scsi_track_queue_full(struct scsi_device *sdev, int depth)
+
+
+    /**
+    * scsi_unblock_requests - allow further commands to be queued to given host
+    *
+    * @shost: pointer to host to unblock commands on
+    *
+    *      Returns nothing
+    *
+    *      Might block: no
+    *
+    *      Defined in: drivers/scsi/scsi_lib.c .
+    **/
+    void scsi_unblock_requests(struct Scsi_Host * shost)
+
+
+    /**
+    * scsi_unregister - unregister and free memory used by host instance
+    * @shp:        pointer to scsi host instance to unregister.
+    *
+    *      Returns nothing
+    *
+    *      Might block: no
+    *
+    *      Notes: Should not be invoked if the "hotplug initialization
+    *      model" is being used. Called internally by exit_this_scsi_driver()
+    *      in the "passive initialization model". Hence a LLD has no need to
+    *      call this function directly.
+    *
+    *      Defined in: drivers/scsi/hosts.c .
+    **/
+    void scsi_unregister(struct Scsi_Host * shp)
+
+
+
+
+Interface Functions
+===================
+Interface functions are supplied (defined) by LLDs and their function
+pointers are placed in an instance of struct scsi_host_template which
+is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()].
+Some are mandatory. Interface functions should be declared static. The
+accepted convention is that driver "xyz" will declare its slave_configure()
+function as::
+
+    static int xyz_slave_configure(struct scsi_device * sdev);
+
+and so forth for all interface functions listed below.
+
+A pointer to this function should be placed in the 'slave_configure' member
+of a "struct scsi_host_template" instance. A pointer to such an instance
+should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
+init_this_scsi_driver()].
+
+The interface functions are also described in the include/scsi/scsi_host.h
+file immediately above their definition point in "struct scsi_host_template".
+In some cases more detail is given in scsi_host.h than below.
+
+The interface functions are listed below in alphabetical order.
+
+Summary:
+
+  - bios_param - fetch head, sector, cylinder info for a disk
+  - eh_timed_out - notify the host that a command timer expired
+  - eh_abort_handler - abort given command
+  - eh_bus_reset_handler - issue SCSI bus reset
+  - eh_device_reset_handler - issue SCSI device reset
+  - eh_host_reset_handler - reset host (host bus adapter)
+  - info - supply information about given host
+  - ioctl - driver can respond to ioctls
+  - proc_info - supports /proc/scsi/{driver_name}/{host_no}
+  - queuecommand - queue scsi command, invoke 'done' on completion
+  - slave_alloc - prior to any commands being sent to a new device
+  - slave_configure - driver fine tuning for given device after attach
+  - slave_destroy - given device is about to be shut down
+
+
+Details::
+
+    /**
+    *      bios_param - fetch head, sector, cylinder info for a disk
+    *      @sdev: pointer to scsi device context (defined in
+    *             include/scsi/scsi_device.h)
+    *      @bdev: pointer to block device context (defined in fs.h)
+    *      @capacity:  device size (in 512 byte sectors)
+    *      @params: three element array to place output:
+    *              params[0] number of heads (max 255)
+    *              params[1] number of sectors (max 63)
+    *              params[2] number of cylinders
+    *
+    *      Return value is ignored
+    *
+    *      Locks: none
+    *
+    *      Calling context: process (sd)
+    *
+    *      Notes: an arbitrary geometry (based on READ CAPACITY) is used
+    *      if this function is not provided. The params array is
+    *      pre-initialized with made up values just in case this function
+    *      doesn't output anything.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int bios_param(struct scsi_device * sdev, struct block_device *bdev,
+		    sector_t capacity, int params[3])
+
+
+    /**
+    *      eh_timed_out - The timer for the command has just fired
+    *      @scp: identifies command timing out
+    *
+    *      Returns:
+    *
+    *      EH_HANDLED:             I fixed the error, please complete the command
+    *      EH_RESET_TIMER:         I need more time, reset the timer and
+    *                              begin counting again
+    *      EH_NOT_HANDLED          Begin normal error recovery
+    *
+    *
+    *      Locks: None held
+    *
+    *      Calling context: interrupt
+    *
+    *      Notes: This is to give the LLD an opportunity to do local recovery.
+    *      This recovery is limited to determining if the outstanding command
+    *      will ever complete.  You may not abort and restart the command from
+    *      this callback.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int eh_timed_out(struct scsi_cmnd * scp)
+
+
+    /**
+    *      eh_abort_handler - abort command associated with scp
+    *      @scp: identifies command to be aborted
+    *
+    *      Returns SUCCESS if command aborted else FAILED
+    *
+    *      Locks: None held
+    *
+    *      Calling context: kernel thread
+    *
+    *      Notes: If 'no_async_abort' is defined this callback
+    *  	will be invoked from scsi_eh thread. No other commands
+    *	will then be queued on current host during eh.
+    *	Otherwise it will be called whenever scsi_times_out()
+    *      is called due to a command timeout.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int eh_abort_handler(struct scsi_cmnd * scp)
+
+
+    /**
+    *      eh_bus_reset_handler - issue SCSI bus reset
+    *      @scp: SCSI bus that contains this device should be reset
+    *
+    *      Returns SUCCESS if command aborted else FAILED
+    *
+    *      Locks: None held
+    *
+    *      Calling context: kernel thread
+    *
+    *      Notes: Invoked from scsi_eh thread. No other commands will be
+    *      queued on current host during eh.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int eh_bus_reset_handler(struct scsi_cmnd * scp)
+
+
+    /**
+    *      eh_device_reset_handler - issue SCSI device reset
+    *      @scp: identifies SCSI device to be reset
+    *
+    *      Returns SUCCESS if command aborted else FAILED
+    *
+    *      Locks: None held
+    *
+    *      Calling context: kernel thread
+    *
+    *      Notes: Invoked from scsi_eh thread. No other commands will be
+    *      queued on current host during eh.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int eh_device_reset_handler(struct scsi_cmnd * scp)
+
+
+    /**
+    *      eh_host_reset_handler - reset host (host bus adapter)
+    *      @scp: SCSI host that contains this device should be reset
+    *
+    *      Returns SUCCESS if command aborted else FAILED
+    *
+    *      Locks: None held
+    *
+    *      Calling context: kernel thread
+    *
+    *      Notes: Invoked from scsi_eh thread. No other commands will be
+    *      queued on current host during eh.
+    *      With the default eh_strategy in place, if none of the _abort_,
+    *      _device_reset_, _bus_reset_ or this eh handler function are
+    *      defined (or they all return FAILED) then the device in question
+    *      will be set offline whenever eh is invoked.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int eh_host_reset_handler(struct scsi_cmnd * scp)
+
+
+    /**
+    *      info - supply information about given host: driver name plus data
+    *             to distinguish given host
+    *      @shp: host to supply information about
+    *
+    *      Return ASCII null terminated string. [This driver is assumed to
+    *      manage the memory pointed to and maintain it, typically for the
+    *      lifetime of this host.]
+    *
+    *      Locks: none
+    *
+    *      Calling context: process
+    *
+    *      Notes: Often supplies PCI or ISA information such as IO addresses
+    *      and interrupt numbers. If not supplied struct Scsi_Host::name used
+    *      instead. It is assumed the returned information fits on one line
+    *      (i.e. does not included embedded newlines).
+    *      The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this
+    *      function (or struct Scsi_Host::name if this function is not
+    *      available).
+    *      In a similar manner, init_this_scsi_driver() outputs to the console
+    *      each host's "info" (or name) for the driver it is registering.
+    *      Also if proc_info() is not supplied, the output of this function
+    *      is used instead.
+    *
+    *      Optionally defined in: LLD
+    **/
+	const char * info(struct Scsi_Host * shp)
+
+
+    /**
+    *      ioctl - driver can respond to ioctls
+    *      @sdp: device that ioctl was issued for
+    *      @cmd: ioctl number
+    *      @arg: pointer to read or write data from. Since it points to
+    *            user space, should use appropriate kernel functions
+    *            (e.g. copy_from_user() ). In the Unix style this argument
+    *            can also be viewed as an unsigned long.
+    *
+    *      Returns negative "errno" value when there is a problem. 0 or a
+    *      positive value indicates success and is returned to the user space.
+    *
+    *      Locks: none
+    *
+    *      Calling context: process
+    *
+    *      Notes: The SCSI subsystem uses a "trickle down" ioctl model.
+    *      The user issues an ioctl() against an upper level driver
+    *      (e.g. /dev/sdc) and if the upper level driver doesn't recognize
+    *      the 'cmd' then it is passed to the SCSI mid level. If the SCSI
+    *      mid level does not recognize it, then the LLD that controls
+    *      the device receives the ioctl. According to recent Unix standards
+    *      unsupported ioctl() 'cmd' numbers should return -ENOTTY.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int ioctl(struct scsi_device *sdp, int cmd, void *arg)
+
+
+    /**
+    *      proc_info - supports /proc/scsi/{driver_name}/{host_no}
+    *      @buffer: anchor point to output to (0==writeto1_read0) or fetch from
+    *               (1==writeto1_read0).
+    *      @start: where "interesting" data is written to. Ignored when
+    *              1==writeto1_read0.
+    *      @offset: offset within buffer 0==writeto1_read0 is actually
+    *               interested in. Ignored when 1==writeto1_read0 .
+    *      @length: maximum (or actual) extent of buffer
+    *      @host_no: host number of interest (struct Scsi_Host::host_no)
+    *      @writeto1_read0: 1 -> data coming from user space towards driver
+    *                            (e.g. "echo some_string > /proc/scsi/xyz/2")
+    *                       0 -> user what data from this driver
+    *                            (e.g. "cat /proc/scsi/xyz/2")
+    *
+    *      Returns length when 1==writeto1_read0. Otherwise number of chars
+    *      output to buffer past offset.
+    *
+    *      Locks: none held
+    *
+    *      Calling context: process
+    *
+    *      Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs
+    *      support can now be configured out of the scsi subsystem.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int proc_info(char * buffer, char ** start, off_t offset,
+		    int length, int host_no, int writeto1_read0)
+
+
+    /**
+    *      queuecommand - queue scsi command, invoke scp->scsi_done on completion
+    *      @shost: pointer to the scsi host object
+    *      @scp: pointer to scsi command object
+    *
+    *      Returns 0 on success.
+    *
+    *      If there's a failure, return either:
+    *
+    *      SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
+    *      SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full
+    *
+    *      On both of these returns, the mid-layer will requeue the I/O
+    *
+    *      - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
+    *      device will be paused, and it will be unpaused when a command to
+    *      the device returns (or after a brief delay if there are no more
+    *      outstanding commands to it).  Commands to other devices continue
+    *      to be processed normally.
+    *
+    *      - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
+    *      is paused and will be unpaused when any command returns from
+    *      the host (or after a brief delay if there are no outstanding
+    *      commands to the host).
+    *
+    *      For compatibility with earlier versions of queuecommand, any
+    *      other return value is treated the same as
+    *      SCSI_MLQUEUE_HOST_BUSY.
+    *
+    *      Other types of errors that are detected immediately may be
+    *      flagged by setting scp->result to an appropriate value,
+    *      invoking the scp->scsi_done callback, and then returning 0
+    *      from this function. If the command is not performed
+    *      immediately (and the LLD is starting (or will start) the given
+    *      command) then this function should place 0 in scp->result and
+    *      return 0.
+    *
+    *      Command ownership.  If the driver returns zero, it owns the
+    *      command and must take responsibility for ensuring the
+    *      scp->scsi_done callback is executed.  Note: the driver may
+    *      call scp->scsi_done before returning zero, but after it has
+    *      called scp->scsi_done, it may not return any value other than
+    *      zero.  If the driver makes a non-zero return, it must not
+    *      execute the command's scsi_done callback at any time.
+    *
+    *      Locks: up to and including 2.6.36, struct Scsi_Host::host_lock
+    *             held on entry (with "irqsave") and is expected to be
+    *             held on return. From 2.6.37 onwards, queuecommand is
+    *             called without any locks held.
+    *
+    *      Calling context: in interrupt (soft irq) or process context
+    *
+    *      Notes: This function should be relatively fast. Normally it
+    *      will not wait for IO to complete. Hence the scp->scsi_done
+    *      callback is invoked (often directly from an interrupt service
+    *      routine) some time after this function has returned. In some
+    *      cases (e.g. pseudo adapter drivers that manufacture the
+    *      response to a SCSI INQUIRY) the scp->scsi_done callback may be
+    *      invoked before this function returns.  If the scp->scsi_done
+    *      callback is not invoked within a certain period the SCSI mid
+    *      level will commence error processing.  If a status of CHECK
+    *      CONDITION is placed in "result" when the scp->scsi_done
+    *      callback is invoked, then the LLD driver should perform
+    *      autosense and fill in the struct scsi_cmnd::sense_buffer
+    *      array. The scsi_cmnd::sense_buffer array is zeroed prior to
+    *      the mid level queuing a command to an LLD.
+    *
+    *      Defined in: LLD
+    **/
+	int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp)
+
+
+    /**
+    *      slave_alloc -   prior to any commands being sent to a new device
+    *                      (i.e. just prior to scan) this call is made
+    *      @sdp: pointer to new device (about to be scanned)
+    *
+    *      Returns 0 if ok. Any other return is assumed to be an error and
+    *      the device is ignored.
+    *
+    *      Locks: none
+    *
+    *      Calling context: process
+    *
+    *      Notes: Allows the driver to allocate any resources for a device
+    *      prior to its initial scan. The corresponding scsi device may not
+    *      exist but the mid level is just about to scan for it (i.e. send
+    *      and INQUIRY command plus ...). If a device is found then
+    *      slave_configure() will be called while if a device is not found
+    *      slave_destroy() is called.
+    *      For more details see the include/scsi/scsi_host.h file.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int slave_alloc(struct scsi_device *sdp)
+
+
+    /**
+    *      slave_configure - driver fine tuning for given device just after it
+    *                     has been first scanned (i.e. it responded to an
+    *                     INQUIRY)
+    *      @sdp: device that has just been attached
+    *
+    *      Returns 0 if ok. Any other return is assumed to be an error and
+    *      the device is taken offline. [offline devices will _not_ have
+    *      slave_destroy() called on them so clean up resources.]
+    *
+    *      Locks: none
+    *
+    *      Calling context: process
+    *
+    *      Notes: Allows the driver to inspect the response to the initial
+    *      INQUIRY done by the scanning code and take appropriate action.
+    *      For more details see the include/scsi/scsi_host.h file.
+    *
+    *      Optionally defined in: LLD
+    **/
+	int slave_configure(struct scsi_device *sdp)
+
+
+    /**
+    *      slave_destroy - given device is about to be shut down. All
+    *                      activity has ceased on this device.
+    *      @sdp: device that is about to be shut down
+    *
+    *      Returns nothing
+    *
+    *      Locks: none
+    *
+    *      Calling context: process
+    *
+    *      Notes: Mid level structures for given device are still in place
+    *      but are about to be torn down. Any per device resources allocated
+    *      by this driver for given device should be freed now. No further
+    *      commands will be sent for this sdp instance. [However the device
+    *      could be re-attached in the future in which case a new instance
+    *      of struct scsi_device would be supplied by future slave_alloc()
+    *      and slave_configure() calls.]
+    *
+    *      Optionally defined in: LLD
+    **/
+	void slave_destroy(struct scsi_device *sdp)
+
+
+
+Data Structures
+===============
+struct scsi_host_template
+-------------------------
+There is one "struct scsi_host_template" instance per LLD [#]_. It is
+typically initialized as a file scope static in a driver's header file. That
+way members that are not explicitly initialized will be set to 0 or NULL.
+Member of interest:
+
+    name
+		 - name of driver (may contain spaces, please limit to
+                   less than 80 characters)
+
+    proc_name
+		 - name used in "/proc/scsi/<proc_name>/<host_no>" and
+                   by sysfs in one of its "drivers" directories. Hence
+                   "proc_name" should only contain characters acceptable
+                   to a Unix file name.
+
+   ``(*queuecommand)()``
+		 - primary callback that the mid level uses to inject
+                   SCSI commands into an LLD.
+
+The structure is defined and commented in include/scsi/scsi_host.h
+
+.. [#] In extreme situations a single driver may have several instances
+       if it controls several different classes of hardware (e.g. an LLD
+       that handles both ISA and PCI cards and has a separate instance of
+       struct scsi_host_template for each class).
+
+struct Scsi_Host
+----------------
+There is one struct Scsi_Host instance per host (HBA) that an LLD
+controls. The struct Scsi_Host structure has many members in common
+with "struct scsi_host_template". When a new struct Scsi_Host instance
+is created (in scsi_host_alloc() in hosts.c) those common members are
+initialized from the driver's struct scsi_host_template instance. Members
+of interest:
+
+    host_no
+		 - system wide unique number that is used for identifying
+                   this host. Issued in ascending order from 0.
+    can_queue
+		 - must be greater than 0; do not send more than can_queue
+                   commands to the adapter.
+    this_id
+		 - scsi id of host (scsi initiator) or -1 if not known
+    sg_tablesize
+		 - maximum scatter gather elements allowed by host.
+                   Set this to SG_ALL or less to avoid chained SG lists.
+                   Must be at least 1.
+    max_sectors
+		 - maximum number of sectors (usually 512 bytes) allowed
+                   in a single SCSI command. The default value of 0 leads
+                   to a setting of SCSI_DEFAULT_MAX_SECTORS (defined in
+                   scsi_host.h) which is currently set to 1024. So for a
+                   disk the maximum transfer size is 512 KB when max_sectors
+                   is not defined. Note that this size may not be sufficient
+                   for disk firmware uploads.
+    cmd_per_lun
+		 - maximum number of commands that can be queued on devices
+                   controlled by the host. Overridden by LLD calls to
+                   scsi_change_queue_depth().
+    unchecked_isa_dma
+		 - 1=>only use bottom 16 MB of ram (ISA DMA addressing
+                   restriction), 0=>can use full 32 bit (or better) DMA
+                   address space
+    no_async_abort
+		 - 1=>Asynchronous aborts are not supported
+		 - 0=>Timed-out commands will be aborted asynchronously
+    hostt
+		 - pointer to driver's struct scsi_host_template from which
+                   this struct Scsi_Host instance was spawned
+    hostt->proc_name
+		 - name of LLD. This is the driver name that sysfs uses
+    transportt
+		 - pointer to driver's struct scsi_transport_template instance
+                   (if any). FC and SPI transports currently supported.
+    sh_list
+		 - a double linked list of pointers to all struct Scsi_Host
+                   instances (currently ordered by ascending host_no)
+    my_devices
+		 - a double linked list of pointers to struct scsi_device
+                   instances that belong to this host.
+    hostdata[0]
+		 - area reserved for LLD at end of struct Scsi_Host. Size
+                   is set by the second argument (named 'xtr_bytes') to
+                   scsi_host_alloc() or scsi_register().
+    vendor_id
+		 - a unique value that identifies the vendor supplying
+                   the LLD for the Scsi_Host.  Used most often in validating
+                   vendor-specific message requests.  Value consists of an
+                   identifier type and a vendor-specific value.
+                   See scsi_netlink.h for a description of valid formats.
+
+The scsi_host structure is defined in include/scsi/scsi_host.h
+
+struct scsi_device
+------------------
+Generally, there is one instance of this structure for each SCSI logical unit
+on a host. Scsi devices connected to a host are uniquely identified by a
+channel number, target id and logical unit number (lun).
+The structure is defined in include/scsi/scsi_device.h
+
+struct scsi_cmnd
+----------------
+Instances of this structure convey SCSI commands to the LLD and responses
+back to the mid level. The SCSI mid level will ensure that no more SCSI
+commands become queued against the LLD than are indicated by
+scsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will
+be at least one instance of struct scsi_cmnd available for each SCSI device.
+Members of interest:
+
+    cmnd
+		 - array containing SCSI command
+    cmnd_len
+		 - length (in bytes) of SCSI command
+    sc_data_direction
+		 - direction of data transfer in data phase. See
+                   "enum dma_data_direction" in include/linux/dma-mapping.h
+    request_bufflen
+		 - number of data bytes to transfer (0 if no data phase)
+    use_sg
+		 - ==0 -> no scatter gather list, hence transfer data
+                          to/from request_buffer
+                 - >0 ->  scatter gather list (actually an array) in
+                          request_buffer with use_sg elements
+    request_buffer
+		   - either contains data buffer or scatter gather list
+                     depending on the setting of use_sg. Scatter gather
+                     elements are defined by 'struct scatterlist' found
+                     in include/linux/scatterlist.h .
+    done
+		 - function pointer that should be invoked by LLD when the
+                   SCSI command is completed (successfully or otherwise).
+                   Should only be called by an LLD if the LLD has accepted
+                   the command (i.e. queuecommand() returned or will return
+                   0). The LLD may invoke 'done'  prior to queuecommand()
+                   finishing.
+    result
+		 - should be set by LLD prior to calling 'done'. A value
+                   of 0 implies a successfully completed command (and all
+                   data (if any) has been transferred to or from the SCSI
+                   target device). 'result' is a 32 bit unsigned integer that
+                   can be viewed as 4 related bytes. The SCSI status value is
+                   in the LSB. See include/scsi/scsi.h status_byte(),
+                   msg_byte(), host_byte() and driver_byte() macros and
+                   related constants.
+    sense_buffer
+		 - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
+                   should be written when the SCSI status (LSB of 'result')
+                   is set to CHECK_CONDITION (2). When CHECK_CONDITION is
+                   set, if the top nibble of sense_buffer[0] has the value 7
+                   then the mid level will assume the sense_buffer array
+                   contains a valid SCSI sense buffer; otherwise the mid
+                   level will issue a REQUEST_SENSE SCSI command to
+                   retrieve the sense buffer. The latter strategy is error
+                   prone in the presence of command queuing so the LLD should
+                   always "auto-sense".
+    device
+		 - pointer to scsi_device object that this command is
+                   associated with.
+    resid
+		 - an LLD should set this signed integer to the requested
+                   transfer length (i.e. 'request_bufflen') less the number
+                   of bytes that are actually transferred. 'resid' is
+                   preset to 0 so an LLD can ignore it if it cannot detect
+                   underruns (overruns should be rare). If possible an LLD
+                   should set 'resid' prior to invoking 'done'. The most
+                   interesting case is data transfers from a SCSI target
+                   device (e.g. READs) that underrun.
+    underflow
+		 - LLD should place (DID_ERROR << 16) in 'result' if
+                   actual number of bytes transferred is less than this
+                   figure. Not many LLDs implement this check and some that
+                   do just output an error message to the log rather than
+                   report a DID_ERROR. Better for an LLD to implement
+                   'resid'.
+
+It is recommended that a LLD set 'resid' on data transfers from a SCSI
+target device (e.g. READs). It is especially important that 'resid' is set
+when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR
+(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much
+data has been received then the safest approach is to indicate no bytes have
+been received. For example: to indicate that no valid data has been received
+a LLD might use these helpers::
+
+    scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
+
+where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512
+bytes blocks has been received 'resid' could be set like this::
+
+    scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
+
+The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h
+
+
+Locks
+=====
+Each struct Scsi_Host instance has a spin_lock called struct
+Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in
+hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
+is initialized to point at default_lock.  Thereafter lock and unlock
+operations performed by the mid level use the struct Scsi_Host::host_lock
+pointer.  Previously drivers could override the host_lock pointer but
+this is not allowed anymore.
+
+
+Autosense
+=========
+Autosense (or auto-sense) is defined in the SAM-2 document as "the
+automatic return of sense data to the application client coincident
+with the completion of a SCSI command" when a status of CHECK CONDITION
+occurs. LLDs should perform autosense. This should be done when the LLD
+detects a CHECK CONDITION status by either:
+
+    a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
+       to perform an extra data in phase on such responses
+    b) or, the LLD issuing a REQUEST SENSE command itself
+
+Either way, when a status of CHECK CONDITION is detected, the mid level
+decides whether the LLD has performed autosense by checking struct
+scsi_cmnd::sense_buffer[0] . If this byte has an upper nibble of 7 (or 0xf)
+then autosense is assumed to have taken place. If it has another value (and
+this byte is initialized to 0 before each command) then the mid level will
+issue a REQUEST SENSE command.
+
+In the presence of queued commands the "nexus" that maintains sense
+buffer data from the command that failed until a following REQUEST SENSE
+may get out of synchronization. This is why it is best for the LLD
+to perform autosense.
+
+
+Changes since lk 2.4 series
+===========================
+io_request_lock has been replaced by several finer grained locks. The lock
+relevant to LLDs is struct Scsi_Host::host_lock and there is
+one per SCSI host.
+
+The older error handling mechanism has been removed. This means the
+LLD interface functions abort() and reset() have been removed.
+The struct scsi_host_template::use_new_eh_code flag has been removed.
+
+In the 2.4 series the SCSI subsystem configuration descriptions were
+aggregated with the configuration descriptions from all other Linux
+subsystems in the Documentation/Configure.help file. In the 2.6 series,
+the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig
+file that contains both configuration and help information.
+
+struct SHT has been renamed to struct scsi_host_template.
+
+Addition of the "hotplug initialization model" and many extra functions
+to support it.
+
+
+Credits
+=======
+The following people have contributed to this document:
+
+	- Mike Anderson <andmike at us dot ibm dot com>
+	- James Bottomley <James dot Bottomley at hansenpartnership dot com>
+	- Patrick Mansfield <patmans at us dot ibm dot com>
+	- Christoph Hellwig <hch at infradead dot org>
+	- Doug Ledford <dledford at redhat dot com>
+	- Andries Brouwer <Andries dot Brouwer at cwi dot nl>
+	- Randy Dunlap <rdunlap at xenotime dot net>
+	- Alan Stern <stern at rowland dot harvard dot edu>
+
+
+Douglas Gilbert
+dgilbert at interlog dot com
+
+21st September 2004
diff --git a/Documentation/scsi/scsi_mid_low_api.txt b/Documentation/scsi/scsi_mid_low_api.txt
deleted file mode 100644
index 537f04728487..000000000000
--- a/Documentation/scsi/scsi_mid_low_api.txt
+++ /dev/null
@@ -1,1259 +0,0 @@
-                          Linux Kernel 2.6 series
-                 SCSI mid_level - lower_level driver interface
-                 =============================================
-
-Introduction
-============
-This document outlines the interface between the Linux SCSI mid level and
-SCSI lower level drivers. Lower level drivers (LLDs) are variously called 
-host bus adapter (HBA) drivers and host drivers (HD). A "host" in this
-context is a bridge between a computer IO bus (e.g. PCI or ISA) and a
-single SCSI initiator port on a SCSI transport. An "initiator" port
-(SCSI terminology, see SAM-3 at http://www.t10.org) sends SCSI commands
-to "target" SCSI ports (e.g. disks). There can be many LLDs in a running
-system, but only one per hardware type. Most LLDs can control one or more
-SCSI HBAs. Some HBAs contain multiple hosts.
-
-In some cases the SCSI transport is an external bus that already has
-its own subsystem in Linux (e.g. USB and ieee1394). In such cases the
-SCSI subsystem LLD is a software bridge to the other driver subsystem.
-Examples are the usb-storage driver (found in the drivers/usb/storage
-directory) and the ieee1394/sbp2 driver (found in the drivers/ieee1394
-directory).
-
-For example, the aic7xxx LLD controls Adaptec SCSI parallel interface
-(SPI) controllers based on that company's 7xxx chip series. The aic7xxx
-LLD can be built into the kernel or loaded as a module. There can only be
-one aic7xxx LLD running in a Linux system but it may be controlling many 
-HBAs. These HBAs might be either on PCI daughter-boards or built into 
-the motherboard (or both). Some aic7xxx based HBAs are dual controllers
-and thus represent two hosts. Like most modern HBAs, each aic7xxx host
-has its own PCI device address. [The one-to-one correspondence between
-a SCSI host and a PCI device is common but not required (e.g. with
-ISA adapters).]
-
-The SCSI mid level isolates an LLD from other layers such as the SCSI
-upper layer drivers and the block layer.
-
-This version of the document roughly matches linux kernel version 2.6.8 .
-
-Documentation
-=============
-There is a SCSI documentation directory within the kernel source tree, 
-typically Documentation/scsi . Most documents are in plain
-(i.e. ASCII) text. This file is named scsi_mid_low_api.txt and can be 
-found in that directory. A more recent copy of this document may be found
-at http://web.archive.org/web/20070107183357rn_1/sg.torque.net/scsi/. 
-Many LLDs are documented there (e.g. aic7xxx.txt). The SCSI mid-level is
-briefly described in scsi.txt which contains a url to a document 
-describing the SCSI subsystem in the lk 2.4 series. Two upper level 
-drivers have documents in that directory: st.txt (SCSI tape driver) and 
-scsi-generic.txt (for the sg driver).
-
-Some documentation (or urls) for LLDs may be found in the C source code
-or in the same directory as the C source code. For example to find a url
-about the USB mass storage driver see the 
-/usr/src/linux/drivers/usb/storage directory.
-
-Driver structure
-================
-Traditionally an LLD for the SCSI subsystem has been at least two files in
-the drivers/scsi directory. For example, a driver called "xyz" has a header
-file "xyz.h" and a source file "xyz.c". [Actually there is no good reason
-why this couldn't all be in one file; the header file is superfluous.] Some
-drivers that have been ported to several operating systems have more than
-two files. For example the aic7xxx driver has separate files for generic 
-and OS-specific code (e.g. FreeBSD and Linux). Such drivers tend to have
-their own directory under the drivers/scsi directory.
-
-When a new LLD is being added to Linux, the following files (found in the
-drivers/scsi directory) will need some attention: Makefile and Kconfig .
-It is probably best to study how existing LLDs are organized.
-
-As the 2.5 series development kernels evolve into the 2.6 series
-production series, changes are being introduced into this interface. An
-example of this is driver initialization code where there are now 2 models
-available. The older one, similar to what was found in the lk 2.4 series,
-is based on hosts that are detected at HBA driver load time. This will be
-referred to the "passive" initialization model. The newer model allows HBAs
-to be hot plugged (and unplugged) during the lifetime of the LLD and will
-be referred to as the "hotplug" initialization model. The newer model is
-preferred as it can handle both traditional SCSI equipment that is
-permanently connected as well as modern "SCSI" devices (e.g. USB or
-IEEE 1394 connected digital cameras) that are hotplugged. Both 
-initialization models are discussed in the following sections.
-
-An LLD interfaces to the SCSI subsystem several ways:
-  a) directly invoking functions supplied by the mid level
-  b) passing a set of function pointers to a registration function
-     supplied by the mid level. The mid level will then invoke these
-     functions at some point in the future. The LLD will supply
-     implementations of these functions.
-  c) direct access to instances of well known data structures maintained
-     by the mid level
-
-Those functions in group a) are listed in a section entitled "Mid level
-supplied functions" below.
-
-Those functions in group b) are listed in a section entitled "Interface
-functions" below. Their function pointers are placed in the members of
-"struct scsi_host_template", an instance of which is passed to
-scsi_host_alloc() ** .  Those interface functions that the LLD does not 
-wish to supply should have NULL placed in the corresponding member of 
-struct scsi_host_template.  Defining an instance of struct 
-scsi_host_template at file scope will cause NULL to be  placed in function
- pointer members not explicitly initialized.
-
-Those usages in group c) should be handled with care, especially in a
-"hotplug" environment. LLDs should be aware of the lifetime of instances
-that are shared with the mid level and other layers.
-
-All functions defined within an LLD and all data defined at file scope
-should be static. For example the slave_alloc() function in an LLD
-called "xxx" could be defined as 
-"static int xxx_slave_alloc(struct scsi_device * sdev) { /* code */ }"
-
-** the scsi_host_alloc() function is a replacement for the rather vaguely
-named scsi_register() function in most situations.
-
-
-Hotplug initialization model
-============================
-In this model an LLD controls when SCSI hosts are introduced and removed
-from the SCSI subsystem. Hosts can be introduced as early as driver
-initialization and removed as late as driver shutdown. Typically a driver
-will respond to a sysfs probe() callback that indicates an HBA has been
-detected. After confirming that the new device is one that the LLD wants
-to control, the LLD will initialize the HBA and then register a new host
-with the SCSI mid level.
-
-During LLD initialization the driver should register itself with the
-appropriate IO bus on which it expects to find HBA(s) (e.g. the PCI bus).
-This can probably be done via sysfs. Any driver parameters (especially
-those that are writable after the driver is loaded) could also be
-registered with sysfs at this point. The SCSI mid level first becomes
-aware of an LLD when that LLD registers its first HBA.
-
-At some later time, the LLD becomes aware of an HBA and what follows
-is a typical sequence of calls between the LLD and the mid level.
-This example shows the mid level scanning the newly introduced HBA for 3 
-scsi devices of which only the first 2 respond:
-
-     HBA PROBE: assume 2 SCSI devices found in scan
-LLD                   mid level                    LLD
-===-------------------=========--------------------===------
-scsi_host_alloc()  -->
-scsi_add_host()  ---->
-scsi_scan_host()  -------+
-                         |
-                    slave_alloc()
-                    slave_configure() -->  scsi_change_queue_depth()
-                         |
-                    slave_alloc()
-                    slave_configure()
-                         |
-                    slave_alloc()   ***
-                    slave_destroy() ***
-------------------------------------------------------------
-
-If the LLD wants to adjust the default queue settings, it can invoke
-scsi_change_queue_depth() in its slave_configure() routine.
-
-*** For scsi devices that the mid level tries to scan but do not
-    respond, a slave_alloc(), slave_destroy() pair is called.
-
-When an HBA is being removed it could be as part of an orderly shutdown
-associated with the LLD module being unloaded (e.g. with the "rmmod"
-command) or in response to a "hot unplug" indicated by sysfs()'s
-remove() callback being invoked. In either case, the sequence is the
-same:
-
-        HBA REMOVE: assume 2 SCSI devices attached
-LLD                      mid level                 LLD
-===----------------------=========-----------------===------
-scsi_remove_host() ---------+
-                            |
-                     slave_destroy()
-                     slave_destroy()
-scsi_host_put()
-------------------------------------------------------------
-                     
-It may be useful for a LLD to keep track of struct Scsi_Host instances
-(a pointer is returned by scsi_host_alloc()). Such instances are "owned"
-by the mid-level.  struct Scsi_Host instances are freed from
-scsi_host_put() when the reference count hits zero.
-
-Hot unplugging an HBA that controls a disk which is processing SCSI
-commands on a mounted file system is an interesting situation. Reference
-counting logic is being introduced into the mid level to cope with many
-of the issues involved. See the section on reference counting below.
-
-
-The hotplug concept may be extended to SCSI devices. Currently, when an
-HBA is added, the scsi_scan_host() function causes a scan for SCSI devices
-attached to the HBA's SCSI transport. On newer SCSI transports the HBA
-may become aware of a new SCSI device _after_ the scan has completed.
-An LLD can use this sequence to make the mid level aware of a SCSI device:
-
-                 SCSI DEVICE hotplug
-LLD                   mid level                    LLD
-===-------------------=========--------------------===------
-scsi_add_device()  ------+
-                         |
-                    slave_alloc()
-                    slave_configure()   [--> scsi_change_queue_depth()]
-------------------------------------------------------------
-
-In a similar fashion, an LLD may become aware that a SCSI device has been
-removed (unplugged) or the connection to it has been interrupted. Some
-existing SCSI transports (e.g. SPI) may not become aware that a SCSI
-device has been removed until a subsequent SCSI command fails which will
-probably cause that device to be set offline by the mid level. An LLD that
-detects the removal of a SCSI device can instigate its removal from
-upper layers with this sequence:
-
-                  SCSI DEVICE hot unplug
-LLD                      mid level                 LLD
-===----------------------=========-----------------===------
-scsi_remove_device() -------+
-                            |
-                     slave_destroy()
-------------------------------------------------------------
-
-It may be useful for an LLD to keep track of struct scsi_device instances
-(a pointer is passed as the parameter to slave_alloc() and
-slave_configure() callbacks). Such instances are "owned" by the mid-level.
-struct scsi_device instances are freed after slave_destroy().
-
-
-Reference Counting
-==================
-The Scsi_Host structure has had reference counting infrastructure added.
-This effectively spreads the ownership of struct Scsi_Host instances
-across the various SCSI layers which use them. Previously such instances
-were exclusively owned by the mid level. LLDs would not usually need to
-directly manipulate these reference counts but there may be some cases
-where they do.
-
-There are 3 reference counting functions of interest associated with
-struct Scsi_Host:
-  - scsi_host_alloc(): returns a pointer to new instance of struct 
-        Scsi_Host which has its reference count ^^ set to 1
-  - scsi_host_get(): adds 1 to the reference count of the given instance
-  - scsi_host_put(): decrements 1 from the reference count of the given
-        instance. If the reference count reaches 0 then the given instance
-        is freed
-
-The scsi_device structure has had reference counting infrastructure added.
-This effectively spreads the ownership of struct scsi_device instances
-across the various SCSI layers which use them. Previously such instances
-were exclusively owned by the mid level. See the access functions declared
-towards the end of include/scsi/scsi_device.h . If an LLD wants to keep
-a copy of a pointer to a scsi_device instance it should use scsi_device_get()
-to bump its reference count. When it is finished with the pointer it can
-use scsi_device_put() to decrement its reference count (and potentially
-delete it).
-
-^^ struct Scsi_Host actually has 2 reference counts which are manipulated
-in parallel by these functions.
-
-
-Conventions
-===========
-First, Linus Torvalds's thoughts on C coding style can be found in the
-Documentation/process/coding-style.rst file.
-
-Next, there is a movement to "outlaw" typedefs introducing synonyms for 
-struct tags. Both can be still found in the SCSI subsystem, but
-the typedefs have been moved to a single file, scsi_typedefs.h to
-make their future removal easier, for example: 
-"typedef struct scsi_cmnd Scsi_Cmnd;"
-
-Also, most C99 enhancements are encouraged to the extent they are supported
-by the relevant gcc compilers. So C99 style structure and array
-initializers are encouraged where appropriate. Don't go too far,
-VLAs are not properly supported yet.  An exception to this is the use of
-"//" style comments; /*...*/ comments are still preferred in Linux.
-
-Well written, tested and documented code, need not be re-formatted to
-comply with the above conventions. For example, the aic7xxx driver
-comes to Linux from FreeBSD and Adaptec's own labs. No doubt FreeBSD
-and Adaptec have their own coding conventions.
-
-
-Mid level supplied functions
-============================
-These functions are supplied by the SCSI mid level for use by LLDs.
-The names (i.e. entry points) of these functions are exported 
-so an LLD that is a module can access them. The kernel will
-arrange for the SCSI mid level to be loaded and initialized before any LLD
-is initialized. The functions below are listed alphabetically and their
-names all start with "scsi_".
-
-Summary:
-   scsi_add_device - creates new scsi device (lu) instance
-   scsi_add_host - perform sysfs registration and set up transport class
-   scsi_change_queue_depth - change the queue depth on a SCSI device
-   scsi_bios_ptable - return copy of block device's partition table
-   scsi_block_requests - prevent further commands being queued to given host
-   scsi_host_alloc - return a new scsi_host instance whose refcount==1
-   scsi_host_get - increments Scsi_Host instance's refcount
-   scsi_host_put - decrements Scsi_Host instance's refcount (free if 0)
-   scsi_register - create and register a scsi host adapter instance.
-   scsi_remove_device - detach and remove a SCSI device
-   scsi_remove_host - detach and remove all SCSI devices owned by host
-   scsi_report_bus_reset - report scsi _bus_ reset observed
-   scsi_scan_host - scan SCSI bus
-   scsi_track_queue_full - track successive QUEUE_FULL events 
-   scsi_unblock_requests - allow further commands to be queued to given host
-   scsi_unregister - [calls scsi_host_put()]
-
-
-Details:
-
-/**
- * scsi_add_device - creates new scsi device (lu) instance
- * @shost:   pointer to scsi host instance
- * @channel: channel number (rarely other than 0)
- * @id:      target id number
- * @lun:     logical unit number
- *
- *      Returns pointer to new struct scsi_device instance or 
- *      ERR_PTR(-ENODEV) (or some other bent pointer) if something is
- *      wrong (e.g. no lu responds at given address)
- *
- *      Might block: yes
- *
- *      Notes: This call is usually performed internally during a scsi
- *      bus scan when an HBA is added (i.e. scsi_scan_host()). So it
- *      should only be called if the HBA becomes aware of a new scsi
- *      device (lu) after scsi_scan_host() has completed. If successful
- *      this call can lead to slave_alloc() and slave_configure() callbacks
- *      into the LLD.
- *
- *      Defined in: drivers/scsi/scsi_scan.c
- **/
-struct scsi_device * scsi_add_device(struct Scsi_Host *shost, 
-                                     unsigned int channel,
-                                     unsigned int id, unsigned int lun)
-
-
-/**
- * scsi_add_host - perform sysfs registration and set up transport class
- * @shost:   pointer to scsi host instance
- * @dev:     pointer to struct device of type scsi class
- *
- *      Returns 0 on success, negative errno of failure (e.g. -ENOMEM)
- *
- *      Might block: no
- *
- *      Notes: Only required in "hotplug initialization model" after a
- *      successful call to scsi_host_alloc().  This function does not
- *	scan the bus; this can be done by calling scsi_scan_host() or
- *	in some other transport-specific way.  The LLD must set up
- *	the transport template before calling this function and may only
- *	access the transport class data after this function has been called.
- *
- *      Defined in: drivers/scsi/hosts.c
- **/
-int scsi_add_host(struct Scsi_Host *shost, struct device * dev)
-
-
-/**
- * scsi_change_queue_depth - allow LLD to change queue depth on a SCSI device
- * @sdev:       pointer to SCSI device to change queue depth on
- * @tags        Number of tags allowed if tagged queuing enabled,
- *              or number of commands the LLD can queue up
- *              in non-tagged mode (as per cmd_per_lun).
- *
- *      Returns nothing
- *
- *      Might block: no
- *
- *      Notes: Can be invoked any time on a SCSI device controlled by this
- *      LLD. [Specifically during and after slave_configure() and prior to
- *      slave_destroy().] Can safely be invoked from interrupt code.
- *
- *      Defined in: drivers/scsi/scsi.c [see source code for more notes]
- *
- **/
-int scsi_change_queue_depth(struct scsi_device *sdev, int tags)
-
-
-/**
- * scsi_bios_ptable - return copy of block device's partition table
- * @dev:        pointer to block device
- *
- *      Returns pointer to partition table, or NULL for failure
- *
- *      Might block: yes
- *
- *      Notes: Caller owns memory returned (free with kfree() )
- *
- *      Defined in: drivers/scsi/scsicam.c
- **/
-unsigned char *scsi_bios_ptable(struct block_device *dev)
-
-
-/**
- * scsi_block_requests - prevent further commands being queued to given host
- *
- * @shost: pointer to host to block commands on
- *
- *      Returns nothing
- *
- *      Might block: no
- *
- *      Notes: There is no timer nor any other means by which the requests
- *      get unblocked other than the LLD calling scsi_unblock_requests().
- *
- *      Defined in: drivers/scsi/scsi_lib.c
-**/
-void scsi_block_requests(struct Scsi_Host * shost)
-
-
-/**
- * scsi_host_alloc - create a scsi host adapter instance and perform basic
- *                   initialization.
- * @sht:        pointer to scsi host template
- * @privsize:   extra bytes to allocate in hostdata array (which is the
- *              last member of the returned Scsi_Host instance)
- *
- *      Returns pointer to new Scsi_Host instance or NULL on failure
- *
- *      Might block: yes
- *
- *      Notes: When this call returns to the LLD, the SCSI bus scan on
- *      this host has _not_ yet been done.
- *      The hostdata array (by default zero length) is a per host scratch 
- *      area for the LLD's exclusive use.
- *      Both associated refcounting objects have their refcount set to 1.
- *      Full registration (in sysfs) and a bus scan are performed later when
- *      scsi_add_host() and scsi_scan_host() are called.
- *
- *      Defined in: drivers/scsi/hosts.c .
- **/
-struct Scsi_Host * scsi_host_alloc(struct scsi_host_template * sht,
-                                   int privsize)
-
-
-/**
- * scsi_host_get - increment Scsi_Host instance refcount
- * @shost:   pointer to struct Scsi_Host instance
- *
- *      Returns nothing
- *
- *      Might block: currently may block but may be changed to not block
- *
- *      Notes: Actually increments the counts in two sub-objects
- *
- *      Defined in: drivers/scsi/hosts.c
- **/
-void scsi_host_get(struct Scsi_Host *shost)
-
-
-/**
- * scsi_host_put - decrement Scsi_Host instance refcount, free if 0
- * @shost:   pointer to struct Scsi_Host instance
- *
- *      Returns nothing
- *
- *      Might block: currently may block but may be changed to not block
- *
- *      Notes: Actually decrements the counts in two sub-objects. If the
- *      latter refcount reaches 0, the Scsi_Host instance is freed.
- *      The LLD need not worry exactly when the Scsi_Host instance is
- *      freed, it just shouldn't access the instance after it has balanced
- *      out its refcount usage.
- *
- *      Defined in: drivers/scsi/hosts.c
- **/
-void scsi_host_put(struct Scsi_Host *shost)
-
-
-/**
- * scsi_register - create and register a scsi host adapter instance.
- * @sht:        pointer to scsi host template
- * @privsize:   extra bytes to allocate in hostdata array (which is the
- *              last member of the returned Scsi_Host instance)
- *
- *      Returns pointer to new Scsi_Host instance or NULL on failure
- *
- *      Might block: yes
- *
- *      Notes: When this call returns to the LLD, the SCSI bus scan on
- *      this host has _not_ yet been done.
- *      The hostdata array (by default zero length) is a per host scratch 
- *      area for the LLD.
- *
- *      Defined in: drivers/scsi/hosts.c .
- **/
-struct Scsi_Host * scsi_register(struct scsi_host_template * sht,
-                                 int privsize)
-
-
-/**
- * scsi_remove_device - detach and remove a SCSI device
- * @sdev:      a pointer to a scsi device instance
- *
- *      Returns value: 0 on success, -EINVAL if device not attached
- *
- *      Might block: yes
- *
- *      Notes: If an LLD becomes aware that a scsi device (lu) has
- *      been removed but its host is still present then it can request
- *      the removal of that scsi device. If successful this call will
- *      lead to the slave_destroy() callback being invoked. sdev is an 
- *      invalid pointer after this call.
- *
- *      Defined in: drivers/scsi/scsi_sysfs.c .
- **/
-int scsi_remove_device(struct scsi_device *sdev)
-
-
-/**
- * scsi_remove_host - detach and remove all SCSI devices owned by host
- * @shost:      a pointer to a scsi host instance
- *
- *      Returns value: 0 on success, 1 on failure (e.g. LLD busy ??)
- *
- *      Might block: yes
- *
- *      Notes: Should only be invoked if the "hotplug initialization
- *      model" is being used. It should be called _prior_ to  
- *      scsi_unregister().
- *
- *      Defined in: drivers/scsi/hosts.c .
- **/
-int scsi_remove_host(struct Scsi_Host *shost)
-
-
-/**
- * scsi_report_bus_reset - report scsi _bus_ reset observed
- * @shost: a pointer to a scsi host involved
- * @channel: channel (within) host on which scsi bus reset occurred
- *
- *      Returns nothing
- *
- *      Might block: no
- *
- *      Notes: This only needs to be called if the reset is one which
- *      originates from an unknown location.  Resets originated by the 
- *      mid level itself don't need to call this, but there should be 
- *      no harm.  The main purpose of this is to make sure that a
- *      CHECK_CONDITION is properly treated.
- *
- *      Defined in: drivers/scsi/scsi_error.c .
- **/
-void scsi_report_bus_reset(struct Scsi_Host * shost, int channel)
-
-
-/**
- * scsi_scan_host - scan SCSI bus
- * @shost: a pointer to a scsi host instance
- *
- *	Might block: yes
- *
- *	Notes: Should be called after scsi_add_host()
- *
- *	Defined in: drivers/scsi/scsi_scan.c
- **/
-void scsi_scan_host(struct Scsi_Host *shost)
-
-
-/**
- * scsi_track_queue_full - track successive QUEUE_FULL events on given
- *                      device to determine if and when there is a need
- *                      to adjust the queue depth on the device.
- * @sdev:  pointer to SCSI device instance
- * @depth: Current number of outstanding SCSI commands on this device,
- *         not counting the one returned as QUEUE_FULL.
- *
- *      Returns 0  - no change needed
- *              >0 - adjust queue depth to this new depth
- *              -1 - drop back to untagged operation using host->cmd_per_lun
- *                   as the untagged command depth
- *
- *      Might block: no
- *
- *      Notes: LLDs may call this at any time and we will do "The Right
- *              Thing"; interrupt context safe. 
- *
- *      Defined in: drivers/scsi/scsi.c .
- **/
-int scsi_track_queue_full(struct scsi_device *sdev, int depth)
-
-
-/**
- * scsi_unblock_requests - allow further commands to be queued to given host
- *
- * @shost: pointer to host to unblock commands on
- *
- *      Returns nothing
- *
- *      Might block: no
- *
- *      Defined in: drivers/scsi/scsi_lib.c .
-**/
-void scsi_unblock_requests(struct Scsi_Host * shost)
-
-
-/**
- * scsi_unregister - unregister and free memory used by host instance
- * @shp:        pointer to scsi host instance to unregister.
- *
- *      Returns nothing
- *
- *      Might block: no
- *
- *      Notes: Should not be invoked if the "hotplug initialization
- *      model" is being used. Called internally by exit_this_scsi_driver()
- *      in the "passive initialization model". Hence a LLD has no need to
- *      call this function directly.
- *
- *      Defined in: drivers/scsi/hosts.c .
- **/
-void scsi_unregister(struct Scsi_Host * shp)
-
-
-
-
-Interface Functions
-===================
-Interface functions are supplied (defined) by LLDs and their function
-pointers are placed in an instance of struct scsi_host_template which
-is passed to scsi_host_alloc() [or scsi_register() / init_this_scsi_driver()].
-Some are mandatory. Interface functions should be declared static. The
-accepted convention is that driver "xyz" will declare its slave_configure() 
-function as:
-    static int xyz_slave_configure(struct scsi_device * sdev);
-and so forth for all interface functions listed below.
-
-A pointer to this function should be placed in the 'slave_configure' member
-of a "struct scsi_host_template" instance. A pointer to such an instance
-should be passed to the mid level's scsi_host_alloc() [or scsi_register() /
-init_this_scsi_driver()].
-
-The interface functions are also described in the include/scsi/scsi_host.h
-file immediately above their definition point in "struct scsi_host_template".
-In some cases more detail is given in scsi_host.h than below.
-
-The interface functions are listed below in alphabetical order.
-
-Summary:
-   bios_param - fetch head, sector, cylinder info for a disk
-   eh_timed_out - notify the host that a command timer expired
-   eh_abort_handler - abort given command
-   eh_bus_reset_handler - issue SCSI bus reset
-   eh_device_reset_handler - issue SCSI device reset
-   eh_host_reset_handler - reset host (host bus adapter)
-   info - supply information about given host
-   ioctl - driver can respond to ioctls
-   proc_info - supports /proc/scsi/{driver_name}/{host_no}
-   queuecommand - queue scsi command, invoke 'done' on completion
-   slave_alloc - prior to any commands being sent to a new device 
-   slave_configure - driver fine tuning for given device after attach
-   slave_destroy - given device is about to be shut down
-
-
-Details:
-
-/**
- *      bios_param - fetch head, sector, cylinder info for a disk
- *      @sdev: pointer to scsi device context (defined in 
- *             include/scsi/scsi_device.h)
- *      @bdev: pointer to block device context (defined in fs.h)
- *      @capacity:  device size (in 512 byte sectors)
- *      @params: three element array to place output:
- *              params[0] number of heads (max 255)
- *              params[1] number of sectors (max 63)
- *              params[2] number of cylinders 
- *
- *      Return value is ignored
- *
- *      Locks: none
- *
- *      Calling context: process (sd)
- *
- *      Notes: an arbitrary geometry (based on READ CAPACITY) is used
- *      if this function is not provided. The params array is
- *      pre-initialized with made up values just in case this function 
- *      doesn't output anything.
- *
- *      Optionally defined in: LLD
- **/
-    int bios_param(struct scsi_device * sdev, struct block_device *bdev,
-                   sector_t capacity, int params[3])
-
-
-/**
- *      eh_timed_out - The timer for the command has just fired
- *      @scp: identifies command timing out
- *
- *      Returns:
- *
- *      EH_HANDLED:             I fixed the error, please complete the command
- *      EH_RESET_TIMER:         I need more time, reset the timer and
- *                              begin counting again
- *      EH_NOT_HANDLED          Begin normal error recovery
- *
- *
- *      Locks: None held
- *
- *      Calling context: interrupt
- *
- *      Notes: This is to give the LLD an opportunity to do local recovery.
- *      This recovery is limited to determining if the outstanding command
- *      will ever complete.  You may not abort and restart the command from
- *      this callback.
- *
- *      Optionally defined in: LLD
- **/
-     int eh_timed_out(struct scsi_cmnd * scp)
-
-
-/**
- *      eh_abort_handler - abort command associated with scp
- *      @scp: identifies command to be aborted
- *
- *      Returns SUCCESS if command aborted else FAILED
- *
- *      Locks: None held
- *
- *      Calling context: kernel thread
- *
- *      Notes: If 'no_async_abort' is defined this callback
- *  	will be invoked from scsi_eh thread. No other commands
- *	will then be queued on current host during eh.
- *	Otherwise it will be called whenever scsi_times_out()
- *      is called due to a command timeout.
- *
- *      Optionally defined in: LLD
- **/
-     int eh_abort_handler(struct scsi_cmnd * scp)
-
-
-/**
- *      eh_bus_reset_handler - issue SCSI bus reset
- *      @scp: SCSI bus that contains this device should be reset
- *
- *      Returns SUCCESS if command aborted else FAILED
- *
- *      Locks: None held
- *
- *      Calling context: kernel thread
- *
- *      Notes: Invoked from scsi_eh thread. No other commands will be
- *      queued on current host during eh.
- *
- *      Optionally defined in: LLD
- **/
-     int eh_bus_reset_handler(struct scsi_cmnd * scp)
-
-
-/**
- *      eh_device_reset_handler - issue SCSI device reset
- *      @scp: identifies SCSI device to be reset
- *
- *      Returns SUCCESS if command aborted else FAILED
- *
- *      Locks: None held
- *
- *      Calling context: kernel thread
- *
- *      Notes: Invoked from scsi_eh thread. No other commands will be
- *      queued on current host during eh.
- *
- *      Optionally defined in: LLD
- **/
-     int eh_device_reset_handler(struct scsi_cmnd * scp)
-
-
-/**
- *      eh_host_reset_handler - reset host (host bus adapter)
- *      @scp: SCSI host that contains this device should be reset
- *
- *      Returns SUCCESS if command aborted else FAILED
- *
- *      Locks: None held
- *
- *      Calling context: kernel thread
- *
- *      Notes: Invoked from scsi_eh thread. No other commands will be
- *      queued on current host during eh. 
- *      With the default eh_strategy in place, if none of the _abort_, 
- *      _device_reset_, _bus_reset_ or this eh handler function are 
- *      defined (or they all return FAILED) then the device in question 
- *      will be set offline whenever eh is invoked.
- *
- *      Optionally defined in: LLD
- **/
-     int eh_host_reset_handler(struct scsi_cmnd * scp)
-
-
-/**
- *      info - supply information about given host: driver name plus data
- *             to distinguish given host
- *      @shp: host to supply information about
- *
- *      Return ASCII null terminated string. [This driver is assumed to
- *      manage the memory pointed to and maintain it, typically for the
- *      lifetime of this host.]
- *
- *      Locks: none
- *
- *      Calling context: process
- *
- *      Notes: Often supplies PCI or ISA information such as IO addresses
- *      and interrupt numbers. If not supplied struct Scsi_Host::name used
- *      instead. It is assumed the returned information fits on one line 
- *      (i.e. does not included embedded newlines).
- *      The SCSI_IOCTL_PROBE_HOST ioctl yields the string returned by this
- *      function (or struct Scsi_Host::name if this function is not
- *      available).
- *      In a similar manner, init_this_scsi_driver() outputs to the console
- *      each host's "info" (or name) for the driver it is registering.
- *      Also if proc_info() is not supplied, the output of this function
- *      is used instead.
- *
- *      Optionally defined in: LLD
- **/
-    const char * info(struct Scsi_Host * shp)
-
-
-/**
- *      ioctl - driver can respond to ioctls
- *      @sdp: device that ioctl was issued for
- *      @cmd: ioctl number
- *      @arg: pointer to read or write data from. Since it points to
- *            user space, should use appropriate kernel functions
- *            (e.g. copy_from_user() ). In the Unix style this argument
- *            can also be viewed as an unsigned long.
- *
- *      Returns negative "errno" value when there is a problem. 0 or a
- *      positive value indicates success and is returned to the user space.
- *
- *      Locks: none
- *
- *      Calling context: process
- *
- *      Notes: The SCSI subsystem uses a "trickle down" ioctl model.
- *      The user issues an ioctl() against an upper level driver
- *      (e.g. /dev/sdc) and if the upper level driver doesn't recognize
- *      the 'cmd' then it is passed to the SCSI mid level. If the SCSI
- *      mid level does not recognize it, then the LLD that controls
- *      the device receives the ioctl. According to recent Unix standards
- *      unsupported ioctl() 'cmd' numbers should return -ENOTTY.
- *
- *      Optionally defined in: LLD
- **/
-    int ioctl(struct scsi_device *sdp, int cmd, void *arg)
-
-
-/**
- *      proc_info - supports /proc/scsi/{driver_name}/{host_no}
- *      @buffer: anchor point to output to (0==writeto1_read0) or fetch from
- *               (1==writeto1_read0).
- *      @start: where "interesting" data is written to. Ignored when
- *              1==writeto1_read0.
- *      @offset: offset within buffer 0==writeto1_read0 is actually
- *               interested in. Ignored when 1==writeto1_read0 .
- *      @length: maximum (or actual) extent of buffer
- *      @host_no: host number of interest (struct Scsi_Host::host_no)
- *      @writeto1_read0: 1 -> data coming from user space towards driver
- *                            (e.g. "echo some_string > /proc/scsi/xyz/2")
- *                       0 -> user what data from this driver
- *                            (e.g. "cat /proc/scsi/xyz/2")
- *
- *      Returns length when 1==writeto1_read0. Otherwise number of chars
- *      output to buffer past offset.
- *
- *      Locks: none held
- *
- *      Calling context: process
- *
- *      Notes: Driven from scsi_proc.c which interfaces to proc_fs. proc_fs
- *      support can now be configured out of the scsi subsystem.
- *
- *      Optionally defined in: LLD
- **/
-    int proc_info(char * buffer, char ** start, off_t offset, 
-                  int length, int host_no, int writeto1_read0)
-
-
-/**
- *      queuecommand - queue scsi command, invoke scp->scsi_done on completion
- *      @shost: pointer to the scsi host object
- *      @scp: pointer to scsi command object
- *
- *      Returns 0 on success.
- *
- *      If there's a failure, return either:
- *
- *      SCSI_MLQUEUE_DEVICE_BUSY if the device queue is full, or
- *      SCSI_MLQUEUE_HOST_BUSY if the entire host queue is full
- *
- *      On both of these returns, the mid-layer will requeue the I/O
- *
- *      - if the return is SCSI_MLQUEUE_DEVICE_BUSY, only that particular
- *      device will be paused, and it will be unpaused when a command to
- *      the device returns (or after a brief delay if there are no more
- *      outstanding commands to it).  Commands to other devices continue
- *      to be processed normally.
- *
- *      - if the return is SCSI_MLQUEUE_HOST_BUSY, all I/O to the host
- *      is paused and will be unpaused when any command returns from
- *      the host (or after a brief delay if there are no outstanding
- *      commands to the host).
- *
- *      For compatibility with earlier versions of queuecommand, any
- *      other return value is treated the same as
- *      SCSI_MLQUEUE_HOST_BUSY.
- *
- *      Other types of errors that are detected immediately may be
- *      flagged by setting scp->result to an appropriate value,
- *      invoking the scp->scsi_done callback, and then returning 0
- *      from this function. If the command is not performed
- *      immediately (and the LLD is starting (or will start) the given
- *      command) then this function should place 0 in scp->result and
- *      return 0.
- *
- *      Command ownership.  If the driver returns zero, it owns the
- *      command and must take responsibility for ensuring the
- *      scp->scsi_done callback is executed.  Note: the driver may
- *      call scp->scsi_done before returning zero, but after it has
- *      called scp->scsi_done, it may not return any value other than
- *      zero.  If the driver makes a non-zero return, it must not
- *      execute the command's scsi_done callback at any time.
- *
- *      Locks: up to and including 2.6.36, struct Scsi_Host::host_lock
- *             held on entry (with "irqsave") and is expected to be
- *             held on return. From 2.6.37 onwards, queuecommand is
- *             called without any locks held.
- *
- *      Calling context: in interrupt (soft irq) or process context
- *
- *      Notes: This function should be relatively fast. Normally it
- *      will not wait for IO to complete. Hence the scp->scsi_done
- *      callback is invoked (often directly from an interrupt service
- *      routine) some time after this function has returned. In some
- *      cases (e.g. pseudo adapter drivers that manufacture the
- *      response to a SCSI INQUIRY) the scp->scsi_done callback may be
- *      invoked before this function returns.  If the scp->scsi_done
- *      callback is not invoked within a certain period the SCSI mid
- *      level will commence error processing.  If a status of CHECK
- *      CONDITION is placed in "result" when the scp->scsi_done
- *      callback is invoked, then the LLD driver should perform
- *      autosense and fill in the struct scsi_cmnd::sense_buffer
- *      array. The scsi_cmnd::sense_buffer array is zeroed prior to
- *      the mid level queuing a command to an LLD.
- *
- *      Defined in: LLD
- **/
-    int queuecommand(struct Scsi_Host *shost, struct scsi_cmnd * scp)
-
-
-/**
- *      slave_alloc -   prior to any commands being sent to a new device 
- *                      (i.e. just prior to scan) this call is made
- *      @sdp: pointer to new device (about to be scanned)
- *
- *      Returns 0 if ok. Any other return is assumed to be an error and
- *      the device is ignored.
- *
- *      Locks: none
- *
- *      Calling context: process
- *
- *      Notes: Allows the driver to allocate any resources for a device
- *      prior to its initial scan. The corresponding scsi device may not
- *      exist but the mid level is just about to scan for it (i.e. send
- *      and INQUIRY command plus ...). If a device is found then
- *      slave_configure() will be called while if a device is not found
- *      slave_destroy() is called.
- *      For more details see the include/scsi/scsi_host.h file.
- *
- *      Optionally defined in: LLD
- **/
-    int slave_alloc(struct scsi_device *sdp)
-
-
-/**
- *      slave_configure - driver fine tuning for given device just after it
- *                     has been first scanned (i.e. it responded to an
- *                     INQUIRY)
- *      @sdp: device that has just been attached
- *
- *      Returns 0 if ok. Any other return is assumed to be an error and
- *      the device is taken offline. [offline devices will _not_ have
- *      slave_destroy() called on them so clean up resources.]
- *
- *      Locks: none
- *
- *      Calling context: process
- *
- *      Notes: Allows the driver to inspect the response to the initial
- *      INQUIRY done by the scanning code and take appropriate action.
- *      For more details see the include/scsi/scsi_host.h file.
- *
- *      Optionally defined in: LLD
- **/
-    int slave_configure(struct scsi_device *sdp)
-
-
-/**
- *      slave_destroy - given device is about to be shut down. All
- *                      activity has ceased on this device.
- *      @sdp: device that is about to be shut down
- *
- *      Returns nothing
- *
- *      Locks: none
- *
- *      Calling context: process
- *
- *      Notes: Mid level structures for given device are still in place
- *      but are about to be torn down. Any per device resources allocated
- *      by this driver for given device should be freed now. No further
- *      commands will be sent for this sdp instance. [However the device
- *      could be re-attached in the future in which case a new instance
- *      of struct scsi_device would be supplied by future slave_alloc()
- *      and slave_configure() calls.]
- *
- *      Optionally defined in: LLD
- **/
-    void slave_destroy(struct scsi_device *sdp)
-
-
-
-Data Structures
-===============
-struct scsi_host_template
--------------------------
-There is one "struct scsi_host_template" instance per LLD ***. It is
-typically initialized as a file scope static in a driver's header file. That
-way members that are not explicitly initialized will be set to 0 or NULL.
-Member of interest:
-    name         - name of driver (may contain spaces, please limit to
-                   less than 80 characters)
-    proc_name    - name used in "/proc/scsi/<proc_name>/<host_no>" and
-                   by sysfs in one of its "drivers" directories. Hence
-                   "proc_name" should only contain characters acceptable
-                   to a Unix file name.
-   (*queuecommand)() - primary callback that the mid level uses to inject
-                   SCSI commands into an LLD.
-The structure is defined and commented in include/scsi/scsi_host.h
-
-*** In extreme situations a single driver may have several instances
-    if it controls several different classes of hardware (e.g. an LLD
-    that handles both ISA and PCI cards and has a separate instance of
-    struct scsi_host_template for each class).
-
-struct Scsi_Host
-----------------
-There is one struct Scsi_Host instance per host (HBA) that an LLD
-controls. The struct Scsi_Host structure has many members in common
-with "struct scsi_host_template". When a new struct Scsi_Host instance
-is created (in scsi_host_alloc() in hosts.c) those common members are
-initialized from the driver's struct scsi_host_template instance. Members
-of interest:
-    host_no      - system wide unique number that is used for identifying
-                   this host. Issued in ascending order from 0.
-    can_queue    - must be greater than 0; do not send more than can_queue
-                   commands to the adapter.
-    this_id      - scsi id of host (scsi initiator) or -1 if not known
-    sg_tablesize - maximum scatter gather elements allowed by host.
-                   Set this to SG_ALL or less to avoid chained SG lists.
-                   Must be at least 1.
-    max_sectors  - maximum number of sectors (usually 512 bytes) allowed
-                   in a single SCSI command. The default value of 0 leads
-                   to a setting of SCSI_DEFAULT_MAX_SECTORS (defined in
-                   scsi_host.h) which is currently set to 1024. So for a
-                   disk the maximum transfer size is 512 KB when max_sectors
-                   is not defined. Note that this size may not be sufficient
-                   for disk firmware uploads.
-    cmd_per_lun  - maximum number of commands that can be queued on devices
-                   controlled by the host. Overridden by LLD calls to
-                   scsi_change_queue_depth().
-    unchecked_isa_dma - 1=>only use bottom 16 MB of ram (ISA DMA addressing
-                   restriction), 0=>can use full 32 bit (or better) DMA
-                   address space
-    no_async_abort - 1=>Asynchronous aborts are not supported
-                     0=>Timed-out commands will be aborted asynchronously
-    hostt        - pointer to driver's struct scsi_host_template from which
-                   this struct Scsi_Host instance was spawned
-    hostt->proc_name  - name of LLD. This is the driver name that sysfs uses
-    transportt   - pointer to driver's struct scsi_transport_template instance
-                   (if any). FC and SPI transports currently supported.
-    sh_list      - a double linked list of pointers to all struct Scsi_Host
-                   instances (currently ordered by ascending host_no)
-    my_devices   - a double linked list of pointers to struct scsi_device 
-                   instances that belong to this host.
-    hostdata[0]  - area reserved for LLD at end of struct Scsi_Host. Size
-                   is set by the second argument (named 'xtr_bytes') to
-                   scsi_host_alloc() or scsi_register().
-    vendor_id    - a unique value that identifies the vendor supplying
-                   the LLD for the Scsi_Host.  Used most often in validating
-                   vendor-specific message requests.  Value consists of an
-                   identifier type and a vendor-specific value.
-                   See scsi_netlink.h for a description of valid formats.
-
-The scsi_host structure is defined in include/scsi/scsi_host.h
-
-struct scsi_device
-------------------
-Generally, there is one instance of this structure for each SCSI logical unit
-on a host. Scsi devices connected to a host are uniquely identified by a
-channel number, target id and logical unit number (lun).
-The structure is defined in include/scsi/scsi_device.h
-
-struct scsi_cmnd
-----------------
-Instances of this structure convey SCSI commands to the LLD and responses
-back to the mid level. The SCSI mid level will ensure that no more SCSI
-commands become queued against the LLD than are indicated by
-scsi_change_queue_depth() (or struct Scsi_Host::cmd_per_lun). There will
-be at least one instance of struct scsi_cmnd available for each SCSI device.
-Members of interest:
-    cmnd         - array containing SCSI command
-    cmnd_len     - length (in bytes) of SCSI command
-    sc_data_direction - direction of data transfer in data phase. See
-                "enum dma_data_direction" in include/linux/dma-mapping.h
-    request_bufflen - number of data bytes to transfer (0 if no data phase)
-    use_sg       - ==0 -> no scatter gather list, hence transfer data
-                          to/from request_buffer
-                 - >0 ->  scatter gather list (actually an array) in
-                          request_buffer with use_sg elements
-    request_buffer - either contains data buffer or scatter gather list
-                     depending on the setting of use_sg. Scatter gather
-                     elements are defined by 'struct scatterlist' found
-                     in include/linux/scatterlist.h .
-    done         - function pointer that should be invoked by LLD when the
-                   SCSI command is completed (successfully or otherwise).
-                   Should only be called by an LLD if the LLD has accepted
-                   the command (i.e. queuecommand() returned or will return
-                   0). The LLD may invoke 'done'  prior to queuecommand()
-                   finishing.
-    result       - should be set by LLD prior to calling 'done'. A value
-                   of 0 implies a successfully completed command (and all
-                   data (if any) has been transferred to or from the SCSI
-                   target device). 'result' is a 32 bit unsigned integer that
-                   can be viewed as 4 related bytes. The SCSI status value is
-                   in the LSB. See include/scsi/scsi.h status_byte(),
-                   msg_byte(), host_byte() and driver_byte() macros and
-                   related constants.
-    sense_buffer - an array (maximum size: SCSI_SENSE_BUFFERSIZE bytes) that
-                   should be written when the SCSI status (LSB of 'result')
-                   is set to CHECK_CONDITION (2). When CHECK_CONDITION is
-                   set, if the top nibble of sense_buffer[0] has the value 7
-                   then the mid level will assume the sense_buffer array
-                   contains a valid SCSI sense buffer; otherwise the mid
-                   level will issue a REQUEST_SENSE SCSI command to
-                   retrieve the sense buffer. The latter strategy is error
-                   prone in the presence of command queuing so the LLD should
-                   always "auto-sense".
-    device       - pointer to scsi_device object that this command is
-                   associated with.
-    resid        - an LLD should set this signed integer to the requested
-                   transfer length (i.e. 'request_bufflen') less the number
-                   of bytes that are actually transferred. 'resid' is
-                   preset to 0 so an LLD can ignore it if it cannot detect
-                   underruns (overruns should be rare). If possible an LLD
-                   should set 'resid' prior to invoking 'done'. The most
-                   interesting case is data transfers from a SCSI target
-                   device (e.g. READs) that underrun.
-    underflow    - LLD should place (DID_ERROR << 16) in 'result' if
-                   actual number of bytes transferred is less than this
-                   figure. Not many LLDs implement this check and some that
-                   do just output an error message to the log rather than
-                   report a DID_ERROR. Better for an LLD to implement
-                   'resid'.
-
-It is recommended that a LLD set 'resid' on data transfers from a SCSI
-target device (e.g. READs). It is especially important that 'resid' is set
-when such data transfers have sense keys of MEDIUM ERROR and HARDWARE ERROR
-(and possibly RECOVERED ERROR). In these cases if a LLD is in doubt how much
-data has been received then the safest approach is to indicate no bytes have
-been received. For example: to indicate that no valid data has been received
-a LLD might use these helpers:
-    scsi_set_resid(SCpnt, scsi_bufflen(SCpnt));
-where 'SCpnt' is a pointer to a scsi_cmnd object. To indicate only three 512
-bytes blocks has been received 'resid' could be set like this:
-    scsi_set_resid(SCpnt, scsi_bufflen(SCpnt) - (3 * 512));
-
-The scsi_cmnd structure is defined in include/scsi/scsi_cmnd.h
-
-
-Locks
-=====
-Each struct Scsi_Host instance has a spin_lock called struct 
-Scsi_Host::default_lock which is initialized in scsi_host_alloc() [found in 
-hosts.c]. Within the same function the struct Scsi_Host::host_lock pointer
-is initialized to point at default_lock.  Thereafter lock and unlock
-operations performed by the mid level use the struct Scsi_Host::host_lock
-pointer.  Previously drivers could override the host_lock pointer but
-this is not allowed anymore.
-
-
-Autosense
-=========
-Autosense (or auto-sense) is defined in the SAM-2 document as "the
-automatic return of sense data to the application client coincident
-with the completion of a SCSI command" when a status of CHECK CONDITION
-occurs. LLDs should perform autosense. This should be done when the LLD
-detects a CHECK CONDITION status by either: 
-    a) instructing the SCSI protocol (e.g. SCSI Parallel Interface (SPI))
-       to perform an extra data in phase on such responses
-    b) or, the LLD issuing a REQUEST SENSE command itself
-
-Either way, when a status of CHECK CONDITION is detected, the mid level
-decides whether the LLD has performed autosense by checking struct 
-scsi_cmnd::sense_buffer[0] . If this byte has an upper nibble of 7 (or 0xf)
-then autosense is assumed to have taken place. If it has another value (and
-this byte is initialized to 0 before each command) then the mid level will
-issue a REQUEST SENSE command.
-
-In the presence of queued commands the "nexus" that maintains sense
-buffer data from the command that failed until a following REQUEST SENSE
-may get out of synchronization. This is why it is best for the LLD
-to perform autosense.
-
-
-Changes since lk 2.4 series
-===========================
-io_request_lock has been replaced by several finer grained locks. The lock 
-relevant to LLDs is struct Scsi_Host::host_lock and there is
-one per SCSI host.
-
-The older error handling mechanism has been removed. This means the
-LLD interface functions abort() and reset() have been removed.
-The struct scsi_host_template::use_new_eh_code flag has been removed.
-
-In the 2.4 series the SCSI subsystem configuration descriptions were 
-aggregated with the configuration descriptions from all other Linux 
-subsystems in the Documentation/Configure.help file. In the 2.6 series, 
-the SCSI subsystem now has its own (much smaller) drivers/scsi/Kconfig
-file that contains both configuration and help information.
-
-struct SHT has been renamed to struct scsi_host_template.
-
-Addition of the "hotplug initialization model" and many extra functions
-to support it.
-
-
-Credits
-=======
-The following people have contributed to this document:
-        Mike Anderson <andmike at us dot ibm dot com>
-        James Bottomley <James dot Bottomley at hansenpartnership dot com>
-        Patrick Mansfield <patmans at us dot ibm dot com> 
-        Christoph Hellwig <hch at infradead dot org>
-        Doug Ledford <dledford at redhat dot com>
-        Andries Brouwer <Andries dot Brouwer at cwi dot nl>
-        Randy Dunlap <rdunlap at xenotime dot net>
-        Alan Stern <stern at rowland dot harvard dot edu>
-
-
-Douglas Gilbert
-dgilbert at interlog dot com
-21st September 2004
diff --git a/Documentation/scsi/scsi_transport_srp/Makefile b/Documentation/scsi/scsi_transport_srp/Makefile
deleted file mode 100644
index 5f6b567e955c..000000000000
--- a/Documentation/scsi/scsi_transport_srp/Makefile
+++ /dev/null
@@ -1,7 +0,0 @@
-all: rport_state_diagram.svg rport_state_diagram.png
-
-rport_state_diagram.svg: rport_state_diagram.dot
-	dot -Tsvg -o $@ $<
-
-rport_state_diagram.png: rport_state_diagram.dot
-	dot -Tpng -o $@ $<
diff --git a/Documentation/scsi/scsi_transport_srp/figures.rst b/Documentation/scsi/scsi_transport_srp/figures.rst
new file mode 100644
index 000000000000..6c8f8dd6301b
--- /dev/null
+++ b/Documentation/scsi/scsi_transport_srp/figures.rst
@@ -0,0 +1,6 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+SCSI RDMA (SRP) transport class diagram
+=======================================
+
+.. kernel-figure:: rport_state_diagram.dot
diff --git a/Documentation/scsi/sd-parameters.rst b/Documentation/scsi/sd-parameters.rst
new file mode 100644
index 000000000000..87d554008bfb
--- /dev/null
+++ b/Documentation/scsi/sd-parameters.rst
@@ -0,0 +1,27 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+======================================
+Linux SCSI Disk Driver (sd) Parameters
+======================================
+
+cache_type (RW)
+---------------
+Enable/disable drive write & read cache.
+
+===========================   === ===   ===========   ==========
+ cache_type string            WCE RCD   Write cache   Read cache
+===========================   === ===   ===========   ==========
+ write through                0   0     off           on
+ none                         0   1     off           off
+ write back                   1   0     on            on
+ write back, no read (daft)   1   1     on            off
+===========================   === ===   ===========   ==========
+
+To set cache type to "write back" and save this setting to the drive::
+
+  # echo "write back" > cache_type
+
+To modify the caching mode without making the change persistent, prepend
+"temporary " to the cache type string. E.g.::
+
+  # echo "temporary write back" > cache_type
diff --git a/Documentation/scsi/sd-parameters.txt b/Documentation/scsi/sd-parameters.txt
deleted file mode 100644
index 8e5af00d88e7..000000000000
--- a/Documentation/scsi/sd-parameters.txt
+++ /dev/null
@@ -1,22 +0,0 @@
-Linux SCSI Disk Driver (sd) Parameters
-======================================
-
-cache_type (RW)
----------------
-Enable/disable drive write & read cache.
-
- cache_type string          | WCE RCD | Write cache | Read cache
-----------------------------+---------+-------------+------------
- write through              | 0   0   | off         | on
- none                       | 0   1   | off         | off
- write back                 | 1   0   | on          | on
- write back, no read (daft) | 1   1   | on          | off
-
-To set cache type to "write back" and save this setting to the drive:
-
-  # echo "write back" > cache_type
-
-To modify the caching mode without making the change persistent, prepend
-"temporary " to the cache type string. E.g.:
-
-  # echo "temporary write back" > cache_type
diff --git a/Documentation/scsi/smartpqi.txt b/Documentation/scsi/smartpqi.rst
index df129f55ace5..a7de27352c6f 100644
--- a/Documentation/scsi/smartpqi.txt
+++ b/Documentation/scsi/smartpqi.rst
@@ -1,6 +1,8 @@
+.. SPDX-License-Identifier: GPL-2.0
 
+=====================================
 SMARTPQI - Microsemi Smart PQI Driver
------------------------------------------
+=====================================
 
 This file describes the smartpqi SCSI driver for Microsemi
 (http://www.microsemi.com) PQI controllers. The smartpqi driver
@@ -16,20 +18,21 @@ For Microsemi smartpqi controller support, enable the smartpqi driver
 when configuring the kernel.
 
 For more information on the PQI Queuing Interface, please see:
-http://www.t10.org/drafts.htm
-http://www.t10.org/members/w_pqi2.htm
 
-Supported devices:
-------------------
+- http://www.t10.org/drafts.htm
+- http://www.t10.org/members/w_pqi2.htm
+
+Supported devices
+=================
 <Controller names to be added as they become publicly available.>
 
 smartpqi specific entries in /sys
------------------------------
+=================================
 
-  smartpqi host attributes:
-  -------------------------
-  /sys/class/scsi_host/host*/rescan
-  /sys/class/scsi_host/host*/driver_version
+smartpqi host attributes
+------------------------
+  - /sys/class/scsi_host/host*/rescan
+  - /sys/class/scsi_host/host*/driver_version
 
   The host rescan attribute is a write only attribute. Writing to this
   attribute will trigger the driver to scan for new, changed, or removed
@@ -37,12 +40,13 @@ smartpqi specific entries in /sys
 
   The version attribute is read-only and will return the driver version
   and the controller firmware version.
-  For example:
+  For example::
+
               driver: 0.9.13-370
               firmware: 0.01-522
 
-  smartpqi sas device attributes
-  ------------------------------
+smartpqi sas device attributes
+------------------------------
   HBA devices are added to the SAS transport layer. These attributes are
   automatically added by the SAS transport layer.
 
@@ -50,31 +54,25 @@ smartpqi specific entries in /sys
   /sys/class/sas_device/end_device-X:X/enclosure_identifier
   /sys/class/sas_device/end_device-X:X/scsi_target_id
 
-smartpqi specific ioctls:
--------------------------
+smartpqi specific ioctls
+========================
 
   For compatibility with applications written for the cciss protocol.
 
-  CCISS_DEREGDISK
-  CCISS_REGNEWDISK
-  CCISS_REGNEWD
-
-  The above three ioctls all do exactly the same thing, which is to cause the driver
-  to rescan for new devices.  This does exactly the same thing as writing to the
-  smartpqi specific host "rescan" attribute.
+  CCISS_DEREGDISK, CCISS_REGNEWDISK, CCISS_REGNEWD
+	The above three ioctls all do exactly the same thing, which is to cause the driver
+	to rescan for new devices.  This does exactly the same thing as writing to the
+	smartpqi specific host "rescan" attribute.
 
   CCISS_GETPCIINFO
-
 	Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID).
 
   CCISS_GETDRIVVER
+	Returns driver version in three bytes encoded as::
 
-	Returns driver version in three bytes encoded as:
-	(DRIVER_MAJOR << 28) | (DRIVER_MINOR << 24) | (DRIVER_RELEASE << 16) | DRIVER_REVISION;
+	  (DRIVER_MAJOR << 28) | (DRIVER_MINOR << 24) | (DRIVER_RELEASE << 16) | DRIVER_REVISION;
 
   CCISS_PASSTHRU
-
 	Allows "BMIC" and "CISS" commands to be passed through to the Smart Storage Array.
 	These are used extensively by the SSA Array Configuration Utility, SNMP storage
 	agents, etc.
-
diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.rst
index ec0acf6acccd..d3b28c28d74c 100644
--- a/Documentation/scsi/st.txt
+++ b/Documentation/scsi/st.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+The SCSI Tape Driver
+====================
+
 This file contains brief information about the SCSI tape driver.
 The driver is currently maintained by Kai Mäkisara (email
 Kai.Makisara@kolumbus.fi)
@@ -5,7 +11,8 @@ Kai.Makisara@kolumbus.fi)
 Last modified: Tue Feb  9 21:54:16 2016 by kai.makisara
 
 
-BASICS
+Basics
+======
 
 The driver is generic, i.e., it does not contain any code tailored
 to any specific tape drive. The tape parameters can be specified with
@@ -110,15 +117,17 @@ tape in the drive (commands trying to write something return error if
 attempted).
 
 
-MINOR NUMBERS
+Minor Numbers
+=============
 
 The tape driver currently supports up to 2^17 drives if 4 modes for
 each drive are used.
 
-The minor numbers consist of the following bit fields:
+The minor numbers consist of the following bit fields::
+
+    dev_upper non-rew mode dev-lower
+    20 -  8     7    6 5  4      0
 
-dev_upper non-rew mode dev-lower
-  20 -  8     7    6 5  4      0
 The non-rewind bit is always bit 7 (the uppermost bit in the lowermost
 byte). The bits defining the mode are below the non-rewind bit. The
 remaining bits define the tape device number. This numbering is
@@ -126,7 +135,8 @@ backward compatible with the numbering used when the minor number was
 only 8 bits wide.
 
 
-SYSFS SUPPORT
+Sysfs Support
+=============
 
 The driver creates the directory /sys/class/scsi_tape and populates it with
 directories corresponding to the existing tape devices. There are autorewind
@@ -148,10 +158,11 @@ bit definitions are the same as those used with MTSETDRVBUFFER in setting the
 options.
 
 A link named 'tape' is made from the SCSI device directory to the class
-directory corresponding to the mode 0 auto-rewind device (e.g., st0). 
+directory corresponding to the mode 0 auto-rewind device (e.g., st0).
 
 
-SYSFS AND STATISTICS FOR TAPE DEVICES
+Sysfs and Statistics for Tape Devices
+=====================================
 
 The st driver maintains statistics for tape drives inside the sysfs filesystem.
 The following method can be used to locate the statistics that are
@@ -160,10 +171,10 @@ available (assuming that sysfs is mounted at /sys):
 1. Use opendir(3) on the directory /sys/class/scsi_tape
 2. Use readdir(3) to read the directory contents
 3. Use regcomp(3)/regexec(3) to match directory entries to the extended
-        regular expression "^st[0-9]+$"
+   regular expression "^st[0-9]+$"
 4. Access the statistics from the /sys/class/scsi_tape/<match>/stats
-        directory (where <match> is a directory entry from /sys/class/scsi_tape
-        that matched the extended regular expression)
+   directory (where <match> is a directory entry from /sys/class/scsi_tape
+   that matched the extended regular expression)
 
 The reason for using this approach is that all the character devices
 pointing to the same tape drive use the same statistics. That means
@@ -171,29 +182,41 @@ that st0 would have the same statistics as nst0.
 
 The directory contains the following statistics files:
 
-1.  in_flight - The number of I/Os currently outstanding to this device.
-2.  io_ns - The amount of time spent waiting (in nanoseconds) for all I/O
+1.  in_flight
+      - The number of I/Os currently outstanding to this device.
+2.  io_ns
+      - The amount of time spent waiting (in nanoseconds) for all I/O
         to complete (including read and write). This includes tape movement
         commands such as seeking between file or set marks and implicit tape
         movement such as when rewind on close tape devices are used.
-3.  other_cnt - The number of I/Os issued to the tape drive other than read or
+3.  other_cnt
+      - The number of I/Os issued to the tape drive other than read or
         write commands. The time taken to complete these commands uses the
         following calculation io_ms-read_ms-write_ms.
-4.  read_byte_cnt - The number of bytes read from the tape drive.
-5.  read_cnt - The number of read requests issued to the tape drive.
-6.  read_ns - The amount of time (in nanoseconds) spent waiting for read
+4.  read_byte_cnt
+      - The number of bytes read from the tape drive.
+5.  read_cnt
+      - The number of read requests issued to the tape drive.
+6.  read_ns
+      - The amount of time (in nanoseconds) spent waiting for read
         requests to complete.
-7.  write_byte_cnt - The number of bytes written to the tape drive.
-8.  write_cnt - The number of write requests issued to the tape drive.
-9.  write_ns - The amount of time (in nanoseconds) spent waiting for write
+7.  write_byte_cnt
+      - The number of bytes written to the tape drive.
+8.  write_cnt
+      - The number of write requests issued to the tape drive.
+9.  write_ns
+      - The amount of time (in nanoseconds) spent waiting for write
         requests to complete.
-10. resid_cnt - The number of times during a read or write we found
+10. resid_cnt
+      - The number of times during a read or write we found
 	the residual amount to be non-zero. This should mean that a program
 	is issuing a read larger thean the block size on tape. For write
 	not all data made it to tape.
 
-Note: The in_flight value is incremented when an I/O starts the I/O
-itself is not added to the statistics until it completes.
+.. Note::
+
+   The in_flight value is incremented when an I/O starts the I/O
+   itself is not added to the statistics until it completes.
 
 The total of read_cnt, write_cnt, and other_cnt may not total to the same
 value as iodone_cnt at the device level. The tape statistics only count
@@ -210,7 +233,8 @@ The value of in_flight is 0 when there are no I/Os outstanding that are
 issued by the st driver. Tape statistics do not take into account any
 I/O performed via the sg device.
 
-BSD AND SYS V SEMANTICS
+BSD and Sys V Semantics
+=======================
 
 The user can choose between these two behaviours of the tape driver by
 defining the value of the symbol ST_SYSV. The semantics differ when a
@@ -221,13 +245,15 @@ filemark unless the filemark has just been crossed.
 The default is BSD semantics.
 
 
-BUFFERING
+Buffering
+=========
 
 The driver tries to do transfers directly to/from user space. If this
 is not possible, a driver buffer allocated at run-time is used. If
 direct i/o is not possible for the whole transfer, the driver buffer
 is used (i.e., bounce buffers for individual pages are not
 used). Direct i/o can be impossible because of several reasons, e.g.:
+
 - one or more pages are at addresses not reachable by the HBA
 - the number of pages in the transfer exceeds the number of
   scatter/gather segments permitted by the HBA
@@ -269,28 +295,30 @@ in the physical memory) are used if contiguous buffers can't be
 allocated. To support all SCSI adapters (including those not
 supporting scatter/gather), buffer allocation is using the following
 three kinds of chunks:
+
 1. The initial segment that is used for all SCSI adapters including
-those not supporting scatter/gather. The size of this buffer will be
-(PAGE_SIZE << ST_FIRST_ORDER) bytes if the system can give a chunk of
-this size (and it is not larger than the buffer size specified by
-ST_BUFFER_BLOCKS). If this size is not available, the driver halves
-the size and tries again until the size of one page. The default
-settings in st_options.h make the driver to try to allocate all of the
-buffer as one chunk.
+   those not supporting scatter/gather. The size of this buffer will be
+   (PAGE_SIZE << ST_FIRST_ORDER) bytes if the system can give a chunk of
+   this size (and it is not larger than the buffer size specified by
+   ST_BUFFER_BLOCKS). If this size is not available, the driver halves
+   the size and tries again until the size of one page. The default
+   settings in st_options.h make the driver to try to allocate all of the
+   buffer as one chunk.
 2. The scatter/gather segments to fill the specified buffer size are
-allocated so that as many segments as possible are used but the number
-of segments does not exceed ST_FIRST_SG.
+   allocated so that as many segments as possible are used but the number
+   of segments does not exceed ST_FIRST_SG.
 3. The remaining segments between ST_MAX_SG (or the module parameter
-max_sg_segs) and the number of segments used in phases 1 and 2
-are used to extend the buffer at run-time if this is necessary. The
-number of scatter/gather segments allowed for the SCSI adapter is not
-exceeded if it is smaller than the maximum number of scatter/gather
-segments specified. If the maximum number allowed for the SCSI adapter
-is smaller than the number of segments used in phases 1 and 2,
-extending the buffer will always fail.
+   max_sg_segs) and the number of segments used in phases 1 and 2
+   are used to extend the buffer at run-time if this is necessary. The
+   number of scatter/gather segments allowed for the SCSI adapter is not
+   exceeded if it is smaller than the maximum number of scatter/gather
+   segments specified. If the maximum number allowed for the SCSI adapter
+   is smaller than the number of segments used in phases 1 and 2,
+   extending the buffer will always fail.
 
 
-EOM BEHAVIOUR WHEN WRITING
+EOM Behaviour When Writing
+==========================
 
 When the end of medium early warning is encountered, the current write
 is finished and the number of bytes is returned. The next write
@@ -300,12 +328,13 @@ bytes is returned. After this, -1 and the number of bytes are
 alternately returned until the physical end of medium (or some other
 error) is encountered.
 
-
-MODULE PARAMETERS
+Module Parameters
+=================
 
 The buffer size, write threshold, and the maximum number of allocated buffers
 are configurable when the driver is loaded as a module. The keywords are:
 
+========================== ===========================================
 buffer_kbs=xxx             the buffer size for fixed block mode is set
 			   to xxx kilobytes
 write_threshold_kbs=xxx    the write threshold in kilobytes set to xxx
@@ -313,12 +342,14 @@ max_sg_segs=xxx		   the maximum number of scatter/gather
 			   segments
 try_direct_io=x		   try direct transfer between user buffer and
 			   tape drive if this is non-zero
+========================== ===========================================
 
 Note that if the buffer size is changed but the write threshold is not
 set, the write threshold is set to the new buffer size - 2 kB.
 
 
-BOOT TIME CONFIGURATION
+Boot Time Configuration
+=======================
 
 If the driver is compiled into the kernel, the same parameters can be
 also set using, e.g., the LILO command line. The preferred syntax is
@@ -332,21 +363,23 @@ versions is supported. The same keywords can be used as when loading
 the driver as module. If several parameters are set, the keyword-value
 pairs are separated with a comma (no spaces allowed). A colon can be
 used instead of the equal mark. The definition is prepended by the
-string st=. Here is an example:
+string st=. Here is an example::
 
 	st=buffer_kbs:64,write_threshold_kbs:60
 
-The following syntax used by the old kernel versions is also supported:
+The following syntax used by the old kernel versions is also supported::
 
            st=aa[,bb[,dd]]
 
-where
-  aa is the buffer size for fixed block mode in 1024 byte units
-  bb is the write threshold in 1024 byte units
-  dd is the maximum number of scatter/gather segments
+where:
 
+  - aa is the buffer size for fixed block mode in 1024 byte units
+  - bb is the write threshold in 1024 byte units
+  - dd is the maximum number of scatter/gather segments
 
-IOCTLS
+
+IOCTLs
+======
 
 The tape is positioned and the drive parameters are set with ioctls
 defined in mtio.h The tape control program 'mt' uses these ioctls. Try
@@ -359,55 +392,80 @@ The supported ioctls are:
 
 The following use the structure mtop:
 
-MTFSF   Space forward over count filemarks. Tape positioned after filemark.
-MTFSFM  As above but tape positioned before filemark.
-MTBSF	Space backward over count filemarks. Tape positioned before
+MTFSF
+	Space forward over count filemarks. Tape positioned after filemark.
+MTFSFM
+	As above but tape positioned before filemark.
+MTBSF
+	Space backward over count filemarks. Tape positioned before
         filemark.
-MTBSFM  As above but ape positioned after filemark.
-MTFSR   Space forward over count records.
-MTBSR   Space backward over count records.
-MTFSS   Space forward over count setmarks.
-MTBSS   Space backward over count setmarks.
-MTWEOF  Write count filemarks.
-MTWEOFI	Write count filemarks with immediate bit set (i.e., does not
+MTBSFM
+	As above but ape positioned after filemark.
+MTFSR
+	Space forward over count records.
+MTBSR
+	Space backward over count records.
+MTFSS
+	Space forward over count setmarks.
+MTBSS
+	Space backward over count setmarks.
+MTWEOF
+	Write count filemarks.
+MTWEOFI
+	Write count filemarks with immediate bit set (i.e., does not
 	wait until data is on tape)
-MTWSM   Write count setmarks.
-MTREW   Rewind tape.
-MTOFFL  Set device off line (often rewind plus eject).
-MTNOP   Do nothing except flush the buffers.
-MTRETEN Re-tension tape.
-MTEOM   Space to end of recorded data.
-MTERASE Erase tape. If the argument is zero, the short erase command
+MTWSM
+	Write count setmarks.
+MTREW
+	Rewind tape.
+MTOFFL
+	Set device off line (often rewind plus eject).
+MTNOP
+	Do nothing except flush the buffers.
+MTRETEN
+	Re-tension tape.
+MTEOM
+	Space to end of recorded data.
+MTERASE
+	Erase tape. If the argument is zero, the short erase command
 	is used. The long erase command is used with all other values
 	of the argument.
-MTSEEK	Seek to tape block count. Uses Tandberg-compatible seek (QFA)
+MTSEEK
+	Seek to tape block count. Uses Tandberg-compatible seek (QFA)
         for SCSI-1 drives and SCSI-2 seek for SCSI-2 drives. The file and
 	block numbers in the status are not valid after a seek.
-MTSETBLK Set the drive block size. Setting to zero sets the drive into
+MTSETBLK
+	Set the drive block size. Setting to zero sets the drive into
         variable block mode (if applicable).
-MTSETDENSITY Sets the drive density code to arg. See drive
+MTSETDENSITY
+	Sets the drive density code to arg. See drive
         documentation for available codes.
-MTLOCK and MTUNLOCK Explicitly lock/unlock the tape drive door.
-MTLOAD and MTUNLOAD Explicitly load and unload the tape. If the
+MTLOCK and MTUNLOCK
+	Explicitly lock/unlock the tape drive door.
+MTLOAD and MTUNLOAD
+	Explicitly load and unload the tape. If the
 	command argument x is between MT_ST_HPLOADER_OFFSET + 1 and
 	MT_ST_HPLOADER_OFFSET + 6, the number x is used sent to the
 	drive with the command and it selects the tape slot to use of
 	HP C1553A changer.
-MTCOMPRESSION Sets compressing or uncompressing drive mode using the
+MTCOMPRESSION
+	Sets compressing or uncompressing drive mode using the
 	SCSI mode page 15. Note that some drives other methods for
 	control of compression. Some drives (like the Exabytes) use
 	density codes for compression control. Some drives use another
 	mode page but this page has not been implemented in the
 	driver. Some drives without compression capability will accept
 	any compression mode without error.
-MTSETPART Moves the tape to the partition given by the argument at the
+MTSETPART
+	Moves the tape to the partition given by the argument at the
 	next tape operation. The block at which the tape is positioned
 	is the block where the tape was previously positioned in the
 	new active partition unless the next tape operation is
 	MTSEEK. In this case the tape is moved directly to the block
 	specified by MTSEEK. MTSETPART is inactive unless
 	MT_ST_CAN_PARTITIONS set.
-MTMKPART Formats the tape with one partition (argument zero) or two
+MTMKPART
+	Formats the tape with one partition (argument zero) or two
 	partitions (argument non-zero). If the argument is positive,
 	it specifies the size of partition 1 in megabytes. For DDS
 	drives and several early drives this is the physically first
@@ -422,64 +480,81 @@ MTSETDRVBUFFER
         with mask MT_SET_OPTIONS, the low order bits are used as argument.
 	This command is only allowed for the superuser (root). The
 	subcommands are:
-	0
+
+	* 0
            The drive buffer option is set to the argument. Zero means
            no buffering.
-        MT_ST_BOOLEANS
+        * MT_ST_BOOLEANS
            Sets the buffering options. The bits are the new states
            (enabled/disabled) the following options (in the
 	   parenthesis is specified whether the option is global or
 	   can be specified differently for each mode):
-	     MT_ST_BUFFER_WRITES write buffering (mode)
-	     MT_ST_ASYNC_WRITES asynchronous writes (mode)
-             MT_ST_READ_AHEAD  read ahead (mode)
-             MT_ST_TWO_FM writing of two filemarks (global)
-	     MT_ST_FAST_EOM using the SCSI spacing to EOD (global)
-	     MT_ST_AUTO_LOCK automatic locking of the drive door (global)
-             MT_ST_DEF_WRITES the defaults are meant only for writes (mode)
-	     MT_ST_CAN_BSR backspacing over more than one records can
+
+	     MT_ST_BUFFER_WRITES
+		write buffering (mode)
+	     MT_ST_ASYNC_WRITES
+		asynchronous writes (mode)
+             MT_ST_READ_AHEAD
+		read ahead (mode)
+             MT_ST_TWO_FM
+		writing of two filemarks (global)
+	     MT_ST_FAST_EOM
+		using the SCSI spacing to EOD (global)
+	     MT_ST_AUTO_LOCK
+		automatic locking of the drive door (global)
+             MT_ST_DEF_WRITES
+		the defaults are meant only for writes (mode)
+	     MT_ST_CAN_BSR
+		backspacing over more than one records can
 		be used for repositioning the tape (global)
-	     MT_ST_NO_BLKLIMS the driver does not ask the block limits
+	     MT_ST_NO_BLKLIMS
+		the driver does not ask the block limits
 		from the drive (block size can be changed only to
 		variable) (global)
-	     MT_ST_CAN_PARTITIONS enables support for partitioned
+	     MT_ST_CAN_PARTITIONS
+		enables support for partitioned
 		tapes (global)
-	     MT_ST_SCSI2LOGICAL the logical block number is used in
+	     MT_ST_SCSI2LOGICAL
+		the logical block number is used in
 		the MTSEEK and MTIOCPOS for SCSI-2 drives instead of
 		the device dependent address. It is recommended to set
 		this flag unless there are tapes using the device
 		dependent (from the old times) (global)
-	     MT_ST_SYSV sets the SYSV semantics (mode)
-	     MT_ST_NOWAIT enables immediate mode (i.e., don't wait for
+	     MT_ST_SYSV
+		sets the SYSV semantics (mode)
+	     MT_ST_NOWAIT
+		enables immediate mode (i.e., don't wait for
 	        the command to finish) for some commands (e.g., rewind)
-	     MT_ST_NOWAIT_EOF enables immediate filemark mode (i.e. when
+	     MT_ST_NOWAIT_EOF
+		enables immediate filemark mode (i.e. when
 	        writing a filemark, don't wait for it to complete). Please
 		see the BASICS note about MTWEOFI with respect to the
 		possible dangers of writing immediate filemarks.
-	     MT_ST_SILI enables setting the SILI bit in SCSI commands when
+	     MT_ST_SILI
+		enables setting the SILI bit in SCSI commands when
 		reading in variable block mode to enhance performance when
 		reading blocks shorter than the byte count; set this only
 		if you are sure that the drive supports SILI and the HBA
 		correctly returns transfer residuals
-	     MT_ST_DEBUGGING debugging (global; debugging must be
+	     MT_ST_DEBUGGING
+		debugging (global; debugging must be
 		compiled into the driver)
-	MT_ST_SETBOOLEANS
-	MT_ST_CLEARBOOLEANS
+
+	* MT_ST_SETBOOLEANS, MT_ST_CLEARBOOLEANS
 	   Sets or clears the option bits.
-        MT_ST_WRITE_THRESHOLD
+        * MT_ST_WRITE_THRESHOLD
            Sets the write threshold for this device to kilobytes
            specified by the lowest bits.
-	MT_ST_DEF_BLKSIZE
+	* MT_ST_DEF_BLKSIZE
 	   Defines the default block size set automatically. Value
 	   0xffffff means that the default is not used any more.
-	MT_ST_DEF_DENSITY
-	MT_ST_DEF_DRVBUFFER
+	* MT_ST_DEF_DENSITY, MT_ST_DEF_DRVBUFFER
 	   Used to set or clear the density (8 bits), and drive buffer
 	   state (3 bits). If the value is MT_ST_CLEAR_DEFAULT
 	   (0xfffff) the default will not be used any more. Otherwise
 	   the lowermost bits of the value contain the new value of
 	   the parameter.
-	MT_ST_DEF_COMPRESSION
+	* MT_ST_DEF_COMPRESSION
 	   The compression default will not be used if the value of
 	   the lowermost byte is 0xff. Otherwise the lowermost bit
 	   contains the new default. If the bits 8-15 are set to a
@@ -487,17 +562,17 @@ MTSETDRVBUFFER
 	   used as the compression algorithm. The value
 	   MT_ST_CLEAR_DEFAULT can be used to clear the compression
 	   default.
-	MT_ST_SET_TIMEOUT
+	* MT_ST_SET_TIMEOUT
 	   Set the normal timeout in seconds for this device. The
 	   default is 900 seconds (15 minutes). The timeout should be
 	   long enough for the retries done by the device while
 	   reading/writing.
-	MT_ST_SET_LONG_TIMEOUT
+	* MT_ST_SET_LONG_TIMEOUT
 	   Set the long timeout that is used for operations that are
 	   known to take a long time. The default is 14000 seconds
 	   (3.9 hours). For erase this value is further multiplied by
 	   eight.
-	MT_ST_SET_CLN
+	* MT_ST_SET_CLN
 	   Set the cleaning request interpretation parameters using
 	   the lowest 24 bits of the argument. The driver can set the
 	   generic status bit GMT_CLN if a cleaning request bit pattern
@@ -506,7 +581,7 @@ MTSETDRVBUFFER
 	   cleaning. The bits are device-dependent. The driver is
 	   given the number of the sense data byte (the lowest eight
 	   bits of the argument; must be >= 18 (values 1 - 17
-	   reserved) and <= the maximum requested sense data sixe), 
+	   reserved) and <= the maximum requested sense data sixe),
 	   a mask to select the relevant bits (the bits 9-16), and the
 	   bit pattern (bits 17-23). If the bit pattern is zero, one
 	   or more bits under the mask indicate cleaning request. If
@@ -518,12 +593,16 @@ MTSETDRVBUFFER
 	   MT_ST_SET_CLN.)
 
 The following ioctl uses the structure mtpos:
-MTIOCPOS Reads the current position from the drive. Uses
+
+MTIOCPOS
+	Reads the current position from the drive. Uses
         Tandberg-compatible QFA for SCSI-1 drives and the SCSI-2
         command for the SCSI-2 drives.
 
 The following ioctl uses the structure mtget to return the status:
-MTIOCGET Returns some status information.
+
+MTIOCGET
+	Returns some status information.
         The file number and block number within file are returned. The
         block is -1 when it can't be determined (e.g., after MTBSF).
         The drive type is either MTISSCSI1 or MTISSCSI2.
@@ -537,7 +616,8 @@ MTIOCGET Returns some status information.
 	end of recorded data or end of tape. GMT_EOT means end of tape.
 
 
-MISCELLANEOUS COMPILE OPTIONS
+Miscellaneous Compile Options
+=============================
 
 The recovered write errors are considered fatal if ST_RECOVERED_WRITE_FATAL
 is defined.
@@ -568,7 +648,8 @@ time or the MT_ST_CAN_BSR bit is set for the drive with an ioctl.
 user does not request data that far.)
 
 
-DEBUGGING HINTS
+Debugging Hints
+===============
 
 Debugging code is now compiled in by default but debugging is turned off
 with the kernel module parameter debug_flag defaulting to 0.  Debugging
diff --git a/Documentation/scsi/sym53c500_cs.txt b/Documentation/scsi/sym53c500_cs.rst
index 75febcf9298c..55464861bbd5 100644
--- a/Documentation/scsi/sym53c500_cs.txt
+++ b/Documentation/scsi/sym53c500_cs.rst
@@ -1,3 +1,9 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=======================
+The sym53c500_cs Driver
+=======================
+
 The sym53c500_cs driver originated as an add-on to David Hinds' pcmcia-cs
 package, and was written by Tom Corner (tcorner@via.at).  A rewrite was
 long overdue, and the current version addresses the following concerns:
@@ -20,4 +26,4 @@ Through the years, there have been a number of downloads of the pcmcia-cs
 version of this driver, and I guess it worked for those users.  It worked
 for Tom Corner, and it works for me.  Your mileage will probably vary.
 
---Bob Tracy (rct@frus.com)
+Bob Tracy (rct@frus.com)
diff --git a/Documentation/scsi/sym53c8xx_2.txt b/Documentation/scsi/sym53c8xx_2.rst
index d28186553fb0..8de44a7baa9b 100644
--- a/Documentation/scsi/sym53c8xx_2.txt
+++ b/Documentation/scsi/sym53c8xx_2.rst
@@ -1,99 +1,111 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================================
 The Linux SYM-2 driver documentation file
+=========================================
 
 Written by Gerard Roudier <groudier@free.fr>
+
 21 Rue Carnot
+
 95170 DEUIL LA BARRE - FRANCE
 
 Updated by Matthew Wilcox <matthew@wil.cx>
 
 2004-10-09
-===============================================================================
-
-1.  Introduction
-2.  Supported chips and SCSI features
-3.  Advantages of this driver for newer chips.
-      3.1 Optimized SCSI SCRIPTS
-      3.2 New features appeared with the SYM53C896
-4.  Memory mapped I/O versus normal I/O
-5.  Tagged command queueing
-6.  Parity checking
-7.  Profiling information
-8.  Control commands
-      8.1  Set minimum synchronous period
-      8.2  Set wide size
-      8.3  Set maximum number of concurrent tagged commands
-      8.4  Set debug mode
-      8.5  Set flag (no_disc)
-      8.6  Set verbose level
-      8.7  Reset all logical units of a target
-      8.8  Abort all tasks of all logical units of a target
-9.  Configuration parameters
-10. Boot setup commands
-      10.1 Syntax
-      10.2 Available arguments
-             10.2.1  Default number of tagged commands
-             10.2.2  Burst max
-             10.2.3  LED support
-             10.2.4  Differential mode
-             10.2.5  IRQ mode
-             10.2.6  Check SCSI BUS 
-             10.2.7  Suggest a default SCSI id for hosts
-             10.2.8  Verbosity level
-             10.2.9  Debug mode
-             10.2.10 Settle delay
-             10.2.11 Serial NVRAM
-             10.2.12 Exclude a host from being attached
-      10.3 Converting from old options
-      10.4 SCSI BUS checking boot option
-11. SCSI problem troubleshooting
-      15.1 Problem tracking
-      15.2 Understanding hardware error reports
-12. Serial NVRAM support (by Richard Waltham)
-      17.1 Features
-      17.2 Symbios NVRAM layout
-      17.3 Tekram  NVRAM layout
-
-===============================================================================
+
+.. Contents
+
+   1.  Introduction
+   2.  Supported chips and SCSI features
+   3.  Advantages of this driver for newer chips.
+         3.1 Optimized SCSI SCRIPTS
+         3.2 New features appeared with the SYM53C896
+   4.  Memory mapped I/O versus normal I/O
+   5.  Tagged command queueing
+   6.  Parity checking
+   7.  Profiling information
+   8.  Control commands
+         8.1  Set minimum synchronous period
+         8.2  Set wide size
+         8.3  Set maximum number of concurrent tagged commands
+         8.4  Set debug mode
+         8.5  Set flag (no_disc)
+         8.6  Set verbose level
+         8.7  Reset all logical units of a target
+         8.8  Abort all tasks of all logical units of a target
+   9.  Configuration parameters
+   10. Boot setup commands
+         10.1 Syntax
+         10.2 Available arguments
+                10.2.1  Default number of tagged commands
+                10.2.2  Burst max
+                10.2.3  LED support
+                10.2.4  Differential mode
+                10.2.5  IRQ mode
+                10.2.6  Check SCSI BUS
+                10.2.7  Suggest a default SCSI id for hosts
+                10.2.8  Verbosity level
+                10.2.9  Debug mode
+                10.2.10 Settle delay
+                10.2.11 Serial NVRAM
+                10.2.12 Exclude a host from being attached
+         10.3 Converting from old options
+         10.4 SCSI BUS checking boot option
+   11. SCSI problem troubleshooting
+         15.1 Problem tracking
+         15.2 Understanding hardware error reports
+   12. Serial NVRAM support (by Richard Waltham)
+         17.1 Features
+         17.2 Symbios NVRAM layout
+         17.3 Tekram  NVRAM layout
+
 
 1. Introduction
+===============
 
 This driver supports the whole SYM53C8XX family of PCI-SCSI controllers.
-It also support the subset of LSI53C10XX PCI-SCSI controllers that are based 
+It also support the subset of LSI53C10XX PCI-SCSI controllers that are based
 on the SYM53C8XX SCRIPTS language.
 
-It replaces the sym53c8xx+ncr53c8xx driver bundle and shares its core code 
-with the FreeBSD SYM-2 driver. The `glue' that allows this driver to work 
+It replaces the sym53c8xx+ncr53c8xx driver bundle and shares its core code
+with the FreeBSD SYM-2 driver. The 'glue' that allows this driver to work
 under Linux is contained in 2 files named sym_glue.h and sym_glue.c.
-Other drivers files are intended not to depend on the Operating System 
+Other drivers files are intended not to depend on the Operating System
 on which the driver is used.
 
 The history of this driver can be summarized as follows:
 
 1993: ncr driver written for 386bsd and FreeBSD by:
-          Wolfgang Stanglmeier        <wolf@cologne.de>
-          Stefan Esser                <se@mi.Uni-Koeln.de>
+
+          - Wolfgang Stanglmeier        <wolf@cologne.de>
+          - Stefan Esser                <se@mi.Uni-Koeln.de>
 
 1996: port of the ncr driver to Linux-1.2.13 and rename it ncr53c8xx.
-          Gerard Roudier
 
-1998: new sym53c8xx driver for Linux based on LOAD/STORE instruction and that 
+          - Gerard Roudier
+
+1998: new sym53c8xx driver for Linux based on LOAD/STORE instruction and that
       adds full support for the 896 but drops support for early NCR devices.
-          Gerard Roudier
 
-1999: port of the sym53c8xx driver to FreeBSD and support for the LSI53C1010 
-      33 MHz and 66MHz Ultra-3 controllers. The new driver is named `sym'.
-          Gerard Roudier
+          - Gerard Roudier
 
-2000: Add support for early NCR devices to FreeBSD `sym' driver.
-      Break the driver into several sources and separate the OS glue 
+1999: port of the sym53c8xx driver to FreeBSD and support for the LSI53C1010
+      33 MHz and 66MHz Ultra-3 controllers. The new driver is named 'sym'.
+
+          - Gerard Roudier
+
+2000: Add support for early NCR devices to FreeBSD 'sym' driver.
+      Break the driver into several sources and separate the OS glue
       code from the core code that can be shared among different O/Ses.
       Write a glue code for Linux.
-          Gerard Roudier
+
+          - Gerard Roudier
 
 2004: Remove FreeBSD compatibility code.  Remove support for versions of
       Linux before 2.6.  Start using Linux facilities.
 
-This README file addresses the Linux version of the driver. Under FreeBSD, 
+This README file addresses the Linux version of the driver. Under FreeBSD,
 the driver documentation is the sym.8 man page.
 
 Information about new chips is available at LSILOGIC web server:
@@ -104,113 +116,145 @@ SCSI standard documentations are available at T10 site:
 
           http://www.t10.org/
 
-Useful SCSI tools written by Eric Youngdale are part of most Linux 
+Useful SCSI tools written by Eric Youngdale are part of most Linux
 distributions:
-   scsiinfo:    command line tool
-   scsi-config: TCL/Tk tool using scsiinfo
+
+   ============ ==========================
+   scsiinfo     command line tool
+   scsi-config  TCL/Tk tool using scsiinfo
+   ============ ==========================
 
 2. Supported chips and SCSI features
+====================================
 
 The following features are supported for all chips:
 
-	Synchronous negotiation
-	Disconnection
-	Tagged command queuing
-	SCSI parity checking
-	PCI Master parity checking
+	- Synchronous negotiation
+	- Disconnection
+	- Tagged command queuing
+	- SCSI parity checking
+	- PCI Master parity checking
 
 Other features depends on chip capabilities.
-The driver notably uses optimized SCRIPTS for devices that support 
-LOAD/STORE and handles PHASE MISMATCH from SCRIPTS for devices that 
+
+The driver notably uses optimized SCRIPTS for devices that support
+LOAD/STORE and handles PHASE MISMATCH from SCRIPTS for devices that
 support the corresponding feature.
 
 The following table shows some characteristics of the chip family.
 
-       On board                                   LOAD/STORE   HARDWARE
-Chip   SDMS BIOS   Wide   SCSI std.   Max. sync   SCRIPTS      PHASE MISMATCH
-----   ---------   ----   ---------   ----------  ----------   --------------
-810        N         N      FAST10    10 MB/s        N             N
-810A       N         N      FAST10    10 MB/s        Y             N
-815        Y         N      FAST10    10 MB/s        N             N
-825        Y         Y      FAST10    20 MB/s        N             N
-825A       Y         Y      FAST10    20 MB/s        Y             N
-860        N         N      FAST20    20 MB/s        Y             N
-875        Y         Y      FAST20    40 MB/s        Y             N
-875A       Y         Y      FAST20    40 MB/s        Y             Y
-876        Y         Y      FAST20    40 MB/s        Y             N
-895        Y         Y      FAST40    80 MB/s        Y             N
-895A       Y         Y      FAST40    80 MB/s        Y             Y
-896        Y         Y      FAST40    80 MB/s        Y             Y
-897        Y         Y      FAST40    80 MB/s        Y             Y
-1510D      Y         Y      FAST40    80 MB/s        Y             Y
-1010       Y         Y      FAST80   160 MB/s        Y             Y
-1010_66*   Y         Y      FAST80   160 MB/s        Y             Y
-
-* Chip supports 33MHz and 66MHz PCI bus clock.
++--------+-----------+-----+-----------+------------+------------+---------+
+|        |           |     |           |            |Load/store  |Hardware |
+|        |On board   |     |           |            |scripts     |phase    |
+|Chip    |SDMS BIOS  |Wide |SCSI std.  | Max. sync  |            |mismatch |
++--------+-----------+-----+-----------+------------+------------+---------+
+|810     |     N     |  N  | FAST10    | 10 MB/s    |      N     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|810A    |     N     |  N  | FAST10    | 10 MB/s    |      Y     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|815     |     Y     |  N  | FAST10    | 10 MB/s    |      N     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|825     |     Y     |  Y  | FAST10    | 20 MB/s    |      N     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|825A    |     Y     |  Y  | FAST10    | 20 MB/s    |      Y     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|860     |     N     |  N  | FAST20    | 20 MB/s    |      Y     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|875     |     Y     |  Y  | FAST20    | 40 MB/s    |      Y     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|875A    |     Y     |  Y  | FAST20    | 40 MB/s    |      Y     |    Y    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|876     |     Y     |  Y  | FAST20    | 40 MB/s    |      Y     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|895     |     Y     |  Y  | FAST40    | 80 MB/s    |      Y     |    N    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|895A    |     Y     |  Y  | FAST40    | 80 MB/s    |      Y     |    Y    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|896     |     Y     |  Y  | FAST40    | 80 MB/s    |      Y     |    Y    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|897     |     Y     |  Y  | FAST40    | 80 MB/s    |      Y     |    Y    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|1510D   |     Y     |  Y  | FAST40    | 80 MB/s    |      Y     |    Y    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|1010    |     Y     |  Y  | FAST80    |160 MB/s    |      Y     |    Y    |
++--------+-----------+-----+-----------+------------+------------+---------+
+|1010_66 |     Y     |  Y  | FAST80    |160 MB/s    |      Y     |    Y    |
+|[1]_    |           |     |           |            |            |         |
++--------+-----------+-----+-----------+------------+------------+---------+
+
+.. [1] Chip supports 33MHz and 66MHz PCI bus clock.
 
 
 Summary of other supported features:
 
-Module:                allow to load the driver
-Memory mapped I/O:     increases performance
-Control commands:      write operations to the proc SCSI file system
-Debugging information: written to syslog (expert only)
-Scatter / gather
-Shared interrupt
-Boot setup commands
-Serial NVRAM:          Symbios and Tekram formats
+:Module:                allow to load the driver
+:Memory mapped I/O:     increases performance
+:Control commands:      write operations to the proc SCSI file system
+:Debugging information: written to syslog (expert only)
+:Serial NVRAM:          Symbios and Tekram formats
+
+- Scatter / gather
+- Shared interrupt
+- Boot setup commands
 
 
 3. Advantages of this driver for newer chips.
+=============================================
 
-3.1 Optimized SCSI SCRIPTS.
+3.1 Optimized SCSI SCRIPTS
+--------------------------
 
-All chips except the 810, 815 and 825, support new SCSI SCRIPTS instructions 
-named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register 
-to/from memory much faster that the MOVE MEMORY instruction that is supported 
+All chips except the 810, 815 and 825, support new SCSI SCRIPTS instructions
+named LOAD and STORE that allow to move up to 1 DWORD from/to an IO register
+to/from memory much faster that the MOVE MEMORY instruction that is supported
 by the 53c7xx and 53c8xx family.
 
-The LOAD/STORE instructions support absolute and DSA relative addressing 
-modes. The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead 
+The LOAD/STORE instructions support absolute and DSA relative addressing
+modes. The SCSI SCRIPTS had been entirely rewritten using LOAD/STORE instead
 of MOVE MEMORY instructions.
 
-Due to the lack of LOAD/STORE SCRIPTS instructions by earlier chips, this 
-driver also incorporates a different SCRIPTS set based on MEMORY MOVE, in 
+Due to the lack of LOAD/STORE SCRIPTS instructions by earlier chips, this
+driver also incorporates a different SCRIPTS set based on MEMORY MOVE, in
 order to provide support for the entire SYM53C8XX chips family.
 
 3.2 New features appeared with the SYM53C896
+--------------------------------------------
 
-Newer chips (see above) allows handling of the phase mismatch context from 
-SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor 
+Newer chips (see above) allows handling of the phase mismatch context from
+SCRIPTS (avoids the phase mismatch interrupt that stops the SCSI processor
 until the C code has saved the context of the transfer).
 
-The 896 and 1010 chips support 64 bit PCI transactions and addressing, 
+The 896 and 1010 chips support 64 bit PCI transactions and addressing,
 while the 895A supports 32 bit PCI transactions and 64 bit addressing.
-The SCRIPTS processor of these chips is not true 64 bit, but uses segment 
-registers for bit 32-63. Another interesting feature is that LOAD/STORE 
+The SCRIPTS processor of these chips is not true 64 bit, but uses segment
+registers for bit 32-63. Another interesting feature is that LOAD/STORE
 instructions that address the on-chip RAM (8k) remain internal to the chip.
 
 4. Memory mapped I/O versus normal I/O
+======================================
 
-Memory mapped I/O has less latency than normal I/O and is the recommended 
-way for doing IO with PCI devices. Memory mapped I/O seems to work fine on 
-most hardware configurations, but some poorly designed chipsets may break 
-this feature. A configuration option is provided for normal I/O to be 
+Memory mapped I/O has less latency than normal I/O and is the recommended
+way for doing IO with PCI devices. Memory mapped I/O seems to work fine on
+most hardware configurations, but some poorly designed chipsets may break
+this feature. A configuration option is provided for normal I/O to be
 used but the driver defaults to MMIO.
 
 5. Tagged command queueing
+==========================
 
-Queuing more than 1 command at a time to a device allows it to perform 
-optimizations based on actual head positions and its mechanical 
+Queuing more than 1 command at a time to a device allows it to perform
+optimizations based on actual head positions and its mechanical
 characteristics. This feature may also reduce average command latency.
-In order to really gain advantage of this feature, devices must have 
-a reasonable cache size (No miracle is to be expected for a low-end 
+In order to really gain advantage of this feature, devices must have
+a reasonable cache size (No miracle is to be expected for a low-end
 hard disk with 128 KB or less).
+
 Some known old SCSI devices do not properly support tagged command queuing.
-Generally, firmware revisions that fix this kind of problems are available 
+Generally, firmware revisions that fix this kind of problems are available
 at respective vendor web/ftp sites.
-All I can say is that I never have had problem with tagged queuing using 
-this driver and its predecessors. Hard disks that behaved correctly for 
+
+All I can say is that I never have had problem with tagged queuing using
+this driver and its predecessors. Hard disks that behaved correctly for
 me using tagged commands are the following:
 
 - IBM S12 0662
@@ -223,9 +267,9 @@ me using tagged commands are the following:
 - Quantum Atlas IV
 - Seagate Cheetah II
 
-If your controller has NVRAM, you can configure this feature per target 
-from the user setup tool. The Tekram Setup program allows to tune the 
-maximum number of queued commands up to 32. The Symbios Setup only allows 
+If your controller has NVRAM, you can configure this feature per target
+from the user setup tool. The Tekram Setup program allows to tune the
+maximum number of queued commands up to 32. The Symbios Setup only allows
 to enable or disable this feature.
 
 The maximum number of simultaneous tagged commands queued to a device
@@ -233,15 +277,15 @@ is currently set to 16 by default.  This value is suitable for most SCSI
 disks.  With large SCSI disks (>= 2GB, cache >= 512KB, average seek time
 <= 10 ms), using a larger value may give better performances.
 
-This driver supports up to 255 commands per device, and but using more than 
-64 is generally not worth-while, unless you are using a very large disk or 
-disk arrays. It is noticeable that most of recent hard disks seem not to 
-accept more than 64 simultaneous commands. So, using more than 64 queued 
+This driver supports up to 255 commands per device, and but using more than
+64 is generally not worth-while, unless you are using a very large disk or
+disk arrays. It is noticeable that most of recent hard disks seem not to
+accept more than 64 simultaneous commands. So, using more than 64 queued
 commands is probably just resource wasting.
 
-If your controller does not have NVRAM or if it is managed by the SDMS 
-BIOS/SETUP, you can configure tagged queueing feature and device queue 
-depths from the boot command-line. For example:
+If your controller does not have NVRAM or if it is managed by the SDMS
+BIOS/SETUP, you can configure tagged queueing feature and device queue
+depths from the boot command-line. For example::
 
   sym53c8xx=tags:4/t2t3q15-t4q7/t1u0q32
 
@@ -257,25 +301,28 @@ In some special conditions, some SCSI disk firmwares may return a
 QUEUE FULL status for a SCSI command. This behaviour is managed by the
 driver using the following heuristic:
 
-- Each time a QUEUE FULL status is returned, tagged queue depth is reduced 
-  to the actual number of disconnected commands. 
+- Each time a QUEUE FULL status is returned, tagged queue depth is reduced
+  to the actual number of disconnected commands.
 
 - Every 200 successfully completed SCSI commands, if allowed by the
   current limit, the maximum number of queueable commands is incremented.
 
-Since QUEUE FULL status reception and handling is resource wasting, the 
-driver notifies by default this problem to user by indicating the actual 
-number of commands used and their status, as well as its decision on the 
+Since QUEUE FULL status reception and handling is resource wasting, the
+driver notifies by default this problem to user by indicating the actual
+number of commands used and their status, as well as its decision on the
 device queue depth change.
-The heuristic used by the driver in handling QUEUE FULL ensures that the 
-impact on performances is not too bad. You can get rid of the messages by 
+The heuristic used by the driver in handling QUEUE FULL ensures that the
+impact on performances is not too bad. You can get rid of the messages by
 setting verbose level to zero, as follow:
 
-1st method: boot your system using 'sym53c8xx=verb:0' option.
-2nd method: apply "setverbose 0" control command to the proc fs entry 
+1st method:
+	    boot your system using 'sym53c8xx=verb:0' option.
+2nd method:
+	    apply "setverbose 0" control command to the proc fs entry
             corresponding to your controller after boot-up.
 
 6. Parity checking
+==================
 
 The driver supports SCSI parity checking and PCI bus master parity
 checking.  These features must be enabled in order to ensure safe
@@ -284,17 +331,19 @@ with parity.  The options to defeat parity checking have been removed
 from the driver.
 
 7. Profiling information
+========================
 
 This driver does not provide profiling information as did its predecessors.
-This feature was not this useful and added complexity to the code. 
-As the driver code got more complex, I have decided to remove everything 
+This feature was not this useful and added complexity to the code.
+As the driver code got more complex, I have decided to remove everything
 that didn't seem actually useful.
 
 8. Control commands
+===================
 
 Control commands can be sent to the driver with write operations to
 the proc SCSI file system. The generic command syntax is the
-following:
+following::
 
       echo "<verb> <parameters>" >/proc/scsi/sym53c8xx/0
       (assumes controller number is 0)
@@ -305,97 +354,112 @@ apply to all targets of the SCSI chain (except the controller).
 Available commands:
 
 8.1 Set minimum synchronous period factor
+-----------------------------------------
 
     setsync <target> <period factor>
 
-    target:    target number
-    period:    minimum synchronous period.
+    :target:   target number
+    :period:   minimum synchronous period.
                Maximum speed = 1000/(4*period factor) except for special
                cases below.
 
     Specify a period of 0, to force asynchronous transfer mode.
 
-       9 means 12.5 nano-seconds synchronous period
-      10 means 25 nano-seconds synchronous period
-      11 means 30 nano-seconds synchronous period
-      12 means 50 nano-seconds synchronous period
+     -  9 means 12.5 nano-seconds synchronous period
+     - 10 means 25 nano-seconds synchronous period
+     - 11 means 30 nano-seconds synchronous period
+     - 12 means 50 nano-seconds synchronous period
 
 8.2 Set wide size
+-----------------
 
     setwide <target> <size>
 
-    target:    target number
-    size:      0=8 bits, 1=16bits
+    :target:   target number
+    :size:     0=8 bits, 1=16bits
 
 8.3 Set maximum number of concurrent tagged commands
- 
+----------------------------------------------------
+
     settags <target> <tags>
 
-    target:    target number
-    tags:      number of concurrent tagged commands
+    :target:   target number
+    :tags:     number of concurrent tagged commands
                must not be greater than configured (default: 16)
 
 8.4 Set debug mode
+------------------
 
     setdebug <list of debug flags>
 
     Available debug flags:
-        alloc:   print info about memory allocations (ccb, lcb)
-        queue:   print info about insertions into the command start queue
-        result:  print sense data on CHECK CONDITION status
-        scatter: print info about the scatter process
-        scripts: print info about the script binding process
-	tiny:    print minimal debugging information
-	timing:  print timing information of the NCR chip
-	nego:    print information about SCSI negotiations
-	phase:   print information on script interruptions
+
+	======== ========================================================
+        alloc    print info about memory allocations (ccb, lcb)
+        queue    print info about insertions into the command start queue
+        result   print sense data on CHECK CONDITION status
+        scatter  print info about the scatter process
+        scripts  print info about the script binding process
+	tiny     print minimal debugging information
+	timing   print timing information of the NCR chip
+	nego     print information about SCSI negotiations
+	phase    print information on script interruptions
+	======== ========================================================
 
     Use "setdebug" with no argument to reset debug flags.
 
 
 8.5 Set flag (no_disc)
- 
+----------------------
+
     setflag <target> <flag>
 
-    target:    target number
+    :target:    target number
 
     For the moment, only one flag is available:
 
         no_disc:   not allow target to disconnect.
 
     Do not specify any flag in order to reset the flag. For example:
-    - setflag 4
+
+    setflag 4
       will reset no_disc flag for target 4, so will allow it disconnections.
-    - setflag all
+    setflag all
       will allow disconnection for all devices on the SCSI bus.
 
 
 8.6 Set verbose level
+---------------------
 
     setverbose #level
 
-    The driver default verbose level is 1. This command allows to change 
+    The driver default verbose level is 1. This command allows to change
     th driver verbose level after boot-up.
 
 8.7 Reset all logical units of a target
+---------------------------------------
 
     resetdev <target>
 
-    target:    target number
+    :target:    target number
+
     The driver will try to send a BUS DEVICE RESET message to the target.
 
 8.8 Abort all tasks of all logical units of a target
+----------------------------------------------------
 
     cleardev <target>
 
-    target:    target number
-    The driver will try to send a ABORT message to all the logical units 
+    :target:    target number
+
+    The driver will try to send a ABORT message to all the logical units
     of the target.
 
 
 9. Configuration parameters
+===========================
 
-Under kernel configuration tools (make menuconfig, for example), it is 
+Under kernel configuration tools (make menuconfig, for example), it is
 possible to change some default driver configuration parameters.
 If the firmware of all your devices is perfect enough, all the
 features supported by the driver can be enabled at start-up. However,
@@ -414,166 +478,238 @@ Default tagged command queue depth    (default answer: 16)
     This parameter can be specified from the boot command line.
 
 Maximum number of queued commands     (default answer: 32)
-    This option allows you to specify the maximum number of tagged commands 
+    This option allows you to specify the maximum number of tagged commands
     that can be queued to a device. The maximum supported value is 255.
 
 Synchronous transfers frequency       (default answer: 80)
-    This option allows you to specify the frequency in MHz the driver 
+    This option allows you to specify the frequency in MHz the driver
     will use at boot time for synchronous data transfer negotiations.
     0 means "asynchronous data transfers".
 
 10. Boot setup commands
+=======================
 
 10.1 Syntax
+-----------
 
 Setup commands can be passed to the driver either at boot time or as
 parameters to modprobe, as described in Documentation/admin-guide/kernel-parameters.rst
 
-Example of boot setup command under lilo prompt:
+Example of boot setup command under lilo prompt::
 
-lilo: linux root=/dev/sda2 sym53c8xx.cmd_per_lun=4 sym53c8xx.sync=10 sym53c8xx.debug=0x200
+    lilo: linux root=/dev/sda2 sym53c8xx.cmd_per_lun=4 sym53c8xx.sync=10 sym53c8xx.debug=0x200
 
 - enable tagged commands, up to 4 tagged commands queued.
 - set synchronous negotiation speed to 10 Mega-transfers / second.
 - set DEBUG_NEGO flag.
 
 The following command will install the driver module with the same
-options as above.
+options as above::
 
     modprobe sym53c8xx cmd_per_lun=4 sync=10 debug=0x200
 
 10.2 Available arguments
+------------------------
 
 10.2.1  Default number of tagged commands
-        cmd_per_lun=0 (or cmd_per_lun=1) tagged command queuing disabled
-        cmd_per_lun=#tags (#tags > 1) tagged command queuing enabled
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+        - cmd_per_lun=0 (or cmd_per_lun=1) tagged command queuing disabled
+        - cmd_per_lun=#tags (#tags > 1) tagged command queuing enabled
+
   #tags will be truncated to the max queued commands configuration parameter.
 
 10.2.2 Burst max
+^^^^^^^^^^^^^^^^
+
+	========== ======================================================
         burst=0    burst disabled
         burst=255  get burst length from initial IO register settings.
         burst=#x   burst enabled (1<<#x burst transfers max)
-  #x is an integer value which is log base 2 of the burst transfers max.
+
+		   #x is an integer value which is log base 2 of the burst
+		   transfers max.
+	========== ======================================================
+
   By default the driver uses the maximum value supported by the chip.
 
 10.2.3 LED support
+^^^^^^^^^^^^^^^^^^
+
+	=====      ===================
         led=1      enable  LED support
         led=0      disable LED support
+	=====      ===================
+
   Do not enable LED support if your scsi board does not use SDMS BIOS.
   (See 'Configuration parameters')
 
 10.2.4 Differential mode
-        diff=0	never set up diff mode
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+	======	=================================
+	diff=0	never set up diff mode
         diff=1	set up diff mode if BIOS set it
         diff=2	always set up diff mode
         diff=3	set diff mode if GPIO3 is not set
+	======	=================================
 
 10.2.5 IRQ mode
+^^^^^^^^^^^^^^^
+
+	======     ================================================
         irqm=0     always open drain
         irqm=1     same as initial settings (assumed BIOS settings)
         irqm=2     always totem pole
+	======     ================================================
+
+10.2.6 Check SCSI BUS
+^^^^^^^^^^^^^^^^^^^^^
 
-10.2.6 Check SCSI BUS 
         buschk=<option bits>
 
     Available option bits:
-        0x0:   No check.
-        0x1:   Check and do not attach the controller on error.  
-        0x2:   Check and just warn on error.
+
+	===    ================================================
+        0x0    No check.
+        0x1    Check and do not attach the controller on error.
+        0x2    Check and just warn on error.
+	===    ================================================
 
 10.2.7 Suggest a default SCSI id for hosts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+	==========	==========================================
         hostid=255	no id suggested.
-        hostid=#x   (0 < x < 7) x suggested for hosts SCSI id.
+        hostid=#x	(0 < x < 7) x suggested for hosts SCSI id.
+	==========	==========================================
 
-    If a host SCSI id is available from the NVRAM, the driver will ignore 
-    any value suggested as boot option. Otherwise, if a suggested value 
-    different from 255 has been supplied, it will use it. Otherwise, it will 
-    try to deduce the value previously set in the hardware and use value 
+    If a host SCSI id is available from the NVRAM, the driver will ignore
+    any value suggested as boot option. Otherwise, if a suggested value
+    different from 255 has been supplied, it will use it. Otherwise, it will
+    try to deduce the value previously set in the hardware and use value
     7 if the hardware value is zero.
 
 10.2.8  Verbosity level
+^^^^^^^^^^^^^^^^^^^^^^^
+
+	======     ========
         verb=0     minimal
         verb=1     normal
         verb=2     too much
+	======     ========
 
 10.2.9 Debug mode
-        debug=0	 clear debug flags
-        debug=#x   set debug flags
-  #x is an integer value combining the following power-of-2 values:
-  DEBUG_ALLOC       0x1
-  DEBUG_PHASE       0x2
-  DEBUG_POLL        0x4
-  DEBUG_QUEUE       0x8
-  DEBUG_RESULT     0x10
-  DEBUG_SCATTER    0x20
-  DEBUG_SCRIPT     0x40
-  DEBUG_TINY       0x80
-  DEBUG_TIMING    0x100
-  DEBUG_NEGO      0x200
-  DEBUG_TAGS      0x400
-  DEBUG_FREEZE    0x800
-  DEBUG_RESTART  0x1000
-
-  You can play safely with DEBUG_NEGO. However, some of these flags may 
-  generate bunches of syslog messages. 
+^^^^^^^^^^^^^^^^^
+
+	=========   ====================================
+        debug=0	    clear debug flags
+        debug=#x    set debug flags
+
+		    #x is an integer value combining the
+		    following power-of-2 values:
+
+		    =============  ======
+		    DEBUG_ALLOC       0x1
+		    DEBUG_PHASE       0x2
+		    DEBUG_POLL        0x4
+		    DEBUG_QUEUE       0x8
+		    DEBUG_RESULT     0x10
+		    DEBUG_SCATTER    0x20
+		    DEBUG_SCRIPT     0x40
+		    DEBUG_TINY       0x80
+		    DEBUG_TIMING    0x100
+		    DEBUG_NEGO      0x200
+		    DEBUG_TAGS      0x400
+		    DEBUG_FREEZE    0x800
+		    DEBUG_RESTART  0x1000
+		    =============  ======
+	=========   ====================================
+
+  You can play safely with DEBUG_NEGO. However, some of these flags may
+  generate bunches of syslog messages.
 
 10.2.10 Settle delay
+^^^^^^^^^^^^^^^^^^^^
+
+	========	===================
         settle=n	delay for n seconds
+	========	===================
 
   After a bus reset, the driver will delay for n seconds before talking
   to any device on the bus.  The default is 3 seconds and safe mode will
   default it to 10.
 
 10.2.11 Serial NVRAM
-	NB: option not currently implemented.
+^^^^^^^^^^^^^^^^^^^^
+
+	.. Note:: option not currently implemented.
+
+	=======     =========================================
         nvram=n     do not look for serial NVRAM
         nvram=y     test controllers for onboard serial NVRAM
+	=======     =========================================
+
         (alternate binary form)
+
         nvram=<bits options>
+
+        ====   =================================================================
         0x01   look for NVRAM  (equivalent to nvram=y)
         0x02   ignore NVRAM "Synchronous negotiation" parameters for all devices
         0x04   ignore NVRAM "Wide negotiation"  parameter for all devices
         0x08   ignore NVRAM "Scan at boot time" parameter for all devices
         0x80   also attach controllers set to OFF in the NVRAM (sym53c8xx only)
+        ====   =================================================================
 
 10.2.12 Exclude a host from being attached
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
         excl=<io_address>,...
 
     Prevent host at a given io address from being attached.
-    For example 'excl=0xb400,0xc000' indicate to the 
+    For example 'excl=0xb400,0xc000' indicate to the
     driver not to attach hosts at address 0xb400 and 0xc000.
 
 10.3 Converting from old style options
+--------------------------------------
+
+Previously, the sym2 driver accepted arguments of the form::
 
-Previously, the sym2 driver accepted arguments of the form
 	sym53c8xx=tags:4,sync:10,debug:0x200
 
 As a result of the new module parameters, this is no longer available.
 Most of the options have remained the same, but tags has become
 cmd_per_lun to reflect its different purposes.  The sample above would
-be specified as:
+be specified as::
+
 	modprobe sym53c8xx cmd_per_lun=4 sync=10 debug=0x200
 
-or on the kernel boot line as:
+or on the kernel boot line as::
+
 	sym53c8xx.cmd_per_lun=4 sym53c8xx.sync=10 sym53c8xx.debug=0x200
 
-10.4 SCSI BUS checking boot option.
+10.4 SCSI BUS checking boot option
+----------------------------------
 
-When this option is set to a non-zero value, the driver checks SCSI lines 
+When this option is set to a non-zero value, the driver checks SCSI lines
 logic state, 100 micro-seconds after having asserted the SCSI RESET line.
 The driver just reads SCSI lines and checks all lines read FALSE except RESET.
-Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI 
+Since SCSI devices shall release the BUS at most 800 nano-seconds after SCSI
 RESET has been asserted, any signal to TRUE may indicate a SCSI BUS problem.
 Unfortunately, the following common SCSI BUS problems are not detected:
+
 - Only 1 terminator installed.
 - Misplaced terminators.
 - Bad quality terminators.
-On the other hand, either bad cabling, broken devices, not conformant 
+
+On the other hand, either bad cabling, broken devices, not conformant
 devices, ... may cause a SCSI signal to be wrong when te driver reads it.
 
 15. SCSI problem troubleshooting
+================================
 
 15.1 Problem tracking
+---------------------
 
 Most SCSI problems are due to a non conformant SCSI bus or too buggy
 devices.  If unfortunately you have SCSI problems, you can check the
@@ -607,86 +743,96 @@ hard disks.  Good SCSI hard disks with a large cache gain advantage of
 tagged commands queuing.
 
 15.2 Understanding hardware error reports
+-----------------------------------------
 
-When the driver detects an unexpected error condition, it may display a 
-message of the following pattern.
+When the driver detects an unexpected error condition, it may display a
+message of the following pattern::
 
-sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
-sym0: script cmd = 19000000
-sym0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.
+    sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
+    sym0: script cmd = 19000000
+    sym0: regdump: da 10 80 95 47 0f 01 07 75 01 81 21 80 01 09 00.
 
-Some fields in such a message may help you understand the cause of the 
-problem, as follows:
+Some fields in such a message may help you understand the cause of the
+problem, as follows::
 
-sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
-.....A.........B.C....D.E..F....G.H..I.......J.....K...L.......
+    sym0:1: ERROR (0:48) (1-21-65) (f/95/0) @ (script 7c0:19000000).
+    .....A.........B.C....D.E..F....G.H..I.......J.....K...L.......
 
 Field A : target number.
-  SCSI ID of the device the controller was talking with at the moment the 
+  SCSI ID of the device the controller was talking with at the moment the
   error occurs.
 
 Field B : DSTAT io register (DMA STATUS)
-  Bit 0x40 : MDPE Master Data Parity Error
+  ========   =============================================================
+  Bit 0x40   MDPE Master Data Parity Error
              Data parity error detected on the PCI BUS.
-  Bit 0x20 : BF   Bus Fault
+  Bit 0x20   BF   Bus Fault
              PCI bus fault condition detected
-  Bit 0x01 : IID  Illegal Instruction Detected
-             Set by the chip when it detects an Illegal Instruction format 
+  Bit 0x01   IID  Illegal Instruction Detected
+             Set by the chip when it detects an Illegal Instruction format
              on some condition that makes an instruction illegal.
-  Bit 0x80 : DFE Dma Fifo Empty
+  Bit 0x80   DFE Dma Fifo Empty
              Pure status bit that does not indicate an error.
-  If the reported DSTAT value contains a combination of MDPE (0x40), 
+  ========   =============================================================
+
+  If the reported DSTAT value contains a combination of MDPE (0x40),
   BF (0x20), then the cause may be likely due to a PCI BUS problem.
 
 Field C : SIST io register (SCSI Interrupt Status)
-  Bit 0x08 : SGE  SCSI GROSS ERROR
-             Indicates that the chip detected a severe error condition 
+  ========   ==================================================================
+  Bit 0x08   SGE  SCSI GROSS ERROR
+             Indicates that the chip detected a severe error condition
              on the SCSI BUS that prevents the SCSI protocol from functioning
              properly.
-  Bit 0x04 : UDC  Unexpected Disconnection
-             Indicates that the device released the SCSI BUS when the chip 
-             was not expecting this to happen. A device may behave so to 
+  Bit 0x04   UDC  Unexpected Disconnection
+             Indicates that the device released the SCSI BUS when the chip
+             was not expecting this to happen. A device may behave so to
              indicate the SCSI initiator that an error condition not reportable              using the SCSI protocol has occurred.
-  Bit 0x02 : RST  SCSI BUS Reset
-             Generally SCSI targets do not reset the SCSI BUS, although any 
+  Bit 0x02   RST  SCSI BUS Reset
+             Generally SCSI targets do not reset the SCSI BUS, although any
              device on the BUS can reset it at any time.
-  Bit 0x01 : PAR  Parity
+  Bit 0x01   PAR  Parity
              SCSI parity error detected.
-  On a faulty SCSI BUS, any error condition among SGE (0x08), UDC (0x04) and 
-  PAR (0x01) may be detected by the chip. If your SCSI system sometimes 
-  encounters such error conditions, especially SCSI GROSS ERROR, then a SCSI 
+  ========   ==================================================================
+
+  On a faulty SCSI BUS, any error condition among SGE (0x08), UDC (0x04) and
+  PAR (0x01) may be detected by the chip. If your SCSI system sometimes
+  encounters such error conditions, especially SCSI GROSS ERROR, then a SCSI
   BUS problem is likely the cause of these errors.
 
-For fields D,E,F,G and H, you may look into the sym53c8xx_defs.h file 
+For fields D,E,F,G and H, you may look into the sym53c8xx_defs.h file
 that contains some minimal comments on IO register bits.
+
 Field D : SOCL  Scsi Output Control Latch
-          This register reflects the state of the SCSI control lines the 
+          This register reflects the state of the SCSI control lines the
           chip want to drive or compare against.
 Field E : SBCL  Scsi Bus Control Lines
           Actual value of control lines on the SCSI BUS.
 Field F : SBDL  Scsi Bus Data Lines
           Actual value of data lines on the SCSI BUS.
 Field G : SXFER  SCSI Transfer
-          Contains the setting of the Synchronous Period for output and 
+          Contains the setting of the Synchronous Period for output and
           the current Synchronous offset (offset 0 means asynchronous).
 Field H : SCNTL3 Scsi Control Register 3
-          Contains the setting of timing values for both asynchronous and 
-          synchronous data transfers. 
+          Contains the setting of timing values for both asynchronous and
+          synchronous data transfers.
 Field I : SCNTL4 Scsi Control Register 4
           Only meaningful for 53C1010 Ultra3 controllers.
 
-Understanding Fields J, K, L and dumps requires to have good knowledge of 
+Understanding Fields J, K, L and dumps requires to have good knowledge of
 SCSI standards, chip cores functionnals and internal driver data structures.
-You are not required to decode and understand them, unless you want to help 
+You are not required to decode and understand them, unless you want to help
 maintain the driver code.
 
 17. Serial NVRAM (added by Richard Waltham: dormouse@farsrobt.demon.co.uk)
+==========================================================================
 
 17.1 Features
+-------------
 
 Enabling serial NVRAM support enables detection of the serial NVRAM included
-on Symbios and some Symbios compatible host adaptors, and Tekram boards. The 
-serial NVRAM is used by Symbios and Tekram to hold set up parameters for the 
+on Symbios and some Symbios compatible host adaptors, and Tekram boards. The
+serial NVRAM is used by Symbios and Tekram to hold set up parameters for the
 host adaptor and its attached drives.
 
 The Symbios NVRAM also holds data on the boot order of host adaptors in a
@@ -694,102 +840,122 @@ system with more than one host adaptor.  This information is no longer used
 as it's fundamentally incompatible with the hotplug PCI model.
 
 Tekram boards using Symbios chips, DC390W/F/U, which have NVRAM are detected
-and this is used to distinguish between Symbios compatible and Tekram host 
+and this is used to distinguish between Symbios compatible and Tekram host
 adaptors. This is used to disable the Symbios compatible "diff" setting
-incorrectly set on Tekram boards if the CONFIG_SCSI_53C8XX_SYMBIOS_COMPAT 
-configuration parameter is set enabling both Symbios and Tekram boards to be 
+incorrectly set on Tekram boards if the CONFIG_SCSI_53C8XX_SYMBIOS_COMPAT
+configuration parameter is set enabling both Symbios and Tekram boards to be
 used together with the Symbios cards using all their features, including
 "diff" support. ("led pin" support for Symbios compatible cards can remain
 enabled when using Tekram cards. It does nothing useful for Tekram host
 adaptors but does not cause problems either.)
 
-The parameters the driver is able to get from the NVRAM depend on the 
+The parameters the driver is able to get from the NVRAM depend on the
 data format used, as follow:
 
-                                 Tekram format      Symbios format
-General and host parameters
-    Boot order                         N                   Y
-    Host SCSI ID                       Y                   Y
-    SCSI parity checking               Y                   Y
-    Verbose boot messages              N                   Y
-SCSI devices parameters
-    Synchronous transfer speed         Y                   Y
-    Wide 16 / Narrow                   Y                   Y
-    Tagged Command Queuing enabled     Y                   Y
-    Disconnections enabled             Y                   Y
-    Scan at boot time                  N                   Y
-
-In order to speed up the system boot, for each device configured without 
-the "scan at boot time" option, the driver forces an error on the 
++-------------------------------+------------------+--------------+
+|                               |Tekram format     |Symbios format|
++-------------------------------+------------------+--------------+
+|General and host parameters    |                  |              |
++-------------------------------+------------------+--------------+
+|  * Boot order                 |        N         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Host SCSI ID               |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * SCSI parity checking       |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Verbose boot messages      |        N         |       Y      |
++-------------------------------+------------------+--------------+
+|SCSI devices parameters                                          |
++-------------------------------+------------------+--------------+
+|  * Synchronous transfer speed |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Wide 16 / Narrow           |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Tagged Command Queuing     |        Y         |       Y      |
+|    enabled                    |                  |              |
++-------------------------------+------------------+--------------+
+|  * Disconnections enabled     |        Y         |       Y      |
++-------------------------------+------------------+--------------+
+|  * Scan at boot time          |        N         |       Y      |
++-------------------------------+------------------+--------------+
+
+
+In order to speed up the system boot, for each device configured without
+the "scan at boot time" option, the driver forces an error on the
 first TEST UNIT READY command received for this device.
 
 
 17.2 Symbios NVRAM layout
+-------------------------
+
+typical data at NVRAM address 0x100 (53c810a NVRAM)::
+
+    00 00
+    64 01
+    8e 0b
+
+    00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
+
+    04 00 0f 00 00 10 00 50 00 00 01 00 00 62
+    04 00 03 00 00 10 00 58 00 00 01 00 00 63
+    04 00 01 00 00 10 00 48 00 00 01 00 00 61
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00
+
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+    00 00 00 00 00 00 00 00
+
+    fe fe
+    00 00
+    00 00
 
-typical data at NVRAM address 0x100 (53c810a NVRAM)
------------------------------------------------------------
-00 00
-64 01
-8e 0b
-
-00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00 
-
-04 00 0f 00 00 10 00 50 00 00 01 00 00 62 
-04 00 03 00 00 10 00 58 00 00 01 00 00 63 
-04 00 01 00 00 10 00 48 00 00 01 00 00 61 
-00 00 00 00 00 00 00 00 00 00 00 00 00 00 
-
-0f 00 08 08 64 00 0a 00
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-00 00 00 00 00 00 00 00 
-
-fe fe
-00 00
-00 00
------------------------------------------------------------
 NVRAM layout details
 
-NVRAM Address 0x000-0x0ff not used
-              0x100-0x26f initialised data
-              0x270-0x7ff not used
+============= =================
+NVRAM Address
+============= =================
+0x000-0x0ff   not used
+0x100-0x26f   initialised data
+0x270-0x7ff   not used
+============= =================
 
-general layout
+general layout::
 
         header  -   6 bytes,
         data    - 356 bytes (checksum is byte sum of this data)
@@ -797,7 +963,7 @@ general layout
                   ---
         total     368 bytes
 
-data area layout
+data area layout::
 
         controller set up  -  20 bytes
         boot configuration -  56 bytes (4x14 bytes)
@@ -806,52 +972,51 @@ data area layout
                              ---
         total                356 bytes
 
------------------------------------------------------------
-header
-
-00 00   - ?? start marker
-64 01   - byte count (lsb/msb excludes header/trailer)
-8e 0b   - checksum (lsb/msb excludes header/trailer)
------------------------------------------------------------
-controller set up
-
-00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
-                   |     |           |     |
-                   |     |           |      -- host ID
-                   |     |           |
-                   |     |            --Removable Media Support
-                   |     |               0x00 = none
-                   |     |               0x01 = Bootable Device
-                   |     |               0x02 = All with Media
-                   |     |
-                   |      --flag bits 2
-                   |        0x00000001= scan order hi->low
-                   |            (default 0x00 - scan low->hi)
-                    --flag bits 1
-                       0x00000001 scam enable
-                       0x00000010 parity enable
-                       0x00000100 verbose boot msgs
+header::
+
+    00 00   - ?? start marker
+    64 01   - byte count (lsb/msb excludes header/trailer)
+    8e 0b   - checksum (lsb/msb excludes header/trailer)
+
+controller set up::
+
+    00 30 00 00 00 00 07 00 00 00 00 00 00 00 07 04 10 04 00 00
+		    |     |           |     |
+		    |     |           |      -- host ID
+		    |     |           |
+		    |     |            --Removable Media Support
+		    |     |               0x00 = none
+		    |     |               0x01 = Bootable Device
+		    |     |               0x02 = All with Media
+		    |     |
+		    |      --flag bits 2
+		    |        0x00000001= scan order hi->low
+		    |            (default 0x00 - scan low->hi)
+			--flag bits 1
+			0x00000001 scam enable
+			0x00000010 parity enable
+			0x00000100 verbose boot msgs
 
 remaining bytes unknown - they do not appear to change in my
 current set up for any of the controllers.
 
 default set up is identical for 53c810a and 53c875 NVRAM
 (Removable Media added Symbios BIOS version 4.09)
------------------------------------------------------------
+
 boot configuration
 
-boot order set by order of the devices in this table
+boot order set by order of the devices in this table::
 
-04 00 0f 00 00 10 00 50 00 00 01 00 00 62 -- 1st controller
-04 00 03 00 00 10 00 58 00 00 01 00 00 63    2nd controller
-04 00 01 00 00 10 00 48 00 00 01 00 00 61    3rd controller
-00 00 00 00 00 00 00 00 00 00 00 00 00 00    4th controller
-       |  |  |  |     |        |     |  |
-       |  |  |  |     |        |      ---- PCI io port adr
-       |  |  |  |     |         --0x01 init/scan at boot time
-       |  |  |  |      --PCI device/function number (0xdddddfff)
-       |  |   ----- ?? PCI vendor ID (lsb/msb)
-        ----PCI device ID (lsb/msb)
+    04 00 0f 00 00 10 00 50 00 00 01 00 00 62 -- 1st controller
+    04 00 03 00 00 10 00 58 00 00 01 00 00 63    2nd controller
+    04 00 01 00 00 10 00 48 00 00 01 00 00 61    3rd controller
+    00 00 00 00 00 00 00 00 00 00 00 00 00 00    4th controller
+	|  |  |  |     |        |     |  |
+	|  |  |  |     |        |      ---- PCI io port adr
+	|  |  |  |     |         --0x01 init/scan at boot time
+	|  |  |  |      --PCI device/function number (0xdddddfff)
+	|  |   ----- ?? PCI vendor ID (lsb/msb)
+	    ----PCI device ID (lsb/msb)
 
 ?? use of this data is a guess but seems reasonable
 
@@ -859,120 +1024,120 @@ remaining bytes unknown - they do not appear to change in my
 current set up
 
 default set up is identical for 53c810a and 53c875 NVRAM
------------------------------------------------------------
-device set up (up to 16 devices - includes controller)
-
-0f 00 08 08 64 00 0a 00 - id 0
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 
-0f 00 08 08 64 00 0a 00 - id 15
- |     |  |  |     |  |
- |     |  |  |      ----timeout (lsb/msb)
- |     |  |   --synch period (0x?? 40 Mtrans/sec- fast 40) (probably 0x28)
- |     |  |                  (0x30 20 Mtrans/sec- fast 20)
- |     |  |                  (0x64 10 Mtrans/sec- fast )
- |     |  |                  (0xc8  5 Mtrans/sec)
- |     |  |                  (0x00  asynchronous)
- |     |   -- ?? max sync offset (0x08 in NVRAM on 53c810a) 
- |     |                         (0x10 in NVRAM on 53c875)
- |      --device bus width (0x08 narrow)
- |                         (0x10 16 bit wide)
-  --flag bits
-    0x00000001 - disconnect enabled
-    0x00000010 - scan at boot time
-    0x00000100 - scan luns
-    0x00001000 - queue tags enabled
+
+device set up (up to 16 devices - includes controller)::
+
+    0f 00 08 08 64 00 0a 00 - id 0
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00
+    0f 00 08 08 64 00 0a 00 - id 15
+    |     |  |  |     |  |
+    |     |  |  |      ----timeout (lsb/msb)
+    |     |  |   --synch period (0x?? 40 Mtrans/sec- fast 40) (probably 0x28)
+    |     |  |                  (0x30 20 Mtrans/sec- fast 20)
+    |     |  |                  (0x64 10 Mtrans/sec- fast )
+    |     |  |                  (0xc8  5 Mtrans/sec)
+    |     |  |                  (0x00  asynchronous)
+    |     |   -- ?? max sync offset (0x08 in NVRAM on 53c810a)
+    |     |                         (0x10 in NVRAM on 53c875)
+    |      --device bus width (0x08 narrow)
+    |                         (0x10 16 bit wide)
+    --flag bits
+	0x00000001 - disconnect enabled
+	0x00000010 - scan at boot time
+	0x00000100 - scan luns
+	0x00001000 - queue tags enabled
 
 remaining bytes unknown - they do not appear to change in my
 current set up
 
-?? use of this data is a guess but seems reasonable 
+?? use of this data is a guess but seems reasonable
 (but it could be max bus width)
 
 default set up for 53c810a NVRAM
-default set up for 53c875 NVRAM - bus width     - 0x10
+default set up for 53c875 NVRAM
+
+				- bus width     - 0x10
                                 - sync offset ? - 0x10
                                 - sync period   - 0x30
------------------------------------------------------------
-?? spare device space (32 bit bus ??)
-
-00 00 00 00 00 00 00 00  (19x8bytes)
-.
-.
-00 00 00 00 00 00 00 00
 
-default set up is identical for 53c810a and 53c875 NVRAM
------------------------------------------------------------
-trailer
+?? spare device space (32 bit bus ??)::
 
-fe fe   - ? end marker ?
-00 00
-00 00
+    00 00 00 00 00 00 00 00  (19x8bytes)
+    .
+    .
+    00 00 00 00 00 00 00 00
 
 default set up is identical for 53c810a and 53c875 NVRAM
------------------------------------------------------------
 
+trailer::
 
+    fe fe   - ? end marker ?
+    00 00
+    00 00
+
+default set up is identical for 53c810a and 53c875 NVRAM
 
 17.3 Tekram NVRAM layout
+------------------------
 
 nvram 64x16 (1024 bit)
 
-Drive settings
-
-Drive ID 0-15 (addr 0x0yyyy0 = device setup, yyyy = ID)
-              (addr 0x0yyyy1 = 0x0000)
-
-    x x x x  x x x x  x x x x  x x x x
-               | | |      | |  | | | |
-               | | |      | |  | | |  ----- parity check   0 - off
-               | | |      | |  | | |                       1 - on
-               | | |      | |  | | |
-               | | |      | |  | |  ------- sync neg       0 - off
-               | | |      | |  | |                         1 - on
-               | | |      | |  | |
-               | | |      | |  |  --------- disconnect     0 - off
-               | | |      | |  |                           1 - on
-               | | |      | |  |
-               | | |      | |   ----------- start cmd      0 - off
-               | | |      | |                              1 - on
-               | | |      | |
-               | | |      |  -------------- tagged cmds    0 - off
-               | | |      |                                1 - on
-               | | |      | 
-               | | |       ---------------- wide neg       0 - off
-               | | |                                       1 - on
-               | | |
-                --------------------------- sync rate      0 - 10.0 Mtrans/sec
-                                                           1 -  8.0
-                                                           2 -  6.6
-                                                           3 -  5.7
-                                                           4 -  5.0
-                                                           5 -  4.0
-                                                           6 -  3.0
-                                                           7 -  2.0
-                                                           7 -  2.0
-                                                           8 - 20.0
-                                                           9 - 16.7
-                                                           a - 13.9
-                                                           b - 11.9
+Drive settings::
+
+    Drive ID 0-15 (addr 0x0yyyy0 = device setup, yyyy = ID)
+		(addr 0x0yyyy1 = 0x0000)
+
+	x x x x  x x x x  x x x x  x x x x
+		| | |      | |  | | | |
+		| | |      | |  | | |  ----- parity check   0 - off
+		| | |      | |  | | |                       1 - on
+		| | |      | |  | | |
+		| | |      | |  | |  ------- sync neg       0 - off
+		| | |      | |  | |                         1 - on
+		| | |      | |  | |
+		| | |      | |  |  --------- disconnect     0 - off
+		| | |      | |  |                           1 - on
+		| | |      | |  |
+		| | |      | |   ----------- start cmd      0 - off
+		| | |      | |                              1 - on
+		| | |      | |
+		| | |      |  -------------- tagged cmds    0 - off
+		| | |      |                                1 - on
+		| | |      |
+		| | |       ---------------- wide neg       0 - off
+		| | |                                       1 - on
+		| | |
+		    --------------------------- sync rate      0 - 10.0 Mtrans/sec
+							    1 -  8.0
+							    2 -  6.6
+							    3 -  5.7
+							    4 -  5.0
+							    5 -  4.0
+							    6 -  3.0
+							    7 -  2.0
+							    7 -  2.0
+							    8 - 20.0
+							    9 - 16.7
+							    a - 13.9
+							    b - 11.9
 
 Global settings
 
-Host flags 0 (addr 0x100000, 32) 
+Host flags 0 (addr 0x100000, 32)::
 
     x x x x  x x x x  x x x x  x x x x
     | | | |  | | | |           | | | |
@@ -980,7 +1145,7 @@ Host flags 0 (addr 0x100000, 32)
     | | | |  | | | |
     | | | |  | | |  ----------------------- support for    0 - off
     | | | |  | | |                          > 2 drives     1 - on
-    | | | |  | | | 
+    | | | |  | | |
     | | | |  | |  ------------------------- support drives 0 - off
     | | | |  | |                            > 1Gbytes      1 - on
     | | | |  | |
@@ -1000,10 +1165,10 @@ Host flags 0 (addr 0x100000, 32)
                                             as BIOS dev    1 - boot device
                                                            2 - all
 
-Host flags 1 (addr 0x100001, 33)
+Host flags 1 (addr 0x100001, 33)::
 
     x x x x  x x x x  x x x x  x x x x
-               | | |             | | | 
+               | | |             | | |
                | | |              --------- boot delay     0 -   3 sec
                | | |                                       1 -   5
                | | |                                       2 -  10
@@ -1018,7 +1183,7 @@ Host flags 1 (addr 0x100001, 33)
                                                            3 - 16
                                                            4 - 32
 
-Host flags 2 (addr 0x100010, 34)
+Host flags 2 (addr 0x100010, 34)::
 
     x x x x  x x x x  x x x x  x x x x
                                      |
@@ -1031,18 +1196,14 @@ checksum = 0x1234 - (sum addr 0-63)
 
 ----------------------------------------------------------------------------
 
-default nvram data:
-
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
-0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 
-
-0x0f07 0x0400 0x0001 0x0000 0x0000 0x0000 0x0000 0x0000
-0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
-0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
-0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0xfbbc
+default nvram data::
 
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
+    0x0037 0x0000 0x0037 0x0000 0x0037 0x0000 0x0037 0x0000
 
-===============================================================================
-End of Linux SYM-2 driver documentation file
+    0x0f07 0x0400 0x0001 0x0000 0x0000 0x0000 0x0000 0x0000
+    0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
+    0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000
+    0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0x0000 0xfbbc
diff --git a/Documentation/scsi/tcm_qla2xxx.txt b/Documentation/scsi/tcm_qla2xxx.rst
index c3a670a25e2b..91bc1fcd369e 100644
--- a/Documentation/scsi/tcm_qla2xxx.txt
+++ b/Documentation/scsi/tcm_qla2xxx.rst
@@ -1,22 +1,36 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================
+tcm_qla2xxx Driver Notes
+========================
+
 tcm_qla2xxx jam_host attribute
 ------------------------------
 There is now a new module endpoint atribute called jam_host
-attribute: jam_host: boolean=0/1
+attribute::
+
+	jam_host: boolean=0/1
+
 This attribute and accompanying code is only included if the
 Kconfig parameter TCM_QLA2XXX_DEBUG is set to Y
+
 By default this jammer code and functionality is disabled
 
 Use this attribute to control the discarding of SCSI commands to a
 selected host.
+
 This may be useful for testing error handling and simulating slow drain
 and other fabric issues.
 
 Setting a boolean of 1 for the jam_host attribute for a particular host
- will discard the commands for that host.
+will discard the commands for that host.
+
 Reset back to 0 to stop the jamming.
 
-Enable host 4 to be jammed
-echo 1 > /sys/kernel/config/target/qla2xxx/21:00:00:24:ff:27:8f:ae/tpgt_1/attrib/jam_host
+Enable host 4 to be jammed::
+
+  echo 1 > /sys/kernel/config/target/qla2xxx/21:00:00:24:ff:27:8f:ae/tpgt_1/attrib/jam_host
+
+Disable jamming on host 4::
 
-Disable jamming on host 4
-echo 0 > /sys/kernel/config/target/qla2xxx/21:00:00:24:ff:27:8f:ae/tpgt_1/attrib/jam_host
+  echo 0 > /sys/kernel/config/target/qla2xxx/21:00:00:24:ff:27:8f:ae/tpgt_1/attrib/jam_host
diff --git a/Documentation/scsi/ufs.txt b/Documentation/scsi/ufs.rst
index 81842ec3e116..a920c0a5a1f6 100644
--- a/Documentation/scsi/ufs.txt
+++ b/Documentation/scsi/ufs.rst
@@ -1,24 +1,26 @@
-                       Universal Flash Storage
-                       =======================
+.. SPDX-License-Identifier: GPL-2.0
 
+=======================
+Universal Flash Storage
+=======================
 
-Contents
---------
 
-1. Overview
-2. UFS Architecture Overview
-  2.1 Application Layer
-  2.2 UFS Transport Protocol(UTP) layer
-  2.3 UFS Interconnect(UIC) Layer
-3. UFSHCD Overview
-  3.1 UFS controller initialization
-  3.2 UTP Transfer requests
-  3.3 UFS error handling
-  3.4 SCSI Error handling
+.. Contents
+
+   1. Overview
+   2. UFS Architecture Overview
+     2.1 Application Layer
+     2.2 UFS Transport Protocol(UTP) layer
+     2.3 UFS Interconnect(UIC) Layer
+   3. UFSHCD Overview
+     3.1 UFS controller initialization
+     3.2 UTP Transfer requests
+     3.3 UFS error handling
+     3.4 SCSI Error handling
 
 
 1. Overview
------------
+===========
 
 Universal Flash Storage(UFS) is a storage specification for flash devices.
 It is aimed to provide a universal storage interface for both
@@ -28,19 +30,25 @@ is defined by JEDEC Solid State Technology Association. UFS is based
 on MIPI M-PHY physical layer standard. UFS uses MIPI M-PHY as the
 physical layer and MIPI Unipro as the link layer.
 
-The main goals of UFS is to provide,
+The main goals of UFS is to provide:
+
  * Optimized performance:
-   For UFS version 1.0 and 1.1 the target performance is as follows,
-   Support for Gear1 is mandatory (rate A: 1248Mbps, rate B: 1457.6Mbps)
-   Support for Gear2 is optional (rate A: 2496Mbps, rate B: 2915.2Mbps)
+
+   For UFS version 1.0 and 1.1 the target performance is as follows:
+
+   - Support for Gear1 is mandatory (rate A: 1248Mbps, rate B: 1457.6Mbps)
+   - Support for Gear2 is optional (rate A: 2496Mbps, rate B: 2915.2Mbps)
+
    Future version of the standard,
-   Gear3 (rate A: 4992Mbps, rate B: 5830.4Mbps)
+
+   - Gear3 (rate A: 4992Mbps, rate B: 5830.4Mbps)
+
  * Low power consumption
  * High random IOPs and low latency
 
 
 2. UFS Architecture Overview
-----------------------------
+============================
 
 UFS has a layered communication architecture which is based on SCSI
 SAM-5 architectural model.
@@ -48,16 +56,22 @@ SAM-5 architectural model.
 UFS communication architecture consists of following layers,
 
 2.1 Application Layer
+---------------------
 
   The Application layer is composed of UFS command set layer(UCS),
   Task Manager and Device manager. The UFS interface is designed to be
   protocol agnostic, however SCSI has been selected as a baseline
   protocol for versions 1.0 and 1.1 of UFS protocol  layer.
+
   UFS supports subset of SCSI commands defined by SPC-4 and SBC-3.
-  * UCS: It handles SCSI commands supported by UFS specification.
-  * Task manager: It handles task management functions defined by the
+
+  * UCS:
+     It handles SCSI commands supported by UFS specification.
+  * Task manager:
+     It handles task management functions defined by the
      UFS which are meant for command queue control.
-  * Device manager: It handles device level operations and device
+  * Device manager:
+     It handles device level operations and device
      configuration operations. Device level operations mainly involve
      device power management operations and commands to Interconnect
      layers. Device level configurations involve handling of query
@@ -65,10 +79,12 @@ UFS communication architecture consists of following layers,
      information of the device.
 
 2.2 UFS Transport Protocol(UTP) layer
+-------------------------------------
 
   UTP layer provides services for
   the higher layers through Service Access Points. UTP defines 3
   service access points for higher layers.
+
   * UDM_SAP: Device manager service access point is exposed to device
     manager for device level operations. These device level operations
     are done through query requests.
@@ -76,20 +92,23 @@ UFS communication architecture consists of following layers,
     set layer(UCS) to transport commands.
   * UTP_TM_SAP: Task management service access point is exposed to task
     manager to transport task management functions.
+
   UTP transports messages through UFS protocol information unit(UPIU).
 
 2.3 UFS Interconnect(UIC) Layer
+-------------------------------
 
   UIC is the lowest layer of UFS layered architecture. It handles
   connection between UFS host and UFS device. UIC consists of
   MIPI UniPro and MIPI M-PHY. UIC provides 2 service access points
   to upper layer,
+
   * UIC_SAP: To transport UPIU between UFS host and UFS device.
   * UIO_SAP: To issue commands to Unipro layers.
 
 
 3. UFSHCD Overview
-------------------
+==================
 
 The UFS host controller driver is based on Linux SCSI Framework.
 UFSHCD is a low level device driver which acts as an interface between
@@ -98,12 +117,14 @@ SCSI Midlayer and PCIe based UFS host controllers.
 The current UFSHCD implementation supports following functionality,
 
 3.1 UFS controller initialization
+---------------------------------
 
   The initialization module brings UFS host controller to active state
   and prepares the controller to transfer commands/response between
   UFSHCD and UFS device.
 
 3.2 UTP Transfer requests
+-------------------------
 
   Transfer request handling module of UFSHCD receives SCSI commands
   from SCSI Midlayer, forms UPIUs and issues the UPIUs to UFS Host
@@ -112,11 +133,13 @@ The current UFSHCD implementation supports following functionality,
   of the status of the command.
 
 3.3 UFS error handling
+----------------------
 
   Error handling module handles Host controller fatal errors,
   Device fatal errors and UIC interconnect layer related errors.
 
 3.4 SCSI Error handling
+-----------------------
 
   This is done through UFSHCD SCSI error handling routines registered
   with SCSI Midlayer. Examples of some of the error handling commands
@@ -129,7 +152,7 @@ In this version of UFSHCD Query requests and power management
 functionality are not implemented.
 
 4. BSG Support
-------------------
+==============
 
 This transport driver supports exchanging UFS protocol information units
 (UPIUs) with a UFS device. Typically, user space will allocate
@@ -138,7 +161,7 @@ request_upiu and reply_upiu respectively.  Filling those UPIUs should
 be done in accordance with JEDEC spec UFS2.1 paragraph 10.7.
 *Caveat emptor*: The driver makes no further input validations and sends the
 UPIU to the device as it is.  Open the bsg device in /dev/ufs-bsg and
-send SG_IO with the applicable sg_io_v4:
+send SG_IO with the applicable sg_io_v4::
 
 	io_hdr_v4.guard = 'Q';
 	io_hdr_v4.protocol = BSG_PROTOCOL_SCSI;
@@ -166,6 +189,7 @@ upiu-based protocol is available at:
 For more detailed information about the tool and its supported
 features, please see the tool's README.
 
-UFS Specifications can be found at,
-UFS - http://www.jedec.org/sites/default/files/docs/JESD220.pdf
-UFSHCI - http://www.jedec.org/sites/default/files/docs/JESD223.pdf
+UFS Specifications can be found at:
+
+- UFS - http://www.jedec.org/sites/default/files/docs/JESD220.pdf
+- UFSHCI - http://www.jedec.org/sites/default/files/docs/JESD223.pdf
diff --git a/Documentation/scsi/wd719x.rst b/Documentation/scsi/wd719x.rst
new file mode 100644
index 000000000000..a35015dfedd9
--- /dev/null
+++ b/Documentation/scsi/wd719x.rst
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===============================================================
+Driver for Western Digital WD7193, WD7197 and WD7296 SCSI cards
+===============================================================
+
+The card requires firmware that can be cut out of the Windows NT driver that
+can be downloaded from WD at:
+http://support.wdc.com/product/download.asp?groupid=801&sid=27&lang=en
+
+There is no license anywhere in the file or on the page - so the firmware
+probably cannot be added to linux-firmware.
+
+This script downloads and extracts the firmware, creating wd719x-risc.bin and
+d719x-wcs.bin files. Put them in /lib/firmware/::
+
+	#!/bin/sh
+	wget http://support.wdc.com/download/archive/pciscsi.exe
+	lha xi pciscsi.exe pci-scsi.exe
+	lha xi pci-scsi.exe nt/wd7296a.sys
+	rm pci-scsi.exe
+	dd if=wd7296a.sys of=wd719x-risc.bin bs=1 skip=5760 count=14336
+	dd if=wd7296a.sys of=wd719x-wcs.bin bs=1 skip=20096 count=514
+	rm wd7296a.sys
diff --git a/Documentation/scsi/wd719x.txt b/Documentation/scsi/wd719x.txt
deleted file mode 100644
index 0816b0220238..000000000000
--- a/Documentation/scsi/wd719x.txt
+++ /dev/null
@@ -1,21 +0,0 @@
-Driver for Western Digital WD7193, WD7197 and WD7296 SCSI cards
----------------------------------------------------------------
-
-The card requires firmware that can be cut out of the Windows NT driver that
-can be downloaded from WD at:
-http://support.wdc.com/product/download.asp?groupid=801&sid=27&lang=en
-
-There is no license anywhere in the file or on the page - so the firmware
-probably cannot be added to linux-firmware.
-
-This script downloads and extracts the firmware, creating wd719x-risc.bin and
-d719x-wcs.bin files. Put them in /lib/firmware/.
-
-#!/bin/sh
-wget http://support.wdc.com/download/archive/pciscsi.exe
-lha xi pciscsi.exe pci-scsi.exe
-lha xi pci-scsi.exe nt/wd7296a.sys
-rm pci-scsi.exe
-dd if=wd7296a.sys of=wd719x-risc.bin bs=1 skip=5760 count=14336
-dd if=wd7296a.sys of=wd719x-wcs.bin bs=1 skip=20096 count=514
-rm wd7296a.sys