xref: /freebsd/sys/dev/isp/DriverManual.txt (revision 71625ec9ad2a9bc8c09784fbd23b759830e0ee5f)
11c374983SMatt Jacob
21c374983SMatt Jacob		Driver Theory of Operation Manual
31c374983SMatt Jacob
41c374983SMatt Jacob1. Introduction
51c374983SMatt Jacob
61c374983SMatt JacobThis is a short text document that will describe the background, goals
71c374983SMatt Jacobfor, and current theory of operation for the joint Fibre Channel/SCSI
81c374983SMatt JacobHBA driver for QLogic hardware.
91c374983SMatt Jacob
101c374983SMatt JacobBecause this driver is an ongoing project, do not expect this manual
111c374983SMatt Jacobto remain entirely up to date. Like a lot of software engineering, the
121c374983SMatt Jacobultimate documentation is the driver source. However, this manual should
131c374983SMatt Jacobserve as a solid basis for attempting to understand where the driver
141c374983SMatt Jacobstarted and what is trying to be accomplished with the current source.
151c374983SMatt Jacob
161c374983SMatt JacobThe reader is expected to understand the basics of SCSI and Fibre Channel
171c374983SMatt Jacoband to be familiar with the range of platforms that Solaris, Linux and
181c374983SMatt Jacobthe variant "BSD" Open Source systems are available on. A glossary and
191c374983SMatt Jacoba few references will be placed at the end of the document.
201c374983SMatt Jacob
211c374983SMatt JacobThere will be references to functions and structures within the body of
221c374983SMatt Jacobthis document. These can be easily found within the source using editor
231c374983SMatt Jacobtags or grep. There will be few code examples here as the code already
241c374983SMatt Jacobexists where the reader can easily find it.
251c374983SMatt Jacob
261c374983SMatt Jacob2. A Brief History for this Driver
271c374983SMatt Jacob
281c374983SMatt JacobThis driver originally started as part of work funded by NASA Ames
291c374983SMatt JacobResearch Center's Numerical Aerodynamic Simulation center ("NAS" for
301c374983SMatt Jacobshort) for the QLogic PCI 1020 and 1040 SCSI Host Adapters as part of my
311c374983SMatt Jacobwork at porting the NetBSD Operating System to the Alpha architectures
321c374983SMatt Jacob(specifically the AlphaServer 8200 and 8400 platforms).  In short, it
331c374983SMatt Jacobstarted just as simple single SCSI HBA driver for just the purpose of
341c374983SMatt Jacobrunning off a SCSI disk. This work took place starting in January, 1997.
351c374983SMatt Jacob
361c374983SMatt JacobBecause the first implementation was for NetBSD, which runs on a very
371c374983SMatt Jacoblarge number of platforms, and because NetBSD supported both systems with
381c374983SMatt JacobSBus cards (e.g., Sun SPARC systems) as well as systems with PCI cards,
391c374983SMatt Jacoband because the QLogic SCSI cards came in both SBus and PCI versions, the
401c374983SMatt Jacobinitial implementation followed the very thoughtful NetBSD design tenet
411c374983SMatt Jacobof splitting drivers into what are called MI (for Machine Independent)
421c374983SMatt Jacoband MD (Machine Dependent) portions. The original design therefore was
431c374983SMatt Jacobfrom the premise that the driver would drive both SBus and PCI card
441c374983SMatt Jacobvariants. These busses are similar but have quite different constraints,
451c374983SMatt Jacoband while the QLogic SBus and PCI cards are very similar, there are some
461c374983SMatt Jacobsignificant differences.
471c374983SMatt Jacob
481c374983SMatt JacobAfter this initial goal had been met, there began to be some talk about
491c374983SMatt Jacoblooking into implementing Fibre Channel mass storage at NAS. At this time
501c374983SMatt Jacobthe QLogic 2100 FC/AL HBA was about to become available. After looking at
511c374983SMatt Jacobthe way it was designed I concluded that it was so darned close to being
521c374983SMatt Jacobjust like the SCSI HBAs that it would be insane to *not* leverage off of
531c374983SMatt Jacobthe existing driver. So, we ended up with a driver for NetBSD that drove
541c374983SMatt JacobPCI and SBus SCSI cards, and now also drove the QLogic 2100 FC-AL HBA.
551c374983SMatt Jacob
561c374983SMatt JacobAfter this, ports to non-NetBSD platforms became interesting as well.
571c374983SMatt JacobThis took the driver out of the interest with NAS and into interested
581c374983SMatt Jacobsupport from a number of other places. Since the original NetBSD
591c374983SMatt Jacobdevelopment, the driver has been ported to FreeBSD, OpenBSD, Linux,
601c374983SMatt JacobSolaris, and two proprietary systems. Following from the original MI/MD
611c374983SMatt Jacobdesign of NetBSD, a rather successful attempt has been made to keep the
621c374983SMatt JacobOperating System Platform differences segregated and to a minimum.
631c374983SMatt Jacob
641c374983SMatt JacobAlong the way, support for the 2200 as well as full fabric and target
651c374983SMatt Jacobmode support has been added, and 2300 support as well as an FC-IP stack
661c374983SMatt Jacobare planned.
671c374983SMatt Jacob
681c374983SMatt Jacob3. Driver Design Goals
691c374983SMatt Jacob
701c374983SMatt JacobThe driver has not started out as one normally would do such an effort.
71453130d9SPedro F. GiffuniNormally you design via top-down methodologies and set an initial goal
721c374983SMatt Jacoband meet it. This driver has had a design goal that changes from almost
731c374983SMatt Jacobthe very first. This has been an extremely peculiar, if not risque,
741c374983SMatt Jacobexperience. As a consequence, this section of this document contains
751c374983SMatt Jacoba bit of "reconstruction after the fact" in that the design goals are
761c374983SMatt Jacobas I perceive them to be now- not necessarily what they started as.
771c374983SMatt Jacob
781c374983SMatt JacobThe primary design goal now is to have a driver that can run both the
791c374983SMatt JacobSCSI and Fibre Channel SCSI prototocols on multiple OS platforms with
801c374983SMatt Jacobas little OS platform support code as possible.
811c374983SMatt Jacob
821c374983SMatt JacobThe intended support targets for SCSI HBAs is to support the single and
831c374983SMatt Jacobdual channel PCI Ultra2 and PCI Ultra3 cards as well as the older PCI
841c374983SMatt JacobUltra single channel cards and SBus cards.
851c374983SMatt Jacob
861c374983SMatt JacobThe intended support targets for Fibre Channel HBAs is the 2100, 2200
871c374983SMatt Jacoband 2300 PCI cards.
881c374983SMatt Jacob
891c374983SMatt JacobFibre Channel support should include complete fabric and public loop
901c374983SMatt Jacobas well as private loop and private loop, direct-attach topologies.
911c374983SMatt JacobFC-IP support is also a goal.
921c374983SMatt Jacob
931c374983SMatt JacobFor both SCSI and Fibre Channel, simultaneous target/initiator mode support
941c374983SMatt Jacobis a goal.
951c374983SMatt Jacob
961c374983SMatt JacobPure, raw, performance is not a primary goal of this design. This design,
971c374983SMatt Jacobbecause it has a tremendous amount of code common across multiple
981c374983SMatt Jacobplatforms, will undoubtedly never be able to beat the performance of a
991c374983SMatt Jacobdriver that is specifically designed for a single platform and a single
1001c374983SMatt Jacobcard. However, it is a good strong secondary goal to make the performance
1011c374983SMatt Jacobpenalties in this design as small as possible.
1021c374983SMatt Jacob
1031c374983SMatt JacobAnother primary aim, which almost need not be stated, is that the
1041c374983SMatt Jacobimplementation of platform differences must not clutter up the common
1051c374983SMatt Jacobcode with platform specific defines. Instead, some reasonable layering
1061c374983SMatt Jacobsemantics are defined such that platform specifics can be kept in the
1071c374983SMatt Jacobplatform specific code.
1081c374983SMatt Jacob
1091c374983SMatt Jacob4. QLogic Hardware Architecture
1101c374983SMatt Jacob
1111c374983SMatt JacobIn order to make the design of this driver more intelligible, some
1121c374983SMatt Jacobdescription of the Qlogic hardware architecture is in order. This will
1131c374983SMatt Jacobnot be an exhaustive description of how this card works, but will
1141c374983SMatt Jacobnote enough of the important features so that the driver design is
1151c374983SMatt Jacobhopefully clearer.
1161c374983SMatt Jacob
1171c374983SMatt Jacob4.1 Basic QLogic hardware
1181c374983SMatt Jacob
1191c374983SMatt JacobThe QLogic HBA cards all contain a tiny 16-bit RISC-like processor and
1201c374983SMatt Jacobvarying sizes of SRAM. Each card contains a Bus Interface Unit (BIU)
1211c374983SMatt Jacobas appropriate for the host bus (SBus or PCI).  The BIUs allow access
1221c374983SMatt Jacobto a set of dual-ranked 16 bit incoming and outgoing mailbox registers
1231c374983SMatt Jacobas well as access to control registers that control the RISC or access
1241c374983SMatt Jacobother portions of the card (e.g., Flash BIOS). The term 'dual-ranked'
1251c374983SMatt Jacobmeans that at the same host visible address if you write a mailbox
1261c374983SMatt Jacobregister, that is a write to an (incoming, to the HBA) mailbox register,
1271c374983SMatt Jacobwhile a read to the same address reads another (outgoing, to the HBA)
1281c374983SMatt Jacobmailbox register with completely different data. Each HBA also then has
129453130d9SPedro F. Giffunicore and auxiliary logic which either is used to interface to a SCSI bus
1301c374983SMatt Jacob(or to external bus drivers that connect to a SCSI bus), or to connect
1311c374983SMatt Jacobto a Fibre Channel bus.
1321c374983SMatt Jacob
1331c374983SMatt Jacob4.2 Basic Control Interface
1341c374983SMatt Jacob
1351c374983SMatt JacobThere are two principle I/O control mechanisms by which the driver
1361c374983SMatt Jacobcommunicates with and controls the QLogic HBA. The first mechanism is to
1371c374983SMatt Jacobuse the incoming mailbox registers to interrupt and issue commands to
1381c374983SMatt Jacobthe RISC processor (with results usually, but not always, ending up in
1391c374983SMatt Jacobthe ougtoing mailbox registers). The second mechanism is to establish,
1401c374983SMatt Jacobvia mailbox commands, circular request and response queues in system
1411c374983SMatt Jacobmemory that are then shared between the QLogic and the driver. The
1421c374983SMatt Jacobrequest queue is used to queue requests (e.g., I/O requests) for the
1431c374983SMatt JacobQLogic HBA's RISC engine to copy into the HBA memory and process. The
1441c374983SMatt Jacobresult queue is used by the QLogic HBA's RISC engine to place results of
1451c374983SMatt Jacobrequests read from the request queue, as well as to place notification
1461c374983SMatt Jacobof asynchronous events (e.g., incoming commands in target mode).
1471c374983SMatt Jacob
1481c374983SMatt JacobTo give a bit more precise scale to the preceding description, the QLogic
1491c374983SMatt JacobHBA has 8 dual-ranked 16 bit mailbox registers, mostly for out-of-band
1501c374983SMatt Jacobcontrol purposes. The QLogic HBA then utilizes a circular request queue
1511c374983SMatt Jacobof 64 byte fixed size Queue Entries to receive normal initiator mode
1521c374983SMatt JacobI/O commands (or continue target mode requests). The request queue may
1531c374983SMatt Jacobbe up to 256 elements for the QLogic 1020 and 1040 chipsets, but may
1541c374983SMatt Jacobbe quite larger for the QLogic 12X0/12160 SCSI and QLogic 2X00 Fibre
1551c374983SMatt JacobChannel chipsets.
1561c374983SMatt Jacob
1571c374983SMatt JacobIn addition to synchronously initiated usage of mailbox commands by
1581c374983SMatt Jacobthe host system, the QLogic may also deliver asynchronous notifications
1591c374983SMatt Jacobsolely in outgoing mailbox registers. These asynchronous notifications in
1601c374983SMatt Jacobmailboxes may be things like notification of SCSI Bus resets, or that the
1611c374983SMatt JacobFabric Name server has sent a change notification, or even that a specific
1621c374983SMatt JacobI/O command completed without error (this is called 'Fast Posting'
1631c374983SMatt Jacoband saves the QLogic HBA from having to write a response queue entry).
1641c374983SMatt Jacob
1651c374983SMatt JacobThe QLogic HBA is an interrupting card, and when servicing an interrupt
1661c374983SMatt Jacobyou really only have to check for either a mailbox interrupt or an
16736daf049SEitan Adlerinterrupt notification that the response queue has an entry to
1681c374983SMatt Jacobbe dequeued.
1691c374983SMatt Jacob
1701c374983SMatt Jacob4.3 Fibre Channel SCSI out of SCSI
1711c374983SMatt Jacob
1721c374983SMatt JacobQLogic took the approach in introducing the 2X00 cards to just treat
1731c374983SMatt JacobFC-AL as a 'fat' SCSI bus (a SCSI bus with more than 15 targets). All
1741c374983SMatt Jacobof the things that you really need to do with Fibre Channel with respect
1751c374983SMatt Jacobto providing FC-4 services on top of a Class 3 connection are performed
1761c374983SMatt Jacobby the RISC engine on the QLogic card itself. This means that from
1771c374983SMatt Jacoban HBA driver point of view, very little needs to change that would
1781c374983SMatt Jacobdistinguish addressing a Fibre Channel disk from addressing a plain
1791c374983SMatt Jacobold SCSI disk.
1801c374983SMatt Jacob
1811c374983SMatt JacobHowever, in the details it's not *quite* that simple. For example, in
1821c374983SMatt Jacoborder to manage Fabric Connections, the HBA driver has to do explicit
1831c374983SMatt Jacobbinding of entities it's queried from the name server to specific 'target'
1841c374983SMatt Jacobids (targets, in this case, being a virtual entity).
1851c374983SMatt Jacob
1861c374983SMatt JacobStill- the HBA firmware does really nearly all of the tedious management
1871c374983SMatt Jacobof Fibre Channel login state. The corollary to this sometimes is the
1881c374983SMatt Jacoblack of ability to say why a particular login connection to a Fibre
1891c374983SMatt JacobChannel disk is not working well.
1901c374983SMatt Jacob
1911c374983SMatt JacobThere are clear limits with the QLogic card in managing fabric devices.
1921c374983SMatt JacobThe QLogic manages local loop devices (LoopID or Target 0..126) itself,
1931c374983SMatt Jacobbut for the management of fabric devices, it has an absolute limit of
1941c374983SMatt Jacob253 simultaneous connections (256 entries less 3 reserved entries).
1951c374983SMatt Jacob
1961c374983SMatt Jacob5. Driver Architecture
1971c374983SMatt Jacob
1981c374983SMatt Jacob5.1 Driver Assumptions
1991c374983SMatt Jacob
2001c374983SMatt JacobThe first basic assumption for this driver is that the requirements for
2011c374983SMatt Jacoba SCSI HBA driver for any system is that of a 2 or 3 layer model where
2021c374983SMatt Jacobthere are SCSI target device drivers (drivers which drive SCSI disks,
2031c374983SMatt JacobSCSI tapes, and so on), possibly a middle services layer, and a bottom
2041c374983SMatt Jacoblayer that manages the transport of SCSI CDB's out a SCSI bus (or across
2051c374983SMatt JacobFibre Channel) to a SCSI device. It's assumed that each SCSI command is
2061c374983SMatt Jacoba separate structure (or pointer to a structure) that contains the SCSI
2071c374983SMatt JacobCDB and a place to store SCSI Status and SCSI Sense Data.
2081c374983SMatt Jacob
2091c374983SMatt JacobThis turns out to be a pretty good assumption. All of the Open Source
2101c374983SMatt Jacobsystems (*BSD and Linux) and most of the proprietary systems have this
2111c374983SMatt Jacobkind of structure. This has been the way to manage SCSI subsystems for
2121c374983SMatt Jacobat least ten years.
2131c374983SMatt Jacob
2141c374983SMatt JacobThere are some additional basic assumptions that this driver makes- primarily
2151c374983SMatt Jacobin the arena of basic simple services like memory zeroing, memory copying,
2161c374983SMatt Jacobdelay, sleep, microtime functions. It doesn't assume much more than this.
2171c374983SMatt Jacob
2181c374983SMatt Jacob5.2 Overall Driver Architecture
2191c374983SMatt Jacob
2201c374983SMatt JacobThe driver is split into a core (machine independent) module and platform
2211c374983SMatt Jacoband bus specific outer modules (machine dependent).
2221c374983SMatt Jacob
2231c374983SMatt JacobThe core code (in the files isp.c, isp_inline.h, ispvar.h, ispreg.h and
2241c374983SMatt Jacobispmbox.h) handles:
2251c374983SMatt Jacob
2261c374983SMatt Jacob + Chipset recognition and reset and firmware download (isp_reset)
2271c374983SMatt Jacob + Board Initialization (isp_init)
2281c374983SMatt Jacob + First level interrupt handling (response retrieval) (isp_intr)
2291c374983SMatt Jacob + A SCSI command queueing entry point (isp_start)
2301c374983SMatt Jacob + A set of control services accessed either via local requirements within
2311c374983SMatt Jacob   the core module or via an externally visible control entry point
2321c374983SMatt Jacob   (isp_control).
2331c374983SMatt Jacob
2341c374983SMatt JacobThe platform/bus specific modules (and definitions) depend on each
2351c374983SMatt Jacobplatform, and they provide both definitions and functions for the core
2361c374983SMatt Jacobmodule's use.  Generally a platform module set is split into a bus
2371c374983SMatt Jacobdependent module (where configuration is begun from and bus specific
2381c374983SMatt Jacobsupport functions reside) and relatively thin platform specific layer
2391c374983SMatt Jacobwhich serves as the interconnect with the rest of this platform's SCSI
2401c374983SMatt Jacobsubsystem.
2411c374983SMatt Jacob
2421c374983SMatt JacobFor ease of bus specific access issues, a centralized soft state
2431c374983SMatt Jacobstructure is maintained for each HBA instance (struct ispsoftc). This
2441c374983SMatt Jacobsoft state structure contains a machine/bus dependent vector (mdvec)
2451c374983SMatt Jacobfor functions that read and write hardware registers, set up DMA for the
2461c374983SMatt Jacobrequest/response queues and fibre channel scratch area, set up and tear
2471c374983SMatt Jacobdown DMA mappings for a SCSI command, provide a pointer to firmware to
2481c374983SMatt Jacobload, and other minor things.
2491c374983SMatt Jacob
2501c374983SMatt JacobThe machine dependent outer module must provide functional entry points
2511c374983SMatt Jacobfor the core module:
2521c374983SMatt Jacob
2531c374983SMatt Jacob + A SCSI command completion handoff point (isp_done)
2541c374983SMatt Jacob + An asynchronous event handler (isp_async)
2551c374983SMatt Jacob + A logging/printing function (isp_prt)
2561c374983SMatt Jacob
2571c374983SMatt JacobThe machine dependent outer module code must also provide a set of
2581c374983SMatt Jacobabstracting definitions which is what the core module utilizes heavily
2591c374983SMatt Jacobto do its job. These are discussed in detail in the comments in the
2601c374983SMatt Jacobfile ispvar.h, but to give a sense of the range of what is required,
2611c374983SMatt Jacoblet's illustrate two basic classes of these defines.
2621c374983SMatt Jacob
2631c374983SMatt JacobThe first class are "structure definition/access" class. An
2641c374983SMatt Jacobexample of these would be:
2651c374983SMatt Jacob
2661c374983SMatt Jacob	XS_T            Platform SCSI transaction type (i.e., command for HBA)
2671c374983SMatt Jacob	..
2681c374983SMatt Jacob	XS_TGT(xs)      gets the target from an XS_T
2691c374983SMatt Jacob	..
2701c374983SMatt Jacob	XS_TAG_TYPE(xs) which type of tag to use
2711c374983SMatt Jacob	..
2721c374983SMatt Jacob
2731c374983SMatt JacobThe second class are 'functional' class definitions. Some examples of
2741c374983SMatt Jacobthis class are:
2751c374983SMatt Jacob
2761c374983SMatt Jacob	MEMZERO(dst, src)                       platform zeroing function
2771c374983SMatt Jacob	..
2781c374983SMatt Jacob	MBOX_WAIT_COMPLETE(struct ispsoftc *)   wait for mailbox cmd to be done
2791c374983SMatt Jacob
2801c374983SMatt JacobNote that the former is likely to be simple replacement with bzero or
2811c374983SMatt Jacobmemset on most systems, while the latter could be quite complex.
2821c374983SMatt Jacob
2831c374983SMatt JacobThis soft state structure also contains different parameter information
2841c374983SMatt Jacobbased upon whether this is a SCSI HBA or a Fibre Channel HBA (which is
2851c374983SMatt Jacobfilled in by the code module).
2861c374983SMatt Jacob
2871c374983SMatt JacobIn order to clear up what is undoubtedly a seeming confusion of
2881c374983SMatt Jacobinterconnects, a description of the typical flow of code that performs
2891c374983SMatt Jacobboards initialization and command transactions may help.
2901c374983SMatt Jacob
2911c374983SMatt Jacob5.3 Initialization Code Flow
2921c374983SMatt Jacob
2931c374983SMatt JacobTypically a bus specific module for a platform (e.g., one that wants
2941c374983SMatt Jacobto configure a PCI card) is entered via that platform's configuration
2951c374983SMatt Jacobmethods. If this module recognizes a card and can utilize or construct the
2961c374983SMatt Jacobspace for the HBA instance softc, it does so, and initializes the machine
2971c374983SMatt Jacobdependent vector as well as any other platform specific information that
2981c374983SMatt Jacobcan be hidden in or associated with this structure.
2991c374983SMatt Jacob
3001c374983SMatt JacobConfiguration at this point usually involves mapping in board registers
3011c374983SMatt Jacoband registering an interrupt. It's quite possible that the core module's
3021c374983SMatt Jacobisp_intr function is adequate to be the interrupt entry point, but often
3031c374983SMatt Jacobit's more useful have a bus specific wrapper module that calls isp_intr.
3041c374983SMatt Jacob
3051c374983SMatt JacobAfter mapping and interrupt registry is done, isp_reset is called.
3061c374983SMatt JacobPart of the isp_reset call may cause callbacks out to the bus dependent
3071c374983SMatt Jacobmodule to perform allocation and/or mapping of Request and Response
3081c374983SMatt Jacobqueues (as well as a Fibre Channel scratch area if this is a Fibre
3091c374983SMatt JacobChannel HBA).  The reason this is considered 'bus dependent' is that
3101c374983SMatt Jacobonly the bus dependent module may have the information that says how
3111c374983SMatt Jacobone could perform I/O mapping and dependent (e.g., on a Solaris system)
312453130d9SPedro F. Giffunion the Request and Response queues. Another callback can enable the *use*
3131c374983SMatt Jacobof interrupts should this platform be able to finish configuration in
3141c374983SMatt Jacobinterrupt driven mode.
3151c374983SMatt Jacob
3161c374983SMatt JacobIf isp_reset is successful at resetting the QLogic chipset and downloading
3171c374983SMatt Jacobnew firmware (if available) and setting it running, isp_init is called. If
3181c374983SMatt Jacobisp_init is successful in doing initial board setups (including reading
3191c374983SMatt JacobNVRAM from the QLogic card), then this bus specicic module will call the
3201c374983SMatt Jacobplatform dependent module that takes the appropriate steps to 'register'
3211c374983SMatt Jacobthis HBA with this platform's SCSI subsystem.  Examining either the
3221c374983SMatt JacobOpenBSD or the NetBSD isp_pci.c or isp_sbus.c files may assist the reader
3231c374983SMatt Jacobhere in clarifying some of this.
3241c374983SMatt Jacob
3251c374983SMatt Jacob5.4 Initiator Mode Command Code Flow
3261c374983SMatt Jacob
327453130d9SPedro F. GiffuniA successful execution of isp_init will lead to the driver 'registering'
3281c374983SMatt Jacobitself with this platform's SCSI subsystem. One assumed action for this
32914517324SEitan Adleris the registry of a function that the SCSI subsystem for this platform
3301c374983SMatt Jacobwill call when it has a SCSI command to run.
3311c374983SMatt Jacob
3321c374983SMatt JacobThe platform specific module function that receives this will do whatever
333*a5beac39SGordon Berglingit needs to prepare this command for execution in the core module. This
3341c374983SMatt Jacobsounds vague, but it's also very flexible. In principle, this could be
3351c374983SMatt Jacoba complete marshalling/demarshalling of this platform's SCSI command
3361c374983SMatt Jacobstructure (should it be impossible to represent in an XS_T). In addition,
3371c374983SMatt Jacobthis function can also block commands from running (if, e.g., Fibre
3381c374983SMatt JacobChannel loop state would preclude successful starting of the command).
3391c374983SMatt Jacob
3401c374983SMatt JacobWhen it's ready to do so, the function isp_start is called with this
3411c374983SMatt Jacobcommand. This core module tries to allocate request queue space for
3421c374983SMatt Jacobthis command. It also calls through the machine dependent vector
3431c374983SMatt Jacobfunction to make sure any DMA mapping for this command is done.
3441c374983SMatt Jacob
3451c374983SMatt JacobNow, DMA mapping here is possibly a misnomer, as more than just
3461c374983SMatt JacobDMA mapping can be done in this bus dependent function. This is
3471c374983SMatt Jacobalso the place where any endian byte-swizzling will be done. At any
3481c374983SMatt Jacobrate, this function is called last because the process of establishing
3491c374983SMatt JacobDMA addresses for any command may in fact consume more Request Queue
3501c374983SMatt Jacobentries than there are currently available. If the mapping and other
3511c374983SMatt Jacobfunctions are successful, the QLogic mailbox inbox pointer register
3521c374983SMatt Jacobis updated to indicate to the QLogic that it has a new request to
3531c374983SMatt Jacobread.
3541c374983SMatt Jacob
3551c374983SMatt JacobIf this function is unsuccessful, policy as to what to do at this point is
3561c374983SMatt Jacobleft to the machine dependent platform function which called isp_start. In
3571c374983SMatt Jacobsome platforms, temporary resource shortages can be handled by the main
3581c374983SMatt JacobSCSI subsystem. In other platforms, the machine dependent code has to
3591c374983SMatt Jacobhandle this.
3601c374983SMatt Jacob
3611c374983SMatt JacobIn order to keep track of commands that are in progress, the soft state
3621c374983SMatt Jacobstructure contains an array of 'handles' that are associated with each
3631c374983SMatt Jacobactive command. When you send a command to the QLogic firmware, a portion
3641c374983SMatt Jacobof the Request Queue entry can contain a non-zero handle identifier so
3651c374983SMatt Jacobthat at a later point in time in reading either a Response Queue entry
3661c374983SMatt Jacobor from a Fast Posting mailbox completion interrupt, you can take this
3671c374983SMatt Jacobhandle to find the command you were waiting on. It should be noted that
3681c374983SMatt Jacobthis is probably one of the most dangerous areas of this driver. Corrupted
3691c374983SMatt Jacobhandles will lead to system panics.
3701c374983SMatt Jacob
3711c374983SMatt JacobAt some later point in time an interrupt will occur. Eventually,
3721c374983SMatt Jacobisp_intr will be called. This core module will determine what the cause
3731c374983SMatt Jacobof the interrupt is, and if it is for a completing command. That is,
3741c374983SMatt Jacobit'll determine the handle and fetch the pointer to the command out of
3751c374983SMatt Jacobstorage within the soft state structure. Skipping over a lot of details,
3761c374983SMatt Jacobthe machine dependent code supplied function isp_done is called with the
3771c374983SMatt Jacobpointer to the completing command. This would then be the glue layer that
3781c374983SMatt Jacobinforms the SCSI subsystem for this platform that a command is complete.
3791c374983SMatt Jacob
3801c374983SMatt Jacob5.5 Asynchronous Events
3811c374983SMatt Jacob
3821c374983SMatt JacobInterrupts occur for events other than commands (mailbox or request queue
3831c374983SMatt Jacobstarted commands) completing. These are called Asynchronous Mailbox
3841c374983SMatt Jacobinterrupts. When some external event causes the SCSI bus to be reset,
3851c374983SMatt Jacobor when a Fibre Channel loop changes state (e.g., a LIP is observed),
3861c374983SMatt Jacobthis generates such an asynchronous event.
3871c374983SMatt Jacob
3881c374983SMatt JacobEach platform module has to provide an isp_async entry point that will
3891c374983SMatt Jacobhandle a set of these. This isp_async entry point also handles things
3901c374983SMatt Jacobwhich aren't properly async events but are simply natural outgrowths
3911c374983SMatt Jacobof code flow for another core function (see discussion on fabric device
3921c374983SMatt Jacobmanagement below).
3931c374983SMatt Jacob
3941c374983SMatt Jacob5.6 Target Mode Code Flow
3951c374983SMatt Jacob
3961c374983SMatt JacobThis section could use a lot of expansion, but this covers the basics.
3971c374983SMatt Jacob
3981c374983SMatt JacobThe QLogic cards, when operating in target mode, follow a code flow that is
3991c374983SMatt Jacobessentially the inverse of that for intiator mode describe above. In this
4001c374983SMatt Jacobscenario, an interrupt occurs, and present on the Response Queue is a
4011c374983SMatt Jacobqueue entry element defining a new command arriving from an initiator.
4021c374983SMatt Jacob
4031c374983SMatt JacobThis is passed to possibly external target mode handler. This driver
4041c374983SMatt Jacobprovides some handling for this in a core module, but also leaves
4051c374983SMatt Jacobthings open enough that a completely different target mode handler
4061c374983SMatt Jacobmay accept this incoming queue entry.
4071c374983SMatt Jacob
4081c374983SMatt JacobThe external target mode handler then turns around forms up a response
4091c374983SMatt Jacobto this 'response' that just arrived which is then placed on the Request
4101c374983SMatt JacobQueue and handled very much like an initiator mode command (i.e., calling
4111c374983SMatt Jacobthe bus dependent DMA mapping function). If this entry completes the
4121c374983SMatt Jacobcommand, no more need occur. But often this handles only part of the
4131c374983SMatt Jacobrequested command, so the QLogic firmware will rewrite the response
4141c374983SMatt Jacobto the initial 'response' again onto the Response Queue, whereupon the
4151c374983SMatt Jacobtarget mode handler will respond to that, and so on until the command
4161c374983SMatt Jacobis completely handled.
4171c374983SMatt Jacob
4181c374983SMatt JacobBecause almost no platform provides basic SCSI Subsystem target mode
4191c374983SMatt Jacobsupport, this design has been left extremely open ended, and as such
4201c374983SMatt Jacobit's a bit hard to describe in more detail than this.
4211c374983SMatt Jacob
4221c374983SMatt Jacob5.7 Locking Assumptions
4231c374983SMatt Jacob
4241c374983SMatt JacobThe observant reader by now is likely to have asked the question, "but what
4251c374983SMatt Jacobabout locking? Or interrupt masking" by now.
4261c374983SMatt Jacob
4271c374983SMatt JacobThe basic assumption about this is that the core module does not know
4281c374983SMatt Jacobanything directly about locking or interrupt masking. It may assume that
4291c374983SMatt Jacobupon entry (e.g., via isp_start, isp_control, isp_intr) that appropriate
4301c374983SMatt Jacoblocking and interrupt masking has been done.
4311c374983SMatt Jacob
4321c374983SMatt JacobThe platform dependent code may also therefore assume that if it is
4331c374983SMatt Jacobcalled (e.g., isp_done or isp_async) that any locking or masking that
4341c374983SMatt Jacobwas in place upon the entry to the core module is still there. It is up
4351c374983SMatt Jacobto the platform dependent code to worry about avoiding any lock nesting
4361c374983SMatt Jacobissues. As an example of this, the Linux implementation simply queues
4371c374983SMatt Jacobup commands completed via the callout to isp_done, which it then pushes
4381c374983SMatt Jacobout to the SCSI subsystem after a return from it's calling isp_intr is
4391c374983SMatt Jacobexecuted (and locks dropped appropriately, as well as avoidance of deep
4401c374983SMatt Jacobinterrupt stacks).
4411c374983SMatt Jacob
4421c374983SMatt JacobRecent changes in the design have now eased what had been an original
4431c374983SMatt Jacobrequirement that the while in the core module no locks or interrupt
4441c374983SMatt Jacobmasking could be dropped. It's now up to each platform to figure out how
4451c374983SMatt Jacobto implement this. This is principally used in the execution of mailbox
4461c374983SMatt Jacobcommands (which are principally used for Loop and Fabric management via
4471c374983SMatt Jacobthe isp_control function).
4481c374983SMatt Jacob
4491c374983SMatt Jacob5.8 SCSI Specifics
4501c374983SMatt Jacob
4511c374983SMatt JacobThe driver core or platform dependent architecture issues that are specific
4521c374983SMatt Jacobto SCSI are few. There is a basic assumption that the QLogic firmware
4531c374983SMatt Jacobsupported Automatic Request sense will work- there is no particular provision
4541c374983SMatt Jacobfor disabling it's usage on a per-command basis.
4551c374983SMatt Jacob
4561c374983SMatt Jacob5.9 Fibre Channel Specifics
4571c374983SMatt Jacob
4581c374983SMatt JacobFibre Channel presents an interesting challenge here. The QLogic firmware
4591c374983SMatt Jacobarchitecture for dealing with Fibre Channel as just a 'fat' SCSI bus
4601c374983SMatt Jacobis fine on the face of it, but there are some subtle and not so subtle
4611c374983SMatt Jacobproblems here.
4621c374983SMatt Jacob
4631c374983SMatt Jacob5.9.1 Firmware State
4641c374983SMatt Jacob
4651c374983SMatt JacobPart of the initialization (isp_init) for Fibre Channel HBAs involves
4661c374983SMatt Jacobsending a command (Initialize Control Block) that establishes Node
4671c374983SMatt Jacoband Port WWNs as well as topology preferences. After this occurs,
4681c374983SMatt Jacobthe QLogic firmware tries to traverese through serveral states:
4691c374983SMatt Jacob
4701c374983SMatt Jacob	FW_CONFIG_WAIT
4711c374983SMatt Jacob	FW_WAIT_AL_PA
4721c374983SMatt Jacob	FW_WAIT_LOGIN
4731c374983SMatt Jacob	FW_READY
4741c374983SMatt Jacob	FW_LOSS_OF_SYNC
4751c374983SMatt Jacob	FW_ERROR
4761c374983SMatt Jacob	FW_REINIT
4771c374983SMatt Jacob	FW_NON_PART
4781c374983SMatt Jacob
4791c374983SMatt JacobIt starts with FW_CONFIG_WAIT, attempts to get an AL_PA (if on an FC-AL
4801c374983SMatt Jacobloop instead of being connected as an N-port), waits to log into all
4811c374983SMatt JacobFC-AL loop entities and then hopefully transitions to FW_READY state.
4821c374983SMatt Jacob
4831c374983SMatt JacobClearly, no command should be attempted prior to FW_READY state is
4841c374983SMatt Jacobachieved. The core internal function isp_fclink_test (reachable via
4851c374983SMatt Jacobisp_control with the ISPCTL_FCLINK_TEST function code). This function
4861c374983SMatt Jacobalso determines connection topology (i.e., whether we're attached to a
4871c374983SMatt Jacobfabric or not).
4881c374983SMatt Jacob
4891c374983SMatt Jacob5.9.2. Loop State Transitions- From Nil to Ready
4901c374983SMatt Jacob
4911c374983SMatt JacobOnce the firmware has transitioned to a ready state, then the state of the
4921c374983SMatt Jacobconnection to either arbitrated loop or to a fabric has to be ascertained,
4931c374983SMatt Jacoband the identity of all loop members (and fabric members validated).
4941c374983SMatt Jacob
4951c374983SMatt JacobThis can be very complicated, and it isn't made easy in that the QLogic
4961c374983SMatt Jacobfirmware manages PLOGI and PRLI to devices that are on a local loop, but
4971c374983SMatt Jacobit is the driver that must manage PLOGI/PRLI with devices on the fabric.
4981c374983SMatt Jacob
4991c374983SMatt JacobIn order to manage this state an eight level staging of current "Loop"
5001c374983SMatt Jacob(where "Loop" is taken to mean FC-AL or N- or F-port connections) states
5011c374983SMatt Jacobin the following ascending order:
5021c374983SMatt Jacob
5031c374983SMatt Jacob	LOOP_NIL
5041c374983SMatt Jacob	LOOP_LIP_RCVD
5051c374983SMatt Jacob	LOOP_PDB_RCVD
5061c374983SMatt Jacob	LOOP_SCANNING_FABRIC
5071c374983SMatt Jacob	LOOP_FSCAN_DONE
5081c374983SMatt Jacob	LOOP_SCANNING_LOOP
5091c374983SMatt Jacob	LOOP_LSCAN_DONE
5101c374983SMatt Jacob	LOOP_SYNCING_PDB
5111c374983SMatt Jacob	LOOP_READY
5121c374983SMatt Jacob
5131c374983SMatt JacobWhen the core code initializes the QLogic firmware, it sets the loop
5141c374983SMatt Jacobstate to LOOP_NIL. The first 'LIP Received' asynchronous event sets state
5151c374983SMatt Jacobto LOOP_LIP_RCVD. This should be followed by a "Port Database Changed"
5161c374983SMatt Jacobasynchronous event which will set the state to LOOP_PDB_RCVD. Each of
5171c374983SMatt Jacobthese states, when entered, causes an isp_async event call to the
5181c374983SMatt Jacobmachine dependent layers with the ISPASYNC_CHANGE_NOTIFY code.
5191c374983SMatt Jacob
5201c374983SMatt JacobAfter the state of LOOP_PDB_RCVD is reached, the internal core function
5211c374983SMatt Jacobisp_scan_fabric (reachable via isp_control(..ISPCTL_SCAN_FABRIC)) will,
5221c374983SMatt Jacobif the connection is to a fabric, use Simple Name Server mailbox mediated
5231c374983SMatt Jacobcommands to dump the entire fabric contents. For each new entity, an
5241c374983SMatt Jacobisp_async event will be generated that says a Fabric device has arrived
5251c374983SMatt Jacob(ISPASYNC_FABRIC_DEV). The function that isp_async must perform in this
5261c374983SMatt Jacobstep is to insert possibly remove devices that it wants to have the
5271c374983SMatt JacobQLogic firmware log into (at LOOP_SYNCING_PDB state level)).
5281c374983SMatt Jacob
5291c374983SMatt JacobAfter this has occurred, the state LOOP_FSCAN_DONE is set, and then the
5301c374983SMatt Jacobinternal function isp_scan_loop (isp_control(...ISPCTL_SCAN_LOOP)) can
5311c374983SMatt Jacobbe called which will then scan for any local (FC-AL) entries by asking
5321c374983SMatt Jacobfor each possible local loop id the QLogic firmware for a Port Database
5331c374983SMatt Jacobentry. It's at this level some entries cached locally are purged
5341c374983SMatt Jacobor shifting loopids are managed (see section 5.9.4).
5351c374983SMatt Jacob
5361c374983SMatt JacobThe final step after this is to call the internal function isp_pdb_sync
5371c374983SMatt Jacob(isp_control(..ISPCTL_PDB_SYNC)). The purpose of this function is to
5381c374983SMatt Jacobthen perform the PLOGI/PRLI functions for fabric devices. The next state
5391c374983SMatt Jacobentered after this is LOOP_READY, which means that the driver is ready
5401c374983SMatt Jacobto process commands to send to Fibre Channel devices.
5411c374983SMatt Jacob
5421c374983SMatt Jacob5.9.3 Fibre Channel variants of Initiator Mode Code Flow
5431c374983SMatt Jacob
5441c374983SMatt JacobThe code flow in isp_start for Fibre Channel devices is the same as it is
5451c374983SMatt Jacobfor SCSI devices, but with a notable exception.
5461c374983SMatt Jacob
5471c374983SMatt JacobMaintained within the fibre channel specific portion of the driver soft
5481c374983SMatt Jacobstate structure is a distillation of the existing population of both
5491c374983SMatt Jacoblocal loop and fabric devices. Because Loop IDs can shift on a local
5501c374983SMatt Jacobloop but we wish to retain a 'constant' Target ID (see 5.9.4), this
5511c374983SMatt Jacobis indexed directly via the Target ID for the command (XS_TGT(xs)).
5521c374983SMatt Jacob
5531c374983SMatt JacobIf there is a valid entry for this Target ID, the command is started
5541c374983SMatt Jacob(with the stored 'Loop ID'). If not the command is completed with
5551c374983SMatt Jacobthe error that is just like a SCSI Selection Timeout error.
5561c374983SMatt Jacob
5571c374983SMatt JacobThis code is currently somewhat in transition. Some platforms to
5581c374983SMatt Jacobdo firmware and loop state management (as described above) at this
5591c374983SMatt Jacobpoint. Other platforms manage this from the machine dependent layers. The
5601c374983SMatt Jacobimportant function to watch in this respect is isp_fc_runstate (in
5611c374983SMatt Jacobisp_inline.h).
5621c374983SMatt Jacob
5631c374983SMatt Jacob5.9.4 "Target" in Fibre Channel is a fixed virtual construct
5641c374983SMatt Jacob
5651c374983SMatt JacobVery few systems can cope with the notion that "Target" for a disk
5661c374983SMatt Jacobdevice can change while you're using it. But one of the properties of
5671c374983SMatt Jacobfor arbitrated loop is that the physical bus address for a loop member
5681c374983SMatt Jacob(the AL_PA) can change depending on when and how things are inserted in
5691c374983SMatt Jacobthe loop.
5701c374983SMatt Jacob
5711c374983SMatt JacobTo illustrate this, let's take an example. Let's say you start with a
5721c374983SMatt Jacobloop that has 5 disks in it. At boot time, the system will likely find
5731c374983SMatt Jacobthem and see them in this order:
5741c374983SMatt Jacob
5751c374983SMatt Jacobdisk#   Loop ID         Target ID
5761c374983SMatt Jacobdisk0   0               0
5771c374983SMatt Jacobdisk1   1               1
5781c374983SMatt Jacobdisk2   2               2
5791c374983SMatt Jacobdisk3   3               3
5801c374983SMatt Jacobdisk4   4               4
5811c374983SMatt Jacob
5821c374983SMatt JacobThe driver uses 'Loop ID' when it forms requests to send a comamnd to
5831c374983SMatt Jacobeach disk. However, it reports to NetBSD that things exist as 'Target
5841c374983SMatt JacobID'. As you can see here, there is perfect correspondence between disk,
5851c374983SMatt JacobLoop ID and Target ID.
5861c374983SMatt Jacob
5871c374983SMatt JacobLet's say you add a new disk between disk2 and disk3 while things are
5881c374983SMatt Jacobrunning. You don't really often see this, but you *could* see this where
5891c374983SMatt Jacobthe loop has to renegotiate, and you end up with:
5901c374983SMatt Jacob
5911c374983SMatt Jacobdisk#   Loop ID         Target ID
5921c374983SMatt Jacobdisk0   0               0
5931c374983SMatt Jacobdisk1   1               1
5941c374983SMatt Jacobdisk2   2               2
5951c374983SMatt JacobdiskN   3               ?
5961c374983SMatt Jacobdisk3   4               ?
5971c374983SMatt Jacobdisk4   5               ?
5981c374983SMatt Jacob
5991c374983SMatt JacobClearly, you don't want disk3 and disk4's "Target ID" to change while you're
6001c374983SMatt Jacobrunning since currently mounted filesystems will get trashed.
6011c374983SMatt Jacob
6021c374983SMatt JacobWhat the driver is supposed to do (this is the function of isp_scan_loop),
6031c374983SMatt Jacobis regenerate things such that the following then occurs:
6041c374983SMatt Jacob
6051c374983SMatt Jacobdisk#   Loop ID         Target ID
6061c374983SMatt Jacobdisk0   0               0
6071c374983SMatt Jacobdisk1   1               1
6081c374983SMatt Jacobdisk2   2               2
6091c374983SMatt JacobdiskN   3               5
6101c374983SMatt Jacobdisk3   4               3
6111c374983SMatt Jacobdisk4   5               4
6121c374983SMatt Jacob
6131c374983SMatt JacobSo, "Target" is a virtual entity that is maintained while you're running.
6141c374983SMatt Jacob
6151c374983SMatt Jacob6. Glossary
6161c374983SMatt Jacob
6171c374983SMatt JacobHBA - Host Bus Adapter
6181c374983SMatt Jacob
6191c374983SMatt JacobSCSI - Small Computer
6201c374983SMatt Jacob
6211c374983SMatt Jacob7. References
6221c374983SMatt Jacob
6231c374983SMatt JacobVarious URLs of interest:
6241c374983SMatt Jacob
6251c374983SMatt Jacobhttp://www.netbsd.org		-	NetBSD's Web Page
6261c374983SMatt Jacobhttp://www.openbsd.org		-	OpenBSD's Web Page
627a2aef24aSEitan Adlerhttps://www.freebsd.org		-	FreeBSD's Web Page
6281c374983SMatt Jacob
6291c374983SMatt Jacobhttp://www.t10.org		-	ANSI SCSI Commitee's Web Page
6301c374983SMatt Jacob					(SCSI Specs)
6311c374983SMatt Jacobhttp://www.t11.org		-	NCITS Device Interface Web Page
6321c374983SMatt Jacob					(Fibre Channel Specs)
6331c374983SMatt Jacob
634