From 74286a3c276bca449f934b2cd921f9bced996e04 Mon Sep 17 00:00:00 2001 From: James Bottomley Date: Wed, 14 Nov 2007 18:01:21 -0600 Subject: [SCSI] DocBook scsi_midlayer.tmpl->scsi.tmpl Signed-off-by: James Bottomley --- Documentation/DocBook/Makefile | 2 +- Documentation/DocBook/scsi.tmpl | 409 +++++++++++++++++++++++++++++++ Documentation/DocBook/scsi_midlayer.tmpl | 409 ------------------------------- 3 files changed, 410 insertions(+), 410 deletions(-) create mode 100644 Documentation/DocBook/scsi.tmpl delete mode 100644 Documentation/DocBook/scsi_midlayer.tmpl diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index c6c5e59daaca..6a0ad4715e9f 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -11,7 +11,7 @@ DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ procfs-guide.xml writing_usb_driver.xml \ kernel-api.xml filesystems.xml lsm.xml usb.xml \ gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ - genericirq.xml s390-drivers.xml uio-howto.xml scsi_midlayer.xml + genericirq.xml s390-drivers.xml uio-howto.xml scsi.xml ### # The build process is as follows (targets): diff --git a/Documentation/DocBook/scsi.tmpl b/Documentation/DocBook/scsi.tmpl new file mode 100644 index 000000000000..6255930216b3 --- /dev/null +++ b/Documentation/DocBook/scsi.tmpl @@ -0,0 +1,409 @@ + + + + + + SCSI Mid Layer Guide + + + + James + Bottomley + +
+ James.Bottomley@steeleye.com +
+ + + + + Rob + Landley + +
+ rob@landley.net +
+ + + + + + + 2007 + Linux Foundation + + + + + This documentation is free software; you can redistribute + it and/or modify it under the terms of the GNU General Public + License version 2. + + + + This program 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. + For more details see the file COPYING in the source + distribution of Linux. + + + + + + + + Introduction + + Protocol vs bus + + Once upon a time, the Small Computer Systems Interface defined both + a parallel I/O bus and a data protocol to connect a wide variety of + peripherals (disk drives, tape drives, modems, printers, scanners, + optical drives, test equipment, and medical devices) to a host + computer. + + + Although the old parallel (fast/wide/ultra) SCSI bus has largely + fallen out of use, the SCSI command set is more widely used than ever + to communicate with devices over a number of different busses. + + + The SCSI protocol + is a big-endian peer-to-peer packet based protocol. SCSI commands + are 6, 10, 12, or 16 bytes long, often followed by an associated data + payload. + + + SCSI commands can be transported over just about any kind of bus, and + are the default protocol for storage devices attached to USB, SATA, + SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are + also commonly exchanged over Infiniband, + I20, TCP/IP + (iSCSI), even + Parallel + ports. + + + + Design of the Linux SCSI subsystem + + The SCSI subsystem uses a three layer design, with upper, mid, and low + layers. Every operation involving the SCSI subsystem (such as reading + a sector from a disk) uses one driver at each of the 3 levels: one + upper layer driver, one lower layer driver, and the scsi midlayer. + + + The SCSI upper layer provides the interface between userspace and the + kernel, in the form of block and char device nodes for I/O and + ioctl(). The SCSI lower layer contains drivers for specific hardware + devices. + + + In between is the SCSI mid-layer, analogous to a network routing + layer such as the IPv4 stack. The SCSI mid-layer routes a packet + based data protocol between the upper layer's /dev nodes and the + corresponding devices in the lower layer. It manages command queues, + provides error handling and power management functions, and responds + to ioctl() requests. + + + + + + SCSI upper layer + + The upper layer supports the user-kernel interface by providing + device nodes. + + + sd (SCSI Disk) + sd (sd_mod.o) + + + + sr (SCSI CD-ROM) + sr (sr_mod.o) + + + st (SCSI Tape) + st (st.o) + + + sg (SCSI Generic) + sg (sg.o) + + + ch (SCSI Media Changer) + ch (ch.c) + + + + + SCSI mid layer + + + SCSI midlayer implementation + + include/scsi/scsi_device.h + + +!Iinclude/scsi/scsi_device.h + + + + drivers/scsi/scsi.c + Main file for the scsi midlayer. +!Edrivers/scsi/scsi.c + + + drivers/scsi/scsicam.c + + SCSI + Common Access Method support functions, for use with + HDIO_GETGEO, etc. + +!Edrivers/scsi/scsicam.c + + + drivers/scsi/scsi_error.c + Common SCSI error/timeout handling routines. +!Edrivers/scsi/scsi_error.c + + + drivers/scsi/scsi_devinfo.c + + Manage scsi_dev_info_list, which tracks blacklisted and whitelisted + devices. + +!Idrivers/scsi/scsi_devinfo.c + + + drivers/scsi/scsi_ioctl.c + + Handle ioctl() calls for scsi devices. + +!Edrivers/scsi/scsi_ioctl.c + + + drivers/scsi/scsi_lib.c + + SCSI queuing library. + +!Edrivers/scsi/scsi_lib.c + + + drivers/scsi/scsi_lib_dma.c + + SCSI library functions depending on DMA + (map and unmap scatter-gather lists). + +!Edrivers/scsi/scsi_lib_dma.c + + + drivers/scsi/scsi_module.c + + The file drivers/scsi/scsi_module.c contains legacy support for + old-style host templates. It should never be used by any new driver. + + + + drivers/scsi/scsi_proc.c + + The functions in this file provide an interface between + the PROC file system and the SCSI device drivers + It is mainly used for debugging, statistics and to pass + information directly to the lowlevel driver. + + I.E. plumbing to manage /proc/scsi/* + +!Idrivers/scsi/scsi_proc.c + + + drivers/scsi/scsi_netlink.c + + Infrastructure to provide async events from transports to userspace + via netlink, using a single NETLINK_SCSITRANSPORT protocol for all + transports. + + See the + original patch submission for more details. + +!Idrivers/scsi/scsi_netlink.c + + + drivers/scsi/scsi_scan.c + + Scan a host to determine which (if any) devices are attached. + + The general scanning/probing algorithm is as follows, exceptions are + made to it depending on device specific flags, compilation options, + and global variable (boot or module load time) settings. + + A specific LUN is scanned via an INQUIRY command; if the LUN has a + device attached, a scsi_device is allocated and setup for it. + + For every id of every channel on the given host, start by scanning + LUN 0. Skip hosts that don't respond at all to a scan of LUN 0. + Otherwise, if LUN 0 has a device attached, allocate and setup a + scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN, + and scan all of the LUNs returned by the REPORT LUN; else, + sequentially scan LUNs up until some maximum is reached, or a LUN is + seen that cannot have a device attached to it. + +!Idrivers/scsi/scsi_scan.c + + + drivers/scsi/scsi_sysctl.c + + Set up the sysctl entry: "/dev/scsi/logging_level" + (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level. + + + + drivers/scsi/scsi_sysfs.c + + SCSI sysfs interface routines. + +!Edrivers/scsi/scsi_sysfs.c + + + drivers/scsi/hosts.c + + mid to lowlevel SCSI driver interface + +!Edrivers/scsi/hosts.c + + + drivers/scsi/constants.c + + mid to lowlevel SCSI driver interface + +!Edrivers/scsi/constants.c + + + + + Transport classes + + Transport classes are service libraries for drivers in the scsi + lower layer, which expose transport attributes in sysfs. + + + Fibre Channel transport + + The file drivers/scsi/scsi_transport_fc.c defines transport attributes + for Fibre Channel. + +!Edrivers/scsi/scsi_transport_fc.c + + + iSCSI transport class + + The file drivers/scsi/scsi_transport_iscsi.c defines transport + attributes for the iSCSI class, which sends SCSI packets over TCP/IP + connections. + +!Edrivers/scsi/scsi_transport_iscsi.c + + + Serial Attached SCSI (SAS) transport class + + The file drivers/scsi/scsi_transport_sas.c defines transport + attributes for Serial Attached SCSI, a variant of SATA aimed at + large high-end systems. + + + The SAS transport class contains common code to deal with SAS HBAs, + an aproximated representation of SAS topologies in the driver model, + and various sysfs attributes to expose these topologies and managment + interfaces to userspace. + + + In addition to the basic SCSI core objects this transport class + introduces two additional intermediate objects: The SAS PHY + as represented by struct sas_phy defines an "outgoing" PHY on + a SAS HBA or Expander, and the SAS remote PHY represented by + struct sas_rphy defines an "incoming" PHY on a SAS Expander or + end device. Note that this is purely a software concept, the + underlying hardware for a PHY and a remote PHY is the exactly + the same. + + + There is no concept of a SAS port in this code, users can see + what PHYs form a wide port based on the port_identifier attribute, + which is the same for all PHYs in a port. + +!Edrivers/scsi/scsi_transport_sas.c + + + SATA transport class + + The SATA transport is handled by libata, which has its own book of + documentation in this directory. + + + + Parallel SCSI (SPI) transport class + + The file drivers/scsi/scsi_transport_spi.c defines transport + attributes for traditional (fast/wide/ultra) SCSI busses. + +!Edrivers/scsi/scsi_transport_spi.c + + + SCSI RDMA (SRP) transport class + + The file drivers/scsi/scsi_transport_srp.c defines transport + attributes for SCSI over Remote Direct Memory Access. + +!Edrivers/scsi/scsi_transport_srp.c + + + + + + + SCSI lower layer + + Host Bus Adapter transport types + + Many modern device controllers use the SCSI command set as a protocol to + communicate with their devices through many different types of physical + connections. + + + In SCSI language a bus capable of carrying SCSI commands is + called a "transport", and a controller connecting to such a bus is + called a "host bus adapter" (HBA). + + + Debug transport + + The file drivers/scsi/scsi_debug.c simulates a host adapter with a + variable number of disks (or disk like devices) attached, sharing a + common amount of RAM. Does a lot of checking to make sure that we are + not getting blocks mixed up, and panics the kernel if anything out of + the ordinary is seen. + + + To be more realistic, the simulated devices have the transport + attributes of SAS disks. + + + For documentation see + http://www.torque.net/sg/sdebug26.html + + + + + todo + Parallel (fast/wide/ultra) SCSI, USB, SATA, + SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband, + I20, iSCSI, Parallel ports, netlink... + + + + + diff --git a/Documentation/DocBook/scsi_midlayer.tmpl b/Documentation/DocBook/scsi_midlayer.tmpl deleted file mode 100644 index 6255930216b3..000000000000 --- a/Documentation/DocBook/scsi_midlayer.tmpl +++ /dev/null @@ -1,409 +0,0 @@ - - - - - - SCSI Mid Layer Guide - - - - James - Bottomley - -
- James.Bottomley@steeleye.com -
- - - - - Rob - Landley - -
- rob@landley.net -
- - - - - - - 2007 - Linux Foundation - - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2. - - - - This program 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. - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - Protocol vs bus - - Once upon a time, the Small Computer Systems Interface defined both - a parallel I/O bus and a data protocol to connect a wide variety of - peripherals (disk drives, tape drives, modems, printers, scanners, - optical drives, test equipment, and medical devices) to a host - computer. - - - Although the old parallel (fast/wide/ultra) SCSI bus has largely - fallen out of use, the SCSI command set is more widely used than ever - to communicate with devices over a number of different busses. - - - The SCSI protocol - is a big-endian peer-to-peer packet based protocol. SCSI commands - are 6, 10, 12, or 16 bytes long, often followed by an associated data - payload. - - - SCSI commands can be transported over just about any kind of bus, and - are the default protocol for storage devices attached to USB, SATA, - SAS, Fibre Channel, FireWire, and ATAPI devices. SCSI packets are - also commonly exchanged over Infiniband, - I20, TCP/IP - (iSCSI), even - Parallel - ports. - - - - Design of the Linux SCSI subsystem - - The SCSI subsystem uses a three layer design, with upper, mid, and low - layers. Every operation involving the SCSI subsystem (such as reading - a sector from a disk) uses one driver at each of the 3 levels: one - upper layer driver, one lower layer driver, and the scsi midlayer. - - - The SCSI upper layer provides the interface between userspace and the - kernel, in the form of block and char device nodes for I/O and - ioctl(). The SCSI lower layer contains drivers for specific hardware - devices. - - - In between is the SCSI mid-layer, analogous to a network routing - layer such as the IPv4 stack. The SCSI mid-layer routes a packet - based data protocol between the upper layer's /dev nodes and the - corresponding devices in the lower layer. It manages command queues, - provides error handling and power management functions, and responds - to ioctl() requests. - - - - - - SCSI upper layer - - The upper layer supports the user-kernel interface by providing - device nodes. - - - sd (SCSI Disk) - sd (sd_mod.o) - - - - sr (SCSI CD-ROM) - sr (sr_mod.o) - - - st (SCSI Tape) - st (st.o) - - - sg (SCSI Generic) - sg (sg.o) - - - ch (SCSI Media Changer) - ch (ch.c) - - - - - SCSI mid layer - - - SCSI midlayer implementation - - include/scsi/scsi_device.h - - -!Iinclude/scsi/scsi_device.h - - - - drivers/scsi/scsi.c - Main file for the scsi midlayer. -!Edrivers/scsi/scsi.c - - - drivers/scsi/scsicam.c - - SCSI - Common Access Method support functions, for use with - HDIO_GETGEO, etc. - -!Edrivers/scsi/scsicam.c - - - drivers/scsi/scsi_error.c - Common SCSI error/timeout handling routines. -!Edrivers/scsi/scsi_error.c - - - drivers/scsi/scsi_devinfo.c - - Manage scsi_dev_info_list, which tracks blacklisted and whitelisted - devices. - -!Idrivers/scsi/scsi_devinfo.c - - - drivers/scsi/scsi_ioctl.c - - Handle ioctl() calls for scsi devices. - -!Edrivers/scsi/scsi_ioctl.c - - - drivers/scsi/scsi_lib.c - - SCSI queuing library. - -!Edrivers/scsi/scsi_lib.c - - - drivers/scsi/scsi_lib_dma.c - - SCSI library functions depending on DMA - (map and unmap scatter-gather lists). - -!Edrivers/scsi/scsi_lib_dma.c - - - drivers/scsi/scsi_module.c - - The file drivers/scsi/scsi_module.c contains legacy support for - old-style host templates. It should never be used by any new driver. - - - - drivers/scsi/scsi_proc.c - - The functions in this file provide an interface between - the PROC file system and the SCSI device drivers - It is mainly used for debugging, statistics and to pass - information directly to the lowlevel driver. - - I.E. plumbing to manage /proc/scsi/* - -!Idrivers/scsi/scsi_proc.c - - - drivers/scsi/scsi_netlink.c - - Infrastructure to provide async events from transports to userspace - via netlink, using a single NETLINK_SCSITRANSPORT protocol for all - transports. - - See the - original patch submission for more details. - -!Idrivers/scsi/scsi_netlink.c - - - drivers/scsi/scsi_scan.c - - Scan a host to determine which (if any) devices are attached. - - The general scanning/probing algorithm is as follows, exceptions are - made to it depending on device specific flags, compilation options, - and global variable (boot or module load time) settings. - - A specific LUN is scanned via an INQUIRY command; if the LUN has a - device attached, a scsi_device is allocated and setup for it. - - For every id of every channel on the given host, start by scanning - LUN 0. Skip hosts that don't respond at all to a scan of LUN 0. - Otherwise, if LUN 0 has a device attached, allocate and setup a - scsi_device for it. If target is SCSI-3 or up, issue a REPORT LUN, - and scan all of the LUNs returned by the REPORT LUN; else, - sequentially scan LUNs up until some maximum is reached, or a LUN is - seen that cannot have a device attached to it. - -!Idrivers/scsi/scsi_scan.c - - - drivers/scsi/scsi_sysctl.c - - Set up the sysctl entry: "/dev/scsi/logging_level" - (DEV_SCSI_LOGGING_LEVEL) which sets/returns scsi_logging_level. - - - - drivers/scsi/scsi_sysfs.c - - SCSI sysfs interface routines. - -!Edrivers/scsi/scsi_sysfs.c - - - drivers/scsi/hosts.c - - mid to lowlevel SCSI driver interface - -!Edrivers/scsi/hosts.c - - - drivers/scsi/constants.c - - mid to lowlevel SCSI driver interface - -!Edrivers/scsi/constants.c - - - - - Transport classes - - Transport classes are service libraries for drivers in the scsi - lower layer, which expose transport attributes in sysfs. - - - Fibre Channel transport - - The file drivers/scsi/scsi_transport_fc.c defines transport attributes - for Fibre Channel. - -!Edrivers/scsi/scsi_transport_fc.c - - - iSCSI transport class - - The file drivers/scsi/scsi_transport_iscsi.c defines transport - attributes for the iSCSI class, which sends SCSI packets over TCP/IP - connections. - -!Edrivers/scsi/scsi_transport_iscsi.c - - - Serial Attached SCSI (SAS) transport class - - The file drivers/scsi/scsi_transport_sas.c defines transport - attributes for Serial Attached SCSI, a variant of SATA aimed at - large high-end systems. - - - The SAS transport class contains common code to deal with SAS HBAs, - an aproximated representation of SAS topologies in the driver model, - and various sysfs attributes to expose these topologies and managment - interfaces to userspace. - - - In addition to the basic SCSI core objects this transport class - introduces two additional intermediate objects: The SAS PHY - as represented by struct sas_phy defines an "outgoing" PHY on - a SAS HBA or Expander, and the SAS remote PHY represented by - struct sas_rphy defines an "incoming" PHY on a SAS Expander or - end device. Note that this is purely a software concept, the - underlying hardware for a PHY and a remote PHY is the exactly - the same. - - - There is no concept of a SAS port in this code, users can see - what PHYs form a wide port based on the port_identifier attribute, - which is the same for all PHYs in a port. - -!Edrivers/scsi/scsi_transport_sas.c - - - SATA transport class - - The SATA transport is handled by libata, which has its own book of - documentation in this directory. - - - - Parallel SCSI (SPI) transport class - - The file drivers/scsi/scsi_transport_spi.c defines transport - attributes for traditional (fast/wide/ultra) SCSI busses. - -!Edrivers/scsi/scsi_transport_spi.c - - - SCSI RDMA (SRP) transport class - - The file drivers/scsi/scsi_transport_srp.c defines transport - attributes for SCSI over Remote Direct Memory Access. - -!Edrivers/scsi/scsi_transport_srp.c - - - - - - - SCSI lower layer - - Host Bus Adapter transport types - - Many modern device controllers use the SCSI command set as a protocol to - communicate with their devices through many different types of physical - connections. - - - In SCSI language a bus capable of carrying SCSI commands is - called a "transport", and a controller connecting to such a bus is - called a "host bus adapter" (HBA). - - - Debug transport - - The file drivers/scsi/scsi_debug.c simulates a host adapter with a - variable number of disks (or disk like devices) attached, sharing a - common amount of RAM. Does a lot of checking to make sure that we are - not getting blocks mixed up, and panics the kernel if anything out of - the ordinary is seen. - - - To be more realistic, the simulated devices have the transport - attributes of SAS disks. - - - For documentation see - http://www.torque.net/sg/sdebug26.html - - - - - todo - Parallel (fast/wide/ultra) SCSI, USB, SATA, - SAS, Fibre Channel, FireWire, ATAPI devices, Infiniband, - I20, iSCSI, Parallel ports, netlink... - - - - - -- cgit v1.2.3-59-g8ed1b