![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to README.rtf CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [NeXTSTEP 3.3 examples] / Examples / DriverKit / AMDPCSCSIDriver|
Return to README.rtf CVS log | Up to [NeXTSTEP 3.3 examples] / Examples / DriverKit / AMDPCSCSIDriver |
1.1 ! root 1: {\rtf0\ansi{\fonttbl\f2\fmodern Courier;\f1\fmodern Ohlfs;} ! 2: \paperw13040 ! 3: \paperh8220 ! 4: \margl20 ! 5: \margr120 ! 6: {\colortbl;\red0\green0\blue0;} ! 7: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\f2\b\i0\ulnone\fs28\fc1\cf1 AMD 53C974/79C974 SCSI Driver Design Notes\ ! 8: ! 9: \f1\b0\fs24\fc0\cf0 \ ! 10: \ ! 11: ! 12: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\f2\b\fs28\fc0\cf0 1. General\ ! 13: ! 14: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 \ ! 15: ! 16: \f1\b0\fs24\li720\fc1\cf1 This driver is primarily intended to be used with the AMD 79C974 PCnet-SCSI combo chip, which combines an Ethernet Controller, a SCSI Host Adapter, and a PCI Bus Interface module on one chip. This driver only controls the SCSI logic on the 79C974; a separate driver is used for the Ethernet logic. The driver also should work with the AMD 53C974, a subset of the 79C974. (This has not been tested as of 25 Jan, 1995.) The 53C974 is, in turn, a superset of the old NCR 53C90A chip, which was the SCSI controller used on all NeXT ("Black") hardware.\ ! 17: \ ! 18: This driver implements the following features:\ ! 19: \ ! 20: � Disconnect/Reselect\ ! 21: � 10 MB/s "Fast SCSI" Synchronous Transfers\ ! 22: � SCSI-2 Command Queueing \ ! 23: � Auto Request Sense\ ! 24: \ ! 25: Synchronous Mode, Command Queueing, and Fast SCSI can be disabled and enabled for the driver as a whole via the driver instance's Instance table. There is a Custom Device Inspector used by the Configure App which allows the user to specify these parameters. Per-target disable flags for Command Queueing and Synchronous Mode are also kept for both of the features, so that if a target rejects an attempt to use the mode (typically via a "Message Reject" message), no further attempts will be made to use the feature with that target. Synchronous Transfer offset and period are also negotiated and kept on a per-target basis, per the SCSI-2 specification. \ ! 26: \ ! 27: \ ! 28: ! 29: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\f2\b\fs28\fc0\cf0 2. Architecture\ ! 30: ! 31: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 \ ! 32: ! 33: \f1\b0\fs24\li720\fc1\cf1 Unlike most other SCSI Host Adapter drivers for the Intel Platform, this driver is involved in a lot of low-level SCSI events, including dealing with phase changes, setting ATN at appropriate times, doing synchronous transfer negotiation, etc. The driver has to maintain quite a bit of state to keep track of what is occurring on the bus and typically responds to 3 or 4 interrupts for every SCSI command.\ ! 34: \ ! 35: The driver is implemented as a subclass of ! 36: \f2\b\fs28 IOSCSIController ! 37: \f1\b0\fs24 called ! 38: \f2\b\fs28 AMD_SCSI ! 39: \f1\b0\fs24 . ! 40: \f2\b\fs28 IOSCSIController ! 41: \f1\b0\fs24 is a subclass of ! 42: \f2\b\fs28 IODirectDevice ! 43: \f1\b0\fs24 . The ! 44: \f2\b\fs28 IODirectDevice ! 45: \f1\b0\fs24 categories ! 46: \f2\b\fs28 IOEISADirectDevice ! 47: \f1\b0\fs24 and ! 48: \f2\b\fs28 IOPCIDirectDevice ! 49: \f1\b0\fs24 are also used by ! 50: \f2\b\fs28 AMD_SCSI ! 51: \f1\b0\fs24 .\ ! 52: \ ! 53: \ ! 54: ! 55: \f2\b\fs28\fc0\cf0 Control Flow and the I/O thread\ ! 56: ! 57: \f1\b0\fs24\fc1\cf1 \ ! 58: The control flow in the driver is the same as for all other NextStep SCSI drivers - all access to the hardware is done by one thread, the I/O thread. This eliminates the need for locks around accesses to the hardware and other critical resources. All communication with the I/O thread by exported methods is performed by passing a command struct, called a ! 59: \f2\b\fs28 commandBuf ! 60: \f1\b0\fs24 , to the I/O thread via the instance variable ! 61: \f2\b\fs28 commandQ ! 62: \f1\b0\fs24 . ! 63: \f2\b\fs28 CommandQ ! 64: \f1\b0\fs24 is protected by ! 65: \f2\b\fs28 commandLock ! 66: \f1\b0\fs24 . After enqueueing a ! 67: \f2\b\fs28 commandBuf ! 68: \f1\b0\fs24 on ! 69: \f2\b\fs28 commandQ ! 70: \f1\b0\fs24 , a message with a ! 71: \f2\b\fs28 msg_id ! 72: \f1\b0\fs24 of ! 73: \f2\b\fs28 IO_COMMAND_MSG ! 74: \f1\b0\fs24 is sent to the driver's interrupt port. The I/O thread is the only code which does a ! 75: \f2\b\fs28 msg_receive() ! 76: \f1\b0\fs24 on the interrupt port. Subsequent to initialization, ! 77: \f2\b\fs28 commandQ ! 78: \f1\b0\fs24 and ! 79: \f2\b\fs28 commandLock ! 80: \f1\b0\fs24 are the only data shared by exported methods and the I/O thread.\ ! 81: \ ! 82: I/O complete notification is performed via ! 83: \f2\b\fs28 commandBuf.cmdLock ! 84: \f1\b0\fs24 , which is an ! 85: \f2\b\fs28 NXConditionLock ! 86: \f1\b0\fs24 . Exported methods wait on this lock after passing a ! 87: \f2\b\fs28 commandBuf ! 88: \f1\b0\fs24 to the I/O thread. \ ! 89: \ ! 90: Subsequent to initialization, the only methods in the driver which do ! 91: \f2\b\i\fs28 not ! 92: \f1\b0\i0\fs24 run solely as part of the I/O thread are:\ ! 93: \ ! 94: ! 95: \f2\b\fs28 -executeRequest:buffer:client:\ ! 96: -resetSCSIBus\ ! 97: -resetStats\ ! 98: -numQueueSamples\ ! 99: -sumQueueLengths\ ! 100: -maxQueueLength\ ! 101: -executeCmdBuf\ ! 102: ! 103: \f1\b0\fs24 \ ! 104: These are all found in ! 105: \f2\b\fs28 AMD_SCSI.m ! 106: \f1\b0\fs24 . (Note: unless otherwise indicated, all files referred to in this document reside in the AMD53C974SCSIDriver_reloc.tproj directory of the driver project.) The first two methods are exported methods used for normal SCSI I/O and are called by indirect SCSI devices like SCSIDisk and SCSITape. The next four are associated with gathering statistics and are called from IOSCSIController. The last one, ! 107: \f2\b\fs28 -executeCmdBuf ! 108: \f1\b0\fs24 , is the common means by which ! 109: \f2\b\fs28 -executeRequest:buffer:client: ! 110: \f1\b0\fs24 and ! 111: \f2\b\fs28 -resetSCSIBus ! 112: \f1\b0\fs24 pass ! 113: \f2\b\fs28 commandBuf ! 114: \f1\b0\fs24 s to the I/O thread and wait for completion.\ ! 115: \ ! 116: \ ! 117: ! 118: \f2\b\fs28\fc0\cf0 Processing of commands by the I/O thread\ ! 119: \ ! 120: ! 121: \f1\b0\fs24\fc1\cf1 The I/O thread's job is basically to dequeue commands from ! 122: \f2\b\fs28 commandQ ! 123: \f1\b0\fs24 , start up SCSI transactions on the 79C974, and deal with interrupts. All of the ! 124: \f2\b\fs28 msg_receive() ! 125: \f1\b0\fs24 s which fetch command requests and interrupt events from the driver's interrupt port are done by ! 126: \f2\b\fs28 IODirectDevice ! 127: \f1\b0\fs24 's I/O Thread. If a command message is received, ! 128: \f2\b\fs28 IODirectDevice ! 129: \f1\b0\fs24 calls ! 130: \f2\b\fs28 -commandRequestOccurred ! 131: \f1\b0\fs24 . If an interrupt message is received, ! 132: \f2\b\fs28 -interruptOccurred ! 133: \f1\b0\fs24 is called. Both of these methods are implemented by the ! 134: \f2\b\fs28 AMD_SCSI ! 135: \f1\b0\fs24 class. \ ! 136: \ ! 137: When an exported method passes a ! 138: \f2\b\fs28 commandBuf ! 139: \f1\b0\fs24 to the I/O thread, it is quite possible that the I/O thread can not immediately process the command due to the fact that there is already a command active on the SCSI bus at that time. If this occurs, the incoming command is enqueued on ! 140: \f2\b\fs28 pendingQ ! 141: \f1\b0\fs24 . (Note that the decision as to whether a command can be processed, and the act of enqueueing a command on ! 142: \f2\b\fs28 pendingQ ! 143: \f1\b0\fs24 , are solely the responsibility of the I/O thread. There are no races or deadlock conditions here.) Whenever the I/O thread detects a "Bus Free" condition, it will look at ! 144: \f2\b\fs28 pendingQ ! 145: \f1\b0\fs24 , and if the queue is non-empty, the first ! 146: \f2\b\fs28 commandBuf ! 147: \f1\b0\fs24 in the queue is dequeued and used to start up a new SCSI transaction. \ ! 148: \ ! 149: The ! 150: \f2\b\fs28 commandBuf ! 151: \f1\b0\fs24 associated with the currently active SCSI transaction is always kept in ! 152: \f2\b\fs28 activeCmd ! 153: \f1\b0\fs24 . If ! 154: \f2\b\fs28 activeCmd ! 155: \f1\b0\fs24 is NULL, the SCSI bus is either free, or there is a reselection in progress for which we do not have complete target/LUN/queue tag information. \ ! 156: \ ! 157: When an active SCSI target disconnects (as opposed to doing a "Command Complete"), the I/O thread places the associated ! 158: \f2\b\fs28 commandBuf ! 159: \f1\b0\fs24 on ! 160: \f2\b\fs28 disconnectQ ! 161: \f1\b0\fs24 . Whenever a reselection occurs, ! 162: \f2\b\fs28 disconnectQ ! 163: \f1\b0\fs24 is scanned for a commandBuf which matches the reselecting target, LUN, and (possibly) queue tag. If a match is found, the ! 164: \f2\b\fs28 commandBuf ! 165: \f1\b0\fs24 is dequeued from ! 166: \f2\b\fs28 disconnectQ ! 167: \f1\b0\fs24 and becomes ! 168: \f2\b\fs28 activeCmd ! 169: \f1\b0\fs24 .\ ! 170: \ ! 171: The driver contains logic to prevent sending a command to a target/LUN nexus which currently has an active, but disconnected, command - unless command queueing is enabled for the driver, and is not disabled for the given target. This allows higher layers in the system (e.g., SCSIDisk) to enqueue multiple requests for one target and LUN without worrying about the nexus's current state. This logic uses the array ! 172: \f2\b\fs28 activeArray[][] ! 173: \f1\b0\fs24 , which is an array of counters which keep track of how many I/Os are active on a per-LUN basis. When command queueing is disabled (either globally, or on a per-target basis), an ! 174: \f2\b\fs28 activeArray ! 175: \f1\b0\fs24 counter has a maximum value of 1. If command queueing is enabled, an ! 176: \f2\b\fs28 activeArray ! 177: \f1\b0\fs24 counter has a maximum value of the target's queue length (if known). See the ! 178: \f2\b\fs28 -cmdBufOk: ! 179: \f1\b0\fs24 method, in AMD_SCSI.m, for the implementation of the decision as to whether a target/lun nexus is ready to accept a new command.\ ! 180: \ ! 181: \ ! 182: ! 183: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\f2\b\fs28\fc0\cf0 3. Organization\ ! 184: ! 185: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 \ ! 186: ! 187: \f1\b0\fs24\li720\fc1\cf1 The driver was organized to facilitate porting to other platforms using chips similar to the 79C974, and also to other "dumb" host adapter chips on the x86 platform. With some exceptions, all of the logic which is independent of either the chip or the host bus is contained in ! 188: \f2\b\fs28 AMD_SCSI.m ! 189: \f1\b0\fs24 . All of the logic which deals directly with the 79C974 is contained in ! 190: \f2\b\fs28 AMD_Chip.m ! 191: \f1\b0\fs24 and ! 192: \f2\b\fs28 AMD_ChipPrivate.m. ! 193: \f1\b0\fs24 All of the logic which is specific to the x86 architecture and the PCI bus is contained in ! 194: \f2\b\fs28 AMD_x86.m ! 195: \f1\b0\fs24 . The API to ! 196: \f2\b\fs28 AMD_Chip.m ! 197: \f1\b0\fs24 which is public to the other parts of the driver consists of six methods:\ ! 198: \ ! 199: � ! 200: \f2\b\fs28 -probeChip ! 201: \f1\b0\fs24 , performs one-time-only initialization.\ ! 202: � ! 203: \f2\b\fs28 -hwReset ! 204: \f1\b0\fs24 , reusable chip reset/init.\ ! 205: � ! 206: \f2\b\fs28 -scsiReset ! 207: \f1\b0\fs24 , performs SCSI reset.\ ! 208: � ! 209: \f2\b\fs28 -hwStart: ! 210: \f1\b0\fs24 , starts up a new SCSI transaction.\ ! 211: � ! 212: \f2\b\fs28 -hwInterrupt ! 213: \f1\b0\fs24 , deals with an interrupt event.\ ! 214: � ! 215: \f2\b\fs28 -logRegs ! 216: \f1\b0\fs24 , a debugging function to dump registers to the console.\ ! 217: ! 218: \f2\b\fs28\fc0\cf0 \ ! 219: ! 220: \f1\b0\fs24\fc1\cf1 When porting this driver to a new chip, these six methods are pretty much all that need to be re-implemented (in addition to any private, implementation-specific methods needed for the new chip). \ ! 221: \ ! 222: The design goal of separating out the chip-specific, architecture-specific, and hardware-independent functionality into separate modules was not religiously adhered to. Sometimes, for example in the routines to handle DMA in ! 223: \f2\b\fs28 AMD_x86.m ! 224: \f1\b0\fs24 , there is a mixture of chip- and bus-specific functions in one file (or even one method). The tradeoff between design clarity and portability went towards design clarity in these cases.\ ! 225: \ ! 226: \ ! 227: ! 228: \pard\tx720\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\f2\b\fs28\fc0\cf0 4. File contents\ ! 229: ! 230: \pard\tx1140\tx2300\tx3440\tx4600\tx5760\tx6900\tx8060\tx9200\tx10360\tx11520\fc0\cf0 \ ! 231: ! 232: \f1\b0\fs24\li720\fc1\cf1 The following files all exist in the AMD53C974SCSIDriver_reloc.tproj directory. (AMD53C974SCSIDriver_reloc is the driver's loadable binary.)\ ! 233: \ ! 234: \ ! 235: AMD_SCSI.h\ ! 236: \ ! 237: ! 238: \fi-20\li1160 Exported interface to the driver. Typically used by SCSI indirect drivers like SCSIDisk and SCSITape.\ ! 239: \ ! 240: ! 241: \fi0\li720 AMD_Private.h\ ! 242: ! 243: \li0 \ ! 244: ! 245: \fi-20\li1160 Private hardware-independent methods.\ ! 246: \ ! 247: ! 248: \fi0\li720 AMD_Types.h\ ! 249: ! 250: \li0 \ ! 251: ! 252: \fi-20\li1160 Private structs and #defines used by the entire driver. \ ! 253: \ ! 254: ! 255: \fi0\li720 AMD_SCSI.m\ ! 256: ! 257: \li0 \ ! 258: ! 259: \fi-20\li1160 Implementation of AMD_SCSI.h and AMD_Private.h methods.\ ! 260: \ ! 261: ! 262: \fi0\li720 AMD_x86.[hm]\ ! 263: ! 264: \li0 \ ! 265: ! 266: \fi-20\li1160 Methods specific to Intel platform and PCI bus.\ ! 267: \ ! 268: ! 269: \fi0\li720 AMD_Chip.[hm]\ ! 270: ! 271: \li0 \ ! 272: ! 273: \fi-20\li1160 Chip-specific methods available to the rest of the driver.\ ! 274: \ ! 275: ! 276: \fi0\li720 AMD_ChipPrivate.m\ ! 277: ! 278: \li0 \ ! 279: ! 280: \fi-20\li1160 Chip-specific methods available only to AMD_Chip.m.\ ! 281: \ ! 282: ! 283: \fi0\li720 AMD_Regs.h\ ! 284: ! 285: \li0 \ ! 286: ! 287: \fi-20\li1160 Definitions of AMD 79C974 registers.\ ! 288: \ ! 289: ! 290: \fi0\li720 bringup.h\ ! 291: ! 292: \li0 \ ! 293: ! 294: \fi-20\li1160 Debugging and bringup flags.\ ! 295: \ ! 296: ! 297: \fi0\li720 AMD_ddm.h\ ! 298: ! 299: \li0 \ ! 300: ! 301: \fi-20\li1160 #defines used for DDM calls.\ ! 302: \ ! 303: ! 304: \fi0\li720 AMD.ddm\ ! 305: ! 306: \li0 \ ! 307: ! 308: \fi-20\li1160 Config file used by DDMViewer.\ ! 309: \ ! 310: ! 311: \fi0\li720 ioPorts.[ch]\ ! 312: ! 313: \li0 \ ! 314: ! 315: \fi-20\li1160 A DEBUG version of <driverkit/i386/ioPorts.h>.\ ! 316: \ ! 317: ! 318: \fi0\li720 pciConf.h\ ! 319: ! 320: \li0 \ ! 321: ! 322: \fi-20\li1160 #defines for PCI configuration registers.\ ! 323: \ ! 324: ! 325: \fi0\li720 configKeys.h\ ! 326: ! 327: \li0 \ ! 328: ! 329: \fi-20\li1160 String definition for keys in driver's config table.\ ! 330: \ ! 331: ! 332: \fi0\li720 Makefile.driver_preamble \ ! 333: Makefile.preamble\ ! 334: Makefile.postamble\ ! 335: ! 336: \li0 \ ! 337: ! 338: \fi-20\li1160 Standard Makefile additions, common to all drivers.\ ! 339: \ ! 340: \ ! 341: ! 342: \f2\b\fs28\fi0\li720 Other Files ! 343: \f1\b0\fs24 \ ! 344: \ ! 345: Here is a brief description of the other files residing in the driver project's root directory. \ ! 346: \ ! 347: \ ! 348: SCSIInspector.[mh]\ ! 349: \ ! 350: ! 351: \fi-20\li1160 Custom Device Inspector for use in the Configure App.\ ! 352: \ ! 353: ! 354: \fi0\li720 Default.table \ ! 355: \ ! 356: ! 357: \fi-20\li1160 Template used by Configure App for creating Instance tables.\ ! 358: \ ! 359: ! 360: \fi0\li720 English.lproj/AMDInspector.nib\ ! 361: \ ! 362: ! 363: \fi-20\li1160 Localizable nib file for Custom Device Inspector. \ ! 364: ! 365: \fi0\li720 \ ! 366: English.lproj/Localizable.strings\ ! 367: \ ! 368: ! 369: \fi-20\li1160 Localizable strings file used by Configure App.\ ! 370: ! 371: \fi0\li720 \ ! 372: English.lproj/DriverHelp/*\ ! 373: \ ! 374: Support for on-line help in the Configure App. \ ! 375: \ ! 376: Makefile \ ! 377: PB.project \ ! 378: \ ! 379: ! 380: \fi-20\li1160 Created by Project Builder.\ ! 381: ! 382: \fi0\li720 \ ! 383: SGS_ENV\ ! 384: \ ! 385: ! 386: \fi-20\li1160 For NeXT internal use.\ ! 387: \ ! 388: ! 389: \fi0\li720 Makefile.postamble\ ! 390: Makefile.preamble\ ! 391: \ ! 392: ! 393: \fi-20\li1160 Standard Makefile additions, common to all drivers.\ ! 394: ! 395: \fi0\li720 \ ! 396: changes\ ! 397: \ ! 398: ! 399: \fi-20\li1160 Revision history of this project.\ ! 400: \ ! 401: ! 402: \fi0\li720 README.rtf\ ! 403: \ ! 404: ! 405: \fi-20\li1160 This file.\ ! 406: ! 407: }
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.