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