From f76576777a03bdd02bc8e5e71838c187051b17a0 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:36 +0100 Subject: scsi: docs: convert 53c700.txt to ReST Link: https://lore.kernel.org/r/a2e5116b70564f36b4fc7f1f1e5da1e693d7dadb.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- MAINTAINERS | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'MAINTAINERS') diff --git a/MAINTAINERS b/MAINTAINERS index 38fe2f3f7b6f..2bcab7c4cf3a 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -9386,7 +9386,7 @@ LASI 53c700 driver for PARISC M: "James E.J. Bottomley" L: linux-scsi@vger.kernel.org S: Maintained -F: Documentation/scsi/53c700.txt +F: Documentation/scsi/53c700.rst F: drivers/scsi/53c700* LEAKING_ADDRESSES -- cgit v1.2.3-59-g8ed1b From dd9cc1447ad39ddf09224357396d5e5175fb44dc Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:37 +0100 Subject: scsi: docs: convert aacraid.txt to ReST Link: https://lore.kernel.org/r/67c60ad88777c91937d49771e2a3f48cbf353e4c.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/aacraid.rst | 177 +++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/aacraid.txt | 150 ---------------------------------- Documentation/scsi/index.rst | 1 + MAINTAINERS | 2 +- drivers/scsi/Kconfig | 2 +- 5 files changed, 180 insertions(+), 152 deletions(-) create mode 100644 Documentation/scsi/aacraid.rst delete mode 100644 Documentation/scsi/aacraid.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/aacraid.rst b/Documentation/scsi/aacraid.rst new file mode 100644 index 000000000000..1904674b94f3 --- /dev/null +++ b/Documentation/scsi/aacraid.rst @@ -0,0 +1,177 @@ +.. 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 +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) + 9005:0285:9005:0288 Adaptec 3230S (Harrier) + 9005:0285:9005:0289 Adaptec 3240S (Tornado) + 9005:0285:9005:028a Adaptec 2020ZCR (Skyhawk) + 9005:0285:9005:028b Adaptec 2025ZCR (Terminator) + 9005:0286:9005:028c Adaptec 2230S (Lancer) + 9005:0286:9005:028c Adaptec 2230SLP (Lancer) + 9005:0286:9005:028d Adaptec 2130S (Lancer) + 9005:0285:9005:028e Adaptec 2020SA (Skyhawk) + 9005:0285:9005:028f Adaptec 2025SA (Terminator) + 9005:0285:9005:0290 Adaptec 2410SA (Jaguar) + 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) + 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16) + 9005:0285:9005:0296 Adaptec 2240S (SabreExpress) + 9005:0285:9005:0292 Adaptec 2810SA (Corsair-8) + 9005:0285:9005:0297 Adaptec 4005 (AvonPark) + 9005:0285:9005:0298 Adaptec 4000 (BlackBird) + 9005:0285:9005:0299 Adaptec 4800SAS (Marauder-X) + 9005:0285:9005:029a Adaptec 4805SAS (Marauder-E) + 9005:0286:9005:029b Adaptec 2820SA (Intruder) + 9005:0286:9005:029c Adaptec 2620SA (Intruder) + 9005:0286:9005:029d Adaptec 2420SA (Intruder HP release) + 9005:0286:9005:02ac Adaptec 1800 (Typhoon44) + 9005:0285:9005:02b5 Adaptec 5445 (Voodoo44) + 9005:0285:15d9:02b5 SMC AOC-USAS-S4i + 9005:0285:9005:02b6 Adaptec 5805 (Voodoo80) + 9005:0285:15d9:02b6 SMC AOC-USAS-S8i + 9005:0285:9005:02b7 Adaptec 5085 (Voodoo08) + 9005:0285:9005:02bb Adaptec 3405 (Marauder40LP) + 9005:0285:9005:02bc Adaptec 3805 (Marauder80LP) + 9005:0285:9005:02c7 Adaptec 3085 (Marauder08ELP) + 9005:0285:9005:02bd Adaptec 31205 (Marauder120) + 9005:0285:9005:02be Adaptec 31605 (Marauder160) + 9005:0285:9005:02c3 Adaptec 51205 (Voodoo120) + 9005:0285:9005:02c4 Adaptec 51605 (Voodoo160) + 9005:0285:15d9:02c9 SMC AOC-USAS-S4iR + 9005:0285:15d9:02ca SMC AOC-USAS-S8iR + 9005:0285:9005:02ce Adaptec 51245 (Voodoo124) + 9005:0285:9005:02cf Adaptec 51645 (Voodoo164) + 9005:0285:9005:02d0 Adaptec 52445 (Voodoo244) + 9005:0285:9005:02d1 Adaptec 5405 (Voodoo40) + 9005:0285:15d9:02d2 SMC AOC-USAS-S8i-LP + 9005:0285:15d9:02d3 SMC AOC-USAS-S8iR-LP + 9005:0285:9005:02d4 Adaptec ASR-2045 (Voodoo04 Lite) + 9005:0285:9005:02d5 Adaptec ASR-2405 (Voodoo40 Lite) + 9005:0285:9005:02d6 Adaptec ASR-2445 (Voodoo44 Lite) + 9005:0285:9005:02d7 Adaptec ASR-2805 (Voodoo80 Lite) + 9005:0285:9005:02d8 Adaptec 5405Z (Voodoo40 BLBU) + 9005:0285:9005:02d9 Adaptec 5445Z (Voodoo44 BLBU) + 9005:0285:9005:02da Adaptec 5805Z (Voodoo80 BLBU) + 1011:0046:9005:0364 Adaptec 5400S (Mustang) + 1011:0046:9005:0365 Adaptec 5400S (Mustang) + 9005:0287:9005:0800 Adaptec Themisto (Jupiter) + 9005:0200:9005:0200 Adaptec Themisto (Jupiter) + 9005:0286:9005:0800 Adaptec Callisto (Jupiter) + 1011:0046:9005:1364 Dell PERC 2/QC (Quad Channel, Mustang) + 1011:0046:9005:1365 Dell PERC 2/QC (Quad Channel, Mustang) + 1028:0001:1028:0001 Dell PERC 2/Si (Iguana) + 1028:0003:1028:0003 Dell PERC 3/Si (SlimFast) + 1028:0002:1028:0002 Dell PERC 3/Di (Opal) + 1028:0004:1028:0004 Dell PERC 3/SiF (Iguana) + 1028:0004:1028:00d0 Dell PERC 3/DiF (Iguana) + 1028:0002:1028:00d1 Dell PERC 3/DiV (Viper) + 1028:0002:1028:00d9 Dell PERC 3/DiL (Lexus) + 1028:000a:1028:0106 Dell PERC 3/DiJ (Jaguar) + 1028:000a:1028:011b Dell PERC 3/DiD (Dagger) + 1028:000a:1028:0121 Dell PERC 3/DiB (Boxster) + 9005:0285:1028:0287 Dell PERC 320/DC (Vulcan) + 9005:0285:1028:0291 Dell CERC 2 (DellCorsair) + 1011:0046:103c:10c2 HP NetRAID-4M (Mustang) + 9005:0285:17aa:0286 Legend S220 (Crusader) + 9005:0285:17aa:0287 Legend S230 (Vulcan) + 9005:0285:9005:0290 IBM ServeRAID 7t (Jaguar) + 9005:0285:1014:02F2 IBM ServeRAID 8i (AvonPark) + 9005:0286:1014:9540 IBM ServeRAID 8k/8k-l4 (AuroraLite) + 9005:0286:1014:9580 IBM ServeRAID 8k/8k-l8 (Aurora) + 9005:0285:1014:034d IBM ServeRAID 8s (Marauder-E) + 9005:0286:9005:029e ICP ICP9024RO (Lancer) + 9005:0286:9005:029f ICP ICP9014RO (Lancer) + 9005:0286:9005:02a0 ICP ICP9047MA (Lancer) + 9005:0286:9005:02a1 ICP ICP9087MA (Lancer) + 9005:0285:9005:02a4 ICP ICP9085LI (Marauder-X) + 9005:0285:9005:02a5 ICP ICP5085BR (Marauder-E) + 9005:0286:9005:02a6 ICP ICP9067MA (Intruder-6) + 9005:0285:9005:02b2 ICP (Voodoo 8 internal 8 external) + 9005:0285:9005:02b8 ICP ICP5445SL (Voodoo44) + 9005:0285:9005:02b9 ICP ICP5085SL (Voodoo80) + 9005:0285:9005:02ba ICP ICP5805SL (Voodoo08) + 9005:0285:9005:02bf ICP ICP5045BL (Marauder40LP) + 9005:0285:9005:02c0 ICP ICP5085BL (Marauder80LP) + 9005:0285:9005:02c8 ICP ICP5805BL (Marauder08ELP) + 9005:0285:9005:02c1 ICP ICP5125BR (Marauder120) + 9005:0285:9005:02c2 ICP ICP5165BR (Marauder160) + 9005:0285:9005:02c5 ICP ICP5125SL (Voodoo120) + 9005:0285:9005:02c6 ICP ICP5165SL (Voodoo160) + 9005:0286:9005:02ab (Typhoon40) + 9005:0286:9005:02ad (Aurora ARK) + 9005:0286:9005:02ae (Aurora Lite ARK) + 9005:0285:9005:02b0 (Sunrise Lake ARK) + 9005:0285:9005:02b1 Adaptec (Voodoo 8 internal 8 external) + 9005:0285:108e:7aac SUN STK RAID REM (Voodoo44 Coyote) + 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 + +Christoph Hellwig + +- updates for new-style PCI probing and SCSI host registration, + small cleanups/fixes + +Matt Domsch + +- 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 + +- Fixed panic issues and added some new product ids for upcoming hbas. +- Performance tuning, card failover and bug mitigations. + +Achim Leubner + +- 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/aacraid.txt b/Documentation/scsi/aacraid.txt deleted file mode 100644 index 30f643f611b2..000000000000 --- a/Documentation/scsi/aacraid.txt +++ /dev/null @@ -1,150 +0,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 -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) - 9005:0285:9005:0288 Adaptec 3230S (Harrier) - 9005:0285:9005:0289 Adaptec 3240S (Tornado) - 9005:0285:9005:028a Adaptec 2020ZCR (Skyhawk) - 9005:0285:9005:028b Adaptec 2025ZCR (Terminator) - 9005:0286:9005:028c Adaptec 2230S (Lancer) - 9005:0286:9005:028c Adaptec 2230SLP (Lancer) - 9005:0286:9005:028d Adaptec 2130S (Lancer) - 9005:0285:9005:028e Adaptec 2020SA (Skyhawk) - 9005:0285:9005:028f Adaptec 2025SA (Terminator) - 9005:0285:9005:0290 Adaptec 2410SA (Jaguar) - 9005:0285:103c:3227 Adaptec 2610SA (Bearcat HP release) - 9005:0285:9005:0293 Adaptec 21610SA (Corsair-16) - 9005:0285:9005:0296 Adaptec 2240S (SabreExpress) - 9005:0285:9005:0292 Adaptec 2810SA (Corsair-8) - 9005:0285:9005:0297 Adaptec 4005 (AvonPark) - 9005:0285:9005:0298 Adaptec 4000 (BlackBird) - 9005:0285:9005:0299 Adaptec 4800SAS (Marauder-X) - 9005:0285:9005:029a Adaptec 4805SAS (Marauder-E) - 9005:0286:9005:029b Adaptec 2820SA (Intruder) - 9005:0286:9005:029c Adaptec 2620SA (Intruder) - 9005:0286:9005:029d Adaptec 2420SA (Intruder HP release) - 9005:0286:9005:02ac Adaptec 1800 (Typhoon44) - 9005:0285:9005:02b5 Adaptec 5445 (Voodoo44) - 9005:0285:15d9:02b5 SMC AOC-USAS-S4i - 9005:0285:9005:02b6 Adaptec 5805 (Voodoo80) - 9005:0285:15d9:02b6 SMC AOC-USAS-S8i - 9005:0285:9005:02b7 Adaptec 5085 (Voodoo08) - 9005:0285:9005:02bb Adaptec 3405 (Marauder40LP) - 9005:0285:9005:02bc Adaptec 3805 (Marauder80LP) - 9005:0285:9005:02c7 Adaptec 3085 (Marauder08ELP) - 9005:0285:9005:02bd Adaptec 31205 (Marauder120) - 9005:0285:9005:02be Adaptec 31605 (Marauder160) - 9005:0285:9005:02c3 Adaptec 51205 (Voodoo120) - 9005:0285:9005:02c4 Adaptec 51605 (Voodoo160) - 9005:0285:15d9:02c9 SMC AOC-USAS-S4iR - 9005:0285:15d9:02ca SMC AOC-USAS-S8iR - 9005:0285:9005:02ce Adaptec 51245 (Voodoo124) - 9005:0285:9005:02cf Adaptec 51645 (Voodoo164) - 9005:0285:9005:02d0 Adaptec 52445 (Voodoo244) - 9005:0285:9005:02d1 Adaptec 5405 (Voodoo40) - 9005:0285:15d9:02d2 SMC AOC-USAS-S8i-LP - 9005:0285:15d9:02d3 SMC AOC-USAS-S8iR-LP - 9005:0285:9005:02d4 Adaptec ASR-2045 (Voodoo04 Lite) - 9005:0285:9005:02d5 Adaptec ASR-2405 (Voodoo40 Lite) - 9005:0285:9005:02d6 Adaptec ASR-2445 (Voodoo44 Lite) - 9005:0285:9005:02d7 Adaptec ASR-2805 (Voodoo80 Lite) - 9005:0285:9005:02d8 Adaptec 5405Z (Voodoo40 BLBU) - 9005:0285:9005:02d9 Adaptec 5445Z (Voodoo44 BLBU) - 9005:0285:9005:02da Adaptec 5805Z (Voodoo80 BLBU) - 1011:0046:9005:0364 Adaptec 5400S (Mustang) - 1011:0046:9005:0365 Adaptec 5400S (Mustang) - 9005:0287:9005:0800 Adaptec Themisto (Jupiter) - 9005:0200:9005:0200 Adaptec Themisto (Jupiter) - 9005:0286:9005:0800 Adaptec Callisto (Jupiter) - 1011:0046:9005:1364 Dell PERC 2/QC (Quad Channel, Mustang) - 1011:0046:9005:1365 Dell PERC 2/QC (Quad Channel, Mustang) - 1028:0001:1028:0001 Dell PERC 2/Si (Iguana) - 1028:0003:1028:0003 Dell PERC 3/Si (SlimFast) - 1028:0002:1028:0002 Dell PERC 3/Di (Opal) - 1028:0004:1028:0004 Dell PERC 3/SiF (Iguana) - 1028:0004:1028:00d0 Dell PERC 3/DiF (Iguana) - 1028:0002:1028:00d1 Dell PERC 3/DiV (Viper) - 1028:0002:1028:00d9 Dell PERC 3/DiL (Lexus) - 1028:000a:1028:0106 Dell PERC 3/DiJ (Jaguar) - 1028:000a:1028:011b Dell PERC 3/DiD (Dagger) - 1028:000a:1028:0121 Dell PERC 3/DiB (Boxster) - 9005:0285:1028:0287 Dell PERC 320/DC (Vulcan) - 9005:0285:1028:0291 Dell CERC 2 (DellCorsair) - 1011:0046:103c:10c2 HP NetRAID-4M (Mustang) - 9005:0285:17aa:0286 Legend S220 (Crusader) - 9005:0285:17aa:0287 Legend S230 (Vulcan) - 9005:0285:9005:0290 IBM ServeRAID 7t (Jaguar) - 9005:0285:1014:02F2 IBM ServeRAID 8i (AvonPark) - 9005:0286:1014:9540 IBM ServeRAID 8k/8k-l4 (AuroraLite) - 9005:0286:1014:9580 IBM ServeRAID 8k/8k-l8 (Aurora) - 9005:0285:1014:034d IBM ServeRAID 8s (Marauder-E) - 9005:0286:9005:029e ICP ICP9024RO (Lancer) - 9005:0286:9005:029f ICP ICP9014RO (Lancer) - 9005:0286:9005:02a0 ICP ICP9047MA (Lancer) - 9005:0286:9005:02a1 ICP ICP9087MA (Lancer) - 9005:0285:9005:02a4 ICP ICP9085LI (Marauder-X) - 9005:0285:9005:02a5 ICP ICP5085BR (Marauder-E) - 9005:0286:9005:02a6 ICP ICP9067MA (Intruder-6) - 9005:0285:9005:02b2 ICP (Voodoo 8 internal 8 external) - 9005:0285:9005:02b8 ICP ICP5445SL (Voodoo44) - 9005:0285:9005:02b9 ICP ICP5085SL (Voodoo80) - 9005:0285:9005:02ba ICP ICP5805SL (Voodoo08) - 9005:0285:9005:02bf ICP ICP5045BL (Marauder40LP) - 9005:0285:9005:02c0 ICP ICP5085BL (Marauder80LP) - 9005:0285:9005:02c8 ICP ICP5805BL (Marauder08ELP) - 9005:0285:9005:02c1 ICP ICP5125BR (Marauder120) - 9005:0285:9005:02c2 ICP ICP5165BR (Marauder160) - 9005:0285:9005:02c5 ICP ICP5125SL (Voodoo120) - 9005:0285:9005:02c6 ICP ICP5165SL (Voodoo160) - 9005:0286:9005:02ab (Typhoon40) - 9005:0286:9005:02ad (Aurora ARK) - 9005:0286:9005:02ae (Aurora Lite ARK) - 9005:0285:9005:02b0 (Sunrise Lake ARK) - 9005:0285:9005:02b1 Adaptec (Voodoo 8 internal 8 external) - 9005:0285:108e:7aac SUN STK RAID REM (Voodoo44 Coyote) - 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 -Christoph Hellwig (updates for new-style PCI probing and SCSI host registration, - small cleanups/fixes) -Matt Domsch (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 Fixed panic issues and added some new product ids for upcoming hbas. Performance tuning, card failover and bug mitigations. -Achim Leubner - -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/index.rst b/Documentation/scsi/index.rst index 99efc77c3ac2..2e0429d1a7a5 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -8,5 +8,6 @@ Linux SCSI Subsystem :maxdepth: 1 53c700 + aacraid scsi_transport_srp/figures diff --git a/MAINTAINERS b/MAINTAINERS index 2bcab7c4cf3a..3251b768fec0 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -236,7 +236,7 @@ M: Adaptec OEM Raid Solutions L: linux-scsi@vger.kernel.org W: http://www.adaptec.com/ S: Supported -F: Documentation/scsi/aacraid.txt +F: Documentation/scsi/aacraid.rst F: drivers/scsi/aacraid/ ABI/API diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig index 2b882b96e0d4..a153444318fb 100644 --- a/drivers/scsi/Kconfig +++ b/drivers/scsi/Kconfig @@ -421,7 +421,7 @@ config SCSI_AACRAID help This driver supports a variety of Dell, HP, Adaptec, IBM and ICP storage products. For a list of supported products, refer - to . + to . To compile this driver as a module, choose M here: the module will be called aacraid. -- cgit v1.2.3-59-g8ed1b From cb3224089417af6c1f6526303c0c7bd1c76652e8 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:38 +0100 Subject: scsi: docs: convert advansys.txt to ReST Link: https://lore.kernel.org/r/3c697a046e641c81cdfd0784f037d41d54766931.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/advansys.rst | 272 ++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/advansys.txt | 243 ----------------------------------- Documentation/scsi/index.rst | 1 + MAINTAINERS | 2 +- 4 files changed, 274 insertions(+), 244 deletions(-) create mode 100644 Documentation/scsi/advansys.rst delete mode 100644 Documentation/scsi/advansys.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/advansys.rst b/Documentation/scsi/advansys.rst new file mode 100644 index 000000000000..e0367e179696 --- /dev/null +++ b/Documentation/scsi/advansys.rst @@ -0,0 +1,272 @@ +.. 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 +buses and RISC-based, Bus-Mastering, Ultra (20 Mhz) Wide (16-bit +transfer) SCSI Host Adapters for the PCI bus. + +The CDB counts below indicate the number of SCSI CDB (Command +Descriptor Block) requests that can be stored in the RISC chip +cache and board LRAM. A CDB is a single SCSI command. The driver +detect routine will display the number of CDBs available for each +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) + +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) + +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) + +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) + +Driver Compile Time Options and Debugging +========================================= + +The following constants can be defined in the source file. + +1. ADVANSYS_ASSERT - Enable driver assertions (Def: Enabled) + + Enabling this option adds assertion logic statements to the + driver. If an assertion fails a message will be displayed to + the console, but the system will continue to operate. Any + assertions encountered should be reported to the person + responsible for the driver. Assertion statements may proactively + detect problems with the driver and facilitate fixing these + problems. Enabling assertions will add a small overhead to the + execution of the driver. + +2. ADVANSYS_DEBUG - Enable driver debugging (Def: Disabled) + + Enabling this option adds tracing functions to the driver and the + ability to set a driver tracing level at boot time. This option is + very useful for debugging the driver, but it will add to the size + of the driver execution image and add overhead to the execution of + the driver. + + The amount of debugging output can be controlled with the global + variable 'asc_dbglvl'. The higher the number the more output. By + default the debug level is 0. + + If the driver is loaded at boot time and the LILO Driver Option + is included in the system, the debug level can be changed by + specifying a 5th (ASC_NUM_IOPORT_PROBE + 1) I/O Port. The + 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:: + + 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:: + + insmod advansys.o asc_dbglvl=1 + + Debugging Message Levels: + + + ==== ================== + 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:: + + kern.* /dev/console + + c. klogd is started with the appropriate -c parameter + (e.g. klogd -c 8) + + This will cause printk() messages to be be displayed on the + current console. Refer to the klogd(8) and syslogd(8) man pages + for details. + + 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); + } + + Increasing LOG_BUF_LEN in kernel/printk.c to something like + 40960 allows more debug messages to be buffered in the kernel + and written to the console or log file. + +3. ADVANSYS_STATS - Enable statistics (Def: Enabled) + + Enabling this option adds statistics collection and display + through /proc to the driver. The information is useful for + monitoring driver and device performance. It will add to the + size of the driver execution image and add minor overhead to + the execution of the driver. + + Statistics are maintained on a per adapter basis. Driver entry + point call counts and transfer size counts are maintained. + 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:: + + /proc/scsi/advansys/{0,1,2,3,...} + + This information can be displayed with cat. For example:: + + cat /proc/scsi/advansys/0 + + When ADVANSYS_STATS is not defined the AdvanSys /proc files only + 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 +recognize the 'advansys' LILO command line and /etc/lilo.conf option. +This option can be used to either disable I/O port scanning or to limit +scanning to 1 - 4 I/O ports. Regardless of the option setting EISA and +PCI boards will still be searched for and detected. This option only +affects searching for ISA and VL boards. + +Examples: + 1. Eliminate I/O port scanning: + + boot:: + + linux advansys= + + or:: + + boot: linux advansys=0x0 + + 2. Limit I/O port scanning to one I/O port: + + boot:: + + linux advansys=0x110 + + 3. Limit I/O port scanning to four I/O ports: + + 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.:: + + insmod advansys.o asc_iopflag=1 asc_ioport=0x110,0x330 + +If ADVANSYS_DEBUG is defined a 5th (ASC_NUM_IOPORT_PROBE + 1) +I/O Port may be added to specify the driver debug level. Refer to +the 'Driver Compile Time Options and Debugging' section above for +more information. + +Credits (Chronological Order) +============================= + +Bob Frey wrote the AdvanSys SCSI driver +and maintained it up to 3.3F. He continues to answer questions +and help maintain the driver. + +Nathan Hartwell provided the directions and +basis for the Linux v1.3.X changes which were included in the +1.2 release. + +Thomas E Zerucha pointed out a bug +in advansys_biosparam() which was fixed in the 1.3 release. + +Erik Ratcliffe has done testing of the +AdvanSys driver in the Caldera releases. + +Rik van Riel provided a patch to +AscWaitTixISRDone() which he found necessary to make the +driver work with a SCSI-1 disk. + +Mark Moran has helped test Ultra-Wide +support in the 3.1A driver. + +Doug Gilbert has made changes and +suggestions to improve the driver and done a lot of testing. + +Ken Mort reported a DEBUG compile bug fixed +in 3.2K. + +Tom Rini provided the CONFIG_ISA +patch and helped with PowerPC wide and narrow board support. + +Philip Blundell provided an +advansys_interrupts_enabled patch. + +Dave Jones reported the compiler +warnings generated when CONFIG_PROC_FS was not defined in +the 3.2M driver. + +Jerry Quinn fixed PowerPC support (endian +problems) for wide cards. + +Bryan Henderson helped debug narrow +card error handling. + +Manuel Veloso worked hard on PowerPC narrow +board support and fixed a bug in AscGetEEPConfig(). + +Arnaldo Carvalho de Melo made +save_flags/restore_flags changes. + +Andy Kellner continued the Advansys SCSI +driver development for ConnectCom (Version > 3.3F). + +Ken Witherow for extensive testing during the development of version 3.4. diff --git a/Documentation/scsi/advansys.txt b/Documentation/scsi/advansys.txt deleted file mode 100644 index 4a3db62b7424..000000000000 --- a/Documentation/scsi/advansys.txt +++ /dev/null @@ -1,243 +0,0 @@ -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 -buses and RISC-based, Bus-Mastering, Ultra (20 Mhz) Wide (16-bit -transfer) SCSI Host Adapters for the PCI bus. - -The CDB counts below indicate the number of SCSI CDB (Command -Descriptor Block) requests that can be stored in the RISC chip -cache and board LRAM. A CDB is a single SCSI command. The driver -detect routine will display the number of CDBs available for each -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) - -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) - -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) - -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) - -Driver Compile Time Options and Debugging - -The following constants can be defined in the source file. - -1. ADVANSYS_ASSERT - Enable driver assertions (Def: Enabled) - - Enabling this option adds assertion logic statements to the - driver. If an assertion fails a message will be displayed to - the console, but the system will continue to operate. Any - assertions encountered should be reported to the person - responsible for the driver. Assertion statements may proactively - detect problems with the driver and facilitate fixing these - problems. Enabling assertions will add a small overhead to the - execution of the driver. - -2. ADVANSYS_DEBUG - Enable driver debugging (Def: Disabled) - - Enabling this option adds tracing functions to the driver and the - ability to set a driver tracing level at boot time. This option is - very useful for debugging the driver, but it will add to the size - of the driver execution image and add overhead to the execution of - the driver. - - The amount of debugging output can be controlled with the global - variable 'asc_dbglvl'. The higher the number the more output. By - default the debug level is 0. - - If the driver is loaded at boot time and the LILO Driver Option - is included in the system, the debug level can be changed by - specifying a 5th (ASC_NUM_IOPORT_PROBE + 1) I/O Port. The - 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. - - 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. - - insmod advansys.o asc_dbglvl=1 - - Debugging Message Levels: - 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: - - kern.* /dev/console - - c. klogd is started with the appropriate -c parameter - (e.g. klogd -c 8) - - This will cause printk() messages to be be displayed on the - current console. Refer to the klogd(8) and syslogd(8) man pages - for details. - - 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); - } - - Increasing LOG_BUF_LEN in kernel/printk.c to something like - 40960 allows more debug messages to be buffered in the kernel - and written to the console or log file. - -3. ADVANSYS_STATS - Enable statistics (Def: Enabled) - - Enabling this option adds statistics collection and display - through /proc to the driver. The information is useful for - monitoring driver and device performance. It will add to the - size of the driver execution image and add minor overhead to - the execution of the driver. - - Statistics are maintained on a per adapter basis. Driver entry - point call counts and transfer size counts are maintained. - 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: - - /proc/scsi/advansys/{0,1,2,3,...} - - This information can be displayed with cat. For example: - - cat /proc/scsi/advansys/0 - - When ADVANSYS_STATS is not defined the AdvanSys /proc files only - 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 -recognize the 'advansys' LILO command line and /etc/lilo.conf option. -This option can be used to either disable I/O port scanning or to limit -scanning to 1 - 4 I/O ports. Regardless of the option setting EISA and -PCI boards will still be searched for and detected. This option only -affects searching for ISA and VL boards. - -Examples: - 1. Eliminate I/O port scanning: - boot: linux advansys= - or - boot: linux advansys=0x0 - 2. Limit I/O port scanning to one I/O port: - boot: linux advansys=0x110 - 3. Limit I/O port scanning to four I/O ports: - 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. - - insmod advansys.o asc_iopflag=1 asc_ioport=0x110,0x330 - -If ADVANSYS_DEBUG is defined a 5th (ASC_NUM_IOPORT_PROBE + 1) -I/O Port may be added to specify the driver debug level. Refer to -the 'Driver Compile Time Options and Debugging' section above for -more information. - -Credits (Chronological Order) - -Bob Frey wrote the AdvanSys SCSI driver -and maintained it up to 3.3F. He continues to answer questions -and help maintain the driver. - -Nathan Hartwell provided the directions and -basis for the Linux v1.3.X changes which were included in the -1.2 release. - -Thomas E Zerucha pointed out a bug -in advansys_biosparam() which was fixed in the 1.3 release. - -Erik Ratcliffe has done testing of the -AdvanSys driver in the Caldera releases. - -Rik van Riel provided a patch to -AscWaitTixISRDone() which he found necessary to make the -driver work with a SCSI-1 disk. - -Mark Moran has helped test Ultra-Wide -support in the 3.1A driver. - -Doug Gilbert has made changes and -suggestions to improve the driver and done a lot of testing. - -Ken Mort reported a DEBUG compile bug fixed -in 3.2K. - -Tom Rini provided the CONFIG_ISA -patch and helped with PowerPC wide and narrow board support. - -Philip Blundell provided an -advansys_interrupts_enabled patch. - -Dave Jones reported the compiler -warnings generated when CONFIG_PROC_FS was not defined in -the 3.2M driver. - -Jerry Quinn fixed PowerPC support (endian -problems) for wide cards. - -Bryan Henderson helped debug narrow -card error handling. - -Manuel Veloso worked hard on PowerPC narrow -board support and fixed a bug in AscGetEEPConfig(). - -Arnaldo Carvalho de Melo made -save_flags/restore_flags changes. - -Andy Kellner continued the Advansys SCSI -driver development for ConnectCom (Version > 3.3F). - -Ken Witherow for extensive testing during the development of version 3.4. diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 2e0429d1a7a5..df526a0ceccf 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -9,5 +9,6 @@ Linux SCSI Subsystem 53c700 aacraid + advansys scsi_transport_srp/figures diff --git a/MAINTAINERS b/MAINTAINERS index 3251b768fec0..abaac06fa0c5 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -540,7 +540,7 @@ M: Matthew Wilcox M: Hannes Reinecke L: linux-scsi@vger.kernel.org S: Maintained -F: Documentation/scsi/advansys.txt +F: Documentation/scsi/advansys.rst F: drivers/scsi/advansys.c ADXL34X THREE-AXIS DIGITAL ACCELEROMETER DRIVER (ADXL345/ADXL346) -- cgit v1.2.3-59-g8ed1b From 62e3bfa4a1869cf8f221dce8ab90790e836e2b61 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:46 +0100 Subject: scsi: docs: convert dc395x.txt to ReST Link: https://lore.kernel.org/r/3c0876df0045695185f922a0404c497a69de36a9.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/dc395x.rst | 117 ++++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/dc395x.txt | 102 ------------------------------------ Documentation/scsi/index.rst | 1 + MAINTAINERS | 2 +- drivers/scsi/Kconfig | 2 +- 5 files changed, 120 insertions(+), 104 deletions(-) create mode 100644 Documentation/scsi/dc395x.rst delete mode 100644 Documentation/scsi/dc395x.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/dc395x.rst b/Documentation/scsi/dc395x.rst new file mode 100644 index 000000000000..d779e782b1cb --- /dev/null +++ b/Documentation/scsi/dc395x.rst @@ -0,0 +1,117 @@ +.. SPDX-License-Identifier: GPL-2.0 + +====================================== +README file for the dc395x SCSI driver +====================================== + +Status +------ +The driver has been tested with CD-R and CD-R/W drives. These should +be safe to use. Testing with hard disks has not been done to any +great degree and caution should be exercised if you want to attempt +to use this driver with hard disks. + +This is a 2.5 only driver. For a 2.4 driver please see the original +driver (which this driver started from) at +http://www.garloff.de/kurt/linux/dc395/ + +Problems, questions and patches should be submitted to the mailing +list. Details on the list, including archives, are available at +http://lists.twibble.org/mailman/listinfo/dc395x/ + +Parameters +---------- +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 + Default: 0, Acceptable values: 0 or 1 + + If safe is set to 1 then the adapter will use conservative + ("safe") default settings. This sets: + + shortcut for dc395x=7,4,9,15,2,10 + +adapter_id + Default: 7, Acceptable values: 0 to 15 + + Sets the host adapter SCSI ID. + +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 + 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 + 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. + 4 0x10 16 Immediate return on BIOS seek command. (Not used) + (*)5 0x20 32 Check for LUNs >= 1. + ===== ======== ======== ==================================================== + +tags + Default: 3, Acceptable values: 0-5 + + The number of tags is 1<= 1. - - - tags - Default: 3, Acceptable values: 0-5 - - The number of tags is 1<. + Documentation can be found in . To compile this driver as a module, choose M here: the module will be called dc395x. -- cgit v1.2.3-59-g8ed1b From 3c1e681bcdd86b86c676044330ec945d9abc4533 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:49 +0100 Subject: scsi: docs: convert g_NCR5380.txt to ReST Link: https://lore.kernel.org/r/a66e9ea704be6a7aa81b9864ad66a32b75ab808d.1583136624.git.mchehab+huawei@kernel.org Acked-by: Finn Thain Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/g_NCR5380.rst | 93 ++++++++++++++++++++++++++++++++++ Documentation/scsi/g_NCR5380.txt | 68 ------------------------- Documentation/scsi/index.rst | 1 + Documentation/scsi/scsi-parameters.txt | 6 +-- MAINTAINERS | 2 +- drivers/scsi/g_NCR5380.c | 2 +- 6 files changed, 99 insertions(+), 73 deletions(-) create mode 100644 Documentation/scsi/g_NCR5380.rst delete mode 100644 Documentation/scsi/g_NCR5380.txt (limited to 'MAINTAINERS') 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:: + +========================================== +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/index.rst b/Documentation/scsi/index.rst index aad8359357e6..4b577c9e804e 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -20,5 +20,6 @@ Linux SCSI Subsystem dc395x dpti FlashPoint + g_NCR5380 scsi_transport_srp/figures diff --git a/Documentation/scsi/scsi-parameters.txt b/Documentation/scsi/scsi-parameters.txt index 266fd3b2398a..864bbf7f737b 100644 --- a/Documentation/scsi/scsi-parameters.txt +++ b/Documentation/scsi/scsi-parameters.txt @@ -57,13 +57,13 @@ 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] diff --git a/MAINTAINERS b/MAINTAINERS index 1df63c2d8d68..11a64d2cd938 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -11473,7 +11473,7 @@ M: Finn Thain M: Michael Schmitz L: linux-scsi@vger.kernel.org S: Maintained -F: Documentation/scsi/g_NCR5380.txt +F: Documentation/scsi/g_NCR5380.rst F: drivers/scsi/NCR5380.* F: drivers/scsi/arm/cumana_1.c F: drivers/scsi/arm/oak.c diff --git a/drivers/scsi/g_NCR5380.c b/drivers/scsi/g_NCR5380.c index 2ab774e62e40..2cc676e3df6a 100644 --- a/drivers/scsi/g_NCR5380.c +++ b/drivers/scsi/g_NCR5380.c @@ -20,7 +20,7 @@ * Added ISAPNP support for DTC436 adapters, * Thomas Sailer, sailer@ife.ee.ethz.ch * - * See Documentation/scsi/g_NCR5380.txt for more info. + * See Documentation/scsi/g_NCR5380.rst for more info. */ #include -- cgit v1.2.3-59-g8ed1b From 1392de9d7a89915bf0269e038b0d2b3a393d253d Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:50 +0100 Subject: scsi: docs: convert hpsa.txt to ReST Link: https://lore.kernel.org/r/ea58e04176d43fb7194615b145060aa04c9cf3ad.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/hpsa.rst | 129 ++++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/hpsa.txt | 130 ------------------------------------------- Documentation/scsi/index.rst | 1 + MAINTAINERS | 2 +- 4 files changed, 131 insertions(+), 131 deletions(-) create mode 100644 Documentation/scsi/hpsa.rst delete mode 100644 Documentation/scsi/hpsa.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/hpsa.rst b/Documentation/scsi/hpsa.rst new file mode 100644 index 000000000000..340e10c6e35f --- /dev/null +++ b/Documentation/scsi/hpsa.rst @@ -0,0 +1,129 @@ +.. 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 +Smart Array controllers. The hpsa driver is a SCSI driver, while the +cciss driver is a "block" driver. Actually cciss is both a block +driver (for logical drives) AND a SCSI driver (for tape drives). This +"split-brained" design of the cciss driver is a source of excess +complexity and eliminating that complexity is one of the reasons +for hpsa to exist. + +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 + +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 +nor supported by HP with this driver. For older Smart Arrays, the cciss +driver should still be used. + +The "hpsa_simple_mode=1" boot parameter may be used to prevent the driver from +putting the controller into "performant" mode. The difference is that with simple +mode, each command completion requires an interrupt, while with "performant mode" +(the default, and ordinarily better performing) it is possible to have multiple +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 +============================= + + :: + + /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 + (e.g. hot-plugged tape drives, or newly configured or deleted logical drives, + etc.) and notify the SCSI midlayer of any changes detected. Normally this is + triggered automatically by HP's Array Configuration Utility (either the GUI or + command line variety) so for logical drive changes, the user should not + normally have to use this. It may be useful when hot plugging devices like + 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:: + + root@host:/sys/class/scsi_host/host4# cat firmware_revision + 7.14 + + The transport_mode indicates whether the controller is in "performant" + or "simple" mode. This is controlled by the "hpsa_simple_mode" module + parameter. + + The "resettable" read-only attribute indicates whether a particular + controller is able to honor the "reset_devices" kernel parameter. If the + device is resettable, this file will contain a "1", otherwise, a "0". This + parameter is used by kdump, for example, to reset the controller at driver + load time to eliminate any outstanding commands on the controller and get the + controller into a known state so that the kdump initiated i/o will work right + and not be disrupted in any way by stale commands or other stale state + remaining on the controller from the previous kernel. This attribute enables + 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 +----------------------------- + + :: + + /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:: + + root@host:/sys/class/scsi_disk/4:0:0:0/device# cat unique_id + 600508B1001044395355323037570F77 + root@host:/sys/class/scsi_disk/4:0:0:0/device# cat lunid + 0x0000004000000000 + root@host:/sys/class/scsi_disk/4:0:0:0/device# cat raid_level + RAID 0 + +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_GETPCIINFO + Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID). + + CCISS_GETDRIVVER + Returns driver version in three bytes encoded as:: + + (major_version << 16) | (minor_version << 8) | (subminor_version) + + 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/hpsa.txt b/Documentation/scsi/hpsa.txt deleted file mode 100644 index 891435a72fce..000000000000 --- a/Documentation/scsi/hpsa.txt +++ /dev/null @@ -1,130 +0,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 -Smart Array controllers. The hpsa driver is a SCSI driver, while the -cciss driver is a "block" driver. Actually cciss is both a block -driver (for logical drives) AND a SCSI driver (for tape drives). This -"split-brained" design of the cciss driver is a source of excess -complexity and eliminating that complexity is one of the reasons -for hpsa to exist. - -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 - -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 -nor supported by HP with this driver. For older Smart Arrays, the cciss -driver should still be used. - -The "hpsa_simple_mode=1" boot parameter may be used to prevent the driver from -putting the controller into "performant" mode. The difference is that with simple -mode, each command completion requires an interrupt, while with "performant mode" -(the default, and ordinarily better performing) it is possible to have multiple -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: - ------------------------------ - - /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 - (e.g. hot-plugged tape drives, or newly configured or deleted logical drives, - etc.) and notify the SCSI midlayer of any changes detected. Normally this is - triggered automatically by HP's Array Configuration Utility (either the GUI or - command line variety) so for logical drive changes, the user should not - normally have to use this. It may be useful when hot plugging devices like - 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: - - root@host:/sys/class/scsi_host/host4# cat firmware_revision - 7.14 - - The transport_mode indicates whether the controller is in "performant" - or "simple" mode. This is controlled by the "hpsa_simple_mode" module - parameter. - - The "resettable" read-only attribute indicates whether a particular - controller is able to honor the "reset_devices" kernel parameter. If the - device is resettable, this file will contain a "1", otherwise, a "0". This - parameter is used by kdump, for example, to reset the controller at driver - load time to eliminate any outstanding commands on the controller and get the - controller into a known state so that the kdump initiated i/o will work right - and not be disrupted in any way by stale commands or other stale state - remaining on the controller from the previous kernel. This attribute enables - 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: - ------------------------------ - - /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: - - root@host:/sys/class/scsi_disk/4:0:0:0/device# cat unique_id - 600508B1001044395355323037570F77 - root@host:/sys/class/scsi_disk/4:0:0:0/device# cat lunid - 0x0000004000000000 - root@host:/sys/class/scsi_disk/4:0:0:0/device# cat raid_level - RAID 0 - -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_GETPCIINFO - - Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID). - - CCISS_GETDRIVVER - - Returns driver version in three bytes encoded as: - (major_version << 16) | (minor_version << 8) | (subminor_version) - - 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/index.rst b/Documentation/scsi/index.rst index 4b577c9e804e..b16f348bd31b 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -21,5 +21,6 @@ Linux SCSI Subsystem dpti FlashPoint g_NCR5380 + hpsa scsi_transport_srp/figures diff --git a/MAINTAINERS b/MAINTAINERS index 11a64d2cd938..48cad576dc70 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7416,7 +7416,7 @@ M: Don Brace L: esc.storagedev@microsemi.com L: linux-scsi@vger.kernel.org S: Supported -F: Documentation/scsi/hpsa.txt +F: Documentation/scsi/hpsa.rst F: drivers/scsi/hpsa*.[ch] F: include/linux/cciss*.h F: include/uapi/linux/cciss*.h -- cgit v1.2.3-59-g8ed1b From ac69461b6058dc8bc84b940665b84828575b0cc6 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:51 +0100 Subject: scsi: docs: convert hptiop.txt to ReST Link: https://lore.kernel.org/r/d189a339bb360b7b397914ee3ddeb75d9a7fd788.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/hptiop.rst | 215 ++++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/hptiop.txt | 184 ------------------------------------ Documentation/scsi/index.rst | 1 + MAINTAINERS | 2 +- 4 files changed, 217 insertions(+), 185 deletions(-) create mode 100644 Documentation/scsi/hptiop.rst delete mode 100644 Documentation/scsi/hptiop.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/hptiop.rst b/Documentation/scsi/hptiop.rst new file mode 100644 index 000000000000..23ae7ae36971 --- /dev/null +++ b/Documentation/scsi/hptiop.rst @@ -0,0 +1,215 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. include:: + +====================================================== +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 + + ============== ================================== + 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 + 0x1C Outbound Message Register 1 + 0x20 Inbound Doorbell Register + 0x24 Inbound Interrupt Status Register + 0x28 Inbound Interrupt Mask Register + 0x30 Outbound Interrupt Status Register + 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 + 0x1C Outbound Message Register 1 + 0x20 Inbound Doorbell Register + 0x24 Inbound Interrupt Status Register + 0x28 Inbound Interrupt Mask Register + 0x30 Outbound Interrupt Status Register + 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 + 0xC Outbound Queue Tail Pointer + 0x10 Inbound Message Register + 0x14 Outbound Message Register + 0x40-0x1040 Inbound 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 + 0x402C Inbound List Configuration and Control + 0x4050 Outbound List Base Address Low + 0x4054 Outbound List Base Address High + 0x4058 Outbound List Copy Pointer Shadow Base Address Low + 0x405C Outbound List Copy Pointer Shadow Base Address High + 0x4088 Outbound List Interrupt Cause + 0x408C Outbound List Interrupt Enable + 0x1020C PCIe Function 0 Interrupt Enable + 0x10400 PCIe Function 0 to CPU Message A + 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. + +To send a request to the controller: + + - Get a free request packet by reading the inbound queue port or + allocate a free request in host DMA coherent memory. + + The value returned from the inbound queue port is an offset + relative to the IOP BAR0. + + Requests allocated in host memory must be aligned on 32-bytes boundary. + + - Fill the packet. + + - Post the packet to IOP by writing it to inbound queue. For requests + allocated in IOP memory, write the offset to inbound queue port. For + requests allocated in host memory, write (0x80000000|(bus_addr>>5)) + to the inbound queue port. + + - The IOP process the request. When the request is completed, it + will be put into outbound queue. An outbound interrupt will be + generated. + + For requests allocated in IOP memory, the request offset is posted to + outbound queue. + + For requests allocated in host memory, (0x80000000|(bus_addr>>5)) + is posted to the outbound queue. If IOP_REQUEST_FLAG_OUTPUT_CONTEXT + flag is set in the request, the low 32-bit context value will be + posted instead. + + - The host read the outbound queue and complete the request. + + For requests allocated in IOP memory, the host driver free the request + by writing it to the outbound queue. + +Non-queued requests (reset/flush etc) can be sent via inbound message +register 0. An outbound message with the same value indicates the completion +of an inbound message. + + +I/O Request Workflow of Marvell Frey +------------------------------------ + +All queued requests are handled via inbound/outbound list. + +To send a request to the controller: + + - Allocate a free request in host DMA coherent memory. + + Requests allocated in host memory must be aligned on 32-bytes boundary. + + - Fill the request with index of the request in the flag. + + Fill a free inbound list unit with the physical address and the size of + the request. + + Set up the inbound list write pointer with the index of previous unit, + round to 0 if the index reaches the supported count of requests. + + - Post the inbound list writer pointer to IOP. + + - The IOP process the request. When the request is completed, the flag of + the request with or-ed IOPMU_QUEUE_MASK_HOST_BITS will be put into a + free outbound list unit and the index of the outbound list unit will be + put into the copy pointer shadow register. An outbound interrupt will be + generated. + + - The host read the outbound list copy pointer shadow register and compare + with previous saved read pointer N. If they are different, the host will + read the (N+1)th outbound list unit. + + The host get the index of the request from the (N+1)th outbound list + unit and complete the request. + +Non-queued requests (reset communication/reset/flush etc) can be sent via PCIe +Function 0 to CPU Message A register. The CPU to PCIe Function 0 Message register +with the same value indicates the completion of message. + + +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 |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 + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + linux@highpoint-tech.com + + http://www.highpoint-tech.com diff --git a/Documentation/scsi/hptiop.txt b/Documentation/scsi/hptiop.txt deleted file mode 100644 index 12ecfd308e55..000000000000 --- a/Documentation/scsi/hptiop.txt +++ /dev/null @@ -1,184 +0,0 @@ -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: - - 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 - 0x1C Outbound Message Register 1 - 0x20 Inbound Doorbell Register - 0x24 Inbound Interrupt Status Register - 0x28 Inbound Interrupt Mask Register - 0x30 Outbound Interrupt Status Register - 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 - 0x1C Outbound Message Register 1 - 0x20 Inbound Doorbell Register - 0x24 Inbound Interrupt Status Register - 0x28 Inbound Interrupt Mask Register - 0x30 Outbound Interrupt Status Register - 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 - 0xC Outbound Queue Tail Pointer - 0x10 Inbound Message Register - 0x14 Outbound Message Register - 0x40-0x1040 Inbound 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 - 0x402C Inbound List Configuration and Control - 0x4050 Outbound List Base Address Low - 0x4054 Outbound List Base Address High - 0x4058 Outbound List Copy Pointer Shadow Base Address Low - 0x405C Outbound List Copy Pointer Shadow Base Address High - 0x4088 Outbound List Interrupt Cause - 0x408C Outbound List Interrupt Enable - 0x1020C PCIe Function 0 Interrupt Enable - 0x10400 PCIe Function 0 to CPU Message A - 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. - -To send a request to the controller: - - - Get a free request packet by reading the inbound queue port or - allocate a free request in host DMA coherent memory. - - The value returned from the inbound queue port is an offset - relative to the IOP BAR0. - - Requests allocated in host memory must be aligned on 32-bytes boundary. - - - Fill the packet. - - - Post the packet to IOP by writing it to inbound queue. For requests - allocated in IOP memory, write the offset to inbound queue port. For - requests allocated in host memory, write (0x80000000|(bus_addr>>5)) - to the inbound queue port. - - - The IOP process the request. When the request is completed, it - will be put into outbound queue. An outbound interrupt will be - generated. - - For requests allocated in IOP memory, the request offset is posted to - outbound queue. - - For requests allocated in host memory, (0x80000000|(bus_addr>>5)) - is posted to the outbound queue. If IOP_REQUEST_FLAG_OUTPUT_CONTEXT - flag is set in the request, the low 32-bit context value will be - posted instead. - - - The host read the outbound queue and complete the request. - - For requests allocated in IOP memory, the host driver free the request - by writing it to the outbound queue. - -Non-queued requests (reset/flush etc) can be sent via inbound message -register 0. An outbound message with the same value indicates the completion -of an inbound message. - - -I/O Request Workflow of Marvell Frey --------------------------------------- - -All queued requests are handled via inbound/outbound list. - -To send a request to the controller: - - - Allocate a free request in host DMA coherent memory. - - Requests allocated in host memory must be aligned on 32-bytes boundary. - - - Fill the request with index of the request in the flag. - - Fill a free inbound list unit with the physical address and the size of - the request. - - Set up the inbound list write pointer with the index of previous unit, - round to 0 if the index reaches the supported count of requests. - - - Post the inbound list writer pointer to IOP. - - - The IOP process the request. When the request is completed, the flag of - the request with or-ed IOPMU_QUEUE_MASK_HOST_BITS will be put into a - free outbound list unit and the index of the outbound list unit will be - put into the copy pointer shadow register. An outbound interrupt will be - generated. - - - The host read the outbound list copy pointer shadow register and compare - with previous saved read pointer N. If they are different, the host will - read the (N+1)th outbound list unit. - - The host get the index of the request from the (N+1)th outbound list - unit and complete the request. - -Non-queued requests (reset communication/reset/flush etc) can be sent via PCIe -Function 0 to CPU Message A register. The CPU to PCIe Function 0 Message register -with the same value indicates the completion of message. - - -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. - - This file is distributed in the hope that it will be useful, - but WITHOUT ANY WARRANTY; without even the implied warranty of - MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - 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 index b16f348bd31b..b13df9c1810a 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -22,5 +22,6 @@ Linux SCSI Subsystem FlashPoint g_NCR5380 hpsa + hptiop scsi_transport_srp/figures diff --git a/MAINTAINERS b/MAINTAINERS index 48cad576dc70..51cc884037f2 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -7505,7 +7505,7 @@ HIGHPOINT ROCKETRAID 3xxx RAID DRIVER M: HighPoint Linux Team W: http://www.highpoint-tech.com S: Supported -F: Documentation/scsi/hptiop.txt +F: Documentation/scsi/hptiop.rst F: drivers/scsi/hptiop.c HIPPI -- cgit v1.2.3-59-g8ed1b From a756185de6792278bb5c7d286c9a6fa22722b319 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:55 +0100 Subject: scsi: docs: convert megaraid.txt to ReST Link: https://lore.kernel.org/r/b7ee59230c5a33ff6d60edba0d0bcf3e2aeaa88f.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/megaraid.rst | 77 +++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/megaraid.txt | 70 ------------------------------------- MAINTAINERS | 2 +- 4 files changed, 79 insertions(+), 71 deletions(-) create mode 100644 Documentation/scsi/megaraid.rst delete mode 100644 Documentation/scsi/megaraid.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 22427511e227..37be1fc9d128 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -26,5 +26,6 @@ Linux SCSI Subsystem libsas link_power_management_policy lpfc + megaraid scsi_transport_srp/figures diff --git a/Documentation/scsi/megaraid.rst b/Documentation/scsi/megaraid.rst new file mode 100644 index 000000000000..22b75a86ba72 --- /dev/null +++ b/Documentation/scsi/megaraid.rst @@ -0,0 +1,77 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========================== +Notes on Management Module +========================== + +Overview +-------- + +Different classes of controllers from LSI Logic accept and respond to the +user applications in a similar way. They understand the same firmware control +commands. Furthermore, the applications also can treat different classes of +the controllers uniformly. Hence it is logical to have a single module that +interfaces with the applications on one side and all the low level drivers +on the other. + +The advantages, though obvious, are listed for completeness: + + i. Avoid duplicate code from the low level drivers. + ii. Unburden the low level drivers from having to export the + character node device and related handling. + iii. Implement any policy mechanisms in one place. + iv. Applications have to interface with only module instead of + multiple low level drivers. + +Currently this module (called Common Management Module) is used only to issue +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 +------- + +:: + + "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 + +:: + + "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 + +Design +------ + +The Common Management Module is implemented in megaraid_mm.[ch] files. This +module acts as a registry for low level hba drivers. The low level drivers +(currently only megaraid) register each controller with the common module. + +The applications interface with the common module via the character device +node exported by the module. + +The lower level drivers now understand only a new improved ioctl packet called +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 +will be retired. + +Common module dedicates one uioc_t packet to each controller registered. This +can easily be more than one. But since megaraid is the only low level driver +today, and it can handle only one ioctl, there is no reason to have more. But +as new controller classes get added, this will be tuned appropriately. diff --git a/Documentation/scsi/megaraid.txt b/Documentation/scsi/megaraid.txt deleted file mode 100644 index 3c7cea51e687..000000000000 --- a/Documentation/scsi/megaraid.txt +++ /dev/null @@ -1,70 +0,0 @@ - Notes on Management Module - ~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Overview: --------- - -Different classes of controllers from LSI Logic accept and respond to the -user applications in a similar way. They understand the same firmware control -commands. Furthermore, the applications also can treat different classes of -the controllers uniformly. Hence it is logical to have a single module that -interfaces with the applications on one side and all the low level drivers -on the other. - -The advantages, though obvious, are listed for completeness: - - i. Avoid duplicate code from the low level drivers. - ii. Unburden the low level drivers from having to export the - character node device and related handling. - iii. Implement any policy mechanisms in one place. - iv. Applications have to interface with only module instead of - multiple low level drivers. - -Currently this module (called Common Management Module) is used only to issue -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: -------- - -"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 - -"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 - -Design: ------- - -The Common Management Module is implemented in megaraid_mm.[ch] files. This -module acts as a registry for low level hba drivers. The low level drivers -(currently only megaraid) register each controller with the common module. - -The applications interface with the common module via the character device -node exported by the module. - -The lower level drivers now understand only a new improved ioctl packet called -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 -will be retired. - -Common module dedicates one uioc_t packet to each controller registered. This -can easily be more than one. But since megaraid is the only low level driver -today, and it can handle only one ioctl, there is no reason to have more. But -as new controller classes get added, this will be tuned appropriately. diff --git a/MAINTAINERS b/MAINTAINERS index 51cc884037f2..a2e497f95012 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -10639,7 +10639,7 @@ L: megaraidlinux.pdl@broadcom.com L: linux-scsi@vger.kernel.org W: http://www.avagotech.com/support/ S: Maintained -F: Documentation/scsi/megaraid.txt +F: Documentation/scsi/megaraid.rst F: drivers/scsi/megaraid.* F: drivers/scsi/megaraid/ -- cgit v1.2.3-59-g8ed1b From dbfa1bceed656539e59873f9f9ad4ca073566b81 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:15:57 +0100 Subject: scsi: docs: convert NinjaSCSI.txt to ReST Link: https://lore.kernel.org/r/6385a411d000dad005b78647629e43700580ecf0.1583136624.git.mchehab+huawei@kernel.org Acked-by: GOTO Masanori Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/NinjaSCSI.rst | 164 +++++++++++++++++++++++++++++++++++++++ Documentation/scsi/NinjaSCSI.txt | 128 ------------------------------ Documentation/scsi/index.rst | 1 + MAINTAINERS | 4 +- drivers/scsi/pcmcia/Kconfig | 2 +- 5 files changed, 168 insertions(+), 131 deletions(-) create mode 100644 Documentation/scsi/NinjaSCSI.rst delete mode 100644 Documentation/scsi/NinjaSCSI.txt (limited to 'MAINTAINERS') 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//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 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//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 diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index a2545efbb407..eb2df0e0dcb7 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -28,5 +28,6 @@ Linux SCSI Subsystem lpfc megaraid ncr53c8xx + NinjaSCSI scsi_transport_srp/figures diff --git a/MAINTAINERS b/MAINTAINERS index a2e497f95012..5a831cc4916f 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -11801,7 +11801,7 @@ NINJA SCSI-3 / NINJA SCSI-32Bi (16bit/CardBus) PCMCIA SCSI HOST ADAPTER DRIVER M: YOKOTA Hiroshi W: http://www.netlab.is.tsukuba.ac.jp/~yokota/izumi/ninja/ S: Maintained -F: Documentation/scsi/NinjaSCSI.txt +F: Documentation/scsi/NinjaSCSI.rst F: drivers/scsi/pcmcia/nsp_* NINJA SCSI-32Bi/UDE PCI/CARDBUS SCSI HOST ADAPTER DRIVER @@ -11809,7 +11809,7 @@ M: GOTO Masanori M: YOKOTA Hiroshi W: http://www.netlab.is.tsukuba.ac.jp/~yokota/izumi/ninja/ S: Maintained -F: Documentation/scsi/NinjaSCSI.txt +F: Documentation/scsi/NinjaSCSI.rst F: drivers/scsi/nsp32* NIOS2 ARCHITECTURE diff --git a/drivers/scsi/pcmcia/Kconfig b/drivers/scsi/pcmcia/Kconfig index dc9b74c9348a..9696b6b5591f 100644 --- a/drivers/scsi/pcmcia/Kconfig +++ b/drivers/scsi/pcmcia/Kconfig @@ -36,7 +36,7 @@ config PCMCIA_NINJA_SCSI help If you intend to attach this type of PCMCIA SCSI host adapter to your computer, say Y here and read - . + . Supported cards: -- cgit v1.2.3-59-g8ed1b From d4d79340fb7b3f6e9d69a47304b165207145b6d1 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:16:03 +0100 Subject: scsi: docs: convert scsi-generic.txt to ReST Link: https://lore.kernel.org/r/f57b8ddf30397c2c7213e49634e5e9cbd4246368.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/scsi-generic.rst | 118 ++++++++++++++++++++++++++++++++++++ Documentation/scsi/scsi-generic.txt | 101 ------------------------------ MAINTAINERS | 2 +- drivers/scsi/Kconfig | 2 +- include/scsi/sg.h | 2 +- 6 files changed, 122 insertions(+), 104 deletions(-) create mode 100644 Documentation/scsi/scsi-generic.rst delete mode 100644 Documentation/scsi/scsi-generic.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 471982ef461d..119280f26da6 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -34,5 +34,6 @@ Linux SCSI Subsystem scsi-changer scsi_eh scsi_fc_transport + scsi-generic scsi_transport_srp/figures diff --git a/Documentation/scsi/scsi-generic.rst b/Documentation/scsi/scsi-generic.rst new file mode 100644 index 000000000000..258505e557a6 --- /dev/null +++ b/Documentation/scsi/scsi-generic.rst @@ -0,0 +1,118 @@ +.. SPDX-License-Identifier: GPL-2.0 + +======================================= +Notes on Linux SCSI Generic (sg) driver +======================================= + + 20020126 + +Introduction +============ +The SCSI Generic driver (sg) is one of the four "high level" SCSI device +drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg +is more generalized (but lower level) than its siblings and tends to be +used on SCSI devices that don't fit into the already serviced categories. +Thus sg is used for scanners, CD writers and reading audio CDs digitally +amongst other things. + +Rather than document the driver's interface here, version information +is provided plus pointers (i.e. URLs) where to find documentation +and examples. + + +Major versions of the sg driver +=============================== +There are three major versions of sg found in the linux kernel (lk): + - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . + It is based in the sg_header interface structure. + - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on + an extended version of the sg_header interface structure. + - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). + It adds the sg_io_hdr interface structure. + + +Sg driver documentation +======================= +The most recent documentation of the sg driver is kept at the Linux +Documentation Project's (LDP) site: + +- http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO + +This describes the sg version 3 driver found in the lk 2.4 series. + +The LDP renders documents in single and multiple page HTML, postscript +and pdf. This document can also be found at: + +- http://sg.danny.cz/sg/p/sg_v3_ho.html + +Documentation for the version 2 sg driver found in the lk 2.2 series can +be found at http://sg.danny.cz/sg/. A larger version +is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. + +The original documentation for the sg driver (prior to lk 2.2.6) can be +found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt +and in the LDP archives. + +A changelog with brief notes can be found in the +/usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy +and edit this file (removing its changelog for example) before placing it +in /usr/include/scsi/sg.h . Driver debugging information and other notes +can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file. + +A more general description of the Linux SCSI subsystem of which sg is a +part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . + + +Example code and utilities +========================== +There are two packages of sg utilities: + + ========= ========================================================== + sg3_utils for the sg version 3 driver found in lk 2.4 + sg_utils for the sg version 2 (and original) driver found in lk 2.2 + and earlier + ========= ========================================================== + +Both packages will work in the lk 2.4 series however sg3_utils offers more +capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and +freecode.com + +Another approach is to look at the applications that use the sg driver. +These include cdrecord, cdparanoia, SANE and cdrdao. + + +Mapping of Linux kernel versions to sg driver versions +====================================================== +Here is a list of linux kernels in the 2.4 series that had new version +of the sg driver: + + - lk 2.4.0 : sg version 3.1.17 + - lk 2.4.7 : sg version 3.1.19 + - lk 2.4.10 : sg version 3.1.20 [#]_ + - lk 2.4.17 : sg version 3.1.22 + +.. [#] There were 3 changes to sg version 3.1.20 by third parties in the + next six linux kernel versions. + +For reference here is a list of linux kernels in the 2.2 series that had +new version of the sg driver: + + - lk 2.2.0 : original sg version [with no version number] + - lk 2.2.6 : sg version 2.1.31 + - lk 2.2.8 : sg version 2.1.32 + - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared] + - lk 2.2.14 : sg version 2.1.36 + - lk 2.2.16 : sg version 2.1.38 + - lk 2.2.17 : sg version 2.1.39 + - lk 2.2.20 : sg version 2.1.40 + +The lk 2.5 development series has recently commenced and it currently +contains sg version 3.5.23 which is functionally equivalent to sg +version 3.1.22 found in lk 2.4.17. + + +Douglas Gilbert + +26th January 2002 + +dgilbert@interlog.com diff --git a/Documentation/scsi/scsi-generic.txt b/Documentation/scsi/scsi-generic.txt deleted file mode 100644 index 51be20a6a14d..000000000000 --- a/Documentation/scsi/scsi-generic.txt +++ /dev/null @@ -1,101 +0,0 @@ - Notes on Linux SCSI Generic (sg) driver - --------------------------------------- - 20020126 -Introduction -============ -The SCSI Generic driver (sg) is one of the four "high level" SCSI device -drivers along with sd, st and sr (disk, tape and CDROM respectively). Sg -is more generalized (but lower level) than its siblings and tends to be -used on SCSI devices that don't fit into the already serviced categories. -Thus sg is used for scanners, CD writers and reading audio CDs digitally -amongst other things. - -Rather than document the driver's interface here, version information -is provided plus pointers (i.e. URLs) where to find documentation -and examples. - - -Major versions of the sg driver -=============================== -There are three major versions of sg found in the linux kernel (lk): - - sg version 1 (original) from 1992 to early 1999 (lk 2.2.5) . - It is based in the sg_header interface structure. - - sg version 2 from lk 2.2.6 in the 2.2 series. It is based on - an extended version of the sg_header interface structure. - - sg version 3 found in the lk 2.4 series (and the lk 2.5 series). - It adds the sg_io_hdr interface structure. - - -Sg driver documentation -======================= -The most recent documentation of the sg driver is kept at the Linux -Documentation Project's (LDP) site: -http://www.tldp.org/HOWTO/SCSI-Generic-HOWTO -This describes the sg version 3 driver found in the lk 2.4 series. -The LDP renders documents in single and multiple page HTML, postscript -and pdf. This document can also be found at: -http://sg.danny.cz/sg/p/sg_v3_ho.html - -Documentation for the version 2 sg driver found in the lk 2.2 series can -be found at http://sg.danny.cz/sg/. A larger version -is at: http://sg.danny.cz/sg/p/scsi-generic_long.txt. - -The original documentation for the sg driver (prior to lk 2.2.6) can be -found at http://www.torque.net/sg/p/original/SCSI-Programming-HOWTO.txt -and in the LDP archives. - -A changelog with brief notes can be found in the -/usr/src/linux/include/scsi/sg.h file. Note that the glibc maintainers copy -and edit this file (removing its changelog for example) before placing it -in /usr/include/scsi/sg.h . Driver debugging information and other notes -can be found at the top of the /usr/src/linux/drivers/scsi/sg.c file. - -A more general description of the Linux SCSI subsystem of which sg is a -part can be found at http://www.tldp.org/HOWTO/SCSI-2.4-HOWTO . - - -Example code and utilities -========================== -There are two packages of sg utilities: - - sg3_utils for the sg version 3 driver found in lk 2.4 - - sg_utils for the sg version 2 (and original) driver found in lk 2.2 - and earlier -Both packages will work in the lk 2.4 series however sg3_utils offers more -capabilities. They can be found at: http://sg.danny.cz/sg/sg3_utils.html and -freecode.com - -Another approach is to look at the applications that use the sg driver. -These include cdrecord, cdparanoia, SANE and cdrdao. - - -Mapping of Linux kernel versions to sg driver versions -====================================================== -Here is a list of linux kernels in the 2.4 series that had new version -of the sg driver: - lk 2.4.0 : sg version 3.1.17 - lk 2.4.7 : sg version 3.1.19 - lk 2.4.10 : sg version 3.1.20 ** - lk 2.4.17 : sg version 3.1.22 - -** There were 3 changes to sg version 3.1.20 by third parties in the - next six linux kernel versions. - -For reference here is a list of linux kernels in the 2.2 series that had -new version of the sg driver: - lk 2.2.0 : original sg version [with no version number] - lk 2.2.6 : sg version 2.1.31 - lk 2.2.8 : sg version 2.1.32 - lk 2.2.10 : sg version 2.1.34 [SG_GET_VERSION_NUM ioctl first appeared] - lk 2.2.14 : sg version 2.1.36 - lk 2.2.16 : sg version 2.1.38 - lk 2.2.17 : sg version 2.1.39 - lk 2.2.20 : sg version 2.1.40 - -The lk 2.5 development series has recently commenced and it currently -contains sg version 3.5.23 which is functionally equivalent to sg -version 3.1.22 found in lk 2.4.17 . - - -Douglas Gilbert -26th January 2002 -dgilbert@interlog.com diff --git a/MAINTAINERS b/MAINTAINERS index 5a831cc4916f..af7cc8b330c4 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14797,7 +14797,7 @@ M: Doug Gilbert L: linux-scsi@vger.kernel.org W: http://sg.danny.cz/sg S: Maintained -F: Documentation/scsi/scsi-generic.txt +F: Documentation/scsi/scsi-generic.rst F: drivers/scsi/sg.c F: include/scsi/sg.h diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig index 6cb9abb0898d..bdf65b0bb78b 100644 --- a/drivers/scsi/Kconfig +++ b/drivers/scsi/Kconfig @@ -133,7 +133,7 @@ config CHR_DEV_SG quality digital reader of audio CDs (). For other devices, it's possible that you'll have to write the driver software yourself. Please read the file - for more information. + for more information. To compile this driver as a module, choose M here and read . The module will be called sg. diff --git a/include/scsi/sg.h b/include/scsi/sg.h index 29c7ad04d2e2..7327e12f3373 100644 --- a/include/scsi/sg.h +++ b/include/scsi/sg.h @@ -24,7 +24,7 @@ * http://sg.danny.cz/sg [alternatively check the MAINTAINERS file] * The documentation for the sg version 3 driver can be found at: * http://sg.danny.cz/sg/p/sg_v3_ho.html - * Also see: /Documentation/scsi/scsi-generic.txt + * Also see: /Documentation/scsi/scsi-generic.rst * * For utility and test programs see: http://sg.danny.cz/sg/sg3_utils.html */ -- cgit v1.2.3-59-g8ed1b From ff1efa74311a03152b985bfbf9daa3303af7d00c Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:16:08 +0100 Subject: scsi: docs: convert smartpqi.txt to ReST Link: https://lore.kernel.org/r/00b398efb7cfc667b046fbef92a84f1d3c33eb64.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/smartpqi.rst | 78 ++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/smartpqi.txt | 80 ----------------------------------------- MAINTAINERS | 2 +- drivers/scsi/smartpqi/Kconfig | 2 +- 5 files changed, 81 insertions(+), 82 deletions(-) create mode 100644 Documentation/scsi/smartpqi.rst delete mode 100644 Documentation/scsi/smartpqi.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index 6805e157b6e8..ff98919faed7 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -39,5 +39,6 @@ Linux SCSI Subsystem scsi-parameters scsi sd-parameters + smartpqi scsi_transport_srp/figures diff --git a/Documentation/scsi/smartpqi.rst b/Documentation/scsi/smartpqi.rst new file mode 100644 index 000000000000..a7de27352c6f --- /dev/null +++ b/Documentation/scsi/smartpqi.rst @@ -0,0 +1,78 @@ +.. 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 +is the next generation SCSI driver for Microsemi Corp. The smartpqi +driver is the first SCSI driver to implement the PQI queuing model. + +The smartpqi driver will replace the aacraid driver for Adaptec Series 9 +controllers. Customers running an older kernel (Pre-4.9) using an Adaptec +Series 9 controller will have to configure the smartpqi driver or their +volumes will not be added to the OS. + +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 +================= + + +smartpqi specific entries in /sys +================================= + +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 + devices and notify the SCSI mid-layer of any changes detected. + + The version attribute is read-only and will return the driver version + and the controller firmware version. + For example:: + + driver: 0.9.13-370 + firmware: 0.01-522 + +smartpqi sas device attributes +------------------------------ + HBA devices are added to the SAS transport layer. These attributes are + automatically added by the SAS transport layer. + + /sys/class/sas_device/end_device-X:X/sas_address + /sys/class/sas_device/end_device-X:X/enclosure_identifier + /sys/class/sas_device/end_device-X:X/scsi_target_id + +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_GETPCIINFO + Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID). + + CCISS_GETDRIVVER + Returns driver version in three bytes encoded as:: + + (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/smartpqi.txt b/Documentation/scsi/smartpqi.txt deleted file mode 100644 index df129f55ace5..000000000000 --- a/Documentation/scsi/smartpqi.txt +++ /dev/null @@ -1,80 +0,0 @@ - -SMARTPQI - Microsemi Smart PQI Driver ------------------------------------------ - -This file describes the smartpqi SCSI driver for Microsemi -(http://www.microsemi.com) PQI controllers. The smartpqi driver -is the next generation SCSI driver for Microsemi Corp. The smartpqi -driver is the first SCSI driver to implement the PQI queuing model. - -The smartpqi driver will replace the aacraid driver for Adaptec Series 9 -controllers. Customers running an older kernel (Pre-4.9) using an Adaptec -Series 9 controller will have to configure the smartpqi driver or their -volumes will not be added to the OS. - -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: ------------------- - - -smartpqi specific entries in /sys ------------------------------ - - 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 - devices and notify the SCSI mid-layer of any changes detected. - - The version attribute is read-only and will return the driver version - and the controller firmware version. - For example: - driver: 0.9.13-370 - firmware: 0.01-522 - - smartpqi sas device attributes - ------------------------------ - HBA devices are added to the SAS transport layer. These attributes are - automatically added by the SAS transport layer. - - /sys/class/sas_device/end_device-X:X/sas_address - /sys/class/sas_device/end_device-X:X/enclosure_identifier - /sys/class/sas_device/end_device-X:X/scsi_target_id - -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_GETPCIINFO - - Returns PCI domain, bus, device and function and "board ID" (PCI subsystem ID). - - CCISS_GETDRIVVER - - Returns driver version in three bytes encoded as: - (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/MAINTAINERS b/MAINTAINERS index af7cc8b330c4..7107ff6ecf92 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -11092,7 +11092,7 @@ F: drivers/scsi/smartpqi/Kconfig F: drivers/scsi/smartpqi/Makefile F: include/linux/cciss*.h F: include/uapi/linux/cciss*.h -F: Documentation/scsi/smartpqi.txt +F: Documentation/scsi/smartpqi.rst MICROSEMI ETHERNET SWITCH DRIVER M: Alexandre Belloni diff --git a/drivers/scsi/smartpqi/Kconfig b/drivers/scsi/smartpqi/Kconfig index bc6506884e3b..d3311c014863 100644 --- a/drivers/scsi/smartpqi/Kconfig +++ b/drivers/scsi/smartpqi/Kconfig @@ -53,4 +53,4 @@ config SCSI_SMARTPQI Note: the aacraid driver will not manage a smartpqi controller. You need to enable smartpqi for smartpqi controllers. For more information, please see - Documentation/scsi/smartpqi.txt + Documentation/scsi/smartpqi.rst -- cgit v1.2.3-59-g8ed1b From bf65c846476fd9e6965c4aea534db0ba96c19198 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:16:09 +0100 Subject: scsi: docs: convert st.txt to ReST Link: https://lore.kernel.org/r/6b2ddb36983e81e7028de6e5fd0c643c2fb4c6c9.1583136624.git.mchehab+huawei@kernel.org Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/scsi-parameters.rst | 4 +- Documentation/scsi/st.rst | 673 +++++++++++++++++++++++++++++++++ Documentation/scsi/st.txt | 592 ----------------------------- MAINTAINERS | 2 +- drivers/scsi/Kconfig | 2 +- drivers/scsi/st.c | 2 +- 7 files changed, 679 insertions(+), 597 deletions(-) create mode 100644 Documentation/scsi/st.rst delete mode 100644 Documentation/scsi/st.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index ff98919faed7..0cc2cfca7474 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -40,5 +40,6 @@ Linux SCSI Subsystem scsi sd-parameters smartpqi + st scsi_transport_srp/figures diff --git a/Documentation/scsi/scsi-parameters.rst b/Documentation/scsi/scsi-parameters.rst index 0c4bbb1aee94..9aba897c97ac 100644 --- a/Documentation/scsi/scsi-parameters.rst +++ b/Documentation/scsi/scsi-parameters.rst @@ -73,7 +73,7 @@ parameters may be changed at runtime by the command osst= [HW,SCSI] SCSI Tape Driver Format: , - See also Documentation/scsi/st.txt. + See also Documentation/scsi/st.rst. scsi_debug_*= [SCSI] See drivers/scsi/scsi_debug.c. @@ -105,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/st.rst b/Documentation/scsi/st.rst new file mode 100644 index 000000000000..d3b28c28d74c --- /dev/null +++ b/Documentation/scsi/st.rst @@ -0,0 +1,673 @@ +.. 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) + +Last modified: Tue Feb 9 21:54:16 2016 by kai.makisara + + +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 +one of the following three methods: + +1. Each user can specify the tape parameters he/she wants to use +directly with ioctls. This is administratively a very simple and +flexible method and applicable to single-user workstations. However, +in a multiuser environment the next user finds the tape parameters in +state the previous user left them. + +2. The system manager (root) can define default values for some tape +parameters, like block size and density using the MTSETDRVBUFFER ioctl. +These parameters can be programmed to come into effect either when a +new tape is loaded into the drive or if writing begins at the +beginning of the tape. The second method is applicable if the tape +drive performs auto-detection of the tape format well (like some +QIC-drives). The result is that any tape can be read, writing can be +continued using existing format, and the default format is used if +the tape is rewritten from the beginning (or a new tape is written +for the first time). The first method is applicable if the drive +does not perform auto-detection well enough and there is a single +"sensible" mode for the device. An example is a DAT drive that is +used only in variable block mode (I don't know if this is sensible +or not :-). + +The user can override the parameters defined by the system +manager. The changes persist until the defaults again come into +effect. + +3. By default, up to four modes can be defined and selected using the minor +number (bits 5 and 6). The number of modes can be changed by changing +ST_NBR_MODE_BITS in st.h. Mode 0 corresponds to the defaults discussed +above. Additional modes are dormant until they are defined by the +system manager (root). When specification of a new mode is started, +the configuration of mode 0 is used to provide a starting point for +definition of the new mode. + +Using the modes allows the system manager to give the users choices +over some of the buffering parameters not directly accessible to the +users (buffered and asynchronous writes). The modes also allow choices +between formats in multi-tape operations (the explicitly overridden +parameters are reset when a new tape is loaded). + +If more than one mode is used, all modes should contain definitions +for the same set of parameters. + +Many Unices contain internal tables that associate different modes to +supported devices. The Linux SCSI tape driver does not contain such +tables (and will not do that in future). Instead of that, a utility +program can be made that fetches the inquiry data sent by the device, +scans its database, and sets up the modes using the ioctls. Another +alternative is to make a small script that uses mt to set the defaults +tailored to the system. + +The driver supports fixed and variable block size (within buffer +limits). Both the auto-rewind (minor equals device number) and +non-rewind devices (minor is 128 + device number) are implemented. + +In variable block mode, the byte count in write() determines the size +of the physical block on tape. When reading, the drive reads the next +tape block and returns to the user the data if the read() byte count +is at least the block size. Otherwise, error ENOMEM is returned. + +In fixed block mode, the data transfer between the drive and the +driver is in multiples of the block size. The write() byte count must +be a multiple of the block size. This is not required when reading but +may be advisable for portability. + +Support is provided for changing the tape partition and partitioning +of the tape with one or two partitions. By default support for +partitioned tape is disabled for each driver and it can be enabled +with the ioctl MTSETDRVBUFFER. + +By default the driver writes one filemark when the device is closed after +writing and the last operation has been a write. Two filemarks can be +optionally written. In both cases end of data is signified by +returning zero bytes for two consecutive reads. + +Writing filemarks without the immediate bit set in the SCSI command block acts +as a synchronization point, i.e., all remaining data form the drive buffers is +written to tape before the command returns. This makes sure that write errors +are caught at that point, but this takes time. In some applications, several +consecutive files must be written fast. The MTWEOFI operation can be used to +write the filemarks without flushing the drive buffer. Writing filemark at +close() is always flushing the drive buffers. However, if the previous +operation is MTWEOFI, close() does not write a filemark. This can be used if +the program wants to close/open the tape device between files and wants to +skip waiting. + +If rewind, offline, bsf, or seek is done and previous tape operation was +write, a filemark is written before moving tape. + +The compile options are defined in the file linux/drivers/scsi/st_options.h. + +4. If the open option O_NONBLOCK is used, open succeeds even if the +drive is not ready. If O_NONBLOCK is not used, the driver waits for +the drive to become ready. If this does not happen in ST_BLOCK_SECONDS +seconds, open fails with the errno value EIO. With O_NONBLOCK the +device can be opened for writing even if there is a write protected +tape in the drive (commands trying to write something return error if +attempted). + + +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:: + + 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 +backward compatible with the numbering used when the minor number was +only 8 bits wide. + + +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 +and non-rewind entries for each mode. The names are stxy and nstxy, where x +is the tape number and y a character corresponding to the mode (none, l, m, +a). For example, the directories for the first tape device are (assuming four +modes): st0 nst0 st0l nst0l st0m nst0m st0a nst0a. + +Each directory contains the entries: default_blksize default_compression +default_density defined dev device driver. The file 'defined' contains 1 +if the mode is defined and zero if not defined. The files 'default_*' contain +the defaults set by the user. The value -1 means the default is not set. The +file 'dev' contains the device numbers corresponding to this device. The links +'device' and 'driver' point to the SCSI device and driver entries. + +Each directory also contains the entry 'options' which shows the currently +enabled driver and mode options. The value in the file is a bit mask where the +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). + + +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 +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]+$" +4. Access the statistics from the /sys/class/scsi_tape//stats + directory (where 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 +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 + 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 + 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 + 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 + requests to complete. +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. + +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 +I/O issued via the st module. + +When read the statistics may not be temporally consistent while I/O is in +progress. The individual values are read and written to atomically however +when reading them back via sysfs they may be in the process of being +updated when starting an I/O or when it is completed. + +The value shown in in_flight is incremented before any statstics are +updated and decremented when an I/O completes after updating statistics. +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 +======================= + +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 +file being read is closed. The BSD semantics leaves the tape where it +currently is whereas the SYS V semantics moves the tape past the next +filemark unless the filemark has just been crossed. + +The default is BSD semantics. + + +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 +- one or more pages can't be locked into memory (should not happen in + any reasonable situation) + +The size of the driver buffers is always at least one tape block. In fixed +block mode, the minimum buffer size is defined (in 1024 byte units) by +ST_FIXED_BUFFER_BLOCKS. With small block size this allows buffering of +several blocks and using one SCSI read or write to transfer all of the +blocks. Buffering of data across write calls in fixed block mode is +allowed if ST_BUFFER_WRITES is non-zero and direct i/o is not used. +Buffer allocation uses chunks of memory having sizes 2^n * (page +size). Because of this the actual buffer size may be larger than the +minimum allowable buffer size. + +NOTE that if direct i/o is used, the small writes are not buffered. This may +cause a surprise when moving from 2.4. There small writes (e.g., tar without +-b option) may have had good throughput but this is not true any more with +2.6. Direct i/o can be turned off to solve this problem but a better solution +is to use bigger write() byte counts (e.g., tar -b 64). + +Asynchronous writing. Writing the buffer contents to the tape is +started and the write call returns immediately. The status is checked +at the next tape operation. Asynchronous writes are not done with +direct i/o and not in fixed block mode. + +Buffered writes and asynchronous writes may in some rare cases cause +problems in multivolume operations if there is not enough space on the +tape after the early-warning mark to flush the driver buffer. + +Read ahead for fixed block mode (ST_READ_AHEAD). Filling the buffer is +attempted even if the user does not want to get all of the data at +this read command. Should be disabled for those drives that don't like +a filemark to truncate a read request or that don't like backspacing. + +Scatter/gather buffers (buffers that consist of chunks non-contiguous +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. +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. +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. + + +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 +returns -1 and errno is set to ENOSPC. To enable writing a trailer, +the next write is allowed to proceed and, if successful, the number of +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 +================= + +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 +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 +======================= + +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 +to use the same keyword used when loading as module but prepended +with 'st.'. For instance, to set the maximum number of scatter/gather +segments, the parameter 'st.max_sg_segs=xx' should be used (xx is the +number of scatter/gather segments). + +For compatibility, the old syntax from early 2.5 and 2.4 kernel +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:: + + st=buffer_kbs:64,write_threshold_kbs:60 + +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 + + +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 +to find an mt that supports all of the Linux SCSI tape ioctls and +opens the device for writing if the tape contents will be modified +(look for a package mt-st* from the Linux ftp sites; the GNU mt does +not open for writing for, e.g., erase). + +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 + 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 + 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 + 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) + 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 + variable block mode (if applicable). +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 + 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 + 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 + 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 + 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 + partition of the tape. If the argument is negative, its absolute + value specifies the size of partition 0 in megabytes. This is + the physically first partition of many later drives, like the + LTO drives from LTO-5 upwards. The drive has to support partitions + with size specified by the initiator. Inactive unless + MT_ST_CAN_PARTITIONS set. +MTSETDRVBUFFER + Is used for several purposes. The command is obtained from count + 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 + The drive buffer option is set to the argument. Zero means + no buffering. + * 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 + be used for repositioning the tape (global) + 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 + tapes (global) + 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 + the command to finish) for some commands (e.g., rewind) + 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 + 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 + compiled into the driver) + + * MT_ST_SETBOOLEANS, MT_ST_CLEARBOOLEANS + Sets or clears the option bits. + * MT_ST_WRITE_THRESHOLD + Sets the write threshold for this device to kilobytes + specified by the lowest bits. + * 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 + 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 + 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 + non-zero number, and this number is not 0xff, the number is + used as the compression algorithm. The value + MT_ST_CLEAR_DEFAULT can be used to clear the compression + default. + * 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 + 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 + 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 + is found from the extended sense data. Many drives set one or + more bits in the extended sense data when the drive needs + 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), + 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 + the pattern is non-zero, the pattern must match the masked + sense data byte. + + (The cleaning bit is set if the additional sense code and + qualifier 00h 17h are seen regardless of the setting of + MT_ST_SET_CLN.) + +The following ioctl uses the structure mtpos: + +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. + 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. + The number of recovered errors since the previous status call + is stored in the lower word of the field mt_erreg. + The current block size and the density code are stored in the field + mt_dsreg (shifts for the subfields are MT_ST_BLKSIZE_SHIFT and + MT_ST_DENSITY_SHIFT). + The GMT_xxx status bits reflect the drive status. GMT_DR_OPEN + is set if there is no tape in the drive. GMT_EOD means either + end of recorded data or end of tape. GMT_EOT means end of tape. + + +Miscellaneous Compile Options +============================= + +The recovered write errors are considered fatal if ST_RECOVERED_WRITE_FATAL +is defined. + +The maximum number of tape devices is determined by the define +ST_MAX_TAPES. If more tapes are detected at driver initialization, the +maximum is adjusted accordingly. + +Immediate return from tape positioning SCSI commands can be enabled by +defining ST_NOWAIT. If this is defined, the user should take care that +the next tape operation is not started before the previous one has +finished. The drives and SCSI adapters should handle this condition +gracefully, but some drive/adapter combinations are known to hang the +SCSI bus in this case. + +The MTEOM command is by default implemented as spacing over 32767 +filemarks. With this method the file number in the status is +correct. The user can request using direct spacing to EOD by setting +ST_FAST_EOM 1 (or using the MT_ST_OPTIONS ioctl). In this case the file +number will be invalid. + +When using read ahead or buffered writes the position within the file +may not be correct after the file is closed (correct position may +require backspacing over more than one record). The correct position +within file can be obtained if ST_IN_FILE_POS is defined at compile +time or the MT_ST_CAN_BSR bit is set for the drive with an ioctl. +(The driver always backs over a filemark crossed by read ahead if the +user does not request data that far.) + + +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 +can still be switched on and off with an ioctl. To enable debug at +module load time add debug_flag=1 to the module load options, the +debugging output is not voluminous. Debugging can also be enabled +and disabled by writing a '0' (disable) or '1' (enable) to the sysfs +file /sys/bus/scsi/drivers/st/debug_flag. + +If the tape seems to hang, I would be very interested to hear where +the driver is waiting. With the command 'ps -l' you can see the state +of the process using the tape. If the state is D, the process is +waiting for something. The field WCHAN tells where the driver is +waiting. If you have the current System.map in the correct place (in +/boot for the procps I use) or have updated /etc/psdatabase (for kmem +ps), ps writes the function name in the WCHAN field. If not, you have +to look up the function from System.map. + +Note also that the timeouts are very long compared to most other +drivers. This means that the Linux driver may appear hung although the +real reason is that the tape firmware has got confused. diff --git a/Documentation/scsi/st.txt b/Documentation/scsi/st.txt deleted file mode 100644 index ec0acf6acccd..000000000000 --- a/Documentation/scsi/st.txt +++ /dev/null @@ -1,592 +0,0 @@ -This file contains brief information about the SCSI tape driver. -The driver is currently maintained by Kai Mäkisara (email -Kai.Makisara@kolumbus.fi) - -Last modified: Tue Feb 9 21:54:16 2016 by kai.makisara - - -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 -one of the following three methods: - -1. Each user can specify the tape parameters he/she wants to use -directly with ioctls. This is administratively a very simple and -flexible method and applicable to single-user workstations. However, -in a multiuser environment the next user finds the tape parameters in -state the previous user left them. - -2. The system manager (root) can define default values for some tape -parameters, like block size and density using the MTSETDRVBUFFER ioctl. -These parameters can be programmed to come into effect either when a -new tape is loaded into the drive or if writing begins at the -beginning of the tape. The second method is applicable if the tape -drive performs auto-detection of the tape format well (like some -QIC-drives). The result is that any tape can be read, writing can be -continued using existing format, and the default format is used if -the tape is rewritten from the beginning (or a new tape is written -for the first time). The first method is applicable if the drive -does not perform auto-detection well enough and there is a single -"sensible" mode for the device. An example is a DAT drive that is -used only in variable block mode (I don't know if this is sensible -or not :-). - -The user can override the parameters defined by the system -manager. The changes persist until the defaults again come into -effect. - -3. By default, up to four modes can be defined and selected using the minor -number (bits 5 and 6). The number of modes can be changed by changing -ST_NBR_MODE_BITS in st.h. Mode 0 corresponds to the defaults discussed -above. Additional modes are dormant until they are defined by the -system manager (root). When specification of a new mode is started, -the configuration of mode 0 is used to provide a starting point for -definition of the new mode. - -Using the modes allows the system manager to give the users choices -over some of the buffering parameters not directly accessible to the -users (buffered and asynchronous writes). The modes also allow choices -between formats in multi-tape operations (the explicitly overridden -parameters are reset when a new tape is loaded). - -If more than one mode is used, all modes should contain definitions -for the same set of parameters. - -Many Unices contain internal tables that associate different modes to -supported devices. The Linux SCSI tape driver does not contain such -tables (and will not do that in future). Instead of that, a utility -program can be made that fetches the inquiry data sent by the device, -scans its database, and sets up the modes using the ioctls. Another -alternative is to make a small script that uses mt to set the defaults -tailored to the system. - -The driver supports fixed and variable block size (within buffer -limits). Both the auto-rewind (minor equals device number) and -non-rewind devices (minor is 128 + device number) are implemented. - -In variable block mode, the byte count in write() determines the size -of the physical block on tape. When reading, the drive reads the next -tape block and returns to the user the data if the read() byte count -is at least the block size. Otherwise, error ENOMEM is returned. - -In fixed block mode, the data transfer between the drive and the -driver is in multiples of the block size. The write() byte count must -be a multiple of the block size. This is not required when reading but -may be advisable for portability. - -Support is provided for changing the tape partition and partitioning -of the tape with one or two partitions. By default support for -partitioned tape is disabled for each driver and it can be enabled -with the ioctl MTSETDRVBUFFER. - -By default the driver writes one filemark when the device is closed after -writing and the last operation has been a write. Two filemarks can be -optionally written. In both cases end of data is signified by -returning zero bytes for two consecutive reads. - -Writing filemarks without the immediate bit set in the SCSI command block acts -as a synchronization point, i.e., all remaining data form the drive buffers is -written to tape before the command returns. This makes sure that write errors -are caught at that point, but this takes time. In some applications, several -consecutive files must be written fast. The MTWEOFI operation can be used to -write the filemarks without flushing the drive buffer. Writing filemark at -close() is always flushing the drive buffers. However, if the previous -operation is MTWEOFI, close() does not write a filemark. This can be used if -the program wants to close/open the tape device between files and wants to -skip waiting. - -If rewind, offline, bsf, or seek is done and previous tape operation was -write, a filemark is written before moving tape. - -The compile options are defined in the file linux/drivers/scsi/st_options.h. - -4. If the open option O_NONBLOCK is used, open succeeds even if the -drive is not ready. If O_NONBLOCK is not used, the driver waits for -the drive to become ready. If this does not happen in ST_BLOCK_SECONDS -seconds, open fails with the errno value EIO. With O_NONBLOCK the -device can be opened for writing even if there is a write protected -tape in the drive (commands trying to write something return error if -attempted). - - -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: - -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 -backward compatible with the numbering used when the minor number was -only 8 bits wide. - - -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 -and non-rewind entries for each mode. The names are stxy and nstxy, where x -is the tape number and y a character corresponding to the mode (none, l, m, -a). For example, the directories for the first tape device are (assuming four -modes): st0 nst0 st0l nst0l st0m nst0m st0a nst0a. - -Each directory contains the entries: default_blksize default_compression -default_density defined dev device driver. The file 'defined' contains 1 -if the mode is defined and zero if not defined. The files 'default_*' contain -the defaults set by the user. The value -1 means the default is not set. The -file 'dev' contains the device numbers corresponding to this device. The links -'device' and 'driver' point to the SCSI device and driver entries. - -Each directory also contains the entry 'options' which shows the currently -enabled driver and mode options. The value in the file is a bit mask where the -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). - - -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 -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]+$" -4. Access the statistics from the /sys/class/scsi_tape//stats - directory (where 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 -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 - 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 - 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 - 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 - requests to complete. -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. - -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 -I/O issued via the st module. - -When read the statistics may not be temporally consistent while I/O is in -progress. The individual values are read and written to atomically however -when reading them back via sysfs they may be in the process of being -updated when starting an I/O or when it is completed. - -The value shown in in_flight is incremented before any statstics are -updated and decremented when an I/O completes after updating statistics. -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 - -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 -file being read is closed. The BSD semantics leaves the tape where it -currently is whereas the SYS V semantics moves the tape past the next -filemark unless the filemark has just been crossed. - -The default is BSD semantics. - - -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 -- one or more pages can't be locked into memory (should not happen in - any reasonable situation) - -The size of the driver buffers is always at least one tape block. In fixed -block mode, the minimum buffer size is defined (in 1024 byte units) by -ST_FIXED_BUFFER_BLOCKS. With small block size this allows buffering of -several blocks and using one SCSI read or write to transfer all of the -blocks. Buffering of data across write calls in fixed block mode is -allowed if ST_BUFFER_WRITES is non-zero and direct i/o is not used. -Buffer allocation uses chunks of memory having sizes 2^n * (page -size). Because of this the actual buffer size may be larger than the -minimum allowable buffer size. - -NOTE that if direct i/o is used, the small writes are not buffered. This may -cause a surprise when moving from 2.4. There small writes (e.g., tar without --b option) may have had good throughput but this is not true any more with -2.6. Direct i/o can be turned off to solve this problem but a better solution -is to use bigger write() byte counts (e.g., tar -b 64). - -Asynchronous writing. Writing the buffer contents to the tape is -started and the write call returns immediately. The status is checked -at the next tape operation. Asynchronous writes are not done with -direct i/o and not in fixed block mode. - -Buffered writes and asynchronous writes may in some rare cases cause -problems in multivolume operations if there is not enough space on the -tape after the early-warning mark to flush the driver buffer. - -Read ahead for fixed block mode (ST_READ_AHEAD). Filling the buffer is -attempted even if the user does not want to get all of the data at -this read command. Should be disabled for those drives that don't like -a filemark to truncate a read request or that don't like backspacing. - -Scatter/gather buffers (buffers that consist of chunks non-contiguous -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. -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. -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. - - -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 -returns -1 and errno is set to ENOSPC. To enable writing a trailer, -the next write is allowed to proceed and, if successful, the number of -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 - -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 -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 - -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 -to use the same keyword used when loading as module but prepended -with 'st.'. For instance, to set the maximum number of scatter/gather -segments, the parameter 'st.max_sg_segs=xx' should be used (xx is the -number of scatter/gather segments). - -For compatibility, the old syntax from early 2.5 and 2.4 kernel -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: - - st=buffer_kbs:64,write_threshold_kbs:60 - -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 - - -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 -to find an mt that supports all of the Linux SCSI tape ioctls and -opens the device for writing if the tape contents will be modified -(look for a package mt-st* from the Linux ftp sites; the GNU mt does -not open for writing for, e.g., erase). - -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 - 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 - 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 - 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) - 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 - variable block mode (if applicable). -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 - 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 - 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 - 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 - 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 - partition of the tape. If the argument is negative, its absolute - value specifies the size of partition 0 in megabytes. This is - the physically first partition of many later drives, like the - LTO drives from LTO-5 upwards. The drive has to support partitions - with size specified by the initiator. Inactive unless - MT_ST_CAN_PARTITIONS set. -MTSETDRVBUFFER - Is used for several purposes. The command is obtained from count - 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 - The drive buffer option is set to the argument. Zero means - no buffering. - 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 - be used for repositioning the tape (global) - 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 - tapes (global) - 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 - the command to finish) for some commands (e.g., rewind) - 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 - 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 - compiled into the driver) - MT_ST_SETBOOLEANS - MT_ST_CLEARBOOLEANS - Sets or clears the option bits. - MT_ST_WRITE_THRESHOLD - Sets the write threshold for this device to kilobytes - specified by the lowest bits. - 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 - 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 - 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 - non-zero number, and this number is not 0xff, the number is - used as the compression algorithm. The value - MT_ST_CLEAR_DEFAULT can be used to clear the compression - default. - 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 - 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 - 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 - is found from the extended sense data. Many drives set one or - more bits in the extended sense data when the drive needs - 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), - 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 - the pattern is non-zero, the pattern must match the masked - sense data byte. - - (The cleaning bit is set if the additional sense code and - qualifier 00h 17h are seen regardless of the setting of - MT_ST_SET_CLN.) - -The following ioctl uses the structure mtpos: -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. - 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. - The number of recovered errors since the previous status call - is stored in the lower word of the field mt_erreg. - The current block size and the density code are stored in the field - mt_dsreg (shifts for the subfields are MT_ST_BLKSIZE_SHIFT and - MT_ST_DENSITY_SHIFT). - The GMT_xxx status bits reflect the drive status. GMT_DR_OPEN - is set if there is no tape in the drive. GMT_EOD means either - end of recorded data or end of tape. GMT_EOT means end of tape. - - -MISCELLANEOUS COMPILE OPTIONS - -The recovered write errors are considered fatal if ST_RECOVERED_WRITE_FATAL -is defined. - -The maximum number of tape devices is determined by the define -ST_MAX_TAPES. If more tapes are detected at driver initialization, the -maximum is adjusted accordingly. - -Immediate return from tape positioning SCSI commands can be enabled by -defining ST_NOWAIT. If this is defined, the user should take care that -the next tape operation is not started before the previous one has -finished. The drives and SCSI adapters should handle this condition -gracefully, but some drive/adapter combinations are known to hang the -SCSI bus in this case. - -The MTEOM command is by default implemented as spacing over 32767 -filemarks. With this method the file number in the status is -correct. The user can request using direct spacing to EOD by setting -ST_FAST_EOM 1 (or using the MT_ST_OPTIONS ioctl). In this case the file -number will be invalid. - -When using read ahead or buffered writes the position within the file -may not be correct after the file is closed (correct position may -require backspacing over more than one record). The correct position -within file can be obtained if ST_IN_FILE_POS is defined at compile -time or the MT_ST_CAN_BSR bit is set for the drive with an ioctl. -(The driver always backs over a filemark crossed by read ahead if the -user does not request data that far.) - - -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 -can still be switched on and off with an ioctl. To enable debug at -module load time add debug_flag=1 to the module load options, the -debugging output is not voluminous. Debugging can also be enabled -and disabled by writing a '0' (disable) or '1' (enable) to the sysfs -file /sys/bus/scsi/drivers/st/debug_flag. - -If the tape seems to hang, I would be very interested to hear where -the driver is waiting. With the command 'ps -l' you can see the state -of the process using the tape. If the state is D, the process is -waiting for something. The field WCHAN tells where the driver is -waiting. If you have the current System.map in the correct place (in -/boot for the procps I use) or have updated /etc/psdatabase (for kmem -ps), ps writes the function name in the WCHAN field. If not, you have -to look up the function from System.map. - -Note also that the timeouts are very long compared to most other -drivers. This means that the Linux driver may appear hung although the -real reason is that the tape firmware has got confused. diff --git a/MAINTAINERS b/MAINTAINERS index 7107ff6ecf92..bc6d68bc555a 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -14817,7 +14817,7 @@ SCSI TAPE DRIVER M: Kai Mäkisara L: linux-scsi@vger.kernel.org S: Maintained -F: Documentation/scsi/st.txt +F: Documentation/scsi/st.rst F: drivers/scsi/st.* F: drivers/scsi/st_*.h diff --git a/drivers/scsi/Kconfig b/drivers/scsi/Kconfig index c705e2b951a4..5bde34020b3a 100644 --- a/drivers/scsi/Kconfig +++ b/drivers/scsi/Kconfig @@ -94,7 +94,7 @@ config CHR_DEV_ST If you want to use a SCSI tape drive under Linux, say Y and read the SCSI-HOWTO, available from , and - in the kernel source. This is NOT + in the kernel source. This is NOT for SCSI CD-ROMs. To compile this driver as a module, choose M here and read diff --git a/drivers/scsi/st.c b/drivers/scsi/st.c index 393f3019ccac..2cff8a7349a7 100644 --- a/drivers/scsi/st.c +++ b/drivers/scsi/st.c @@ -1,7 +1,7 @@ // SPDX-License-Identifier: GPL-2.0-only /* SCSI Tape Driver for Linux version 1.1 and newer. See the accompanying - file Documentation/scsi/st.txt for more information. + file Documentation/scsi/st.rst for more information. History: Rewritten from Dwayne Forsyth's SCSI tape driver by Kai Makisara. -- cgit v1.2.3-59-g8ed1b From b64f682240453932f73d58438c928bdd319aeb8a Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Mon, 2 Mar 2020 09:16:13 +0100 Subject: scsi: docs: convert ufs.txt to ReST Link: https://lore.kernel.org/r/052d45576e342a217185e91a83793b384b1592a4.1583136624.git.mchehab+huawei@kernel.org Acked-by: Avri Altman Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Martin K. Petersen --- Documentation/scsi/index.rst | 1 + Documentation/scsi/ufs.rst | 195 +++++++++++++++++++++++++++++++++++++++++++ Documentation/scsi/ufs.txt | 171 ------------------------------------- MAINTAINERS | 2 +- drivers/scsi/ufs/Kconfig | 2 +- 5 files changed, 198 insertions(+), 173 deletions(-) create mode 100644 Documentation/scsi/ufs.rst delete mode 100644 Documentation/scsi/ufs.txt (limited to 'MAINTAINERS') diff --git a/Documentation/scsi/index.rst b/Documentation/scsi/index.rst index df005cb94f6b..27720d145eff 100644 --- a/Documentation/scsi/index.rst +++ b/Documentation/scsi/index.rst @@ -44,5 +44,6 @@ Linux SCSI Subsystem sym53c500_cs sym53c8xx_2 tcm_qla2xxx + ufs scsi_transport_srp/figures diff --git a/Documentation/scsi/ufs.rst b/Documentation/scsi/ufs.rst new file mode 100644 index 000000000000..a920c0a5a1f6 --- /dev/null +++ b/Documentation/scsi/ufs.rst @@ -0,0 +1,195 @@ +.. 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 + + +1. Overview +=========== + +Universal Flash Storage(UFS) is a storage specification for flash devices. +It is aimed to provide a universal storage interface for both +embedded and removable flash memory based storage in mobile +devices such as smart phones and tablet computers. The specification +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: + + * 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) + + Future version of the standard, + + - 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. + +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 + UFS which are meant for command queue control. + * 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 + requests which are used to modify and retrieve configuration + 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. + * UTP_CMD_SAP: Command service access point is exposed to UFS command + 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 +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 + controller. Also, the module decodes, responses received from UFS + host controller in the form of UPIUs and intimates the SCSI Midlayer + 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 + issues by SCSI Midlayer are Abort task, Lun reset and host reset. + UFSHCD Routines to perform these tasks are registered with + SCSI Midlayer through .eh_abort_handler, .eh_device_reset_handler and + .eh_host_reset_handler. + +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 +struct ufs_bsg_request and struct ufs_bsg_reply (see ufs_bsg.h) as +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:: + + io_hdr_v4.guard = 'Q'; + io_hdr_v4.protocol = BSG_PROTOCOL_SCSI; + io_hdr_v4.subprotocol = BSG_SUB_PROTOCOL_SCSI_TRANSPORT; + io_hdr_v4.response = (__u64)reply_upiu; + io_hdr_v4.max_response_len = reply_len; + io_hdr_v4.request_len = request_len; + io_hdr_v4.request = (__u64)request_upiu; + if (dir == SG_DXFER_TO_DEV) { + io_hdr_v4.dout_xfer_len = (uint32_t)byte_cnt; + io_hdr_v4.dout_xferp = (uintptr_t)(__u64)buff; + } else { + io_hdr_v4.din_xfer_len = (uint32_t)byte_cnt; + io_hdr_v4.din_xferp = (uintptr_t)(__u64)buff; + } + +If you wish to read or write a descriptor, use the appropriate xferp of +sg_io_v4. + +The userspace tool that interacts with the ufs-bsg endpoint and uses its +upiu-based protocol is available at: + + https://github.com/westerndigitalcorporation/ufs-tool + +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 diff --git a/Documentation/scsi/ufs.txt b/Documentation/scsi/ufs.txt deleted file mode 100644 index 81842ec3e116..000000000000 --- a/Documentation/scsi/ufs.txt +++ /dev/null @@ -1,171 +0,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 - - -1. Overview ------------ - -Universal Flash Storage(UFS) is a storage specification for flash devices. -It is aimed to provide a universal storage interface for both -embedded and removable flash memory based storage in mobile -devices such as smart phones and tablet computers. The specification -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, - * 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) - Future version of the standard, - 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. - -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 - UFS which are meant for command queue control. - * 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 - requests which are used to modify and retrieve configuration - 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. - * UTP_CMD_SAP: Command service access point is exposed to UFS command - 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 -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 - controller. Also, the module decodes, responses received from UFS - host controller in the form of UPIUs and intimates the SCSI Midlayer - 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 - issues by SCSI Midlayer are Abort task, Lun reset and host reset. - UFSHCD Routines to perform these tasks are registered with - SCSI Midlayer through .eh_abort_handler, .eh_device_reset_handler and - .eh_host_reset_handler. - -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 -struct ufs_bsg_request and struct ufs_bsg_reply (see ufs_bsg.h) as -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: - - io_hdr_v4.guard = 'Q'; - io_hdr_v4.protocol = BSG_PROTOCOL_SCSI; - io_hdr_v4.subprotocol = BSG_SUB_PROTOCOL_SCSI_TRANSPORT; - io_hdr_v4.response = (__u64)reply_upiu; - io_hdr_v4.max_response_len = reply_len; - io_hdr_v4.request_len = request_len; - io_hdr_v4.request = (__u64)request_upiu; - if (dir == SG_DXFER_TO_DEV) { - io_hdr_v4.dout_xfer_len = (uint32_t)byte_cnt; - io_hdr_v4.dout_xferp = (uintptr_t)(__u64)buff; - } else { - io_hdr_v4.din_xfer_len = (uint32_t)byte_cnt; - io_hdr_v4.din_xferp = (uintptr_t)(__u64)buff; - } - -If you wish to read or write a descriptor, use the appropriate xferp of -sg_io_v4. - -The userspace tool that interacts with the ufs-bsg endpoint and uses its -upiu-based protocol is available at: - - https://github.com/westerndigitalcorporation/ufs-tool - -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 diff --git a/MAINTAINERS b/MAINTAINERS index bc6d68bc555a..7bd5e23648b1 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -17140,7 +17140,7 @@ R: Alim Akhtar R: Avri Altman L: linux-scsi@vger.kernel.org S: Supported -F: Documentation/scsi/ufs.txt +F: Documentation/scsi/ufs.rst F: drivers/scsi/ufs/ UNIVERSAL FLASH STORAGE HOST CONTROLLER DRIVER DWC HOOKS diff --git a/drivers/scsi/ufs/Kconfig b/drivers/scsi/ufs/Kconfig index d14c2243e02a..e2005aeddc2d 100644 --- a/drivers/scsi/ufs/Kconfig +++ b/drivers/scsi/ufs/Kconfig @@ -46,7 +46,7 @@ config SCSI_UFSHCD The module will be called ufshcd. To compile this driver as a module, choose M here and read - . + . However, do not compile this as a module if your root file system (the one containing the directory /) is located on a UFS device. -- cgit v1.2.3-59-g8ed1b