home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / rmfiles.zip / RMCALLS.txt < prev   
Text File  |  1994-10-20  |  103KB  |  3,331 lines
  1.  
  2. Overview
  3. --------
  4.  
  5. RESOURCE.SYS provides a set of C-callable services to other
  6. device drivers to record usage of basic hardware resources
  7. as well as to provide end users with physical and logical
  8. 'views' of their system.
  9.  
  10. Resources
  11. ---------
  12.  
  13. Hardware resources usage tracked by RESOURCE.SYS include:
  14.  
  15.   - I/O Port Ranges
  16.   - IRQ Levels
  17.   - DMA Channels
  18.   - Timer Channels
  19.  
  20. When resources are assigned, various levels of 'sharing'
  21. are allowed. The type of sharing allowed depends on
  22. the underlying characteristics of the devices including.
  23. Resource sharing options include EXCLUSIVE, SHARED,
  24. and MULTIPLEXED. The definition of these options are
  25. discussed in the section on "Managing System Resources".
  26.  
  27. Port Probing / Adapter Identification
  28. -------------------------------------
  29.  
  30. Driver writers are encouraged to identify their hardware settings
  31. during driver initialization directly rather than relying on the
  32. end-user to provide this information.
  33.  
  34. The Resource Manager APIs facilitate this process by identifying
  35. resources (I/O Ports, DMA Channels, IRQ Levels) that are already
  36. claimed by drivers that initialized previously. A driver using
  37. the resource management calls can avoid inadvertently corrupting
  38. the state adapters of initialized by previously loaded drivers.
  39.  
  40. Adapters/Drivers/Devices
  41. ------------------------
  42.  
  43. In addition to basic hardware resources, the RESOURCE.SYS driver
  44. manages the following constructs:
  45.  
  46.    Drivers
  47.    -------
  48.    A driver usually represents a software module responsible
  49.    for management of one or more pieces of physical hardware.
  50.  
  51.    In addition, drivers include value-added subsystems
  52.    that may not interact with physical hardware
  53.    directly.
  54.  
  55.    Note: In order to use other Resource Manager APIs, it is necessary
  56.          to provide a Driver Handle, which is obtained when declaring
  57.          a driver.
  58.  
  59.    Adapters
  60.    --------
  61.    Adapters are defined as devices which convert from one bus protocol
  62.    to another.
  63.  
  64.    For example, a SCSI adapter, converts the host bus protocol, (ISA
  65.    EISA, PCI) to SCSI Bus protocols.
  66.  
  67.    The system bus itself (ISA, EISA, PCI) is represented
  68.    in the Resource Manager as an adapter, converting from the
  69.    CPU internal bus protocols, to a standard host bus protocol.
  70.  
  71.    In some cases, adapters may not directly correspond
  72.    to physical packaging. An example of this could be a CD-ROM
  73.    port on a multifunction sound board being represented as
  74.    a separate adapter. However, it is generally encouraged to try
  75.    to 'align' adapters with the physical packaging of the system
  76.    help end-users to identify their hardware easily.
  77.  
  78.  
  79.    Devices
  80.    -------
  81.    Devices are defined in their 'traditional' meaning of end-user
  82.    devices. This includes, printers, disks, cdroms, etc.
  83.  
  84.  
  85. Adapter/Device Ownership
  86. ------------------------
  87.  
  88. Adapters, and Devices are associated with each other in a
  89. Parent-Child-Sibling relationship. A driver is associated with
  90. each Adapter or Device node.
  91.  
  92. The Resource Manager automatically creates Adapters, and Devices
  93. representing basic system resources such as the CPU and system
  94. busses during its initialization.
  95.  
  96. In addition devices managed directly by the OS/2 Kernel such as
  97. the Interrupt controller (PIC) and DMA Channels
  98. are automatically defined.
  99.  
  100.  
  101.  
  102.                           System Root
  103.  
  104.                               │
  105.                               │
  106.                               V
  107.  
  108.                             CPU_0
  109.  
  110.                               │
  111.              ┌────────────────┼───────────────┐
  112.              │                │               │
  113.              V                V               V
  114.  
  115.            X_BUS           ISA_BUS         PCI_BUS
  116.  
  117.              │
  118.              V
  119.  
  120.    ┌─────────┬─────────┬─────────────┬─────────────┬────────┐
  121.    │         │         │             │             │        │
  122.    V         V         V             V             V        V
  123.  
  124.  PIC_0     PIC_1     DMA_0         DMA_1          RTC      VGA
  125.  
  126.  │         │         │             │
  127.  ├ IRQ_0   ├ IRQ_8   ├ DMA_CH_0    ├ DMA_CH_4
  128.  ├ IRQ_1   ├ IRQ_9   ├ DMA_CH_1    ├ DMA_CH_5
  129.  │         ├ IRQ_10  │             ├ DMA_CH_6
  130.  ├ IRQ_3   ├ IRQ_11  └ DMA_CH_3    └ DMA_CH_7
  131.  ├ IRQ_4   ├ IRQ_12
  132.  ├ IRQ_5   ├ IRQ_13
  133.  ├ IRQ_6   ├ IRQ_14
  134.  └ IRQ_7   └ IRQ_15
  135.  
  136.  
  137.  
  138. As device drivers initialize, additional Adapter and Device nodes
  139. are created by the device drivers issuing Resource Manager API calls.
  140.  
  141.                           System Root
  142.  
  143.                               │
  144.                               │
  145.                               V
  146.  
  147.                             CPU_0
  148.  
  149.                               │
  150.              ┌────────────────┼───────────────┐
  151.              │                │               │
  152.              V                V               V
  153.  
  154.            X_BUS           ISA_BUS         PCI_BUS
  155.  
  156.              │
  157.              └──────────┐
  158.                         │
  159.                         │
  160.                         V
  161.      ┌──────────────────┬──────────────────────┐
  162.      │                  │                      │
  163.      V                  V                      V
  164.  
  165.    KBD_0              IDE_0                   DKT_0
  166.  
  167.     │ IBMKBD.SYS        │ IBM1S506.ADD        │ IBM1FLPY.ADD
  168.     │ ----------        │ ------------        │ ------------
  169.     │ I/O 60-64         │ I/O 1F0-1F7, 3F6    │ I/O 3F2-3F5, 3F7
  170.     │ IRQ 8             │ IRQ 14              │ IRQ 6
  171.     V                   V                     V
  172.  
  173.   KEYB_101            DISK_0                DSKT_0
  174.  
  175.  
  176. Each node has associated resources owned by the
  177. underlying device or adapter and the software driver responsible for
  178. managing the adapter or device.
  179.  
  180. Device/Adapter Keys
  181. -------------------
  182.  
  183. Each Adapter/Device node contains text describing the adapter or device.
  184.  
  185. To facilitate searching for a particular node, the beginning characters
  186. of the descriptive text are assumed to be a key.
  187.  
  188. Keys are subject to the following rules:
  189.  
  190. 1.) Any sibling nodes, i.e. nodes connected to the same parent
  191.     must have unique keys.
  192.  
  193. 2.) Keys end at either the first blank character or the 16th
  194.     consecutive non-blank character.
  195.  
  196. 3.) Keys are part of the descriptive text and must consist of
  197.     printable ascii characters.
  198.  
  199. It is recommended that adapter nodes be given unique keys based
  200. on their product name or function:
  201.  
  202. For example:
  203.  
  204.     CPU_0     - CPU x486
  205.  
  206.     IDE_0     - Generic IDE Channel Adapter
  207.  
  208.     AHA154X_0 - Adaptec 154X SCSI Adapter
  209.     AHA154X_1
  210.  
  211.     PAS16     - ProAudio Spectrum Audio Adapter
  212.  
  213. If multiple occurrences of the same type of adapter can occur,
  214. keys myst be made unique by appending a _0, _1, ..., suffix
  215. to the key.
  216.  
  217. Note: The the Resource APIs can automatically generate the _0,
  218.       _1, based on the adapter number supplied. Refer to
  219.       the RMCreateAdapter API description for further information.
  220.  
  221. It is recommended that device nodes follow the naming convention
  222. provided below:
  223.  
  224.     COMM_0        - Serial Port
  225.     DISK_0        - DASD Device
  226.     CDROM_0       - CDROM Device
  227.     TAPE_0        - Tape Device
  228.     PRINTER_0     - Printer Device
  229.     SCANNER_0     - Scanner Device
  230.  
  231. Note: The the Resource APIs can automatically generate the _0,
  232.       _1, based on the device number supplied. This is done
  233.       by including a "#" character at the end of the key. The
  234.       RMCreateAdapter/RMCreateDevice APIs will replace the "#"
  235.       character with the adapter or device number indicated.
  236.  
  237.       For example
  238.  
  239.       "DSKT_#  - 1.44MB diskette drive"
  240.  
  241.       Will be converted to:
  242.  
  243.       "DSKT_0  - 1.44 MB diskette drive"
  244.  
  245.       Provided the an adjunct structure containing the device
  246.       number (ADJ_DEVICE_NUMBER) is passed on the RMCreateDevice
  247.       API call. Adjunct data structures are discussed in the next
  248.       section.
  249.  
  250. Keys for SCSI devices should use the above device types followed
  251. by _(t,l) corresponding to the SCSI device Target/Lun.
  252.  
  253. For example:
  254.  
  255.  
  256.     DISK_(0,0)
  257.     CDROM_(3,0)
  258.  
  259.  
  260. Note: RMParseSCSIInquiry will automatically generate
  261.       appropriate keys for SCSI devices. An adjunct structure
  262.       containing the device target/lun (ADJ_SCSI_TARGET_LUN)
  263.       should be passed on the RMCreateDevice API call.
  264.  
  265. Adjunct Data
  266. ------------
  267.  
  268. In some cases, it is necessary to pass data to the Resource
  269. Manager APIs that may be relevant, in one case but not in another
  270. call to the same API. In these cases, this optional data is passed
  271. in a linked list of structures called an AdjunctList.
  272.  
  273. The contents of the structures are determined by the adjuct type.
  274. which are defined in RMBASE.H. A few of the more common adjunct
  275. types are listed here.
  276.  
  277.  
  278.     ADJ_DEVICE_NUMBER -   Contains the zero-based unit number for the
  279.                           device being created. The Resource Manager
  280.                           will use this number to enumerate the
  281.                           key for the device.
  282.  
  283.  
  284.     ADJ_ADAPTER_NUMBER -  Contains the zero-based adapter number for
  285.                           the adapter being created. The Resource Manager
  286.                           will use this number to enumerate the key
  287.                           for the adapter.
  288.  
  289.     ADJ_SCSI_TARGET_LUN - Contains the SCSI target/lun for the device
  290.                           being created. The Resource Manager will generate
  291.                           a SCSI type enumeration suffix as described
  292.                           above.
  293.  
  294.     ADJ_ADD_UNIT        - Contains the ADD/DM ADD Handle and Unit Handle
  295.                           assigned to the device being created.
  296.  
  297.  
  298.  
  299. Managing System Resources
  300. -------------------------
  301.  
  302. When a device driver allocates resources, it specifies
  303. the level of 'sharing' the driver is willing to accept. The level
  304. of sharing selected depends on the characteristics of the
  305. hardware, i.e. its ability to coordinate usage of IRQ or DMA channels
  306. with other adapters as well as the 'importance' of other functions which may
  307. need the same IRQ level.
  308.  
  309. Resources are allocated on a first-come first-served basis.
  310.  
  311. If a driver requests a resource that has been previously
  312. allocated to another driver, then the sharing mode selected
  313. by the earlier driver be used to determine if the new driver's
  314. request will be granted.
  315.  
  316.  
  317. The following resource sharing options are available
  318.  
  319.  
  320.  - EXCLUSIVE - The resource (I/O Port, DMA Channel, etc.)
  321.                is committed to the owner until it is
  322.                explicitly released. Any other that include
  323.                this resource will be denied.
  324.  
  325.  - SHARED    - The resource will be granted to any requester
  326.                that also requests the resource as shared.
  327.                This implies that the users of the resource
  328.                may use it at anytime without interfering
  329.                with each other. An example of this would
  330.                be a shared interrupt on a uC or EISA
  331.                bus machine.
  332.  
  333.  - MULTIPLEXED - The resource will be granted to any requester
  334.                that also requests the resource as multiplexed.
  335.                Multiplexed (unlike shared) implies that only
  336.                one owner may actively be using the resource
  337.                and that there explicit notification between
  338.                owners to control who is using the resource.
  339.                In general this sharing protocol is private to
  340.                of the Multiplexed resource.
  341.  
  342.  - GRANTYIELD - The resource will be granted to any requester
  343.                that also requests the resource as GRANTYIELD.
  344.                GRANTYIELD implies that the owner of the resource
  345.                is willing to participate in an Resource Manager
  346.                arbitrated sharing of a resource.
  347.  
  348.                Note: GRANTYIELD protocol is not currently Version
  349.                      1.01 of RESOURCE.SYS.
  350.  
  351.  
  352.  
  353. Logical Devices Management
  354. --------------------------
  355.  
  356. Note: The following section pertains primarily to Device Managers
  357.       and Device Drivers which assume similar functions. It may be
  358.       skipped unless there is a specific interest in these subjects.
  359.  
  360. OS/2 uses aliases to identify various physical devices. Typically these
  361. aliases are short descriptive names that are familiar to most
  362. users, such as DISK_0, A:, C:, COM1, LPT1.
  363.  
  364. The use of aliases simplify the operating systems (end-users)
  365. view of the system in several ways:
  366.  
  367. 1.) The implementation of a physical device, for example, a disk,
  368.     actually depends on combination of the System Bus, a SCSI or
  369.     IDE adapter and the disk device. It is convenient to the
  370.     end user to abstract this to a simple name such as DISK_0,
  371.     DISK_1, etc. rather than using the full path name to the device.
  372.  
  373. 2.) The operating system may subdivide or group devices so that
  374.     the physical device boundaries are no longer relevant. For
  375.     instance partitioning subdivides a physical disk into
  376.     a series of separate drives, while a RAID array may group
  377.     several physical devices into a single drive.
  378.  
  379. 3.) The operating system may have alternate views of the same
  380.     physical device. For example, a Physical Serial Port, may
  381.     be used as a FAX port FMD1$ or a ASYNC port COM1 depending
  382.     on the application using the port.
  383.  
  384. In order to provide a mapping from the operating system (end-user)
  385. view of the system to the actual implementing hardware,
  386. the Resource Manager maintains a separate node structure called
  387. a logical tree.
  388.  
  389.  
  390.  
  391.  
  392.                                LDEV Root
  393.  
  394.                                   │
  395.         ┌─────────────────────────┼────────────┬────────────┐
  396.         │            │            │            │            │
  397.         V            V            V            V            V
  398.  
  399.        DASD        CDROM         TAPE        SERIAL      PARALLEL
  400.  
  401.         │            │                       │
  402.         │            │                       └ COMM_1
  403.         │            │                         ------
  404.         │            │                         Alias: \ISA\COMM_0
  405.         │            │                         │
  406.         │            │                         ├ FMD1$
  407.         │            │                         └ COM1:
  408.         │            └─────────────────────┐
  409.         │
  410.         ├ DISK_0                           CDROM_0
  411.         │ ------                           -------
  412.         │ Alias: \ISA\IDE_0\DISK_0         Alias: \ISA\AHA154X_0\CDROM_(2,0)
  413.         │ │                                │
  414.         │ ├ C:                             └ G:
  415.         │ ├ E:
  416.         │ └ F:
  417.         │
  418.         │
  419.         └ DISK_1
  420.           ------
  421.           Alias: \ISA\AHA154X_0\DISK_(0,0)
  422.           │
  423.           └ D:
  424.  
  425.  
  426. The logical tree contains two types of nodes:
  427.  
  428.  
  429.    LDEVs
  430.    -----
  431.  
  432.    Logical device nodes represent aliases of nodes on the
  433.    physical device tree.
  434.  
  435.  
  436.    SYSNAMEs
  437.    --------
  438.  
  439.    System Name nodes represent named divisions of the parent LDEV.
  440.  
  441.    Depending on the nature of the device, these may be alternate
  442.    definitions of the LDEV which are mutually exclusive (e.g.
  443.    FMD1$ and COM1:) or may be shared such (e.g. C:, E: F:).
  444.  
  445.  
  446. Logical Devices and System Name are associated with each other in a
  447. Parent-Child-Sibling relationship. A driver is associated with
  448. each LDEV node.
  449.  
  450. The Resource Manager automatically creates Logical Device nodes
  451. representing basic system device types such as DASD, CDROM, TAPE,
  452. SERIAL, and PARALLEL during its initialization. Device Managers
  453. and certain device drivers (such as COM.SYS) create additional
  454. Logical Devices and System Name nodes as they declare new
  455. devices to the OS/2 Kernel.
  456.  
  457.  
  458.  
  459. Summary of Resource Manager APIs
  460. --------------------------------
  461.  
  462. The previous sections explain the basic resource management
  463. concepts. Prior to providing a detailed description of
  464. each API, it may be helpful to group the APIs into function
  465. based sets:
  466.  
  467.  
  468. Physical Node Management
  469. ------------------------
  470.  
  471.   These APIs create Driver, Adapter and Device nodes:
  472.   - RMCreateDriver
  473.   - RMCreateAdapter
  474.   - RMCreateDevice
  475.  
  476.   These APIs delete Driver, Adapter and Device nodes:
  477.   - RMDestroyDriver
  478.   - RMDestroyAdapter
  479.   - RMDestroyDevice
  480.  
  481.  
  482.  
  483. Resource Management
  484. -------------------
  485.  
  486.   These APIs allocate/deallocate resources.
  487.   - RMAllocResource
  488.   - RMDeallocResource
  489.  
  490.   These APIs claim/release resources allocated with GrantYield
  491.   protocols.
  492.   - RMClaimResources
  493.   - RMReleaseResources
  494.  
  495.   This API edits an existing device or adapter resource sets, either
  496.   adding or removing resources.
  497.   - RMModifyResources
  498.  
  499.  
  500.  
  501. Node Searches
  502. -------------
  503.  
  504.   This API searches for nodes matching a particular key:
  505.   - RMKeyToHandleList
  506.  
  507.   This API searches for nodes using a particular resource:
  508.   - RMResToHandleList
  509.  
  510.   This API searchs for nodes containing matching adjunct data:
  511.   - RMAdjToHandleList
  512.  
  513.   This API returns the LDEV associated with a physical device node:
  514.   - RMHDevtoHLDev
  515.  
  516.  
  517. Node Information
  518. ---------------
  519.  
  520.   This API provide the type of node the Handle is associated with:
  521.   - RMHandleToType
  522.  
  523.   This API returns the handle of the node's parent:
  524.   - RMHandleToParent
  525.  
  526.   This API returns the contents of the Resource Manager node indicated
  527.   by the Handle:
  528.   - RMGetNodeInfo
  529.  
  530.  
  531.  
  532. Logical Node Management
  533. -----------------------
  534.  
  535.   These APIs creates/destroy a Logical Device Node:
  536.   - RMCreateLDev
  537.   - RMDestroyLDev
  538.  
  539.   These APIs create/destroy a System Name Node:
  540.   - RMCreateSysName
  541.   - RMDestroySysName
  542.  
  543.   This API creates a 'pseudo device' representing a group of
  544.   physical devices:
  545.   - RMCreateLinkDevice
  546.  
  547.  
  548.                 ----------------------------------
  549.  
  550.  
  551. RMCreateDriver - Obtain a Driver Handle
  552.  
  553. Purpose: This api registers basic information about the calling
  554.          device driver with the Resource Manager. A driver handle
  555.          (HDRIVER) is returned by this API which is required by other
  556.          Resource Manager APIs to identify the requestor.
  557.  
  558.          The first call to this API causes the Resource Manager
  559.          interface code, i.e. the part that is linked to your
  560.          device driver to initialize. Therefore, normally, this
  561.          would be the first Resource Manager call a driver
  562.          would normally make.
  563.  
  564.          Information about the driver registering with the
  565.          Resource Manager is passed in a DRIVERSTRUCT which
  566.          is described below.
  567.  
  568.  
  569. Calling Sequence:
  570.  
  571.          rc = RMCreateDriver( (PDRIVERSTRUCT) &DriverStruct,
  572.                               (PHDRIVER)      &hDriver         );
  573.  
  574.  
  575.          Note: On systems where the resource manager driver is
  576.                not installed, the library interface code will
  577.                return RMRC_SUCCESS and a driver handle of -1L.
  578.  
  579.  
  580. Calling Parameters:
  581.  
  582.  
  583.          &hDriver
  584.  
  585.            Pointer to a variable to receive the returned driver
  586.            handle.
  587.  
  588.          &DriverStruct (PDRIVERSTRUCT)
  589.  
  590.            Pointer to the following structure
  591.  
  592.            DRIVERSTRUCT
  593.            ------------
  594.            struct
  595.            {
  596.               PSZ       DrvrName;
  597.               PSZ       DrvrDescript;
  598.               PSZ       VendorName;
  599.               UCHAR     MajorVer;
  600.               UCHAR     MinorVer;
  601.               DATESTAMP Date;
  602.               USHORT    DrvrFlags;
  603.               USHORT    DrvrType;
  604.               USHORT    DrvrSubType;
  605.               PFNRMCB   DrvrCallback;
  606.            };
  607.  
  608.  
  609.            DrvrName (PSZ)
  610.                Pointer to ASCIIZ name of device driver.
  611.  
  612.                Ex: "IBM1FLPY.ADD"
  613.                    "C:\MMOS2\MVPRODD.SYS"
  614.  
  615.            DrvrDescript (PSZ)
  616.                Pointer brief ASCIIZ description of device driver.
  617.  
  618.                Ex: "ISA/EISA Diskette ADD Driver"
  619.                    "ProAudio Spectrum Device Driver"
  620.  
  621.            VendorName (PSZ)
  622.                Pointer to ASCIIZ vendor name
  623.  
  624.                Ex: "IBM Corporation"
  625.  
  626.            MajorVer (UCHAR)
  627.            MinorVer (UCHAR)
  628.                RM interface level. This is the version of
  629.                the Resource manager APIs your driver is using.
  630.  
  631.                Currently these fields must be set to CMVERSION_MAJOR
  632.                and CMVERSION_MINOR which are defined in RMBASE.H
  633.  
  634.                Note: This is not the version or level of your driver.
  635.                      If this field does not contain a valid value, the
  636.                      RMCreateDriver request will fail.
  637.  
  638.  
  639.            Date (DATESTAMP)
  640.                A structure containing the year/month/day to identify
  641.                the version of your driver.
  642.  
  643.                DATESTAMP
  644.                ---------
  645.                struct
  646.                {
  647.                  USHORT Year;
  648.                  UCHAR  Month;
  649.                  UCHAR  Day;
  650.                };
  651.  
  652.                Year (USHORT)
  653.                   Year as a 16-bit integer.
  654.  
  655.                Month (UCHAR)
  656.                   Month as an 8-bit integer. Allowable range (1-12).
  657.  
  658.                Day (UCHAR)
  659.                   Day of month as na 8-bit integer. Allowable range (1-31).
  660.  
  661.                Ex: October 11, 1994
  662.  
  663.                pDS->Date.Year  = 1994;
  664.                pDS->Date.Month = 10;
  665.                pDS->Date.Day   = 11;
  666.  
  667.  
  668.  
  669.            DrvrFlags (USHORT)
  670.                Driver attribute flags. Unused bits must be set to zero
  671.                by the caller.
  672.  
  673.                Valid flag values: (Also see DRF_* in RMBASE.H).
  674.  
  675.                DRF_STATIC
  676.                  Driver is loaded at system IPL time.
  677.  
  678.  
  679.            DrvrType    (USHORT)
  680.            DrvrSubType (USHORT)
  681.                These fields identify the type of interface your
  682.                driver supports.
  683.  
  684.                The following categories are defined:
  685.  
  686.                DRT_PCMCIA
  687.  
  688.                A driver which conforms to PCMCIA specifications,
  689.  
  690.                  DRS_SOCKETSERV
  691.  
  692.                  A driver which supports the PCMCIA socket service
  693.                  API.
  694.  
  695.                  DRS_CARDSERV
  696.  
  697.                  A driver which supports the PCMCIA card service
  698.                  API.
  699.  
  700.                  DRS_CLIENT
  701.  
  702.                  A client driver which solely supports PCMCIA options.
  703.  
  704.                  Note: If a driver supports both PCMCIA and non-PCMCIA
  705.                        options, then the driver category reflect
  706.                        the non-PCMCIA usage.
  707.  
  708.                DRT_ADDDM
  709.  
  710.                A driver which conform to Adapter Device Driver /
  711.                Device Manager Interfaces.
  712.  
  713.                  DRS_DM
  714.  
  715.                  An ADD/DM driver which acts as a Device Manager
  716.                  interfacing directly with the OS2 Kernel.
  717.  
  718.                  For example: OS2DASD.DMD, OS2CDROM.DMD.
  719.  
  720.                  DRS_FILTER
  721.  
  722.                  An ADD/DM driver which acts as Filter.
  723.  
  724.                  DRS_ADD
  725.  
  726.                  An ADD/DM driver which acts as an Adapter Device
  727.                  Driver.
  728.  
  729.                  For example: IBM1FLPY.ADD, IBM1S506.ADD.
  730.  
  731.                  DRS_DM_TRANSPORT
  732.  
  733.                  A Device Manager whose primary purpose is
  734.                  to convert another protocol to ADD/DM protocols.
  735.  
  736.                  For example: OS2ASPI.DMD converts Adaptec ASPI
  737.                  protocols to ADD/DM protocols.
  738.  
  739.                DRT_OS2
  740.  
  741.                Character or Block device drivers which interface directly
  742.                to the OS/2 Kernel.
  743.  
  744.                  DRS_CHAR
  745.  
  746.                  A driver which creates a character devices intended
  747.                  for end-user usage.
  748.  
  749.                  DRS_BLOCK
  750.  
  751.                  A driver which creates block devices intended for
  752.                  end-user usage.
  753.  
  754.                  DRS_APP_HELPER
  755.  
  756.                  A driver provides private services intended for
  757.                  a particular application rather than the end-user
  758.                  directly.
  759.  
  760.                DRT_AUDIO
  761.  
  762.                  A driver which conforms to the OS/2 Multimedia
  763.                  APIs.
  764.  
  765.  
  766.                DRT_SERVICE
  767.  
  768.                  A driver which provides services to other drivers.
  769.  
  770.                  For example: RESOURCE.SYS
  771.  
  772.  
  773.                 ----------------------------------
  774.  
  775.  
  776.  
  777. RMDestroyDriver - Destroy a Driver Handle
  778.  
  779.  
  780. Purpose: This api releases a driver handle created by RMCreateDriver.
  781.  
  782.          Usually, if a driver determines it should fail its
  783.          initialization, i.e. unload, it will issue this call if
  784.          it had previously issued an RMCreateDriver request.
  785.  
  786.          Issuing this call will delete all Devices/Adapaters/Resource
  787.          records created under this driver handle.
  788.  
  789.          Note: Drivers which intend to unload must still issue the
  790.                appropriate DevHelp calls to release IRQs and other
  791.                kernel resources.
  792.  
  793. Calling Sequence:
  794.  
  795.          rc = RMDestroyDriver( (HDRIVER) hDriver );
  796.  
  797.          Note: On systems where the resource manager driver is
  798.                not installed, the library interface code will
  799.                return RMRC_SUCCESS.
  800.  
  801. Calling Parameters:
  802.  
  803.          hDriver
  804.  
  805.          Handle of the driver to be destroyed.
  806.  
  807.  
  808.                 ----------------------------------
  809.  
  810.  
  811.  
  812. RMCreateAdapter - Obtain an Adapter Handle
  813.  
  814. Purpose: This api allows a driver to register an adapter with
  815.          the resource manager. An adapter handle (HADAPTER) is
  816.          returned by this api to identify the adapter.
  817.  
  818.          Information about the adapter being registered is passed
  819.          in an ADAPTERSTRUCT which is described below.
  820.  
  821.          When adapter is registered, a list of resource handles
  822.          representing hardware resources used by this adapter
  823.          may be optionally passed.
  824.  
  825. Calling Sequence:
  826.  
  827.          rc = RMCreateAdapter( (HDRIVER)        hDriver,
  828.                                (PHADAPTER)      &hAdapter
  829.                                (PADAPTERSTRUCT) &AdapterStruct,
  830.                                (HDEVICE)        hParentDevice,
  831.                                (PAHRESOURCE)    &ResourceList  );
  832.  
  833.          Note: On systems where the resource manager driver is
  834.                not installed, the library interface code will
  835.                return RMRC_SUCCESS and an adapter handle of -1L.
  836.  
  837.  
  838. Calling Parameters:
  839.  
  840.          hDriver (HDRIVER)
  841.  
  842.            Driver handle of the device driver creating this adapter.
  843.  
  844.  
  845.          &hAdapter (PHADAPTER)
  846.  
  847.            Pointer to variable to receive the returned adapter
  848.            handle.
  849.  
  850.          &AdapterStruct
  851.  
  852.            Pointer to the following structure:
  853.  
  854.            ADAPTERSTRUCT
  855.            -------------
  856.            struct
  857.            {
  858.              PSZ          AdaptDescriptName;
  859.              USHORT       AdaptFlags;
  860.              USHORT       BaseType;
  861.              USHORT       SubType;
  862.              USHORT       InterfaceType;
  863.              USHORT       HostBusType;
  864.              USHORT       HostBusWidth;
  865.              PADJUNCT     pAdjunctList;
  866.              ULONG        Reserved;
  867.            };
  868.  
  869.            AdaptDescriptName (PSZ)
  870.                Pointer to an ASCIIZ string containing the adapter
  871.                key and a brief description the adapter.
  872.  
  873.                Ex: "FLOPPY_#  Diskette Controller"
  874.                    "PAS16 ProAudio Spectrum Adapter"
  875.                    "AHA154X_#  Adaptec 154X SCSI Adapter"
  876.  
  877.                Note: Up to the first 16 non-blank characters of the
  878.                      are used as a key to locate this adapter.
  879.  
  880.                      The RMCreateAdapter API will substitute the "#"
  881.                      character with the Adapter Number supplied in
  882.                      the Adjunct List.
  883.  
  884.                      Refer to "Adapter/Device Keys on page x" for
  885.                      additional information concerning device/adapter
  886.                      keys.
  887.  
  888.  
  889.            AdaptFlags (USHORT)
  890.                Adapter attribute flags. Unused flags must be set to
  891.                zero by the caller.
  892.  
  893.                Valid flag values:
  894.  
  895.                AS_16MB_ADDRESS_LIMIT
  896.                  Adapter does not support data transfers to storage
  897.                  above 16MB (24-bit addressing limit).
  898.  
  899.  
  900.            The next three fields provide provide a category of the
  901.            adapter being created.
  902.  
  903.                BaseType (USHORT)
  904.                  Indicate the general functional category the adapter:
  905.  
  906.                  AS_BASE_MSD    - Mass storage including disk, tape, cdrom
  907.                                   etc.
  908.  
  909.                  AS_BASE_COMM   - Communications, including serial and parallel
  910.                                   ports.
  911.  
  912.                  AS_BASE_PERIPH - System board components including, DMA
  913.                                   controllers, Interrupt controller, etc.
  914.  
  915.  
  916.                Subtype (USHORT)
  917.                  Indicates the interface supported by the adapter:
  918.  
  919.                  For example:
  920.  
  921.                  SCSI Adapter  - AS_BASE_MSD/AS_SUB_SCSI
  922.                  IDE Adapter   - AS_BASE_MSD/AS_SUB_IDE
  923.  
  924.                  Serial Port   - AS_BASE_COMM/AS_SUB_SERIAL
  925.                  Parallel Port - AS_BASE_COMM/AS_SUB_PARALLEL
  926.  
  927.  
  928.                InterfaceType (USHORT)
  929.                  Provides specific interface information.
  930.  
  931.                  For example:
  932.  
  933.                  Parallel Port  - AS_BASE_COMM/AS_SUB_PARALLEL/AS_INTF_ECP
  934.  
  935.                  These fields provide provide a category of the
  936.                  adapter being created.
  937.  
  938.            Refer to RMBASE.H for a complete list of adapter categories.
  939.  
  940.            The next two fields describe the host bus the adapter
  941.            supports.
  942.  
  943.            Note: This field describes how the adapter is connected to
  944.                  the host system rather than how the adapter is connected
  945.                  to the devices it supports.
  946.  
  947.                HostBusType
  948.                  Describes how the adapter is attached to the host
  949.                  system. Typically ISA, EISA, uC, PCI, etc..
  950.  
  951.  
  952.                HostBusWidth
  953.                  Indicates the maximum width of host bus data transfers
  954.                  the adapter supports.
  955.  
  956.            Refer to RMBASE.H for values for these fields.
  957.  
  958.  
  959.            pAdjunctList (PADJUNCT)
  960.  
  961.                Pointer to a linked list of Adjunct Data structures.
  962.  
  963.                The following adjunct structures should be included
  964.                in the list:
  965.  
  966.                  ADJ_ADAPTER_NUMBER
  967.                      This adjunct contains the zero based adapter number
  968.                      for the adapter being created.
  969.  
  970.  
  971.          hParentDevice (HDEVICE)
  972.  
  973.            Indicates the handle of the parent Adapter/Device for
  974.            the adapter being being created.
  975.  
  976.            In general this field may be set to null in
  977.            which case the adapter will be assigned to
  978.            the default system bus. If the system contains
  979.            multiple buses such as ISA/PCI, the HostBusType
  980.            field will be used to choose the appropriate
  981.            bus.
  982.  
  983.          &ResourceList (PAHRESOURCE)
  984.  
  985.            Pointer to a structure containing a count and a
  986.            list of resource handles to be assigned to this
  987.            adapter.
  988.  
  989.  
  990.            AHRESOURCE
  991.            ----------
  992.            struct
  993.            {
  994.              ULONG     NumResource;
  995.              HRESOURCE hResource[1];
  996.            }
  997.  
  998.            Note: As an alternative, resources may be added after
  999.                  the adapter is created by using the RMModifyAdapter
  1000.                  API. In this case the ResourceList pointer should
  1001.                  be set to NULL.
  1002.  
  1003.                 ----------------------------------
  1004.  
  1005.  
  1006.  
  1007. RMDestroyAdapter - Destroy an Adapter Handle
  1008.  
  1009.  
  1010. Purpose: This api releases an adapter handle created by RMCreateAdapter.
  1011.  
  1012.          Normally, once an adapter handle is created, it would not be
  1013.          destroyed. However, in PCMCIA environments, where adapters
  1014.          may be inserted or removed 'on-the-fly' this call allows
  1015.          the PCMCIA Client driver to keep the resource manager
  1016.          records consistent with the PC-Cards currently installed.
  1017.  
  1018.          Destroying an adapter, also destroys any child devices
  1019.          associated with the adapter. Any resource handles
  1020.          allocated to the adapter or child devices are also
  1021.          released.
  1022.  
  1023.  
  1024. Calling Sequence:
  1025.  
  1026.          rc = RMDestroyAdapter( (HDRIVER)  hDriver
  1027.                                 (HADAPTER) hAdapter );
  1028.  
  1029.          Note: On systems where the resource manager driver is
  1030.                not installed, the library interface code will
  1031.                return RMRC_SUCCESS.
  1032.  
  1033. Calling Parameters:
  1034.  
  1035.          hDriver
  1036.  
  1037.            Handle of driver supplied when adapter was created.
  1038.  
  1039.  
  1040.          hAdapter
  1041.  
  1042.            Handle of the adapter to be destroyed.
  1043.  
  1044.  
  1045.                 ----------------------------------
  1046.  
  1047.  
  1048.  
  1049. RMCreateDevice - Obtain an Device Handle
  1050.  
  1051.  
  1052. Purpose: This api allows a driver to register a devices with
  1053.          the resource manager and to assign the device to an adapter.
  1054.          A device handle (HDEVICE) is returned by this api to
  1055.          identify the device.
  1056.  
  1057.          Information about the device being registered is passed
  1058.          in a DEVICESTRUCT which is described below.
  1059.  
  1060.          When a device is registered, a list of resource handles
  1061.          representing hardware resources used by this device
  1062.          may be optionally assigned to the device.
  1063.  
  1064.  
  1065.  
  1066.  
  1067. Calling Sequence:
  1068.  
  1069.  
  1070.          rc = RMCreateDevice( (HDRIVER)       hDriver,
  1071.                               (PHDEVICE)      &hDevice,
  1072.                               (PDEVICESTRUCT) &DeviceStruct,
  1073.                               (HADAPTER)      hParentAdapter,
  1074.                               (PAHRESOURCE)   pahResource);
  1075.  
  1076.          Note: On systems where the resource manager driver is
  1077.                not installed, the library interface code will
  1078.                return RMRC_SUCCESS and an adapter handle of -1L.
  1079.  
  1080.  
  1081. Calling Parameters:
  1082.  
  1083.          hDriver (HDRIVER)
  1084.  
  1085.            Driver handle of the device driver creating this device.
  1086.  
  1087.  
  1088.          &hDevice (PHDEVICE)
  1089.  
  1090.            Pointer to variable to receive the returned device
  1091.            handle.
  1092.  
  1093.  
  1094.          &DeviceStruct
  1095.  
  1096.            Pointer to the following structure:
  1097.  
  1098.            DEVICESTRUCT
  1099.            ------------
  1100.            struct
  1101.            {
  1102.              PSZ      DevDescriptName;
  1103.              USHORT   DevFlags;
  1104.              USHORT   DevType;
  1105.              PADJUNCT pAdjunctList;
  1106.            };
  1107.  
  1108.            DevDescriptName (PSZ)
  1109.                Pointer to an ASCIIZ string containing the device
  1110.                key and a brief description the device.
  1111.  
  1112.                Ex: "DSKT_#  1.44MB Diskette Drive"
  1113.                    "DISK_#   Fixed Disk"
  1114.                    "CDROM_#  MITSUMI CD-ROM FX001D D02"
  1115.  
  1116.                Note: Up to the first 16 non-blank characters of the
  1117.                      are used as a key to locate this device.
  1118.  
  1119.                      The RMCreateDevice API will substitute the "#"
  1120.                      character with the Device Number or SCSI Target/LUN
  1121.                      supplied in the Adjunct List.
  1122.  
  1123.                      Refer to "Adapter/Device Keys on page x" for
  1124.                      additional information concerning device/adapter
  1125.                      keys.
  1126.  
  1127.  
  1128.            DevFlags (USHORT)
  1129.                Device attribute flags. Unused flags must be set
  1130.                to zero by the caller.
  1131.  
  1132.                Valid flag values are:
  1133.  
  1134.                DS_REMOVEABLE_MEDIA
  1135.                    Device has removable media.
  1136.  
  1137.            DevType (USHORT)
  1138.                Device type.
  1139.  
  1140.                Valid device types include:
  1141.  
  1142.                DS_TYPE_DISK            All Direct Access Devices
  1143.                DS_TYPE_TAPE            Sequential Access Devices
  1144.                DS_TYPE_PRINTER         Printer Device
  1145.                DS_TYPE_PROCESSOR       Processor type device
  1146.                DS_TYPE_WORM            Write Once Read Many Device
  1147.                DS_TYPE_CDROM           CD-ROM Device
  1148.                DS_TYPE_SCANNER         Scanner Device
  1149.                DS_TYPE_OPT_MEM         Optical disk
  1150.                DS_TYPE_CHANGER         Changer device
  1151.                DS_TYPE_COMM            Communication devices
  1152.                DS_TYPE_ATAPI           ATAPI protocol device
  1153.                DS_TYPE_SCSI_ATT        SCSI Bus Attach (Bridge controller)
  1154.                DS_TYPE_SOCKET          PCMCIA Socket
  1155.                DS_TYPE_SLOT            ISA/uC/EISA/PCI Bus Slot
  1156.                DS_TYPE_PLANAR_CHIPSET  DMA/IRQ/TIMER Controllers
  1157.                DS_TYPE_IO              Input/Output
  1158.                DS_TYPE_AUDIO           Audio Device
  1159.                DS_TYPE_UNKNOWN         Unknown Device Type
  1160.  
  1161.  
  1162.            pAdjunctList (PADJUNCT)
  1163.  
  1164.                Pointer to a linked list of Adjunct Data structures.
  1165.  
  1166.                The following adjunct structures should be included
  1167.                in the list:
  1168.  
  1169.                ADD Drivers:
  1170.  
  1171.                  ADJ_ADD_UNIT
  1172.                      This adjunct contains the ADD Handle and ADD UnitNumber
  1173.                      the ADD driver will assign to the device.
  1174.  
  1175.                Non-SCSI Devices:
  1176.  
  1177.                  ADJ_DEVICE_NUMBER
  1178.                      This adjunct contains the zero based device number
  1179.                      for non-scsi devices.
  1180.  
  1181.                      For example, the nth CD-ROM supported by an adapter
  1182.  
  1183.                SCSI Devices:
  1184.  
  1185.                  ADJ_SCSI_TARGET_LUN
  1186.                      This adjunct contains the SCSI Target ID and Logical
  1187.                      Device Number (LUN) assigned to the device.
  1188.  
  1189.          hParentAdapter (HADAPTER)
  1190.  
  1191.            Indicates the handle of the parent Adapter for
  1192.            the device being being created.
  1193.  
  1194.          &ResourceList (PAHRESOURCE)
  1195.  
  1196.            Pointer to a structure containing a count and a
  1197.            list of resource handles to be assigned to this
  1198.            device.
  1199.  
  1200.  
  1201.            AHRESOURCE
  1202.            ----------
  1203.            struct
  1204.            {
  1205.              ULONG     NumResource;
  1206.              HRESOURCE hResource[1];
  1207.            }
  1208.  
  1209.            Note: Resources are normally assigned to the adapter
  1210.                  (parent) which owns the device. In some cases,
  1211.                  resources are used specifically by a particular
  1212.                  device rather than shared between multiple devices
  1213.                  supported by an adapter. In this case, resources
  1214.                  should be assigned to the device as appropriate.
  1215.  
  1216.  
  1217.                 ----------------------------------
  1218.  
  1219.  
  1220.  
  1221. RMDestroyDevice - Destroy an Device Handle
  1222.  
  1223.  
  1224. Purpose: This api releases a device handle created by RMCreateDevice.
  1225.  
  1226.          Any resources assigned to the device are released the
  1227.          device is destroyed.
  1228.  
  1229.  
  1230.  
  1231. Calling Sequence:
  1232.  
  1233.          rc = RMDestroyDevice( (HDRIVER) hDriver
  1234.                                (HDEVICE) hDevice );
  1235.  
  1236.          Note: On systems where the resource manager driver is
  1237.                not installed, the library interface code will
  1238.                return RMRC_SUCCESS.
  1239.  
  1240. Calling Parameters:
  1241.  
  1242.          hDriver
  1243.  
  1244.            Handle of driver supplied when device was created.
  1245.  
  1246.  
  1247.          hDevice
  1248.  
  1249.            Handle of the device to be destroyed.
  1250.  
  1251.  
  1252.                 ----------------------------------
  1253.  
  1254.  
  1255.  
  1256. RMAllocResource - Obtain an Resource Handle
  1257.  
  1258.  
  1259. Purpose: This api allows a driver to register usage of a hardware
  1260.          resource.
  1261.  
  1262.          Resources which may be allocated include:
  1263.  
  1264.            I/O Port Range
  1265.            DMA Channel
  1266.            IRQ Level
  1267.            Timer Channel
  1268.            BIOS Memory Region
  1269.  
  1270.          A driver must issue this call and successfully obtain
  1271.          ownership of a resource prior to making any attempt
  1272.          to access the resource.
  1273.  
  1274.          Note: This includes non-destructive (read type) accesses.
  1275.  
  1276.          For I/O and BIOS Memory resources, searches to locate an
  1277.          available I/O or Memory region are supported.
  1278.  
  1279.          The resource to be allocated is described in a RESOURCESTRUCT
  1280.          which contains  C-union of structures which are resource
  1281.          type specific.
  1282.  
  1283.          This api returns a resource handle (HRESOURCE) which is
  1284.          used to identify usage of the resource by this driver.
  1285.  
  1286.          Resources are initially assigned to the driver issuing
  1287.          RMAllocResource request. This is done to facilitate
  1288.          driver doing hardware probing to determine if hardware
  1289.          it intends to support is installed.
  1290.  
  1291.          Once the driver determines that a supported adapter
  1292.          is present, it should register an adapter (RMCreateAdapter)
  1293.          and assign resource handles by providing a list
  1294.          of resource handles on the RMCreateAdapter API.
  1295.  
  1296.          If an adapter is not found, resources that are
  1297.          not assigned to a device or adapter must be released.
  1298.          See RMDeallocResource.
  1299.  
  1300.  
  1301. Calling Sequence:
  1302.  
  1303.          rc = RMAllocResource( (HDRIVER)         hDriver,
  1304.                                (PHRESOURCE)      &hResource,
  1305.                                (PRESOURCESTRUCT) &ResourceStruct );
  1306.  
  1307.          Note: On systems where the resource manager driver is
  1308.                not installed, the library interface code will
  1309.                return RMRC_SUCCESS and an resource handle of -1L.
  1310.  
  1311.  
  1312. Calling Parameters:
  1313.  
  1314.          hDriver (HDRIVER)
  1315.  
  1316.            Driver handle of the device driver requesting the resource.
  1317.  
  1318.  
  1319.          &hResource (PHRESOURCE)
  1320.  
  1321.            Pointer to variable to receive the returned resource
  1322.            handle.
  1323.  
  1324.          &ResourceStruct
  1325.  
  1326.            Pointer to the following structure:
  1327.  
  1328.            RESOURCESTRUCT
  1329.            --------------
  1330.            struct
  1331.            {
  1332.              ULONG ResourceType;
  1333.              union
  1334.              {
  1335.                IORESOURCE   IOResource;
  1336.                IRQRESOURCE  IRQResource;
  1337.                MEMRESOURCE  MEMResource;
  1338.                DMARESOURCE  DMAResource;
  1339.                TMRRESOURCE  TMRResource;
  1340.              };
  1341.              ULONG  Reserved;
  1342.            };
  1343.  
  1344.            ResourceType (ULONG)
  1345.                Indicates the type of resource being requested.
  1346.  
  1347.                Note: The resource structure contained in the union must
  1348.                       match the type of resource indicated by this field.
  1349.  
  1350.                Resource Requested  ResourceType    Resource Structure
  1351.                ------------------  ------------    ------------------
  1352.                I/O Port Range      RS_TYPE_I/O     IORESOURCE
  1353.                IRQ Level           RS_TYPE_IRQ     IRQRESOURCE
  1354.                BIOS Memory Region  RS_TYPE_MEM     MEMRESOURCE
  1355.                DMA Channel         RS_TYPE_DMA     DMARESOURCE
  1356.                Timer Channel       RS_TYPE_TIMER   TMRRESOURCE
  1357.  
  1358.  
  1359.  
  1360.            IOResource (IORESOURCE)
  1361.  
  1362.                For ResourceType = RS_TYPE_IO, the union contains the
  1363.                following structure:
  1364.  
  1365.                IORESOURCE
  1366.                ----------
  1367.                struct
  1368.                {
  1369.                  USHORT BaseIOPort;
  1370.                  USHORT NumIOPorts;
  1371.                  USHORT IOFlags;
  1372.                  USHORT IOAddressLines;
  1373.                };
  1374.  
  1375.                BaseIOPort
  1376.                   Specifies the start of the I/O Port range requested.
  1377.                   If a search is being performed, then this field
  1378.                   is considered the starting point for the search.
  1379.  
  1380.                NumIOPorts
  1381.                   Specifies number of contiguous I/O Ports requested.
  1382.  
  1383.                IOFlags
  1384.                   One of the following sharing mode flags
  1385.                   must be specified:
  1386.  
  1387.                     RS_IO_EXCLUSIVE
  1388.                     RS_IO_MULTIPLEXED
  1389.                     RS_IO_SHARED
  1390.                     RS_IO_GRANT_YIELD
  1391.  
  1392.                     Note: See section "Managing System Resources"
  1393.                           for a description on resource sharing
  1394.                           modes.
  1395.  
  1396.                   If a device driver and supported adapter is capable of
  1397.                   selecting a new I/O range and is participating
  1398.                   in Grant-Yield protocols, then the following flag
  1399.                   indicates the driver will accept reconfiguration
  1400.                   requests for this resource.
  1401.  
  1402.                     RS_IO_RECONFIGURE
  1403.  
  1404.                   If a search is to be performed the following
  1405.                   flag must be specified.
  1406.  
  1407.                     RS_SEARCH
  1408.  
  1409.                   Notes: When a search is performed and is successful, the
  1410.                          BaseIOPort field will be updated to indicate
  1411.                          the start of the allocated I/O Port range.
  1412.  
  1413.                          The port range returned will be aligned on
  1414.                          2^n boundary >= NumIOPorts.
  1415.  
  1416.  
  1417.                IOAddressLines
  1418.                   Specifies the number of address lines the adapter
  1419.                   can decode.
  1420.  
  1421.                   This field must contain the value 10 or 16.
  1422.  
  1423.                   Most current generation 16-bit adapters decode all
  1424.                   16 I/O address lines. PC-XT and some early 16-bit
  1425.                   adapters only decode 10 address lines.
  1426.  
  1427.                   Adapters which do not fully decode appear multiple
  1428.                   places in the IO Address space since they ignore
  1429.                   the high-order I/O address bits.
  1430.  
  1431.                   Note: Port allocations outside the ISA compatibility
  1432.                         range (100h - 3FFh) must indicate
  1433.                         IOAddressLines = 16.
  1434.  
  1435.  
  1436.            IRQResource (IRQRESOURCE)
  1437.  
  1438.                For ResourceType = RS_TYPE_IRQ, the union contains the
  1439.                following structure:
  1440.  
  1441.                IRQRESOURCE
  1442.                ----------
  1443.                struct
  1444.                {
  1445.                  USHORT          IRQLevel;
  1446.                  USHORT          PCIIrqPin;
  1447.                  USHORT          IRQFlags;
  1448.                  USHORT          Reserved;
  1449.                  PFNRMINTHANDLER pfnIntHandler;
  1450.                };
  1451.  
  1452.                IRQLevel
  1453.                   Specifies requested IRQ Level (0-15)
  1454.  
  1455.                PCIIrqPin
  1456.                   For PCI devices, set to one of the following
  1457.                   values based on the PCI Interrupt Pin assigned
  1458.                   to the device.
  1459.  
  1460.                   PCI Interrupt Pin          PCIIrqPin Value
  1461.                   -----------------          ---------------
  1462.                   None                       RS_PCI_INT_NONE
  1463.                   A                          RS_PCI_INT_A
  1464.                   B                          RS_PCI_INT_B
  1465.                   C                          RS_PCI_INT_C
  1466.                   D                          RS_PCI_INT_D
  1467.  
  1468.                   For non-PCI devices, this field must be set
  1469.                   to zero.
  1470.  
  1471.                IRQFlags
  1472.                   One of the following sharing mode flags
  1473.                   must be specified:
  1474.  
  1475.                     RS_IRQ_EXCLUSIVE
  1476.                     RS_IRQ_MULTIPLEXED
  1477.                     RS_IRQ_SHARED
  1478.                     RS_IRQ_GRANT_YIELD
  1479.  
  1480.                     Note: See section "Managing System Resources"
  1481.                           for a description on resource sharing
  1482.                           modes.
  1483.  
  1484.                pfnIntHandler
  1485.                   This field is reserved for future use and must
  1486.                   be set to zero.
  1487.  
  1488.  
  1489.            MEMResource (MEMRESOURCE)
  1490.  
  1491.                For ResourceType = RS_TYPE_MEM, the union contains the
  1492.                following structure:
  1493.  
  1494.                MEMRESOURCE
  1495.                ----------
  1496.                struct
  1497.                {
  1498.                  ULONG  MemBase;
  1499.                  ULONG  MemSize;
  1500.                  USHORT MemFlags;
  1501.                  USHORT ReservedAlign;
  1502.                };
  1503.  
  1504.                MemBase
  1505.                   Specifies the start of the BIOS Memory region requested
  1506.                   as physical address. If a search is being performed
  1507.                   then this is the starting point for the search.
  1508.  
  1509.                MemSize
  1510.                   Specifies the size of the BIOS Memory region requested
  1511.                   in bytes.
  1512.  
  1513.                MemFlags
  1514.                   One of the following sharing mode flags
  1515.                   must be specified:
  1516.  
  1517.                     RS_MEM_EXCLUSIVE
  1518.                     RS_MEM_MULTIPLEXED
  1519.                     RS_MEM_SHARED
  1520.                     RS_MEM_GRANT_YIELD
  1521.  
  1522.                     Note: See section "Managing System Resources"
  1523.                           for a description on resource sharing
  1524.                           modes.
  1525.  
  1526.                   If a device driver and adapter is capable of
  1527.                   selecting a new Memory Range and is participating
  1528.                   in Grant-Yield protocols, then the following flag
  1529.                   indicates the driver will accept reconfiguration
  1530.                   requests for this resource.
  1531.  
  1532.                     RS_MEM_RECONFIGURE
  1533.  
  1534.                   If a search is to be performed the following
  1535.                   flag must be specified.
  1536.  
  1537.                     RS_SEARCH
  1538.  
  1539.                   Notes: When a search is performed and is successful, the
  1540.                          MemBase field will be updated to indicate
  1541.                          the start of the allocated Memory range.
  1542.  
  1543.            DMAResource (DMARESOURCE)
  1544.  
  1545.                For ResourceType = RS_TYPE_DMA, the union contains the
  1546.                following structure:
  1547.  
  1548.                DMARESOURCE
  1549.                ----------
  1550.                struct
  1551.                {
  1552.                  USHORT DMAChannel;
  1553.                  USHORT DMAFlags;
  1554.                };
  1555.  
  1556.                DMAChannel
  1557.                   Specifies the number of the DMA Channel requested (0-7).
  1558.  
  1559.                DMAFlags
  1560.                   One of the following sharing mode flags
  1561.                   must be specified:
  1562.  
  1563.                     RS_DMA_EXCLUSIVE
  1564.                     RS_DMA_MULTIPLEXED
  1565.                     RS_DMA_SHARED
  1566.                     RS_DMA_GRANT_YIELD
  1567.  
  1568.                     Note: See section "Managing System Resources"
  1569.                           for a description on resource sharing
  1570.                           modes.
  1571.  
  1572.            TMRResource (TMRRESOURCE)
  1573.  
  1574.                For ResourceType = RS_TYPE_TIMER, the union contains the
  1575.                following structure:
  1576.  
  1577.                TMRRESOURCE
  1578.                ----------
  1579.                struct
  1580.                {
  1581.                  USHORT TMRChannel;
  1582.                  USHORT TMRFlags;
  1583.                };
  1584.  
  1585.                TMRChannel
  1586.                   Specifies the number of the Timer Channel requested (0-2).
  1587.  
  1588.                TMRFlags
  1589.                   One of the following sharing mode flags
  1590.                   must be specified:
  1591.  
  1592.                     RS_TMR_EXCLUSIVE
  1593.                     RS_TMR_MULTIPLEXED
  1594.                     RS_TMR_SHARED
  1595.                     RS_TMR_GRANT_YIELD
  1596.  
  1597.                     Note: See section "Managing System Resources"
  1598.                           for a description on resource sharing
  1599.                           modes.
  1600.  
  1601.  
  1602.                 ----------------------------------
  1603.  
  1604.  
  1605.  
  1606. RMDeallocResource - Destroy an Resource Handle
  1607.  
  1608.  
  1609. Purpose: This api destroys a resource handle created by RMAllocResource.
  1610.  
  1611.  
  1612. Calling Sequence:
  1613.  
  1614.          rc = RMDeallocResourcer( (HDRIVER)  hDriver
  1615.                                   (HRESOURCE) hResource );
  1616.  
  1617.          Note: On systems where the resource manager driver is
  1618.                not installed, the library interface code will
  1619.                return RMRC_SUCCESS.
  1620.  
  1621. Calling Parameters:
  1622.  
  1623.          hDriver
  1624.  
  1625.            Handle of driver supplied the resource was created.
  1626.  
  1627.  
  1628.          hResource
  1629.  
  1630.            Handle of the resource to be destroyed.
  1631.  
  1632.  
  1633.                 ----------------------------------
  1634.  
  1635.  
  1636.  
  1637.  
  1638. RMClaimResources - Claim Grant/Yield Resources for an adapter
  1639.  
  1640.  
  1641.          Preliminary/Advance Information
  1642.  
  1643.          Note: This api is not currently supported in Resource Manager
  1644.                Version 1.01 and will return RMRC_NOT_SUPPORTED in all
  1645.                cases.
  1646.  
  1647.  
  1648. Purpose: This api indicates a driver requires the use of Grant/Yield
  1649.          resources for an adapter.
  1650.  
  1651.          The resource manager will attempt to assign resources
  1652.          to the driver issuing this request. If the requested
  1653.          resources are held by other drivers, then those drivers
  1654.          will be notified that a Grant/Yield request is in
  1655.          progress.
  1656.  
  1657.          If the resource manager cannot satisfy the RMClaimResource
  1658.          request in the time indicated, then the request will
  1659.          fail. In this case any pending resource requests to
  1660.          other drivers will be cancelled.
  1661.  
  1662.  
  1663.  
  1664. Calling Sequence:
  1665.  
  1666.          rc = RMClaimResources( (HDRIVER)  hDriver,
  1667.                                 (HADAPTER) hAdapter,
  1668.                                 (ULONG)    TimeoutMS );
  1669.  
  1670.          Note: On systems where the resource manager driver is
  1671.                not installed, the library interface code will
  1672.                return RMRC_NOT_INSTALLED.
  1673.  
  1674.  
  1675. Calling Parameters:
  1676.  
  1677.          hDriver (HDRIVER)
  1678.  
  1679.            Driver handle of the device driver requesting the resource.
  1680.  
  1681.  
  1682.          hAdapter (HADAPTER)
  1683.  
  1684.            Handle of the adapter claiming its grant-yield resources.
  1685.  
  1686.  
  1687.          TimeoutMS (ULONG)
  1688.  
  1689.            Maximum time (milliseconds) to wait for RMClaimResources
  1690.            to be satisfied.
  1691.  
  1692.            Special timeout values:
  1693.  
  1694.            0L - Indicates that a RMClaimResources request should fail
  1695.                 if resource are not immediately available.
  1696.  
  1697.           -1L - Indicates that a RMClaimResources request should wait
  1698.                 indefinitely for resources to become available.
  1699.  
  1700.  
  1701.                 ----------------------------------
  1702.  
  1703.  
  1704.  
  1705. RMReleaseResources - Release Grant/Yield Resources for an adapter
  1706.  
  1707.  
  1708.          Preliminary/Advance Information
  1709.  
  1710.          Note: This api is not currently supported in Resource Manager
  1711.                Version 1.01 and will return RMRC_NOT_SUPPORTED in all
  1712.                cases.
  1713.  
  1714.  
  1715. Purpose: This api indicates a driver no longer require use of Grant/Yield
  1716.          resources for an adapter.
  1717.  
  1718.          A driver may reclaim a grant-yield resource set for an
  1719.          adapter by issuing a RMClaimResources.
  1720.  
  1721.  
  1722. Calling Sequence:
  1723.  
  1724.          rc = RMReleaseResources( (HDRIVER)  hDriver,
  1725.                                   (HADAPTER) hAdapter );
  1726.  
  1727.          Note: On systems where the resource manager driver is
  1728.                not installed, the library interface code will
  1729.                return RMRC_NOT_INSTALLED.
  1730.  
  1731.  
  1732. Calling Parameters:
  1733.  
  1734.          hDriver (HDRIVER)
  1735.  
  1736.            Driver handle of the device driver requesting the resource.
  1737.  
  1738.  
  1739.          hAdapter (HADAPTER)
  1740.  
  1741.            Handle of the adapter releasing its grant-yield resources.
  1742.  
  1743.  
  1744.  
  1745.                 ----------------------------------
  1746.  
  1747.  
  1748.  
  1749. RMCreateLDev - Obtain a Logical Device Handle
  1750.  
  1751. Purpose: This api allows a driver to register a logical device with
  1752.          the resource manager. An logical device handle (HLDEV) is
  1753.          returned by this api to identify the logical device.
  1754.  
  1755.          Information about the logical device being registered is passed
  1756.          in an LDEVSTRUCT which is described below.
  1757.  
  1758.  
  1759. Calling Sequence:
  1760.  
  1761.          rc = RMCreateLDev( (HDRIVER)     hDriver,
  1762.                             (PHLDEV)      &hLDev,
  1763.                             (HDEVICE)     hAssocDevice,
  1764.                             (PLDEVSTRICT) &LDevStruct );
  1765.  
  1766.          Note: On systems where the resource manager driver is
  1767.                not installed, the library interface code will
  1768.                return RMRC_SUCCESS and a logical device handle
  1769.                of -1L.
  1770.  
  1771.  
  1772. Calling Parameters:
  1773.  
  1774.          hDriver (HDRIVER)
  1775.  
  1776.            Driver handle of the device driver creating this adapter.
  1777.  
  1778.  
  1779.          &hLDev (PHLDEV)
  1780.  
  1781.            Pointer to variable to receive the returned logical device
  1782.            handle.
  1783.  
  1784.          hAssocDevice (HDEVICE)
  1785.  
  1786.            Handle of the physical device/adapter that this logical
  1787.            device is aliasing.
  1788.  
  1789.            Note: This field may also contain an adapter handle
  1790.                  coerced to an HDEVICE type.
  1791.  
  1792.          &LDevStruct
  1793.  
  1794.            Pointer to the following structure:
  1795.  
  1796.            LDEVSTRUCT
  1797.            ----------
  1798.            struct
  1799.            {
  1800.              PSZ      LDevDescriptName;
  1801.              USHORT   LDevFlags;
  1802.              USHORT   LDevClass;
  1803.              HDEVICE  LDevHDevice;
  1804.              PADJUNCT pAdjunctList;
  1805.            };
  1806.  
  1807.            LDevDescriptName (PSZ)
  1808.                Pointer to an ASCIIZ string containing the logical device
  1809.                key and a brief description the device.
  1810.  
  1811.                Ex: "FIXDSK_#  Fixed Disk Drive"
  1812.                    "COMM_#    Serial Port"
  1813.  
  1814.                Note: Up to the first 16 non-blank characters of the
  1815.                      are used as a key to locate this device.
  1816.  
  1817.                      The RMCreateLDev API will substitute the "#"
  1818.                      character with the Device Number supplied in
  1819.                      the Adjunct List.
  1820.  
  1821.                      Refer to "Adapter/Device Keys on page x" for
  1822.                      additional information concerning device/adapter
  1823.                      keys.
  1824.  
  1825.            LDevFlags (USHORT)
  1826.                There currently no flags defined. This field must
  1827.                be initialized to zero by the called.
  1828.  
  1829.            LDevClass (USHORT)
  1830.                Specifies the type of logical device being created.
  1831.  
  1832.                The logical device returned will be made a child
  1833.                of resource manager node for the class of device
  1834.                specified.
  1835.  
  1836.                Logical Device Type            Class Node Name
  1837.                -------------------            ---------------
  1838.                LDEV_CLASS_DASD                DASD
  1839.                LDEV_CLASS_CDROM               CDROM
  1840.                LDEV_CLASS_SERIAL              SERIAL
  1841.                LDEV_CLASS_PARALLEL            PARALLEL
  1842.                LDEV_CLASS_TAPE                TAPE
  1843.  
  1844.                Refer to section on "Logical Device Management" for
  1845.                further information.
  1846.  
  1847.            LDevHDevice
  1848.                This field must be initialized to zero by the called.
  1849.  
  1850.                It is used to return the handle of physical device
  1851.                indicated by hAssocDevice, when a a copy of the logical
  1852.                device node is returned by RMGetNodeInfo.
  1853.  
  1854.            pAdjunctList (PADJUNCT)
  1855.  
  1856.                Pointer to a linked list of Adjunct Data structures.
  1857.  
  1858.                The following adjunct structures should be included
  1859.                in the list:
  1860.  
  1861.                  ADJ_DEVICE_NUMBER
  1862.                      This adjunct contains the zero based device number
  1863.                      for the logical device being created.
  1864.  
  1865.  
  1866.                 ----------------------------------
  1867.  
  1868.  
  1869.  
  1870. RMDestroyLDev - Destroy a Logical Device Handle
  1871.  
  1872.  
  1873. Purpose: This api destroys a logical device handle created by
  1874.          RMCreateLDev.
  1875.  
  1876.          Destroying a logical device also destroys any system
  1877.          names associated with the logical device.
  1878.  
  1879.  
  1880. Calling Sequence:
  1881.  
  1882.          rc = RMDestroyLDev( (HDRIVER)  hDriver,
  1883.                              (HLDEV)    hLDev    );
  1884.  
  1885.          Note: On systems where the resource manager driver is
  1886.                not installed, the library interface code will
  1887.                return RMRC_SUCCESS.
  1888.  
  1889.  
  1890. Calling Parameters:
  1891.  
  1892.          hDriver (HDRIVER)
  1893.  
  1894.            Driver handle of the device driver which created the logical
  1895.            device.
  1896.  
  1897.  
  1898.          hLDev (HLDEV)
  1899.  
  1900.            Handle of the logical device to be destroyed.
  1901.  
  1902.  
  1903.                 ----------------------------------
  1904.  
  1905.  
  1906.  
  1907. RMCreateSysName - Obtain a System Name Handle
  1908.  
  1909. Purpose: This api allows a driver to register a system name with
  1910.          the resource manager and associate it with a logical device.
  1911.          A system name handle (HSYSNAME) is returned by this api
  1912.          to identify the system name.
  1913.  
  1914.          Information about the system name being registered is passed
  1915.          in an SYSNAMESTRUCT which is described below.
  1916.  
  1917.  
  1918. Calling Sequence:
  1919.  
  1920.          rc = RMCreateSysName( (HDRIVER)        hDriver,
  1921.                                (PHSYSNAME)      &hSysName,
  1922.                                (HLDEV)          hLDevParent,
  1923.                                (PSYSNAMESTRUCT) &SysNameStruct );
  1924.  
  1925.          Note: On systems where the resource manager driver is
  1926.                not installed, the library interface code will
  1927.                return RMRC_SUCCESS and a system name handle
  1928.                of -1L.
  1929.  
  1930.  
  1931. Calling Parameters:
  1932.  
  1933.          hDriver (HDRIVER)
  1934.  
  1935.            Driver handle of the device driver creating this adapter.
  1936.  
  1937.  
  1938.          &hSysName (PSYSNAME)
  1939.  
  1940.            Pointer to variable to receive the returned system name
  1941.            handle.
  1942.  
  1943.          hLDevParent (HLDEV)
  1944.  
  1945.            Handle of the logical device which the system name is
  1946.            associated, i.e. the parent of the system name.
  1947.  
  1948.  
  1949.          &SysNameStruct
  1950.  
  1951.            Pointer to the following structure:
  1952.  
  1953.            SYSNAMESTRUCT
  1954.            -------------
  1955.            struct
  1956.            {
  1957.              PSZ      SysDescriptName;
  1958.              PADJUNCT pAdjunctList;
  1959.              USHORT   SysFlags;
  1960.              USHORT   Reserved;
  1961.            };
  1962.  
  1963.            SysDescriptName (PSZ)
  1964.                Pointer to an ASCIIZ string containing the system name
  1965.                key and a brief description the system name.
  1966.  
  1967.                Ex: "C:    Logical DASD Volume"
  1968.                    "COM1: Communications Port"
  1969.  
  1970.            pAdjunctList
  1971.                Pointer to a linked list of Adjunct Data structures.
  1972.  
  1973.                The following adjunct structures should be included
  1974.                in the list:
  1975.  
  1976.                  ADJ_DASD_VOL
  1977.                      This adjunct is used for dasd type devices
  1978.                      to indicate the capacity and file system
  1979.                      type for drive letter indicated by the
  1980.                      system name.
  1981.  
  1982.  
  1983.                 ----------------------------------
  1984.  
  1985.  
  1986.  
  1987. RMDestroySysName - Destroy a System Name Handle
  1988.  
  1989.  
  1990. Purpose: This api destroys a system name handle created by
  1991.          RMCreateSysName.
  1992.  
  1993.  
  1994. Calling Sequence:
  1995.  
  1996.          rc = RMDestroySysName( (HDRIVER)  hDriver,
  1997.                                 (HSYSNAME) hSysName    );
  1998.  
  1999.          Note: On systems where the resource manager driver is
  2000.                not installed, the library interface code will
  2001.                return RMRC_SUCCESS.
  2002.  
  2003.  
  2004. Calling Parameters:
  2005.  
  2006.          hDriver (HDRIVER)
  2007.  
  2008.            Driver handle of the device driver which created the logical
  2009.            device.
  2010.  
  2011.  
  2012.          hSysName (HSYSNAME)
  2013.  
  2014.            Handle of the system name to be destroyed.
  2015.  
  2016.  
  2017.                 ----------------------------------
  2018.  
  2019.  
  2020.  
  2021. RMADDToHDEVICE - Map an ADD/DM Handle to Resource Manager Device Handle
  2022.  
  2023.  
  2024.          Preliminary/Advance Information
  2025.  
  2026.          Note: This api will be removed in the next Resource Manager
  2027.                release.
  2028.  
  2029.                Use RMAdjToHandleList rather than this api to maintain
  2030.                compatibility with future Resource Manager releases.
  2031.  
  2032.  
  2033. Purpose: This api converts an ADD/DM ADD Handle and ADD/DM UnitHandle
  2034.          to a corresponding Resource Manager Device Handle. This is
  2035.          done by searching the Resource Manager physical device
  2036.          tree for a node that contains an ADJ_ADD_UNIT adjunct
  2037.          that matches the supplied ADD Handle and ADD UnitHandle.
  2038.  
  2039. Calling Sequence:
  2040.  
  2041.          rc = RMADDToHDEVICE( (PHDEVICE)  &hDevice,
  2042.                               (USHORT)    ADDHandle,
  2043.                               (USHORT)    UnitHandle );
  2044.  
  2045.          Note: On systems where the resource manager driver is
  2046.                not installed, the library interface code will
  2047.                return RMRC_NOT_INSTALLED and will set hDevice
  2048.                to -1L.
  2049.  
  2050. Calling Parameters:
  2051.  
  2052.          &hDevice (PHDEVICE)
  2053.  
  2054.            Pointer to variable to receive device handle of device
  2055.            with a matching ADDHandle and UnitHandle.
  2056.  
  2057.  
  2058.          ADDHandle (USHORT)
  2059.  
  2060.            Handle of the ADD driver assigned by DevHelp_RegisterDeviceClass.
  2061.  
  2062.  
  2063.          UnitHandle (USHORT)
  2064.  
  2065.            UnitHandle the ADD driver assigned to this device.
  2066.  
  2067.  
  2068.          Note: Refer to "Storage Device Reference" for additional
  2069.                information on ADD/DM architecture.
  2070.  
  2071.  
  2072.                 ----------------------------------
  2073.  
  2074.  
  2075.  
  2076. RMKeyToHandleList - Search for the specified Adapter/Device/LDev Key
  2077.  
  2078.  
  2079. Purpose: This api searches for Resource Manager nodes which match
  2080.          the key specified. A list of node handles found is returned
  2081.          in the HandleList structure provided by the caller.
  2082.  
  2083.  
  2084. Calling Sequence:
  2085.  
  2086.          rc = RMKeyToHandleList( (RMHANDLE)    hStartNode,
  2087.                                  (PSZ)         SearchKey,
  2088.                                  (PHANDLELIST) &HandleList );
  2089.  
  2090.          Note: On systems where the resource manager driver is
  2091.                not installed, the library interface code will
  2092.                return RMRC_NOT_INSTALLED.
  2093.  
  2094. Calling Parameters:
  2095.  
  2096.  
  2097.          hStartNode (RMHANDLE)
  2098.  
  2099.            Handle of resource manager node to start the search at. This
  2100.            node and all its descendents will be checked. The handle
  2101.            provided may be an adapter handle (HADAPTER) or logical
  2102.            device handle (HLDEV).
  2103.  
  2104.            The following 'pseudo handles' may also be used as
  2105.            a starting point for a search:
  2106.  
  2107.            Pseudo Handle             Nodes Searched
  2108.            -------------             --------------
  2109.            HANDLE_PHYS_TREE          Physical Device Nodes
  2110.            HANDLE_SYS_TREE           Logical Device Nodes
  2111.            HANDLE_DEFAULT_SYSBUS     System Bus Nodes (ISA/EISA/uC)
  2112.            HANDLE_X_BUS              Planar Bus Nodes
  2113.            HANDLE_PCI_BUS            PCI Bus Nodes
  2114.  
  2115.  
  2116.          SearchKey (PSZ)
  2117.  
  2118.            Pointer to an ASCIIZ string containing the key to be located.
  2119.  
  2120.            If the key supplied ends in a "*" then all keys which match
  2121.            the characters up to the "*" will be returned.
  2122.  
  2123.            Key searches are treated as case-insensitive.
  2124.  
  2125.            Ex: "AHA154X_*" will find all Adaptec adapters that
  2126.                are registered.
  2127.  
  2128.                "FIXDSK_*" will return all Fixed Disk logical device
  2129.                handles.
  2130.  
  2131.            Note: This api does not currently support full (regular
  2132.                  pattern matching), i.e. only "*" is supported.
  2133.  
  2134.            Note: Adapter keys values are chosen at the discretion of
  2135.                  the device driver supplier and may be subject to change.
  2136.  
  2137.  
  2138.          &HandleList (PHANDLELIST)
  2139.  
  2140.            Pointer to the following structure:
  2141.  
  2142.            HANDLELIST
  2143.            ----------
  2144.            struct
  2145.            {
  2146.              USHORT        cMaxHandles;
  2147.              USHORT        cHandles;
  2148.              HADAPTER      Handles[1];
  2149.            };
  2150.  
  2151.            cMaxHandles (USHORT)
  2152.                Number handles can be accepted in the Handles
  2153.                array. This field must be set by the caller.
  2154.  
  2155.                Note: The default HANDLELIST type provides room for one
  2156.                      handle. cMaxHandles must be set to 1 in this case.
  2157.  
  2158.                Example: Suppose 10 handles are expected.
  2159.  
  2160.                  #define MAX_HANDLE_COUNT 10
  2161.  
  2162.                  #define HLISTSIZE(c) ( sizeof(HANDLELIST) +  \
  2163.                                         (c-1) * sizeof(HADAPTER) )
  2164.  
  2165.                  UCHAR HandleList[HLISTSIZE(MAX_HANDLE_COUNT)];
  2166.  
  2167.                  PHANDLELIST pHndList = (PHANDLELIST) HandleList;
  2168.  
  2169.                  pHndList->cMaxHandles = MAX_HANDLE_COUNT;
  2170.  
  2171.            cHandles (USHORT)
  2172.                Actual handle count found. This field must be
  2173.                initially set to zero by the caller.
  2174.  
  2175.                Note: The number of handles reported by this field may
  2176.                      exceed cMaxHandles. This indicates that the
  2177.                      HandleList structure supplied was too small.
  2178.                      The count will be set to the number of handles
  2179.                      actually found.
  2180.  
  2181.            Handles[] (HADAPTER)
  2182.                Array containing the Resource Manager handles that
  2183.                match the specified key.
  2184.  
  2185.  
  2186.                 ----------------------------------
  2187.  
  2188.  
  2189.  
  2190. RMHandleToType - Return the type of a Resource Manager handle.
  2191.  
  2192.  
  2193. Purpose: Returns the type of Resource Manager handle supplied.
  2194.  
  2195.  
  2196. Calling Sequence:
  2197.  
  2198.          rc = RMHandleToType( (RMHANDLE)    hHandle,
  2199.                               (PUSHORT)     &HandleType )
  2200.  
  2201.          Note: On systems where the resource manager driver is
  2202.                not installed, the library interface code will
  2203.                return RMRC_NOT_INSTALLED.
  2204.  
  2205.  
  2206. Calling Parameters:
  2207.  
  2208.          hHandle (RMHANDLE)
  2209.  
  2210.            Handle whose type is to be determined.
  2211.  
  2212.  
  2213.          &HandleType (USHORT)
  2214.  
  2215.            Pointer to variable to contain the returned handle type.
  2216.  
  2217.            The following handle types can be returned:
  2218.  
  2219.            HandleType            Description         API
  2220.            ----------            -----------         ---
  2221.            HANDLE_TYPE_INVALID   Invalid Handle      None
  2222.            HANDLE_TYPE_DRIVER    Driver Handle       RMCreateDriver
  2223.            HANDLE_TYPE_ADAPTER   Adapter Handle      RMCreateAdapter
  2224.            HANDLE_TYPE_DEVICE    Device Handle       RMCreateDevice
  2225.            HANDLE_TYPE_RESOURCE  Resource Handle     RMAllocResource
  2226.            HANDLE_TYPE_LOGDEV    Logical Dev Handle  RMCreateLDev
  2227.            HANDLE_TYPE_SYSDEV    System Name Handle  RMCreateSysName
  2228.  
  2229.  
  2230.                 ----------------------------------
  2231.  
  2232.  
  2233.  
  2234. RMHandleToParent - Return a parent handle.
  2235.  
  2236.  
  2237. Purpose: Returns the parent handle of the handle provided.
  2238.  
  2239.  
  2240. Calling Sequence:
  2241.  
  2242.          rc = RMHandleToParent( (RMHANDLE)    hHandle,
  2243.                                 (PRMHANDLE)   &hParent );
  2244.  
  2245.          Note: On systems where the resource manager driver is
  2246.                not installed, the library interface code will
  2247.                return RMRC_NOT_INSTALLED.
  2248.  
  2249.  
  2250. Calling Parameters:
  2251.  
  2252.          hHandle (RMHANDLE)
  2253.  
  2254.            Handle whose parent is to be determined.
  2255.  
  2256.            Valid handle types for this api include:
  2257.  
  2258.            HandleType            Description
  2259.            ----------            -----------
  2260.            HANDLE_TYPE_ADAPTER   Adapter Handle
  2261.            HANDLE_TYPE_DEVICE    Device Handle
  2262.            HANDLE_TYPE_RESOURCE  Resource Handle
  2263.            HANDLE_TYPE_LOGDEV    Logical Dev Handle
  2264.            HANDLE_TYPE_SYSDEV    System Name Handle
  2265.  
  2266.            Note: The parent of a resource handle is considered
  2267.                  to be the owner of the resource.
  2268.  
  2269.  
  2270.          &hParent (PRMHANDLE)
  2271.  
  2272.            Handle of the parent of the specified handle.
  2273.  
  2274.                 ----------------------------------
  2275.  
  2276.  
  2277.  
  2278. RMUpdateAdjunct - Update adjunct data structure.
  2279.  
  2280.  
  2281. Purpose: Update an existing adjunct structure.
  2282.  
  2283.  
  2284. Calling Sequence:
  2285.  
  2286.          rc = RMUpdateAdjunct( (HDRIVER)  hDriver,
  2287.                                (HDEVICE)  hDevice,
  2288.                                (USHORT)   AdjunctIndex,
  2289.                                (PADJUNCT) &AdjunctData   );
  2290.  
  2291.          Note: On systems where the resource manager driver is
  2292.                not installed, the library interface code will
  2293.                return RMRC_NOT_INSTALLED.
  2294.  
  2295.  
  2296. Calling Parameters:
  2297.  
  2298.          hDriver (HDRIVER)
  2299.  
  2300.            Driver handle of the device driver which created
  2301.            the adjunct data.
  2302.  
  2303.          hDevice (HDEVICE)
  2304.  
  2305.            Device Handle which the adjunct data is associated
  2306.            with.
  2307.  
  2308.          AdjunctIndex (USHORT)
  2309.  
  2310.            Index to the adjunct structure to be replaced.
  2311.  
  2312.          &AdjunctData
  2313.  
  2314.            Pointer to an adjunct structure containing replacement
  2315.            data for the adjunct indicated.
  2316.  
  2317.  
  2318.            Note: For Resource Manager Version 1.01, the size of the
  2319.                  replacement adjunct structure must not exceed the
  2320.                  size of the existing adjunct.
  2321.  
  2322.  
  2323.                 ----------------------------------
  2324.  
  2325.  
  2326.  
  2327. RMAdjToHandleList - Update adjunct data structure.
  2328.  
  2329.  
  2330. Purpose: This api searches for Resource Manager nodes which match
  2331.          the adjunct structure specified. A list of node handles
  2332.          and adjunct indices are in the HandleList structure provided
  2333.          by the caller.
  2334.  
  2335.  
  2336. Calling Sequence:
  2337.  
  2338.          rc = RMAdjToHandleList( (PADJUNCT)       &AdjunctData,
  2339.                                  (HADAPTER)       hStartNode
  2340.                                  (PAJDHANDLELIST) &AdjHandleList );
  2341.  
  2342.          Note: On systems where the resource manager driver is
  2343.                not installed, the library interface code will
  2344.                return RMRC_NOT_INSTALLED.
  2345.  
  2346. Calling Parameters:
  2347.  
  2348.          &AdjunctData (PADJUNCT)
  2349.  
  2350.            Pointer to a an adjunct structure to search for.
  2351.  
  2352.            Note: The ADJUNCT type contains a union of data structures
  2353.                  of varying lengths. When searching for a particular
  2354.                  adjunct, it is recommended to set the length field
  2355.                  of the AdjunctData structure passed to the exact
  2356.                  length of the adjunct structure being located.
  2357.  
  2358.                  For example:
  2359.  
  2360.                  /* Correct */
  2361.  
  2362.                  AdjData.AdjLength = ADJ_HEADER_SIZE + sizeof(ADD_UNIT);
  2363.  
  2364.                 /* Incorrect */
  2365.  
  2366.                  AdjData.AdjLength = sizeof(ADJUNCT);
  2367.  
  2368.  
  2369.          hStartNode (HADAPTER)
  2370.  
  2371.            Handle of resource manager node to start the search at.
  2372.  
  2373.  
  2374.          &AdjHandleList (PADJHANDLELIST)
  2375.  
  2376.            Pointer to the following structure:
  2377.  
  2378.            ADJHANDLELIST
  2379.            -------------
  2380.            struct
  2381.            {
  2382.              USHORT        cMaxHandles;
  2383.              USHORT        cHandles;
  2384.              ADJINFO       Adj[1];
  2385.            };
  2386.  
  2387.            ADJINFO
  2388.            -------
  2389.            sturct
  2390.            {
  2391.              HADAPTER    hAdapter;
  2392.              USHORT      AdjIndex;
  2393.            };
  2394.  
  2395.            cMaxHandles (USHORT)
  2396.                Number handles can be accepted in the Handles
  2397.                array. This field must be set by the caller.
  2398.  
  2399.                Note: The default ADJHANDLELIST type provides room for one
  2400.                      handle. cMaxHandles must be set to 1 in this case.
  2401.  
  2402.                      Refer example in RMKeyToHandleList if more
  2403.                      than one Adjunct handle is expected.
  2404.  
  2405.            cHandles (USHORT)
  2406.                Actual handle count found. This field must be
  2407.                initially set to zero by the caller.
  2408.  
  2409.                Note: The number of handles reported by this field may
  2410.                      exceed cMaxHandles. This indicates that the
  2411.                      HandleList structure supplied was too small.
  2412.                      The count will be set to the number of handles
  2413.                      actually found.
  2414.  
  2415.            Adj[] (ADJINFO)
  2416.                Array of ADJINFO structures. The ADJINFO structure
  2417.                contains the following fields:
  2418.  
  2419.                hAdapter (HADAPTER)
  2420.                    Handle of the owner of adjunct data which matches
  2421.                    the adjunct specified.
  2422.  
  2423.                AdjIndex (USHORT)
  2424.                    Index of the adjunct structure found.
  2425.  
  2426.  
  2427.  
  2428.                 ----------------------------------
  2429.  
  2430.  
  2431.  
  2432. RMHDevToHLDev - Return Physical Device associated with a Logical Device.
  2433.  
  2434.  
  2435. Purpose: Returns the Logical Device handle (HLDEV) that is associated
  2436.          with the physical device handle indicated.
  2437.  
  2438.  
  2439. Calling Sequence:
  2440.  
  2441.          rc = RMHandleToParent( (HDEVICE)    hDevice,
  2442.                                 (HLDEV)      hStartLDev
  2443.                                 (PHLDEV)     &hLDev       );
  2444.  
  2445.          Note: On systems where the resource manager driver is
  2446.                not installed, the library interface code will
  2447.                return RMRC_NOT_INSTALLED.
  2448.  
  2449.  
  2450. Calling Parameters:
  2451.  
  2452.          hDevice
  2453.  
  2454.            Resource manager handle to the physical device. The
  2455.            logical device handle which is associated with
  2456.            this physical device handle will be returned.
  2457.  
  2458.  
  2459.          &hStartLDev (HLDEV)
  2460.  
  2461.            Handle of the logical device to start the search
  2462.            at. If all logical nodes are to be searched then
  2463.            HANDLE_LDEV_ROOT should be specified.
  2464.  
  2465.  
  2466.          &hLDev (PHLDEV)
  2467.  
  2468.            Pointer to variable to receive the logical device
  2469.            handle (HLDEV) associated with the physical device
  2470.            specified.
  2471.  
  2472.  
  2473.  
  2474.                 ----------------------------------
  2475.  
  2476.  
  2477.  
  2478. RMResToHandleList - Return List of Adapter/Device Handles which own a
  2479.                     resource.
  2480.  
  2481.  
  2482. Purpose: Returns a list of Adapter/Device handles which own the
  2483.          resource indicated.
  2484.  
  2485.  
  2486. Calling Sequence:
  2487.  
  2488.          rc = RMResToHandleList( (PRESOURCESTRUCT) &ResStruct,
  2489.                                  (PHANDLELIST)     &HandleList );
  2490.                                                                  α
  2491.          Note: On systems where the resource manager driver is
  2492.                not installed, the library interface code will
  2493.                return RMRC_NOT_INSTALLED.
  2494.  
  2495.  
  2496. Calling Parameters:
  2497.  
  2498.          &ResStruct (PRESOURCESTRUCT)
  2499.  
  2500.            Pointer to a RESOURCESTRUCT to be whose owners are to be
  2501.            located.
  2502.  
  2503.            Refer to RMAllocResource for a description of the
  2504.            RESOURCESTRUCT datatype.
  2505.  
  2506.  
  2507.          &HandleList (PHANDLELIST)
  2508.  
  2509.            Structure of containing list of Adapter/Device handles
  2510.            which include the specified resource.
  2511.  
  2512.            Refer to RMKeyToHandleList for a description of the
  2513.            HANDLELIST datatype.
  2514.  
  2515.  
  2516.                 ----------------------------------
  2517.  
  2518.  
  2519.  
  2520. RMActivateAdapter - Indicate adapter (re)activation.
  2521.  
  2522.          Preliminary/Advance Information
  2523.  
  2524.          Note: This api is not currently supported in Resource Manager
  2525.                Version 1.01 and will return RMRC_NOT_SUPPORTED in all
  2526.                cases.
  2527.  
  2528.  
  2529. Purpose: This API indicates that an adapter that was deactivated via
  2530.          RMDeactivateAdapter is now available.
  2531.  
  2532.          A device driver would use this api to notify other resource
  2533.          manager clients that a PCMCIA adapter (PCCard) which was
  2534.          removed without being properly quiesced has been reinserted
  2535.          and reinitialized. This allows the system to do a proper
  2536.          shutdown on devices attached to this adapter.
  2537.  
  2538.  
  2539. Calling Sequence:
  2540.  
  2541.          rc = RMActivateAdapter( (HDRIVER)  hDriver,
  2542.                                  (HADAPTER) hAdapter );
  2543.  
  2544.          Note: On systems where the resource manager driver is
  2545.                not installed, the library interface code will
  2546.                return RMRC_NOT_INSTALLED.
  2547.  
  2548.  
  2549. Calling Parameters:
  2550.  
  2551.          hDriver (HDRIVER)
  2552.  
  2553.            Driver handle of the device driver which created
  2554.            the adapter.
  2555.  
  2556.  
  2557.          hAdapter (HADAPTER)
  2558.  
  2559.            Handle of the adapter to be activated.
  2560.  
  2561.  
  2562.                 ----------------------------------
  2563.  
  2564.  
  2565.  
  2566. RMDeactivateAdapter - Indicate adapter deactivation.
  2567.  
  2568.          Preliminary/Advance Information
  2569.  
  2570.          Note: This api is not currently supported in Resource Manager
  2571.                Version 1.01 and will return RMRC_NOT_SUPPORTED in all
  2572.                cases.
  2573.  
  2574.  
  2575. Purpose: This API indicates that an adapter currently attached
  2576.          to the system is nolonger available.
  2577.  
  2578.          A device driver would use this api to notify other resource
  2579.          manager clients that a PCMCIA adapter (PCCard) which was
  2580.          removed from the system. The return code from this API
  2581.          will indicate whether the driver should wait for reactivation
  2582.          of the adapter or can proceed with destroying the Resource
  2583.          Manager handle for this adapter via RMDestroyAdapter.
  2584.  
  2585.  
  2586. Calling Sequence:
  2587.  
  2588.          rc = RMDeactivateAdapter( (HDRIVER)  hDriver,
  2589.                                    (HADAPTER) hAdapter );
  2590.  
  2591.          Note: On systems where the resource manager driver is
  2592.                not installed, the library interface code will
  2593.                return RMRC_NOT_INSTALLED.
  2594.  
  2595.  
  2596. Calling Parameters:
  2597.  
  2598.          hDriver (HDRIVER)
  2599.  
  2600.            Driver handle of the device driver which created
  2601.            the adapter.
  2602.  
  2603.  
  2604.          hAdapter (HADAPTER)
  2605.  
  2606.            Handle of the adapter to be deactivated.
  2607.  
  2608.  
  2609.                 ----------------------------------
  2610.  
  2611.  
  2612.  
  2613. RMCreateLinkDevice - Create a composite physical device
  2614.  
  2615.          Preliminary/Advance Information
  2616.  
  2617.          Note: This api is not currently supported in Resource Manager
  2618.                Version 1.01 and will return RMRC_NOT_SUPPORTED in all
  2619.                cases.
  2620.  
  2621.  
  2622. Purpose: This API indicate links a set of independent physical
  2623.          devices together to form a new composite device.
  2624.  
  2625.          An example of this would be a RAID DASD driver which
  2626.          would combine a number of independent physical
  2627.          devices together to form a new 'pseudo' device
  2628.          with the attributes of a DASD type device.
  2629.  
  2630.  
  2631. Calling Sequence:
  2632.  
  2633.          rc = RMCreateLinkDevice( (HDRIVER)       hDriver,
  2634.                                   (PHDEVICE)      &hLinkDevice,
  2635.                                   (PDEVICESTRUCT) &DeviceStruct,
  2636.                                   (PAHDEVICES)    &hDeviceList    );
  2637.  
  2638.          Note: On systems where the resource manager driver is
  2639.                not installed, the library interface code will
  2640.                return RMRC_NOT_INSTALLED.
  2641.  
  2642.  
  2643. Calling Parameters:
  2644.  
  2645.          hDriver (HDRIVER)
  2646.  
  2647.            Driver handle of the device driver which created
  2648.            the composite device.
  2649.  
  2650.  
  2651.          &hLinkDevice (PHDEVICE)
  2652.  
  2653.            Pointer to variable to receive the device handle for the
  2654.            composite device to be created.
  2655.  
  2656.  
  2657.          &DeviceStruct (PDEVICESTRUCT)
  2658.  
  2659.            Pointer to a structure (DEVICESTRUCT) which describes
  2660.            the composite device to be created. Refer to RMCreateDevice
  2661.            for a description of the DEVICESTRUCT datatype.
  2662.  
  2663.  
  2664.          &hDeviceList (PAHDEVICES)
  2665.  
  2666.            Pointer to the following structure.
  2667.  
  2668.            AHDEVICES
  2669.            ---------
  2670.            struct
  2671.            {
  2672.              ULONG     NumDevices;
  2673.              HDEVICE   hDevice[1];
  2674.            };
  2675.  
  2676.            NumDevices (ULONG)
  2677.                 Number of device handles in the hDevice array.
  2678.  
  2679.            hDevice[] (HDEVICE)
  2680.                 An array of physical device handles which will comprise
  2681.                 the composite device.
  2682.  
  2683.  
  2684.                 ----------------------------------
  2685.  
  2686.  
  2687.  
  2688. RMModifyResources - Modify Adapter/Device resource sets.
  2689.  
  2690.  
  2691. Purpose: This API allow for modification of resources owned
  2692.          by an existing adapter or device. Resource handles
  2693.          may be deleted or added to an adapter or device
  2694.          using this api.
  2695.  
  2696.  
  2697. Calling Sequence:
  2698.  
  2699.          rc = RMModifyResources( (HDRIVER)   hDriver,
  2700.                                  (HADAPTER)  hAdapter,
  2701.                                  (USHORT)    ModifyAction,
  2702.                                  (HRESOURCE) hResource);
  2703.  
  2704.          Note: On systems where the resource manager driver is
  2705.                not installed, the library interface code will
  2706.                return RMRC_NOT_INSTALLED.
  2707.  
  2708.  
  2709. Calling Parameters:
  2710.  
  2711.          hDriver (HDRIVER)
  2712.  
  2713.            Driver handle of the device driver which created
  2714.            the adapter or device.
  2715.  
  2716.  
  2717.          &hAdapter (HADAPTER)
  2718.  
  2719.            Handle of the adapter or device whose resource set
  2720.            is to be modified.
  2721.  
  2722.  
  2723.          ModifyAction (USHORT)
  2724.  
  2725.            RM_MODIFY_ADD
  2726.                 Add the resource handle indicated to the adapter
  2727.                 or device.
  2728.  
  2729.            RM_MODIFY_DELETE
  2730.                 Delete the resource handle indicated.
  2731.  
  2732.            Note: Deleting a resource implicitly causes an
  2733.                  RMDeallocResource to occur, i.e. the resource
  2734.                  handle is no longer valid.
  2735.  
  2736.  
  2737.          hResource (HRESOURCE)
  2738.  
  2739.            Handle of the resource to be added or deleted.
  2740.  
  2741.  
  2742.                 ----------------------------------
  2743.  
  2744.  
  2745.  
  2746. RMGetNodeInfo - Return resource manager node information.
  2747.  
  2748.  
  2749. Purpose: This API returns the information content of the
  2750.          resource manager handle indicated.
  2751.  
  2752.  
  2753. Calling Sequence:
  2754.  
  2755.          rc = RMGetNodeInfo( (RMHANDLE)         hRMHandle,
  2756.                              (PRM_GETNODE_DATA) &NodeInfo,
  2757.                              (USHORT)           NodeInfoSize );
  2758.  
  2759.          Note: On systems where the resource manager driver is
  2760.                not installed, the library interface code will
  2761.                return RMRC_NOT_INSTALLED.
  2762.  
  2763.  
  2764. Calling Parameters:
  2765.  
  2766.          &hRMHandle (RMHANDLE)
  2767.  
  2768.            Resource manager handle whose information is to be
  2769.            returned. The following handle types are allowed:
  2770.  
  2771.            HandleType            Description
  2772.            ----------            -----------
  2773.            HANDLE_TYPE_DRIVER    Driver Handle
  2774.            HANDLE_TYPE_ADAPTER   Adapter Handle
  2775.            HANDLE_TYPE_DEVICE    Device Handle
  2776.            HANDLE_TYPE_LOGDEV    Logical Device Handle
  2777.            HANDLE_TYPE_SYSDEV    System Name Handle
  2778.  
  2779.  
  2780.          &NodeInfo (PRM_GETNODE_DATA)
  2781.  
  2782.            Pointer to a buffer that will contain the resource manager
  2783.            node information.
  2784.  
  2785.            RM_GETNODE_DATA
  2786.            ---------------
  2787.            struct
  2788.            {
  2789.              ULONG          RMNodeSize;
  2790.              RM_NODE        RMNode;
  2791.            };
  2792.  
  2793.            RMNodeSize (ULONG)
  2794.                Total data length returned in bytes. If the buffer
  2795.                provided is too small to contain the Resource
  2796.                Manager node information, this field will contain
  2797.                the required buffer length.
  2798.  
  2799.            RMNode (RM_NODE)
  2800.                A structure containing information about the requested
  2801.                Resource Manager node.
  2802.  
  2803.            RM_NODE
  2804.            -------
  2805.            struct
  2806.            {
  2807.              ULONG             VersionInfo;
  2808.              ULONG             NodeType;
  2809.              RMHANDLE          DriverHandle;
  2810.  
  2811.              union
  2812.              {
  2813.                PADAPTERSTRUCT  pAdapterNode;
  2814.                PDEVICESTRUCT   pDeviceNode;
  2815.                PLDEVSTRUCT     pLDevNode;
  2816.                PSYSNAMESTRUCT  pSysNameNode;
  2817.                PDRIVERSTRUCT   pDriver;
  2818.              };
  2819.              PRESOURCELIST     pResourceList;
  2820.            }
  2821.  
  2822.            VersionInfo (ULONG)
  2823.                Version of the resource management driver.
  2824.  
  2825.  
  2826.            NodeType (ULONG)
  2827.                The type of node the handle provided refers to.
  2828.  
  2829.  
  2830.            pAdapterNode (PADAPTERSTRUCT)
  2831.                This field contains a pointer to a structure
  2832.                that describes the Resource Manager node. This
  2833.                structure is a copy of the structure that was
  2834.                provided when the node was created.
  2835.  
  2836.                The pointer type selected from the union should
  2837.                be based on the NodeType value returned.
  2838.  
  2839.  
  2840.                NodeType           Structure Pointer   API
  2841.                ----------         -----------------   ---
  2842.                RMTYPE_ADAPTER     pAdapterNode        RMCreateAdapter
  2843.                RMTYPE_DEVICE      pDeviceNode         RMCreateDevice
  2844.                RMTYPE_LDEV        pLDevNode           RMCreateLDev
  2845.                RMTYPE_SYSNAME     pSysNameNode        RMCreateSysName
  2846.                RMTYPE_DRIVER      pDriver             RMCreateDriver
  2847.  
  2848.  
  2849.            pResourceList (PRESOURCELIST)
  2850.                Pointer to a structure containing a count and list
  2851.                of resource assigned to this node.
  2852.  
  2853.  
  2854.            PRESOURCELIST
  2855.            -------------
  2856.            struct
  2857.            {
  2858.              ULONG          Count;
  2859.              RESOURCESTRUCT Resource[1];
  2860.            }
  2861.  
  2862.            Count (ULONG)
  2863.                Count of resource structures returned.
  2864.  
  2865.            Resource[] (RESOURCESTRUCT)
  2866.                Array of resource structures assigned to this
  2867.                node. Refer to RMAllocResource for a description
  2868.                of the RESOURCESTRUCT datatype.
  2869.  
  2870.  
  2871.  
  2872.                 ----------------------------------
  2873.  
  2874.  
  2875.  
  2876. RMParseSCSIInquiry - Build SCSI device description.
  2877.  
  2878.  
  2879. Purpose: This api is provided as a convenience device drivers
  2880.          dealing with SCSI devices. It converts SCSI Inquiry
  2881.          Data for a device into a device key and description
  2882.          that may be used in RMCreateDevice.
  2883.  
  2884.  
  2885. Calling Sequence:
  2886.  
  2887.          rc = RMParseScsiInquiry( (PVOID)   &InquiryData,
  2888.                                   (PSZ)     DescBuffer,
  2889.                                   (USHORT)  DescBufferSize  );
  2890.  
  2891.          Note: On systems where the resource manager driver is
  2892.                not installed, the library interface code will
  2893.                return RMRC_NOT_INSTALLED.
  2894.  
  2895.  
  2896. Calling Parameters:
  2897.  
  2898.          &InquiryData (PVOID)
  2899.  
  2900.            Pointer a buffer containing SCSI Inquiry data for
  2901.            the device.
  2902.  
  2903.  
  2904.          DescBuffer (PSZ)
  2905.  
  2906.            Pointer to buffer which will receive the device key
  2907.            and device description built by this api.
  2908.  
  2909.            This data may be used as the device description
  2910.            field (DevDescriptName) of the DEVICESTRUCT used
  2911.            to create the device.
  2912.  
  2913.            Refer to the RMCreateDevice api description for further
  2914.            information.
  2915.  
  2916.  
  2917.          DescBufferSize (USHORT)
  2918.  
  2919.            Size of the DescBuffer in bytes.
  2920.  
  2921.                 ----------------------------------
  2922.  
  2923.  
  2924.  
  2925. Return Codes
  2926. ------------
  2927.  
  2928. This section describes Resource Manager return codes.
  2929.  
  2930. All Resource Manager APIs return a 16-bit return code.
  2931.  
  2932. RMRC_SUCCESS
  2933.    Indicates that the indicated Resource Manager api completed
  2934.    completed successfully.
  2935.  
  2936.    In cases where the resource management driver (RESOURCE.SYS)
  2937.    is not installed, some of the basic resource management calls
  2938.    will return RMRC_SUCCESS, but essentially are a no-operation.
  2939.  
  2940.    The purpose of this is to allow the use of the same device driver
  2941.    across various OS/2 versions without the driver needing to
  2942.    check specific return codes indicating whether or not the
  2943.    resource management facility is available.
  2944.  
  2945. RMRC_NOTINITIALIZED
  2946.    This indicates than a resource management library was not properly
  2947.    initialized.
  2948.  
  2949.    A device driver must call RMCreateDriver prior to issuing any
  2950.    other resource management call.
  2951.  
  2952. RMRC_BAD_DRIVERHANDLE
  2953. RMRC_BAD_ADAPTERHANDLE
  2954. RMRC_BAD_DEVICEHANDLE
  2955. RMRC_BAD_RESOURCEHANDLE
  2956. RMRC_BAD_LDEVHANDLE
  2957. RMRC_BAD_SYSNAMEHANDLE
  2958.    The expected Resource Manager handle was not provided:
  2959.  
  2960.    1. The handle was not a valid resource manager handle.
  2961.    2. The handle did not point to the type of object the api
  2962.       required.
  2963.  
  2964.    The individual return codes indicate the type of handle that
  2965.    was expected.
  2966.  
  2967. RMRC_BAD_DEVHELP
  2968.    The resource management library requires the C-variable
  2969.    (Device_Help) to initialized to the Device Help entry point
  2970.    prior to issuing the first resource management call.
  2971.  
  2972. RMRC_NULL_POINTER
  2973.    A resource manager api received a NULL value for a pointer
  2974.    that was expected to contain a valid 16:16 address.
  2975.  
  2976. RMRC_NULL_STRINGS
  2977.    A descriptive text pointer in a DRIVERSTRUCT, ADAPTERSTRUCT
  2978.    or DEVICESTRUCT datatype was found to be NULL rather than
  2979.    pointing to the expected ASCIIZ text data.
  2980.  
  2981. RMRC_BAD_VERSION
  2982.    The Resource Manager level indicated on the RMCreateDriver
  2983.    api is not supported by the resource management driver
  2984.    currently installed:
  2985.  
  2986.    Possible causes:
  2987.  
  2988.    1. Downlevel Resource Management driver (RESOURCE.SYS).
  2989.    2. MajorVer/MinorVer fields of DRIVERSTRUCT not properly
  2990.       initizalized.
  2991.  
  2992.    Refer to RMCreateDriver api description for further information.
  2993.  
  2994. RMRC_RES_ALREADY_CLAIMED
  2995.    The requested resource is allocated exclusively to another driver,
  2996.    or the requested sharing mode conflicts with the sharing mode
  2997.    with other owners of the resource.
  2998.  
  2999. RMRC_INVALID_PARM_VALUE
  3000.    A non-handle/non-pointer variable contains an invalid or out
  3001.    or range value.
  3002.  
  3003.    Possible causes:
  3004.  
  3005.    1. An invalid decode width specified when allocating
  3006.       an I/O Port range.
  3007.    2. A handle search being performed with cMaxHandles set to 0.
  3008.  
  3009. RMRC_OUT_OF_MEMORY
  3010.    The resource manager is out of memory.
  3011.  
  3012. RMRC_BUFFER_TOO_SMALL
  3013.    The buffer provided to receive information from a Resource Manager
  3014.    api was too small.
  3015.  
  3016. RMRC_IRQ_ENTRY_ILLEGAL
  3017.    A resource manager API was issued at "Interrupt Time". Resource
  3018.    manager api request may only be issued in at "Task Time" or
  3019.    "Init Time".
  3020.  
  3021. RMRC_NOT_IMPLEMENTED
  3022.    The resource manager API requested is not implement in the version
  3023.    of resource manager you are currently using.
  3024.  
  3025. RMRC_NOT_INSTALLED
  3026.    The Resource Management driver (RESOURCE.SYS) is required to service
  3027.    this API request but is not installed.
  3028.  
  3029.  
  3030.                 ----------------------------------
  3031.  
  3032.  
  3033.  
  3034. Linking Resource Manager Services
  3035. ---------------------------------
  3036.  
  3037. This section discusses the mechanics of adding Resource Management
  3038. services to your driver.
  3039.  
  3040. Overview
  3041. --------
  3042.  
  3043. OS/2 Resource Management consists of two components:
  3044.  
  3045. 1. RESOURCE.SYS
  3046.  
  3047.    This is a base device driver. On OS/2 WARP and subsequent versions,
  3048.    this driver is provided as part of the product and is loaded
  3049.    automatically without an explicit CONFIG.SYS "BASEDEV=" statement.
  3050.  
  3051. 2. RMCALLS.LIB
  3052.  
  3053.    This library is linked with your device driver and provides the
  3054.    interface code to communicate with the RESOURCE.SYS driver.
  3055.  
  3056.    In addition, the RMCALLS library will provide rudimentary support
  3057.    for the following subset of Resource Manager APIs.
  3058.  
  3059.    RMCreateDriver       RMDestroyDriver
  3060.    RMCreateAdapter      RMDestroyAdapter
  3061.    RMCreateDevice       RMDestroyDevice
  3062.    RMCreateLDev         RMDestroyLDev
  3063.    RMCreateSysName      RMDestroySysName
  3064.    RMAllocResource      RMDeallocResource
  3065.  
  3066.    In general this support consists of returning a handle value of -1L
  3067.    and a return code of RMRC_SUCCESS as applicable.
  3068.  
  3069.    This support is enabled when your driver is run on a system
  3070.    that does not have RESOURCE.SYS installed, such as an earlier
  3071.    version of OS/2.
  3072.  
  3073.  
  3074. RMCALLS Library Data
  3075. --------------------
  3076.  
  3077. The RMCALLS library references the following four variables:
  3078.  
  3079.    PFN Device_Help;
  3080.  
  3081.    This variable must be initialized by your driver prior to calling
  3082.    any resource manager APIs. It is expected to contain the
  3083.    Device Help entry point provided in the OS/2 Init Request
  3084.    Packet your driver receives.
  3085.  
  3086.    ULONG RMFlags   = NULL;
  3087.    PFNRM RM_Help0  = NULL;
  3088.    PFNRM RM_Help3  = NULL;
  3089.  
  3090.    These are data variables must be initialized to zero prior
  3091.    prior to calling any Resource Manager APIs. The recommended
  3092.    method is to specify C-initializers when declaring the variables.
  3093.  
  3094. These variables must be allocated by your driver. If you plan to
  3095. use Resource Manager services after your driver has completed
  3096. initialization you must insure that these variables are not discarded.
  3097.  
  3098. Note: If you do not declare these variables, you will get an linker
  3099.       error message indicating that they are missing.
  3100.  
  3101. RMCALLS Library Code
  3102. --------------------
  3103.  
  3104. The code portion of the RMCALLS library is included in a segment
  3105. named RMCode.
  3106.  
  3107. There are three alternatives in handling the code in this segment.
  3108.  
  3109. 1. Combine RMCode with your driver's default code segment.
  3110.  
  3111.    This would be done if your driver does not intend to use Resource
  3112.    Manager services after initialization. Since the library code
  3113.    is linked after OBJ text, it would be discarded as your driver
  3114.    discards its initialization code.
  3115.  
  3116. 2. Combine RMCode with your driver's swappable code segment.
  3117.  
  3118.    If your driver intends to use Resource Manager services after
  3119.    its initialization, and has a swappable code segment, then
  3120.    RMCode should be combined with this segment.
  3121.  
  3122. 3. Place RMCode in its own swappable segment.
  3123.  
  3124.    If your driver does not have a swappable code segment then
  3125.    the RMCode will reside in its own swappable segment by
  3126.    default.
  3127.  
  3128.  
  3129.  
  3130.                 ----------------------------------
  3131.  
  3132.  
  3133.  
  3134. Resource Manager IOCTLs
  3135. -----------------------
  3136.  
  3137. RESOURCE.SYS provides two IOCTLs that allow a ring 3 application
  3138. to obtain a 'snapshot' of the resource management data structures.
  3139.  
  3140. Obtaining a snapshot of the resource management data structures
  3141. consists of two steps:
  3142.  
  3143. 1. A data structure representing a depth-first traversal of the
  3144.    resource manager node structure is obtained.
  3145.  
  3146.    For each node traversed the following information is provided:
  3147.  
  3148.    - A Resource Manager handle to access the node.
  3149.    - The depth of the node in the tree structure.
  3150.  
  3151. 2. A copy of each resource manager node may be obtained
  3152.    by supplying the node handle returned in Step 1.
  3153.  
  3154.  
  3155.  
  3156. Category 80 - Resource Manager
  3157. ------------------------------
  3158.  
  3159. Function 02  - Enumerate Resource Manager Nodes
  3160.  
  3161. This function traverses the Resource Manager node structure
  3162. and returns the results of the traversal as a list of
  3163. Resource Manager handles and traversal depth.
  3164.  
  3165. Parameter Packet Format
  3166.  
  3167. All Parameter packet fields are input fields for this function.
  3168.  
  3169. Field                   Length
  3170. -----                   ------
  3171. Command                 WORD
  3172.  
  3173. Command
  3174.      This field must be indicates the type of traversal being requested.
  3175.  
  3176.      RM_COMMAND_PHYS
  3177.         Traverse the Physical Devices tree. This traversal
  3178.         reports all Adapters and Devices registered with the
  3179.         Resource Manager.
  3180.  
  3181.      RM_COMMAND_LOG
  3182.         Traverse the Logical Device tree. This traversal
  3183.         reports all Logical Devices and System Names registered
  3184.         with the Resource Manager.
  3185.  
  3186.      RM_COMMAND_DRVR
  3187.         Traverse the Device Driver list. This traversal
  3188.         reports all device drivers registered and any adapters,
  3189.         devices, logical devices, or system names associated
  3190.         with each driver.
  3191.  
  3192.  
  3193. Data Packet Format
  3194.  
  3195. All data packet fields are output fields for this function.
  3196.  
  3197. Field                   Length
  3198. -----                   ------
  3199. NumEntries              ULONG
  3200. NodeEntry[]             8 * NumEntries
  3201.  
  3202.  
  3203. NumEntries
  3204.      This field reports the number of node entries traversed.
  3205.  
  3206. NodeEntry[]
  3207.      This field is an array of the following structure:
  3208.  
  3209.      NODEENTRY
  3210.      ---------
  3211.      struct
  3212.      {
  3213.        RMHANDLE RMHandle;
  3214.        ULONG    Depth;
  3215.      };
  3216.  
  3217.      RMHandle (RMHANDLE)
  3218.          Resource Manager handle of the node traversed.
  3219.  
  3220.      Depth (ULONG)
  3221.          Level of the tree structure the node resides on.
  3222.  
  3223.  
  3224.  
  3225. Category 80 - Resource Manager
  3226. ------------------------------
  3227.  
  3228. Function 01  - Get Resource Manager Node Data
  3229.  
  3230. This function returns the contents of the Resource Manager
  3231. node indicated by the handle provided.
  3232.  
  3233. Parameter Packet Format
  3234.  
  3235. All Parameter packet fields are input fields for this function.
  3236.  
  3237.  
  3238. Field                   Length
  3239. -----                   ------
  3240. RMHandle                ULONG
  3241.  
  3242. RMHandle
  3243.      This field must be initialized to the handle of the Resource
  3244.      Manager Node to be interrogated.
  3245.  
  3246.  
  3247. Data Packet Format
  3248.  
  3249. All data packet fields are output fields for this function.
  3250.  
  3251. Field                   Length
  3252. -----                   ------
  3253. RMNodeSize              ULONG
  3254. RMNode                  ----
  3255.  
  3256.  
  3257. RMNodeSize (ULONG)
  3258.     Size of the Resource Manager node information returned.
  3259.  
  3260. RMNode
  3261.     This field is set to a structure describing the Resource
  3262.     Manager node and its associated resources.
  3263.  
  3264.     RM_NODE
  3265.     -------
  3266.     struct
  3267.     {
  3268.       ULONG             VersionInfo;
  3269.       ULONG             NodeType;
  3270.       RMHANDLE          DriverHandle;
  3271.  
  3272.       union
  3273.       {
  3274.         PADAPTERSTRUCT  pAdapterNode;
  3275.         PDEVICESTRUCT   pDeviceNode;
  3276.         PLDEVSTRUCT     pLDevNode;
  3277.         PSYSNAMESTRUCT  pSysNameNode;
  3278.         PDRIVERSTRUCT   pDriver;
  3279.       };
  3280.       PRESOURCELIST     pResourceList;
  3281.     }
  3282.  
  3283.     VersionInfo (ULONG)
  3284.         Version of the resource management driver.
  3285.  
  3286.  
  3287.     NodeType (ULONG)
  3288.         The type of node the handle provided refers to.
  3289.  
  3290.  
  3291.     pAdapterNode (PADAPTERSTRUCT)
  3292.         This field contains a pointer to a structure
  3293.         that describes the Resource Manager node. This
  3294.         structure is a copy of the structure that was
  3295.         provided when the node was created.
  3296.  
  3297.         The pointer type selected from the union should
  3298.         be based on the NodeType value returned.
  3299.  
  3300.  
  3301.         NodeType           Structure Pointer   API
  3302.         ----------         -----------------   ---
  3303.         RMTYPE_ADAPTER     pAdapterNode        RMCreateAdapter
  3304.         RMTYPE_DEVICE      pDeviceNode         RMCreateDevice
  3305.         RMTYPE_LDEV        pLDevNode           RMCreateLDev
  3306.         RMTYPE_SYSNAME     pSysNameNode        RMCreateSysName
  3307.         RMTYPE_DRIVER      pDriver             RMCreateDriver
  3308.  
  3309.  
  3310.     pResourceList (PRESOURCELIST)
  3311.         Pointer to a structure containing a count and list
  3312.         of resource assigned to this node.
  3313.  
  3314.  
  3315.     PRESOURCELIST
  3316.     -------------
  3317.     struct
  3318.     {
  3319.       ULONG          Count;
  3320.       RESOURCESTRUCT Resource[1];
  3321.     }
  3322.  
  3323.     Count (ULONG)
  3324.         Count of resource structures returned.
  3325.  
  3326.     Resource[] (RESOURCESTRUCT)
  3327.         Array of resource structures assigned to this
  3328.         node. Refer to RMAllocResource for a description
  3329.         of the RESOURCESTRUCT datatype.
  3330.  
  3331.