home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / scsipg.zip / OEMBASE.TXT < prev    next >
Text File  |  1993-03-07  |  38KB  |  1,149 lines
  1.  
  2. APPENDIX B.  OS/2 SCSI DEVICE DRIVER INTERFACE SPECIFICATION   . . . . .  B-1
  3. Introduction   . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  B-1
  4.  Naming Conventions  . . . . . . . . . . . . . . . . . . . . . . . . . .  B-3
  5. Generic IOCtl Request  . . . . . . . . . . . . . . . . . . . . . . . . .  B-3
  6.   OS/2 SCSI Services   . . . . . . . . . . . . . . . . . . . . . . . . .  B-4
  7.     Read Device Parameters   . . . . . . . . . . . . . . . . . . . . . .  B-4
  8.     Reset/Initialize   . . . . . . . . . . . . . . . . . . . . . . . . .  B-5
  9.     Enable Adapter Cache   . . . . . . . . . . . . . . . . . . . . . . .  B-6
  10.     Disable Adapter Cache  . . . . . . . . . . . . . . . . . . . . . . .  B-6
  11.     Return Adapter Cache Status  . . . . . . . . . . . . . . . . . . . .  B-7
  12.     Set Device Timeout   . . . . . . . . . . . . . . . . . . . . . . . .  B-7
  13.     Read Device Timeout  . . . . . . . . . . . . . . . . . . . . . . . .  B-8
  14.     Transfer SCB   . . . . . . . . . . . . . . . . . . . . . . . . . . .  B-8
  15.     Allocate Device  . . . . . . . . . . . . . . . . . . . . . . . . .   B-10
  16.     Deallocate Device  . . . . . . . . . . . . . . . . . . . . . . . .   B-11
  17.     Return Peripheral Type Count   . . . . . . . . . . . . . . . . . .   B-12
  18.     Send Abort   . . . . . . . . . . . . . . . . . . . . . . . . . . .   B-12
  19. Return Codes   . . . . . . . . . . . . . . . . . . . . . . . . . . . .   B-14
  20. Error Recovery Procedure   . . . . . . . . . . . . . . . . . . . . . .   B-16
  21. Device-Class Driver Model  . . . . . . . . . . . . . . . . . . . . . .   B-16
  22.   Overview   . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   B-16
  23.   Initialization Routine   . . . . . . . . . . . . . . . . . . . . . .   B-17
  24.   Strategy Routine   . . . . . . . . . . . . . . . . . . . . . . . . .   B-17
  25.   Interrupt Handler  . . . . . . . . . . . . . . . . . . . . . . . . .   B-17
  26.   DMA Data Structures  . . . . . . . . . . . . . . . . . . . . . . . .   B-17
  27.  
  28.  
  29.  
  30. APPENDIX B.  OS/2 SCSI DEVICE DRIVER INTERFACE SPECIFICATION
  31.  
  32.  
  33.  
  34.  
  35.  
  36. This appendix describes the high-level interface for the SCSI Device Driver
  37. for OS/2.  For completeness, all functions are listed; however, functions
  38. that are not implemented are so indicated.  This appendix is derived from the
  39. SCSI Device Driver Design Workbook by Barry Khatri and Dan Feriozi.  Some of
  40. the internal specifications of the device driver have not been included here
  41. so that this document can be externally distributed to vendors wanting to
  42. write device drivers to the SCSI device driver interface.
  43.  
  44.  
  45. INTRODUCTION
  46.  
  47. The SCSI driver is the lower half of a split model for OS/2 SCSI device
  48. drivers.  The SCSI driver drives the SCSI adapter through the SCSI ADD as
  49. shown in the following functional diagram.
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-1
  87.  
  88.  
  89.  
  90.                +-----------------------------------------------------------+
  91.                |                                                           |
  92.                |                                                           |
  93.                |                       OS/2 KERNEL                         |
  94.                |                                                           |
  95.                |                                                           |
  96.                +-----------------------------------------------------------+
  97.                       |                  |                 |
  98.                       |                  |                 |
  99.                       |                  |                 |
  100.                +--------------+ +----------------+ +--------------+
  101.                | CDROM CLASS  | |  OPTICAL CLASS | | OTHER CLASS  |  ....
  102.                |   DRIVER     | |     DRIVER     | |    DRIVER    |
  103.                +--------------+ +----------------+ +--------------+
  104.                       |                  |                 |
  105.                       |                  |                 |
  106.                +-----------------------------------------------------------+
  107.                |                                                           |
  108.                |             OS2SCSI.DMD SCSI DEVICE MANAGER               |
  109.                |                                                           |
  110.                +-----------------------------------------------------------+
  111.                                              |
  112.                                              |
  113.                                              |
  114.                +-----------------------------------------------------------+
  115.                |                         SCSI ADD                          |
  116.                +-----------------------------------------------------------+
  117.                                              |
  118.                                              |
  119.                +-----------------------------------------------------------+
  120.                |                        SCSI ADAPTER                       |
  121.                +-----------------------------------------------------------+
  122.                       |                 |                  |
  123.                       |                 |                  |
  124.                +--------------+ +----------------+ +--------------+
  125.                | CDROM SCSI   | |  OPTICAL SCSI  | | OTHER SCSI   |  ....
  126.                |    DEVICE    | |     DEVICE     | |    DEVICE    |
  127.                +--------------+ +----------------+ +--------------+
  128.  
  129.  
  130. Figure  B-1. Split Device Driver Model for OS/2
  131.  
  132. The diagram illustrates the relationship between the device drivers and their
  133. interaction with other components of the system.
  134.  
  135. The split device driver model uses the principles of code layering to
  136. facilitate development and maintenance of new SCSI device drivers.  The
  137. provision of common functions in the SCSI driver also reduces memory
  138. requirements.  Performance is enhanced because the SCSI driver centralizes
  139. control of the SCSI channel, thus reducing contention.  Only one interrupt
  140. handler is registered for all the SCSI peripheral devices.
  141.  
  142.  
  143.  
  144.  
  145.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-2
  146.  
  147.  
  148. A split device driver model has been used by IBM for all the SCSI devices
  149. except the SCSI fixed disks, which use the OS/2 DASD Manager.  The
  150. device-class driver is the upper-level driver, and the SCSI driver is the
  151. lower-level driver.  The device-class driver does not interact directly with
  152. the SCSI adapter or the SCSI device.  The device-class driver sends commands
  153. to the SCSI device manager, which in turn sends commands to the device using
  154. the IORB ADD interface.
  155.  
  156. The device-class driver looks very much like an OS/2 device driver.  It maps
  157. an OS/2 request into an SCB, or a chain of SCBs, and passes the request
  158. immediately to the SCSI driver.  The SCSI driver handles all queuing and
  159. interrupts and insulates the device-class driver from the procedural details
  160. of managing adapter hardware.  The device-class driver requests a service,
  161. like Transfer SCB, from the SCSI device manager.  When control is returned to
  162. the device-class driver, the called service is complete.  If an error
  163. occurred, the termination status block (TSB) might contain error information.
  164. In addition, sense data might have been returned.
  165.  
  166.  
  167. NAMING CONVENTIONS
  168.  
  169. o   SCSI DRIVER
  170.     The file name for the SCSI driver is OS2SCSI.DMD.  The IDC entry point
  171.     for the SCSI driver can be obtained from the ATTACHDD DevHlp function by
  172.     using the name SCSI-02$ as the device driver name parameter.
  173.  
  174. o   IBM DEVICE-CLASS DRIVERS
  175.     Current device driver names used by IBM are:
  176.  
  177.     CDROM.SYS     CD-ROM device driver
  178.     OPTICAL.SYS   Read/Write optical device driver
  179.  
  180.     NOTE:  Naming conflicts are possible, so try to choose unique names for
  181.            your device-class drivers.  In a SCSI environment, different
  182.            vendor devices for the same SCSI device class can be present in
  183.            one system.
  184.  
  185. o   MESSAGE FILES
  186.     The IBM-reserved message file name for device drivers that have been
  187.     developed internally is DEV002.MSG.  Independent vendors must not use
  188.     DEV002.MSG for their message files, because if they do, one of those
  189.     message files could be destroyed during the user installation process.
  190.     It is suggested that vendors choose a unique message file name by
  191.     embedding part of their logo or company name in the file name; that would
  192.     eliminate the possibility of having different vendor devices with the
  193.     same message file name installed in the same system.
  194.  
  195.  
  196. GENERIC IOCTL REQUEST
  197.  
  198. The input to the SCSI driver is a generic IOCtl request packet, pointed to by
  199. the ES:BX register pair.
  200.  
  201.  
  202.  
  203.  
  204.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-3
  205.  
  206.  
  207. OS/2 SCSI SERVICES
  208.  
  209. *iiiiiiiiiiiiiiiiiiiiii i1.OS/2 SCSI services i2 refid=serv.OS2SCSI i1.80H
  210. function category, OS/2 SCSI services i1.40H function code, OS/2 SCSI
  211. services i2 refid=scsi.OS/2 SCSI requests i1.Read Device Parameters i2
  212. refid=scsi.Read Device Parameters request i2 refid=func.Read Device
  213. Parameters *iiiiiiiiiiiiiiiiiiiiii
  214.  
  215. The SCSI driver supports the following requests:
  216.  
  217. o   Read Device Parameters
  218. o   Reset/Initialization
  219. o   Enable Adapter Cache
  220. o   Disable Adapter Cache
  221. o   Return Adapter Cache Status
  222. o   Set Device Timeout
  223. o   Read Device Timeout
  224. o   Transfer SCB
  225. o   Deallocate Device
  226. o   Allocate Device
  227. o   Return Peripheral Type Count
  228. o   Abort
  229.  
  230.  
  231. Read Device Parameters
  232.  
  233. This function returns some information about the device.  Of particular
  234. interest is the LUN, which is required if a Send Other command is used.
  235.  
  236. INPUT PARAMETER STRUCTURE
  237.  
  238. FIELD            LENGTH
  239. Device Handle    WORD
  240.  
  241.   FUNCTION CATEGORY : 80H
  242.   FUNCTION CODE     : 43H
  243.  
  244. This function requires a device handle to be passed in the request.  The
  245. device must be allocated by the device-class driver before calling this
  246. function.  The function category and function code are to be set up as shown
  247. above.
  248.  
  249. +---------------------------------------------------------------------------+
  250. | Table  B-1 (Page 1 of 2). Data Buffer                                     |
  251. +-----------------------------+---------------------------------------------+
  252. | FIELD NAME                  | LENGTH                                      |
  253. +-----------------------------+---------------------------------------------+
  254. | Device Key Index            | WORD                                        |
  255. +-----------------------------+---------------------------------------------+
  256. | SCB Architecture Card Comp. | BYTE                                        |
  257. | Level                       |                                             |
  258. +-----------------------------+---------------------------------------------+
  259. | Adapter Index               | BYTE                                        |
  260. +-----------------------------+---------------------------------------------+
  261.  
  262.  
  263.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-4
  264.  
  265.  
  266. +---------------------------------------------------------------------------+
  267. | Table  B-1 (Page 2 of 2). Data Buffer                                     |
  268. +-----------------------------+---------------------------------------------+
  269. | FIELD NAME                  | LENGTH                                      |
  270. +-----------------------------+---------------------------------------------+
  271. | Device Flags                | WORD                                        |
  272. +-----------------------------+---------------------------------------------+
  273. | Logical unit number (LUN)   | BYTE                                        |
  274. +-----------------------------+---------------------------------------------+
  275. | Physical unit number (LUN)  | BYTE                                        |
  276. +-----------------------------+---------------------------------------------+
  277.  
  278. Adapter Index
  279. contains the adapter number for the SCSI adapter.
  280.  
  281. Device Flags
  282.  
  283. BIT 4     0 = Adapter cache not supported.
  284.           1 = Adapter cache supported.
  285.  
  286. BIT 1     0 = Device power ON.
  287.           1 = Device power OFF.
  288.  
  289. BIT 0     0 = Device is not defective.
  290.           1 = Device is defective.
  291.  
  292.  
  293. Reset/Initialize
  294.  
  295. This function results in a reset message being issued to the physical device.
  296.  
  297. INPUT PARAMETER STRUCTURE
  298.  
  299. FIELD            LENGTH
  300. Device Handle    WORD
  301. Sense Data Size  WORD
  302.  
  303.   FUNCTION CATEGORY : 80H
  304.   FUNCTION CODE     : 45H
  305.  
  306. This function requires a device handle to be passed in the request.  The
  307. device must be allocated by the device-class driver before calling this
  308. function.  The function category and function code must be set up as shown
  309. above.
  310.  
  311. DATA BUFFER
  312.  
  313. This function does not require a data buffer.  Status is returned in the
  314. Status field of the request packet.
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-5
  323.  
  324.  
  325. Enable Adapter Cache
  326.  
  327. This function enables the adapter cache capability for all subsequent
  328. commands to this device.
  329.  
  330. INPUT PARAMETER STRUCTURE
  331.  
  332. FIELD            LENGTH
  333. Device Handle    WORD
  334.  
  335.   FUNCTION CATEGORY : 80H
  336.   FUNCTION CODE     : 4DH
  337.  
  338. This function requires a device handle to be passed in the request.  The
  339. device must be allocated by the device-class driver before calling this
  340. function.  The function category and function code must be set up as shown
  341. above.
  342.  
  343. DATA BUFFER
  344.  
  345. This function does not require a data buffer.  Status is returned in the
  346. Status field of the request packet.
  347.  
  348.  
  349. Disable Adapter Cache
  350.  
  351. This function disables the adapter cache capability for subsequent commands
  352. to the specified device.
  353.  
  354. INPUT PARAMETER STRUCTURE
  355.  
  356. FIELD            LENGTH
  357. Device Handle    WORD
  358.  
  359.   FUNCTION CATEGORY : 80H
  360.   FUNCTION CODE     : 4EH
  361.  
  362. This function requires a device handle to be passed in the request.  The
  363. device must be allocated by the device-class driver before calling this
  364. function.  The function category and function code must be set up as shown
  365. above.
  366.  
  367. DATA BUFFER
  368.  
  369. This function does not require a data buffer.  Status is returned in the
  370. Status field of the request packet.
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-6
  382.  
  383.  
  384. Return Adapter Cache Status
  385.  
  386. This function returns the adapter cache status for the specified device.
  387.  
  388. INPUT PARAMETER STRUCTURE
  389.  
  390. FIELD            LENGTH
  391. Device Handle    WORD
  392.  
  393.   FUNCTION CATEGORY : 80H
  394.   FUNCTION CODE     : 4FH
  395.  
  396. This function requires a device handle to be passed in the request.  The
  397. device must be allocated by the device-class driver before calling this
  398. function.  The function category and function code must be set up as shown
  399. above.
  400.  
  401. +---------------------------------------------------------------------------+
  402. | Table  B-2. Data Buffer                                                   |
  403. +-------------------------------------+-------------------------------------+
  404. | FIELD NAME                          | LENGTH                              |
  405. +-------------------------------------+-------------------------------------+
  406. | Adapter Cache Status                | BYTE                                |
  407. +-------------------------------------+-------------------------------------+
  408.  
  409.   Adapter Cache Status : 00H  Enabled
  410.                          01H  Disabled
  411.  
  412.  
  413. Set Device Timeout
  414.  
  415. This function sets the timeout value for this device.
  416.  
  417. INPUT PARAMETER STRUCTURE
  418.  
  419. FIELD            LENGTH
  420. Timeout Value    DWORD
  421.  
  422.   FUNCTION CATEGORY : 80H
  423.   FUNCTION CODE     : 50H
  424.  
  425. This function requires a device handle and a timeout value to be passed in
  426. the request.  The timeout value is in milliseconds.  The device must be
  427. allocated by the device-class driver before calling this function.  The
  428. function category and function code must be set up as shown above.
  429.  
  430. DATA BUFFER
  431.  
  432. This function does not require a data buffer.  Status is returned in the
  433. Status field of the request packet.
  434.  
  435.  
  436.  
  437.  
  438.  
  439.  
  440.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-7
  441.  
  442.  
  443. Read Device Timeout
  444.  
  445. This function returns the current timeout value for this device.
  446.  
  447. INPUT PARAMETER STRUCTURE
  448.  
  449. FIELD            LENGTH
  450. Device Handle    WORD
  451.  
  452.   FUNCTION CATEGORY : 80H
  453.   FUNCTION CODE     : 51H
  454.  
  455. This function requires a device handle to be passed in the request.  The
  456. device must be allocated by the device-class driver before calling this
  457. function.  The function category and function code must be set up as shown
  458. above.
  459.  
  460. +---------------------------------------------------------------------------+
  461. | Table  B-3. Data Buffer                                                   |
  462. +-----------------------------+---------------------------------------------+
  463. | FIELD NAME                  | LENGTH                                      |
  464. +-----------------------------+---------------------------------------------+
  465. | Timeout Value               | DWORD                                       |
  466. +-----------------------------+---------------------------------------------+
  467.  
  468. The timeout value is in milliseconds.
  469.  
  470.  
  471. Transfer SCB
  472.  
  473. This function causes an SCB or a chain of SCBs to be sent to the adapter.
  474.  
  475. +---------------------------------------------------------------------------+
  476. | Table  B-4. Input Parameter Structure                                     |
  477. +--------------------------------------------------------+------------------+
  478. | FIELD NAME                                             | LENGTH           |
  479. +--------------------------------------------------------+------------------+
  480. | DEVICE HANDLE                                          | WORD             |
  481. +--------------------------------------------------------+------------------+
  482. | SENSE DATA SIZE                                        | WORD             |
  483. +--------------------------------------------------------+------------------+
  484. | PHYSICAL POINTER TO SCB                                | DWORD            |
  485. +--------------------------------------------------------+------------------+
  486. | LOGICAL POINTER TO SCB CHAIN HEADER                    | DWORD            |
  487. +--------------------------------------------------------+------------------+
  488. | FLAGS                                                  | BYTE             |
  489. +--------------------------------------------------------+------------------+
  490.  
  491.   FUNCTION CATEGORY : 80H
  492.   FUNCTION CODE     : 52H
  493.  
  494. This function requires a device handle to be passed in the request.  The
  495. device must be allocated by the device-class driver before calling this
  496.  
  497.  
  498.  
  499.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-8
  500.  
  501.  
  502. function.  The function category and function code are to be set up as shown
  503. above.
  504.  
  505. Flags
  506.  
  507. Bit 0 =   0 Normal Length SCB
  508.           1 Long SCB
  509.  
  510. A normal length SCB is used to send generic SCSI commands to a device.  The
  511. long SCB is used to send a vendor-unique SCSI command embedded in the SCB.
  512.  
  513. DATA BUFFER
  514.  
  515. If an error occurs, the data buffer might contain sense data; the return code
  516. indicates whether the sense data is valid.  A termination status block also
  517. might be returned.
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.  
  537.  
  538.  
  539.  
  540.  
  541.  
  542.  
  543.  
  544.  
  545.  
  546.  
  547.  
  548.  
  549.  
  550.  
  551.  
  552.  
  553.  
  554.  
  555.  
  556.  
  557.  
  558.             Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-9
  559.  
  560.  
  561. SCB CHAIN HEADER
  562.  
  563.  
  564.           +00H  +----------------------------+
  565.                 |   Reserved                 |
  566.           +02H  |----------------------------|
  567.                 |   Logical Pointer to next  |
  568.                 |-  SCB Chain Header        -|
  569.                 |                            |
  570.           +06H  |----------------------------|
  571.                 |   Reserved                 |
  572.           +08H  |----------------------------|
  573.                 |   Reserved                 |
  574.           +0AH  |----------------------------|
  575.                 |   Logical Pointer to TSB   |
  576.                 |-                          -|
  577.                 |                            |
  578.           +0EH  |----------------------------|
  579.                 |   Reserved                 |
  580.           +10H  |----------------------------|
  581.                 |                            |
  582.                 |                            |
  583.                 |            SCB             |
  584.                 |                            |
  585.                 |        Immediately         |
  586.                 |                            |
  587.                 |           Follows          |
  588.                 |                            |
  589.                 |             the            |
  590.                 |                            |
  591.                 |            Chain           |
  592.                 |                            |
  593.                 |           Header           |
  594.                 |                            |
  595.                 |                            |
  596.                 +----------------------------+
  597.  
  598. Refer to the IBM Personal System/2 MicroChannel SCSI Adapter Technical
  599. Reference for a description of the SCB architecture.
  600.  
  601.  
  602. Allocate Device
  603.  
  604. This function allocates a SCSI peripheral device and returns the device
  605. handle that will be used to access the device.
  606.  
  607. INPUT PARAMETER STRUCTURE
  608.  
  609. FIELD                 LENGTH
  610. Device Peripheral Type        BYTE
  611. Device Type Flags     BYTE
  612. Nth Available         WORD
  613.  
  614.  
  615.  
  616.  
  617.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-10
  618.  
  619.  
  620.   FUNCTION CATEGORY : 80H
  621.   FUNCTION CODE     : 55H
  622.  
  623. This function requires a device type, device type flags, and Nth available
  624. device to be passed in the request.  The device type flags define the
  625. removable media indicator.  The most significant bit of the device type flags
  626. set indicates that the media is removable.  The Nth available is the Nth
  627. device in the device type group.  If Nth available is 0, the next available
  628. device is returned.
  629.  
  630. o   SCSI DEVICE TYPES
  631.  
  632.     Direct Access           0x00
  633.     Sequential Access       0x01
  634.     Printer                 0x02
  635.     Processor               0x03
  636.     Write Once/Read Many    0x04
  637.     CD-ROM                  0x05
  638.     Scanner                 0x06
  639.     Optical Memory          0x07
  640.     Medium Changer          0x08
  641.     Communications          0x09
  642.  
  643.  
  644. DATA BUFFER
  645.  
  646. +---------------------------------------------------------------------------+
  647. | Table  B-5. Data Buffer                                                   |
  648. +-----------------------------+---------------------------------------------+
  649. | FIELD NAME                  | LENGTH                                      |
  650. +-----------------------------+---------------------------------------------+
  651. | Device Handle               | WORD                                        |
  652. +-----------------------------+---------------------------------------------+
  653.  
  654. Device Handle
  655. Returned to the caller.
  656.  
  657.  
  658. Deallocate Device
  659.  
  660. This function deallocates the SCSI Peripheral Device assigned to this device
  661. handle.
  662.  
  663. INPUT PARAMETER STRUCTURE
  664.  
  665. FIELD            LENGTH
  666. Device Handle    WORD
  667.  
  668.   FUNCTION CATEGORY : 80H
  669.   FUNCTION CODE     : 54H
  670.  
  671. This function requires a device handle to be passed in the request.  The
  672. device must be allocated by the device-class driver before calling this
  673.  
  674.  
  675.  
  676.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-11
  677.  
  678.  
  679. function.  The function category and function code must be set up as shown
  680. above.
  681.  
  682. DATA BUFFER
  683.  
  684. This function does not require a data buffer.  Status is returned in the
  685. Status field of the request packet.
  686.  
  687.  
  688. Return Peripheral Type Count
  689.  
  690. This function returns a count of the number of devices of a particular type
  691. that are detected.
  692.  
  693. INPUT PARAMETER STRUCTURE
  694.  
  695. FIELD                 LENGTH
  696. Device Peripheral Type        BYTE
  697. Device Type Flags     BYTE
  698.  
  699.   FUNCTION CATEGORY : 80H
  700.   FUNCTION CODE     : 56H
  701.  
  702. This function requires a device type and device type flags to be passed in
  703. the request.  The device type flags define the removable media indicator.
  704. The most significant bit of the device type flags set indicates that the
  705. media is removable.  Function category and function code must be set up as
  706. shown above.
  707.  
  708. +---------------------------------------------------------------------------+
  709. | Table  B-6. Data Buffer                                                   |
  710. +-----------------------------+---------------------------------------------+
  711. | FIELD NAME                  | LENGTH                                      |
  712. +-----------------------------+---------------------------------------------+
  713. | Count of Device Type        | WORD                                        |
  714. | Requested                   |                                             |
  715. +-----------------------------+---------------------------------------------+
  716.  
  717. Count of Device Type Requested
  718. Returned when the request is completed successfully.
  719.  
  720.  
  721. Send Abort
  722.  
  723. This function causes an abort request to be sent to the device.
  724.  
  725. INPUT PARAMETER STRUCTURE
  726.  
  727. FIELD            LENGTH
  728. Device Handle    WORD
  729. Sense Data Size  WORD
  730. Reserved         DWORD
  731.  
  732.  
  733.  
  734.  
  735.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-12
  736.  
  737.  
  738.   FUNCTION CATEGORY : 80H
  739.   FUNCTION CODE     : 57H
  740.  
  741. DATA BUFFER
  742.  
  743. This function does not require a data buffer.  Status is returned in the
  744. Status field of the request packet.
  745.  
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-13
  795.  
  796.  
  797. RETURN CODES
  798.  
  799. The following tables describe the SCSI return codes.
  800.  
  801. +---------------------------------------------------------------------------+
  802. | Table  B-7. Return Code Bit Categories                                    |
  803. +------------------+--------------------------------------------------------+
  804. | BIT NUMBERS      | CATEGORY                                               |
  805. +------------------+--------------------------------------------------------+
  806. | 15               | ERROR                                                  |
  807. +------------------+--------------------------------------------------------+
  808. | 14 - 10          | RESERVED                                               |
  809. +------------------+--------------------------------------------------------+
  810. | 9                | BUSY                                                   |
  811. +------------------+--------------------------------------------------------+
  812. | 8                | DONE                                                   |
  813. +------------------+--------------------------------------------------------+
  814. | 7                | SCSI ERROR                                             |
  815. +------------------+--------------------------------------------------------+
  816. | 6 - 0            | ERROR CODE (when Bit 15 = 1)                           |
  817. +------------------+--------------------------------------------------------+
  818.  
  819. +---------------------------------------------------------------------------+
  820. | Table  B-8. Bit Descriptions                                              |
  821. +------------------+--------------------------------------------------------+
  822. | BIT              | DESCRIPTION                                            |
  823. +------------------+--------------------------------------------------------+
  824. | 07               | SCSI Driver-Specific Error                             |
  825. +------------------+--------------------------------------------------------+
  826. | 08               | Operation Complete                                     |
  827. +------------------+--------------------------------------------------------+
  828. | 15               | Request Completed with Error                           |
  829. +------------------+--------------------------------------------------------+
  830.  
  831. +---------------------------------------------------------------------------+
  832. | Table  B-9 (Page 1 of 2). SCSI Error Codes                                |
  833. +------------------+--------------------------------------------------------+
  834. | ERROR CODE       | DESCRIPTION                                            |
  835. +------------------+--------------------------------------------------------+
  836. | 00H              | Device Error (Sense Data Returned)                     |
  837. +------------------+--------------------------------------------------------+
  838. | 01H              | Timeout Error                                          |
  839. +------------------+--------------------------------------------------------+
  840. | 02H              | Unusual Wakeup Error                                   |
  841. +------------------+--------------------------------------------------------+
  842. | 03H              | DevHlp Error                                           |
  843. +------------------+--------------------------------------------------------+
  844. | 04H              | Request Block Not Available                            |
  845. +------------------+--------------------------------------------------------+
  846. | 05H              | Maximum Device Support Exceeded                        |
  847. +------------------+--------------------------------------------------------+
  848. | 06H              | Interrupt Level Not Available                          |
  849. +------------------+--------------------------------------------------------+
  850.  
  851.  
  852.  
  853.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-14
  854.  
  855.  
  856. +---------------------------------------------------------------------------+
  857. | Table  B-9 (Page 2 of 2). SCSI Error Codes                                |
  858. +------------------+--------------------------------------------------------+
  859. | ERROR CODE       | DESCRIPTION                                            |
  860. +------------------+--------------------------------------------------------+
  861. | 07H              | Device Not Available                                   |
  862. +------------------+--------------------------------------------------------+
  863. | 08H              | More IRQ Levels than Adapters                          |
  864. +------------------+--------------------------------------------------------+
  865. | 09H              | Device Busy                                            |
  866. +------------------+--------------------------------------------------------+
  867. | 0AH              | Request Sense Failed                                   |
  868. +------------------+--------------------------------------------------------+
  869. | 0BH              | Adapter Cache Not Supported                            |
  870. +------------------+--------------------------------------------------------+
  871.  
  872.  
  873.  
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883.  
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-15
  913.  
  914.  
  915. The SCSI device driver can return any of the standard OS/2 device driver
  916. return codes as well as the specific error codes listed above.
  917.  
  918. If Bit 15 is set, Bits 0 - 6 contain an error code.  If, in addition, Bit 7
  919. is set, the error code in Bits 0 - 6 is one of the SCSI device
  920. driver-specific error codes from the table.  Otherwise, it is a standard OS/2
  921. device driver error code, such as unknown_command or invalid_parameter.
  922.  
  923. The DONE bit always is set by the SCSI device driver so that a successful
  924. return code is 0100H, not 0.
  925.  
  926. At Init time, the returned status is OR'd with FF00H by the kernel.
  927.  
  928.  
  929. ERROR RECOVERY PROCEDURE
  930.  
  931. The SCSI device driver will not perform any error recovery on the SCSI
  932. adapter.  The SCSI adapter will not be allocated and, therefore, no error
  933. recovery procedure is followed.
  934.  
  935. If a Check Condition is detected, the SCSI device driver will request sense
  936. data from the device and return it to the device-specific driver if
  937. successful.  A return code of xx80H indicates that sense data has been
  938. returned.
  939.  
  940.  
  941. DEVICE-CLASS DRIVER MODEL
  942.  
  943. The device-class driver model is described briefly here to assist in the
  944. design of a device-class driver.
  945.  
  946.  
  947. OVERVIEW
  948.  
  949. The device-class driver receives OS/2 request packets from the kernel.  It is
  950. responsible for mapping the received request to a generic IOCtl request to be
  951. passed to the SCSI device driver.  When a request from the kernel results in
  952. sending a Transfer SCB command to the SCSI driver, the device-class driver
  953. allocates the SCB chain header and formats the SCB and the SCB chain header.
  954. The TSB also must be allocated.  When a request from the kernel results in
  955. multiple Transfer SCBs, the device-class driver chains the SCBs and sends
  956. only one Transfer SCB command to the SCSI driver.  This achieves better
  957. performance and guarantees that requests are processed sequentially.
  958.  
  959. The device-class driver calls the SCSI driver to send the request to the
  960. device.  The SCSI driver returns to the device-class driver after the request
  961. is completed.  When a Transfer SCB request completes with an error, the SCSI
  962. driver performs a Request Sense command to the device to obtain sense data.
  963. The sense data is passed back to the caller in the data buffer area of the
  964. generic IOCtl request packet.  The device-class driver might take some
  965. error-recovery steps at this point or return to the kernel, passing the
  966. return code from the device.
  967.  
  968.  
  969.  
  970.  
  971.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-16
  972.  
  973.  
  974. INITIALIZATION ROUTINE
  975.  
  976. This routine is called when the device-class driver is first loaded into the
  977. system.  This routine performs all initialization required for the
  978. device-class driver and the device.  At Init time, all calls to the SCSI
  979. driver are made through the DosDevIoctl interface.  Typically, initialization
  980. performs the functions in the following list:
  981.  
  982. 1.  Performs a return peripheral device count to determine the count of
  983.     devices attached.
  984. 2.  Allocates the device.
  985. 3.  Queries the device to determine whether it is supported.
  986. 4.  Sets the return code in the request block.
  987. 5.  Returns the offsets for the end of the code and data segments.
  988.  
  989.  
  990. STRATEGY ROUTINE
  991.  
  992. This routine receives requests from the kernel at task time.  It builds a
  993. generic IOCtl request packet and sends it to the SCSI driver through the IDC
  994. entry point.
  995.  
  996. The generic IOCtl request contains the following parameters:
  997.  
  998. o   FUNCTION CATEGORY
  999.     80H
  1000.  
  1001. o   FUNCTION CODE
  1002.     Represents function to be performed by the SCSI driver.
  1003.  
  1004. o   PARAMETER BUFFER ADDRESS
  1005.     Contains a pointer to the parameters required for the function to be
  1006.     performed.
  1007.  
  1008. o   DATA BUFFER ADDRESS
  1009.     Contains a pointer to the data buffer where returned data is stored.
  1010.  
  1011.  
  1012. INTERRUPT HANDLER
  1013.  
  1014. An interrupt handler is not required for the device-class driver.  All
  1015. interrupts from the SCSI peripheral devices are handled by the SCSI driver.
  1016.  
  1017.  
  1018. DMA DATA STRUCTURES
  1019.  
  1020. All data structures that will be accessed by the DMA must be locked into
  1021. memory before calling SCSI.SYS.  These data structures include the following:
  1022.  
  1023. o   SCB chain header and SCBs
  1024. o   Scatter/gather list
  1025. o   Scatter/gather data areas
  1026. o   TSB
  1027. o   Sense data area
  1028.  
  1029.  
  1030.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-17
  1031.  
  1032.  
  1033. o   User data areas.
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.  
  1071.  
  1072.  
  1073.  
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  
  1085.  
  1086.  
  1087.  
  1088.  
  1089.            Appendix B.  OS/2 SCSI Device Driver Interface Specification  B-18
  1090.  
  1091.  
  1092. BIBLIOGRAPHY
  1093.  
  1094.  
  1095.  
  1096.  
  1097.  
  1098. For more information, refer to one        IBM Personal System/2(*) and
  1099. or more of these related                  Personal Computer BIOS Technical
  1100. publications.                             Reference Supplement.  Publication
  1101.                                           number S15F-2161.
  1102.  
  1103. IBM PUBLICATIONS                          IBM Personal System/2(*) and
  1104.                                           MicroChannel SCSI Adapter with Cache
  1105. OS/2 2.0 Technical Library, Physical      Technical Reference.   Publication
  1106. Device Driver Reference.                  number S68X-2365.
  1107. Publication number 10G6266.
  1108.                                           OS/2 SCSI Device Driver Interface
  1109. This book defines the interface           Specification.  Revision level 1.31,
  1110. between the OS/2 2.0 kernel and an        dated March 22, 1991.  Issued by
  1111. installable device driver.  It            D.T. Feriozi and R.B. Tegart,
  1112. includes much useful information,         Department 6G9, IBM Boca Raton.
  1113. including full specifications for
  1114. the OS/2 2.0 device helper (DevHlp)       Defines the client programming
  1115. services.                                 interfaces to SCSI.SYS and
  1116.                                           OS2SCSI.SYS.
  1117. IBM Personal System/2(*) and
  1118. Personal Computer BIOS Technical
  1119. Reference.  Publication number            STANDARDS PUBLICATIONS
  1120. S68X-2341.
  1121.                                           Small Computer Systems Interface - 2
  1122. You also will want to refer to the        (SCSI-2) X3T9/89-042.  Revision 10g.
  1123. following supplement, which provides      Dated September 1, 1991.
  1124. a programming specification for
  1125. ABIOS SCB Transfer.                       American National Standards
  1126.                                           Institute draft proposal for SCSI-2.
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.  
  1144.  
  1145.  
  1146.  
  1147.  
  1148.                                                             Bibliography  X-8
  1149.