* [PATCH v4] docs: aha152x.txt convert it to ReST
@ 2019-07-03 6:14 Sushma Unnibhavi
0 siblings, 0 replies; only message in thread
From: Sushma Unnibhavi @ 2019-07-03 6:14 UTC (permalink / raw)
To: skhan
Cc: Sushma Unnibhavi, corbet, mchehab, linux-kernel-mentees,
linux-doc, linux-kernel
This patch converts aha152x.rst
to ReST format, No content change.
Added aha152x.rst to sh/index.rst
Added SPDX tag in index.rst
Signed-off-by: Sushma Unnibhavi <sushmaunnibhavi425@gmail.com>
---
Documentation/driver-api/index.rst | 1 +
Documentation/scsi/aha152x.rst | 203 ++++++++++++++++++++++++++++
Documentation/scsi/aha152x.txt | 183 -------------------------
Documentation/scsi/source/conf.py | 52 +++++++
Documentation/scsi/source/index.rst | 22 +++
5 files changed, 278 insertions(+), 183 deletions(-)
create mode 100644 Documentation/scsi/aha152x.rst
delete mode 100644 Documentation/scsi/aha152x.txt
create mode 100644 Documentation/scsi/source/conf.py
create mode 100644 Documentation/scsi/source/index.rst
diff --git a/Documentation/driver-api/index.rst b/Documentation/driver-api/index.rst
index d26308af6036..e26809c95c79 100644
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -32,6 +32,7 @@ available subsections can be seen below.
usb/index
firewire
pci/index
+ scsi/index
spi
i2c
i3c/index
diff --git a/Documentation/scsi/aha152x.rst b/Documentation/scsi/aha152x.rst
new file mode 100644
index 000000000000..3c4d558b9daf
--- /dev/null
+++ b/Documentation/scsi/aha152x.rst
@@ -0,0 +1,203 @@
+
+=====================================================
+Adaptec AHA-1520/1522 SCSI driver for Linux (aha152x)
+=====================================================
+
+Copyright 1993-1999 Jürgen Fischer <fischer@norbit.de>
+TC1550 patches by Luuk van Dijk (ldz@xs4all.nl)
+
+
+In Revision 2 the driver was modified a lot (especially the
+bottom-half handler complete()).
+
+The driver is much cleaner now, has support for the new
+error handling code in 2.3, produced less cpu load (much
+less polling loops), has slightly higher throughput (at
+least on my ancient test box; a i486/33Mhz/20MB).
+
+
+========================
+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) |
++-----------+------------------------------------------+---------------------------+
+|RECONNECT | allow targets to disconnect from the bus| (0/1; default 1 [on]) |
++-----------+------------------------------------------+---------------------------+
+|PARITY | enable parity checking | (0/1; default 1 [on]) |
++-----------+------------------------------------------+---------------------------+
+|SYNCHRONOUS| enable synchronous transfers | (0/1; default 1 [on]) |
++-----------+------------------------------------------+---------------------------+
+|DELAY: | bus reset delay | (default 100) |
++-----------+------------------------------------------+---------------------------+
+|EXT_TRANS: | enable extended translation (see NOTES) | (0/1: default 0 [off]) |
++-----------+------------------------------------------+---------------------------+
+
+========================================================================
+Compile Time Configuration (go into AHA152X in drivers/scsi/Makefile)
+========================================================================
+
+-DAUTOCONF
+ use configuration the controller reports (AHA-152x only)
+
+-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
+
+-DSETUP1="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
+ override for the second controller
+
+-DAHA152X_DEBUG
+ enable debugging output
+
+-DAHA152X_STAT
+ enable some statistics
+
+
+==========================
+Lilo Command Line Options
+==========================
+
+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 valid (known). Don't use values that aren't supported
+under normal operation. If you think that you need other values:
+contact me. For two controllers use the aha152x statement twice.
+
+
+=================================
+Symbols For Module Configuration
+=================================
+---------------------------
+Choose From 2 Alternatives
+---------------------------
+1. specify everything (old)
+
+ 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
+ configuration override for second controller
+
+2. specify only what you need to (irq or io is required; new)
+
+ io=IOPORT0[,IOPORT1]
+ IOPORT for first and second controller
+
+ irq=IRQ0[,IRQ1]
+ IRQ for first and second controller
+
+ scsiid=SCSIID0[,SCSIID1]
+ SCSIID for first and second controller
+
+ reconnect=RECONNECT0[,RECONNECT1]
+ allow targets to disconnect for first and second controller
+
+ parity=PAR0[PAR1]
+ use parity for first and second controller
+
+ sync=SYNCHRONOUS0[,SYNCHRONOUS1]
+ enable synchronous transfers for first and second controller
+
+ delay=DELAY0[,DELAY1]
+ reset DELAY for first and second controller
+
+ exttrans=EXTTRANS0[,EXTTRANS1]
+ enable extended translation for first and second controller
+
+
+If you use both alternatives the first will be taken.
+
+
+====================
+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)
+scheme instead. DOS expects a BIOS or driver that understands
+this C/H/S addressing.
+
+The number of cylinders/heads/sectors is called geometry and is
+required as base for requests in C/H/S addressing. SCSI only
+knows about the total capacity of disks in blocks (sectors).
+
+Therefore the SCSI BIOS/DOS driver has to calculate a logical/virtual
+geometry just to be able to support that addressing scheme. The
+geometry returned by the SCSI BIOS is a pure calculation and has
+nothing to do with the real/physical geometry of the disk (which
+is usually irrelevant anyway).
+
+Basically this has no impact at all on Linux, because it also uses block
+instead of C/H/S addressing. Unfortunately C/H/S addressing is also used
+in the partition table and therefore every operating system has to know
+the right geometry to be able to interpret it.
+
+Moreover there are certain limitations to the C/H/S addressing scheme,
+namely the address space is limited to up to 255 heads, up to 63 sectors
+and a maximum of 1023 cylinders.
+
+The AHA-1522 BIOS calculates the geometry by fixing the number of heads
+to 64, the number of sectors to 32 and by calculating the number of
+cylinders by dividing the capacity reported by the disk by 64*32 (1 MB).
+This is considered to be the default translation.
+
+With respect to the limit of 1023 cylinders using C/H/S you can only
+address the first GB of your disk in the partition table. Therefore
+BIOSes of some newer controllers based on the AIC-6260/6360 support
+extended translation. This means that the BIOS uses 255 for heads,
+63 for sectors and then divides the capacity of the disk by 255*63
+(about 8 MB), as soon it sees a disk greater than 1 GB. That results
+in a maximum of about 8 GB addressable diskspace in the partition
+table (but there are already bigger disks out there today).
+
+To make it even more complicated the translation mode might/might
+not be configurable in certain BIOS setups.
+
+This driver does some more or less failsafe guessing to get the
+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, ie. either (C/32/64) or (C/63/255)).
+ This can be extended translation even if it's not enabled in the driver.
+
+ - if that fails, take extended translation if enabled by override,
+ kernel or module parameter, otherwise take default translation and
+ ask the user for verification. This might on not yet partitioned
+ disks.
+
+
+==================
+REFERENCES USED:
+==================
+ "AIC-6260 SCSI Chip Specification", Adaptec Corporation.
+
+ "SCSI COMPUTER SYSTEM INTERFACE - 2 (SCSI-2)", X3T9.2/86-109 rev. 10h
+
+ "Writing a SCSI device driver for Linux", Rik Faith (faith@cs.unc.edu)
+
+ "Kernel Hacker's Guide", Michael K. Johnson (johnsonm@sunsite.unc.edu)
+
+ "Adaptec 1520/1522 User's Guide", Adaptec Corporation.
+
+ Michael K. Johnson (johnsonm@sunsite.unc.edu)
+
+ Drew Eckhardt (drew@cs.colorado.edu)
+
+ Eric Youngdale (eric@andante.org)
+
+ special thanks to Eric Youngdale for the free(!) supplying the
+ documentation on the chip.
diff --git a/Documentation/scsi/aha152x.txt b/Documentation/scsi/aha152x.txt
deleted file mode 100644
index 94848734ac66..000000000000
--- a/Documentation/scsi/aha152x.txt
+++ /dev/null
@@ -1,183 +0,0 @@
-$Id: README.aha152x,v 1.2 1999/12/25 15:32:30 fischer Exp fischer $
-Adaptec AHA-1520/1522 SCSI driver for Linux (aha152x)
-
-Copyright 1993-1999 Jürgen Fischer <fischer@norbit.de>
-TC1550 patches by Luuk van Dijk (ldz@xs4all.nl)
-
-
-In Revision 2 the driver was modified a lot (especially the
-bottom-half handler complete()).
-
-The driver is much cleaner now, has support for the new
-error handling code in 2.3, produced less cpu load (much
-less polling loops), has slightly higher throughput (at
-least on my ancient test box; a i486/33Mhz/20MB).
-
-
-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)
-RECONNECT allow targets to disconnect from the bus (0/1; default 1 [on])
-PARITY enable parity checking (0/1; default 1 [on])
-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):
-
--DAUTOCONF
- use configuration the controller reports (AHA-152x only)
-
--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
-
--DSETUP1="{ IOPORT, IRQ, SCSI_ID, RECONNECT, PARITY, SYNCHRONOUS, DELAY, EXT_TRANS }"
- override for the second controller
-
--DAHA152X_DEBUG
- enable debugging output
-
--DAHA152X_STAT
- enable some statistics
-
-
-LILO COMMAND LINE OPTIONS:
-
-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
- valid (known). Don't use values that aren't supported under normal
- operation. If you think that you need other values: contact me.
- For two controllers use the aha152x statement twice.
-
-
-SYMBOLS FOR MODULE CONFIGURATION:
-
-Choose from 2 alternatives:
-
-1. specify everything (old)
-
-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
- configuration override for second controller
-
-2. specify only what you need to (irq or io is required; new)
-
-io=IOPORT0[,IOPORT1]
- IOPORT for first and second controller
-
-irq=IRQ0[,IRQ1]
- IRQ for first and second controller
-
-scsiid=SCSIID0[,SCSIID1]
- SCSIID for first and second controller
-
-reconnect=RECONNECT0[,RECONNECT1]
- allow targets to disconnect for first and second controller
-
-parity=PAR0[PAR1]
- use parity for first and second controller
-
-sync=SYNCHRONOUS0[,SYNCHRONOUS1]
- enable synchronous transfers for first and second controller
-
-delay=DELAY0[,DELAY1]
- reset DELAY for first and second controller
-
-exttrans=EXTTRANS0[,EXTTRANS1]
- enable extended translation for first and second controller
-
-
-If you use both alternatives the first will be taken.
-
-
-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)
-scheme instead. DOS expects a BIOS or driver that understands this
-C/H/S addressing.
-
-The number of cylinders/heads/sectors is called geometry and is required
-as base for requests in C/H/S addressing. SCSI only knows about the
-total capacity of disks in blocks (sectors).
-
-Therefore the SCSI BIOS/DOS driver has to calculate a logical/virtual
-geometry just to be able to support that addressing scheme. The geometry
-returned by the SCSI BIOS is a pure calculation and has nothing to
-do with the real/physical geometry of the disk (which is usually
-irrelevant anyway).
-
-Basically this has no impact at all on Linux, because it also uses block
-instead of C/H/S addressing. Unfortunately C/H/S addressing is also used
-in the partition table and therefore every operating system has to know
-the right geometry to be able to interpret it.
-
-Moreover there are certain limitations to the C/H/S addressing scheme,
-namely the address space is limited to up to 255 heads, up to 63 sectors
-and a maximum of 1023 cylinders.
-
-The AHA-1522 BIOS calculates the geometry by fixing the number of heads
-to 64, the number of sectors to 32 and by calculating the number of
-cylinders by dividing the capacity reported by the disk by 64*32 (1 MB).
-This is considered to be the default translation.
-
-With respect to the limit of 1023 cylinders using C/H/S you can only
-address the first GB of your disk in the partition table. Therefore
-BIOSes of some newer controllers based on the AIC-6260/6360 support
-extended translation. This means that the BIOS uses 255 for heads,
-63 for sectors and then divides the capacity of the disk by 255*63
-(about 8 MB), as soon it sees a disk greater than 1 GB. That results
-in a maximum of about 8 GB addressable diskspace in the partition table
-(but there are already bigger disks out there today).
-
-To make it even more complicated the translation mode might/might
-not be configurable in certain BIOS setups.
-
-This driver does some more or less failsafe guessing to get the
-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,
- ie. either (C/32/64) or (C/63/255)). This can be extended translation
- even if it's not enabled in the driver.
-
- - if that fails, take extended translation if enabled by override,
- kernel or module parameter, otherwise take default translation and
- ask the user for verification. This might on not yet partitioned
- disks.
-
-
-REFERENCES USED:
-
- "AIC-6260 SCSI Chip Specification", Adaptec Corporation.
-
- "SCSI COMPUTER SYSTEM INTERFACE - 2 (SCSI-2)", X3T9.2/86-109 rev. 10h
-
- "Writing a SCSI device driver for Linux", Rik Faith (faith@cs.unc.edu)
-
- "Kernel Hacker's Guide", Michael K. Johnson (johnsonm@sunsite.unc.edu)
-
- "Adaptec 1520/1522 User's Guide", Adaptec Corporation.
-
- Michael K. Johnson (johnsonm@sunsite.unc.edu)
-
- Drew Eckhardt (drew@cs.colorado.edu)
-
- Eric Youngdale (eric@andante.org)
-
- special thanks to Eric Youngdale for the free(!) supplying the
- documentation on the chip.
diff --git a/Documentation/scsi/source/conf.py b/Documentation/scsi/source/conf.py
new file mode 100644
index 000000000000..8f60483b49fb
--- /dev/null
+++ b/Documentation/scsi/source/conf.py
@@ -0,0 +1,52 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# http://www.sphinx-doc.org/en/master/config
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'doc'
+copyright = '2019, sushma'
+author = 'sushma'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
diff --git a/Documentation/scsi/source/index.rst b/Documentation/scsi/source/index.rst
new file mode 100644
index 000000000000..003259e30a59
--- /dev/null
+++ b/Documentation/scsi/source/index.rst
@@ -0,0 +1,22 @@
+.. doc documentation master file, created by
+ sphinx-quickstart on Mon Jul 1 11:21:20 2019.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
+.SPDX-License-Identifier: GPL-2.0
+
+===============================
+SCSI Subsystem
+===============================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+aha152x
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--
2.17.1
^ permalink raw reply related [flat|nested] only message in thread
only message in thread, other threads:[~2019-07-03 6:15 UTC | newest]
Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2019-07-03 6:14 [PATCH v4] docs: aha152x.txt convert it to ReST Sushma Unnibhavi
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).