
Overview
--------

RESOURCE.SYS provides a set of C-callable services to other
device drivers to record usage of basic hardware resources
as well as to provide end users with physical and logical
'views' of their system.

Resources
---------

Hardware resources usage tracked by RESOURCE.SYS include:

  - I/O Port Ranges
  - IRQ Levels
  - DMA Channels
  - Timer Channels

When resources are assigned, various levels of 'sharing'
are allowed. The type of sharing allowed depends on
the underlying characteristics of the devices including.
Resource sharing options include EXCLUSIVE, SHARED,
and MULTIPLEXED. The definition of these options are
discussed in the section on "Managing System Resources".

Port Probing / Adapter Identification
-------------------------------------

Driver writers are encouraged to identify their hardware settings
during driver initialization directly rather than relying on the
end-user to provide this information.

The Resource Manager APIs facilitate this process by identifying
resources (I/O Ports, DMA Channels, IRQ Levels) that are already
claimed by drivers that initialized previously. A driver using
the resource management calls can avoid inadvertently corrupting
the state adapters of initialized by previously loaded drivers.

Adapters/Drivers/Devices
------------------------

In addition to basic hardware resources, the RESOURCE.SYS driver
manages the following constructs:

   Drivers
   -------
   A driver usually represents a software module responsible
   for management of one or more pieces of physical hardware.

   In addition, drivers include value-added subsystems
   that may not interact with physical hardware
   directly.

   Note: In order to use other Resource Manager APIs, it is necessary
         to provide a Driver Handle, which is obtained when declaring
         a driver.

   Adapters
   --------
   Adapters are defined as devices which convert from one bus protocol
   to another.

   For example, a SCSI adapter, converts the host bus protocol, (ISA
   EISA, PCI) to SCSI Bus protocols.

   The system bus itself (ISA, EISA, PCI) is represented
   in the Resource Manager as an adapter, converting from the
   CPU internal bus protocols, to a standard host bus protocol.

   In some cases, adapters may not directly correspond
   to physical packaging. An example of this could be a CD-ROM
   port on a multifunction sound board being represented as
   a separate adapter. However, it is generally encouraged to try
   to 'align' adapters with the physical packaging of the system
   help end-users to identify their hardware easily.


   Devices
   -------
   Devices are defined in their 'traditional' meaning of end-user
   devices. This includes, printers, disks, cdroms, etc.


Adapter/Device Ownership
------------------------

Adapters, and Devices are associated with each other in a
Parent-Child-Sibling relationship. A driver is associated with
each Adapter or Device node.

The Resource Manager automatically creates Adapters, and Devices
representing basic system resources such as the CPU and system
busses during its initialization.

In addition devices managed directly by the OS/2 Kernel such as
the Interrupt controller (PIC) and DMA Channels
are automatically defined.



                          System Root

                              
                              
                              V

                            CPU_0

                              
             Ŀ
                                            
             V                V               V

           X_BUS           ISA_BUS         PCI_BUS

             
             V

   Ŀ
                                                       
   V         V         V             V             V        V

 PIC_0     PIC_1     DMA_0         DMA_1          RTC      VGA

                                
  IRQ_0    IRQ_8    DMA_CH_0     DMA_CH_4
  IRQ_1    IRQ_9    DMA_CH_1     DMA_CH_5
           IRQ_10                DMA_CH_6
  IRQ_3    IRQ_11   DMA_CH_3     DMA_CH_7
  IRQ_4    IRQ_12
  IRQ_5    IRQ_13
  IRQ_6    IRQ_14
  IRQ_7    IRQ_15



As device drivers initialize, additional Adapter and Device nodes
are created by the device drivers issuing Resource Manager API calls.

                          System Root

                              
                              
                              V

                            CPU_0

                              
             Ŀ
                                            
             V                V               V

           X_BUS           ISA_BUS         PCI_BUS

             
             Ŀ
                        
                        
                        V
     Ŀ
                                             
     V                  V                      V

   KBD_0              IDE_0                   DKT_0

     IBMKBD.SYS         IBM1S506.ADD         IBM1FLPY.ADD
     ----------         ------------         ------------
     I/O 60-64          I/O 1F0-1F7, 3F6     I/O 3F2-3F5, 3F7
     IRQ 8              IRQ 14               IRQ 6
    V                   V                     V

  KEYB_101            DISK_0                DSKT_0


Each node has associated resources owned by the
underlying device or adapter and the software driver responsible for
managing the adapter or device.

Device/Adapter Keys
-------------------

Each Adapter/Device node contains text describing the adapter or device.

To facilitate searching for a particular node, the beginning characters
of the descriptive text are assumed to be a key.

Keys are subject to the following rules:

1.) Any sibling nodes, i.e. nodes connected to the same parent
    must have unique keys.

2.) Keys end at either the first blank character or the 16th
    consecutive non-blank character.

3.) Keys are part of the descriptive text and must consist of
    printable ascii characters.

It is recommended that adapter nodes be given unique keys based
on their product name or function:

For example:

    CPU_0     - CPU x486

    IDE_0     - Generic IDE Channel Adapter

    AHA154X_0 - Adaptec 154X SCSI Adapter
    AHA154X_1

    PAS16     - ProAudio Spectrum Audio Adapter

If multiple occurrences of the same type of adapter can occur,
keys myst be made unique by appending a _0, _1, ..., suffix
to the key.

Note: The the Resource APIs can automatically generate the _0,
      _1, based on the adapter number supplied. Refer to
      the RMCreateAdapter API description for further information.

It is recommended that device nodes follow the naming convention
provided below:

    COMM_0        - Serial Port
    DISK_0        - DASD Device
    CDROM_0       - CDROM Device
    TAPE_0        - Tape Device
    PRINTER_0     - Printer Device
    SCANNER_0     - Scanner Device

Note: The the Resource APIs can automatically generate the _0,
      _1, based on the device number supplied. This is done
      by including a "#" character at the end of the key. The
      RMCreateAdapter/RMCreateDevice APIs will replace the "#"
      character with the adapter or device number indicated.

      For example

      "DSKT_#  - 1.44MB diskette drive"

      Will be converted to:

      "DSKT_0  - 1.44 MB diskette drive"

      Provided the an adjunct structure containing the device
      number (ADJ_DEVICE_NUMBER) is passed on the RMCreateDevice
      API call. Adjunct data structures are discussed in the next
      section.

Keys for SCSI devices should use the above device types followed
by _(t,l) corresponding to the SCSI device Target/Lun.

For example:


    DISK_(0,0)
    CDROM_(3,0)


Note: RMParseSCSIInquiry will automatically generate
      appropriate keys for SCSI devices. An adjunct structure
      containing the device target/lun (ADJ_SCSI_TARGET_LUN)
      should be passed on the RMCreateDevice API call.

Adjunct Data
------------

In some cases, it is necessary to pass data to the Resource
Manager APIs that may be relevant, in one case but not in another
call to the same API. In these cases, this optional data is passed
in a linked list of structures called an AdjunctList.

The contents of the structures are determined by the adjuct type.
which are defined in RMBASE.H. A few of the more common adjunct
types are listed here.


    ADJ_DEVICE_NUMBER -   Contains the zero-based unit number for the
                          device being created. The Resource Manager
                          will use this number to enumerate the
                          key for the device.


    ADJ_ADAPTER_NUMBER -  Contains the zero-based adapter number for
                          the adapter being created. The Resource Manager
                          will use this number to enumerate the key
                          for the adapter.

    ADJ_SCSI_TARGET_LUN - Contains the SCSI target/lun for the device
                          being created. The Resource Manager will generate
                          a SCSI type enumeration suffix as described
                          above.

    ADJ_ADD_UNIT        - Contains the ADD/DM ADD Handle and Unit Handle
                          assigned to the device being created.



Managing System Resources
-------------------------

When a device driver allocates resources, it specifies
the level of 'sharing' the driver is willing to accept. The level
of sharing selected depends on the characteristics of the
hardware, i.e. its ability to coordinate usage of IRQ or DMA channels
with other adapters as well as the 'importance' of other functions which may
need the same IRQ level.

Resources are allocated on a first-come first-served basis.

If a driver requests a resource that has been previously
allocated to another driver, then the sharing mode selected
by the earlier driver be used to determine if the new driver's
request will be granted.


The following resource sharing options are available


 - EXCLUSIVE - The resource (I/O Port, DMA Channel, etc.)
               is committed to the owner until it is
               explicitly released. Any other that include
               this resource will be denied.

 - SHARED    - The resource will be granted to any requester
               that also requests the resource as shared.
               This implies that the users of the resource
               may use it at anytime without interfering
               with each other. An example of this would
               be a shared interrupt on a uC or EISA
               bus machine.

 - MULTIPLEXED - The resource will be granted to any requester
               that also requests the resource as multiplexed.
               Multiplexed (unlike shared) implies that only
               one owner may actively be using the resource
               and that there explicit notification between
               owners to control who is using the resource.
               In general this sharing protocol is private to
               of the Multiplexed resource.

 - GRANTYIELD - The resource will be granted to any requester
               that also requests the resource as GRANTYIELD.
               GRANTYIELD implies that the owner of the resource
               is willing to participate in an Resource Manager
               arbitrated sharing of a resource.

               Note: GRANTYIELD protocol is not currently Version
                     1.01 of RESOURCE.SYS.



Logical Devices Management
--------------------------

Note: The following section pertains primarily to Device Managers
      and Device Drivers which assume similar functions. It may be
      skipped unless there is a specific interest in these subjects.

OS/2 uses aliases to identify various physical devices. Typically these
aliases are short descriptive names that are familiar to most
users, such as DISK_0, A:, C:, COM1, LPT1.

The use of aliases simplify the operating systems (end-users)
view of the system in several ways:

1.) The implementation of a physical device, for example, a disk,
    actually depends on combination of the System Bus, a SCSI or
    IDE adapter and the disk device. It is convenient to the
    end user to abstract this to a simple name such as DISK_0,
    DISK_1, etc. rather than using the full path name to the device.

2.) The operating system may subdivide or group devices so that
    the physical device boundaries are no longer relevant. For
    instance partitioning subdivides a physical disk into
    a series of separate drives, while a RAID array may group
    several physical devices into a single drive.

3.) The operating system may have alternate views of the same
    physical device. For example, a Physical Serial Port, may
    be used as a FAX port FMD1$ or a ASYNC port COM1 depending
    on the application using the port.

In order to provide a mapping from the operating system (end-user)
view of the system to the actual implementing hardware,
the Resource Manager maintains a separate node structure called
a logical tree.




                               LDEV Root

                                  
        Ŀ
                                                        
        V            V            V            V            V

       DASD        CDROM         TAPE        SERIAL      PARALLEL

                                           
                                            COMM_1
                                             ------
                                             Alias: \ISA\COMM_0
                                             
                                              FMD1$
                                              COM1:
                    Ŀ
        
         DISK_0                           CDROM_0
         ------                           -------
         Alias: \ISA\IDE_0\DISK_0         Alias: \ISA\AHA154X_0\CDROM_(2,0)
                                         
          C:                              G:
          E:
          F:
        
        
         DISK_1
          ------
          Alias: \ISA\AHA154X_0\DISK_(0,0)
          
           D:


The logical tree contains two types of nodes:


   LDEVs
   -----

   Logical device nodes represent aliases of nodes on the
   physical device tree.


   SYSNAMEs
   --------

   System Name nodes represent named divisions of the parent LDEV.

   Depending on the nature of the device, these may be alternate
   definitions of the LDEV which are mutually exclusive (e.g.
   FMD1$ and COM1:) or may be shared such (e.g. C:, E: F:).


Logical Devices and System Name are associated with each other in a
Parent-Child-Sibling relationship. A driver is associated with
each LDEV node.

The Resource Manager automatically creates Logical Device nodes
representing basic system device types such as DASD, CDROM, TAPE,
SERIAL, and PARALLEL during its initialization. Device Managers
and certain device drivers (such as COM.SYS) create additional
Logical Devices and System Name nodes as they declare new
devices to the OS/2 Kernel.



Summary of Resource Manager APIs
--------------------------------

The previous sections explain the basic resource management
concepts. Prior to providing a detailed description of
each API, it may be helpful to group the APIs into function
based sets:


Physical Node Management
------------------------

  These APIs create Driver, Adapter and Device nodes:
  - RMCreateDriver
  - RMCreateAdapter
  - RMCreateDevice

  These APIs delete Driver, Adapter and Device nodes:
  - RMDestroyDriver
  - RMDestroyAdapter
  - RMDestroyDevice



Resource Management
-------------------

  These APIs allocate/deallocate resources.
  - RMAllocResource
  - RMDeallocResource

  These APIs claim/release resources allocated with GrantYield
  protocols.
  - RMClaimResources
  - RMReleaseResources

  This API edits an existing device or adapter resource sets, either
  adding or removing resources.
  - RMModifyResources



Node Searches
-------------

  This API searches for nodes matching a particular key:
  - RMKeyToHandleList

  This API searches for nodes using a particular resource:
  - RMResToHandleList

  This API searchs for nodes containing matching adjunct data:
  - RMAdjToHandleList

  This API returns the LDEV associated with a physical device node:
  - RMHDevtoHLDev


Node Information
---------------

  This API provide the type of node the Handle is associated with:
  - RMHandleToType

  This API returns the handle of the node's parent:
  - RMHandleToParent

  This API returns the contents of the Resource Manager node indicated
  by the Handle:
  - RMGetNodeInfo



Logical Node Management
-----------------------

  These APIs creates/destroy a Logical Device Node:
  - RMCreateLDev
  - RMDestroyLDev

  These APIs create/destroy a System Name Node:
  - RMCreateSysName
  - RMDestroySysName

  This API creates a 'pseudo device' representing a group of
  physical devices:
  - RMCreateLinkDevice


                ----------------------------------


RMCreateDriver - Obtain a Driver Handle

Purpose: This api registers basic information about the calling
         device driver with the Resource Manager. A driver handle
         (HDRIVER) is returned by this API which is required by other
         Resource Manager APIs to identify the requestor.

         The first call to this API causes the Resource Manager
         interface code, i.e. the part that is linked to your
         device driver to initialize. Therefore, normally, this
         would be the first Resource Manager call a driver
         would normally make.

         Information about the driver registering with the
         Resource Manager is passed in a DRIVERSTRUCT which
         is described below.


Calling Sequence:

         rc = RMCreateDriver( (PDRIVERSTRUCT) &DriverStruct,
                              (PHDRIVER)      &hDriver         );


         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS and a driver handle of -1L.


Calling Parameters:


         &hDriver

           Pointer to a variable to receive the returned driver
           handle.

         &DriverStruct (PDRIVERSTRUCT)

           Pointer to the following structure

           DRIVERSTRUCT
           ------------
           struct
           {
              PSZ       DrvrName;
              PSZ       DrvrDescript;
              PSZ       VendorName;
              UCHAR     MajorVer;
              UCHAR     MinorVer;
              DATESTAMP Date;
              USHORT    DrvrFlags;
              USHORT    DrvrType;
              USHORT    DrvrSubType;
              PFNRMCB   DrvrCallback;
           };


           DrvrName (PSZ)
               Pointer to ASCIIZ name of device driver.

               Ex: "IBM1FLPY.ADD"
                   "C:\MMOS2\MVPRODD.SYS"

           DrvrDescript (PSZ)
               Pointer brief ASCIIZ description of device driver.

               Ex: "ISA/EISA Diskette ADD Driver"
                   "ProAudio Spectrum Device Driver"

           VendorName (PSZ)
               Pointer to ASCIIZ vendor name

               Ex: "IBM Corporation"

           MajorVer (UCHAR)
           MinorVer (UCHAR)
               RM interface level. This is the version of
               the Resource manager APIs your driver is using.

               Currently these fields must be set to CMVERSION_MAJOR
               and CMVERSION_MINOR which are defined in RMBASE.H

               Note: This is not the version or level of your driver.
                     If this field does not contain a valid value, the
                     RMCreateDriver request will fail.


           Date (DATESTAMP)
               A structure containing the year/month/day to identify
               the version of your driver.

               DATESTAMP
               ---------
               struct
               {
                 USHORT Year;
                 UCHAR  Month;
                 UCHAR  Day;
               };

               Year (USHORT)
                  Year as a 16-bit integer.

               Month (UCHAR)
                  Month as an 8-bit integer. Allowable range (1-12).

               Day (UCHAR)
                  Day of month as na 8-bit integer. Allowable range (1-31).

               Ex: October 11, 1994

               pDS->Date.Year  = 1994;
               pDS->Date.Month = 10;
               pDS->Date.Day   = 11;



           DrvrFlags (USHORT)
               Driver attribute flags. Unused bits must be set to zero
               by the caller.

               Valid flag values: (Also see DRF_* in RMBASE.H).

               DRF_STATIC
                 Driver is loaded at system IPL time.


           DrvrType    (USHORT)
           DrvrSubType (USHORT)
               These fields identify the type of interface your
               driver supports.

               The following categories are defined:

               DRT_PCMCIA

               A driver which conforms to PCMCIA specifications,

                 DRS_SOCKETSERV

                 A driver which supports the PCMCIA socket service
                 API.

                 DRS_CARDSERV

                 A driver which supports the PCMCIA card service
                 API.

                 DRS_CLIENT

                 A client driver which solely supports PCMCIA options.

                 Note: If a driver supports both PCMCIA and non-PCMCIA
                       options, then the driver category reflect
                       the non-PCMCIA usage.

               DRT_ADDDM

               A driver which conform to Adapter Device Driver /
               Device Manager Interfaces.

                 DRS_DM

                 An ADD/DM driver which acts as a Device Manager
                 interfacing directly with the OS2 Kernel.

                 For example: OS2DASD.DMD, OS2CDROM.DMD.

                 DRS_FILTER

                 An ADD/DM driver which acts as Filter.

                 DRS_ADD

                 An ADD/DM driver which acts as an Adapter Device
                 Driver.

                 For example: IBM1FLPY.ADD, IBM1S506.ADD.

                 DRS_DM_TRANSPORT

                 A Device Manager whose primary purpose is
                 to convert another protocol to ADD/DM protocols.

                 For example: OS2ASPI.DMD converts Adaptec ASPI
                 protocols to ADD/DM protocols.

               DRT_OS2

               Character or Block device drivers which interface directly
               to the OS/2 Kernel.

                 DRS_CHAR

                 A driver which creates a character devices intended
                 for end-user usage.

                 DRS_BLOCK

                 A driver which creates block devices intended for
                 end-user usage.

                 DRS_APP_HELPER

                 A driver provides private services intended for
                 a particular application rather than the end-user
                 directly.

               DRT_AUDIO

                 A driver which conforms to the OS/2 Multimedia
                 APIs.


               DRT_SERVICE

                 A driver which provides services to other drivers.

                 For example: RESOURCE.SYS


                ----------------------------------



RMDestroyDriver - Destroy a Driver Handle


Purpose: This api releases a driver handle created by RMCreateDriver.

         Usually, if a driver determines it should fail its
         initialization, i.e. unload, it will issue this call if
         it had previously issued an RMCreateDriver request.

         Issuing this call will delete all Devices/Adapaters/Resource
         records created under this driver handle.

         Note: Drivers which intend to unload must still issue the
               appropriate DevHelp calls to release IRQs and other
               kernel resources.

Calling Sequence:

         rc = RMDestroyDriver( (HDRIVER) hDriver );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS.

Calling Parameters:

         hDriver

         Handle of the driver to be destroyed.


                ----------------------------------



RMCreateAdapter - Obtain an Adapter Handle

Purpose: This api allows a driver to register an adapter with
         the resource manager. An adapter handle (HADAPTER) is
         returned by this api to identify the adapter.

         Information about the adapter being registered is passed
         in an ADAPTERSTRUCT which is described below.

         When adapter is registered, a list of resource handles
         representing hardware resources used by this adapter
         may be optionally passed.

Calling Sequence:

         rc = RMCreateAdapter( (HDRIVER)        hDriver,
                               (PHADAPTER)      &hAdapter
                               (PADAPTERSTRUCT) &AdapterStruct,
                               (HDEVICE)        hParentDevice,
                               (PAHRESOURCE)    &ResourceList  );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS and an adapter handle of -1L.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver creating this adapter.


         &hAdapter (PHADAPTER)

           Pointer to variable to receive the returned adapter
           handle.

         &AdapterStruct

           Pointer to the following structure:

           ADAPTERSTRUCT
           -------------
           struct
           {
             PSZ          AdaptDescriptName;
             USHORT       AdaptFlags;
             USHORT       BaseType;
             USHORT       SubType;
             USHORT       InterfaceType;
             USHORT       HostBusType;
             USHORT       HostBusWidth;
             PADJUNCT     pAdjunctList;
             ULONG        Reserved;
           };

           AdaptDescriptName (PSZ)
               Pointer to an ASCIIZ string containing the adapter
               key and a brief description the adapter.

               Ex: "FLOPPY_#  Diskette Controller"
                   "PAS16 ProAudio Spectrum Adapter"
                   "AHA154X_#  Adaptec 154X SCSI Adapter"

               Note: Up to the first 16 non-blank characters of the
                     are used as a key to locate this adapter.

                     The RMCreateAdapter API will substitute the "#"
                     character with the Adapter Number supplied in
                     the Adjunct List.

                     Refer to "Adapter/Device Keys on page x" for
                     additional information concerning device/adapter
                     keys.


           AdaptFlags (USHORT)
               Adapter attribute flags. Unused flags must be set to
               zero by the caller.

               Valid flag values:

               AS_16MB_ADDRESS_LIMIT
                 Adapter does not support data transfers to storage
                 above 16MB (24-bit addressing limit).


           The next three fields provide provide a category of the
           adapter being created.

               BaseType (USHORT)
                 Indicate the general functional category the adapter:

                 AS_BASE_MSD    - Mass storage including disk, tape, cdrom
                                  etc.

                 AS_BASE_COMM   - Communications, including serial and parallel
                                  ports.

                 AS_BASE_PERIPH - System board components including, DMA
                                  controllers, Interrupt controller, etc.


               Subtype (USHORT)
                 Indicates the interface supported by the adapter:

                 For example:

                 SCSI Adapter  - AS_BASE_MSD/AS_SUB_SCSI
                 IDE Adapter   - AS_BASE_MSD/AS_SUB_IDE

                 Serial Port   - AS_BASE_COMM/AS_SUB_SERIAL
                 Parallel Port - AS_BASE_COMM/AS_SUB_PARALLEL


               InterfaceType (USHORT)
                 Provides specific interface information.

                 For example:

                 Parallel Port  - AS_BASE_COMM/AS_SUB_PARALLEL/AS_INTF_ECP

                 These fields provide provide a category of the
                 adapter being created.

           Refer to RMBASE.H for a complete list of adapter categories.

           The next two fields describe the host bus the adapter
           supports.

           Note: This field describes how the adapter is connected to
                 the host system rather than how the adapter is connected
                 to the devices it supports.

               HostBusType
                 Describes how the adapter is attached to the host
                 system. Typically ISA, EISA, uC, PCI, etc..


               HostBusWidth
                 Indicates the maximum width of host bus data transfers
                 the adapter supports.

           Refer to RMBASE.H for values for these fields.


           pAdjunctList (PADJUNCT)

               Pointer to a linked list of Adjunct Data structures.

               The following adjunct structures should be included
               in the list:

                 ADJ_ADAPTER_NUMBER
                     This adjunct contains the zero based adapter number
                     for the adapter being created.


         hParentDevice (HDEVICE)

           Indicates the handle of the parent Adapter/Device for
           the adapter being being created.

           In general this field may be set to null in
           which case the adapter will be assigned to
           the default system bus. If the system contains
           multiple buses such as ISA/PCI, the HostBusType
           field will be used to choose the appropriate
           bus.

         &ResourceList (PAHRESOURCE)

           Pointer to a structure containing a count and a
           list of resource handles to be assigned to this
           adapter.


           AHRESOURCE
           ----------
           struct
           {
             ULONG     NumResource;
             HRESOURCE hResource[1];
           }

           Note: As an alternative, resources may be added after
                 the adapter is created by using the RMModifyAdapter
                 API. In this case the ResourceList pointer should
                 be set to NULL.

                ----------------------------------



RMDestroyAdapter - Destroy an Adapter Handle


Purpose: This api releases an adapter handle created by RMCreateAdapter.

         Normally, once an adapter handle is created, it would not be
         destroyed. However, in PCMCIA environments, where adapters
         may be inserted or removed 'on-the-fly' this call allows
         the PCMCIA Client driver to keep the resource manager
         records consistent with the PC-Cards currently installed.

         Destroying an adapter, also destroys any child devices
         associated with the adapter. Any resource handles
         allocated to the adapter or child devices are also
         released.


Calling Sequence:

         rc = RMDestroyAdapter( (HDRIVER)  hDriver
                                (HADAPTER) hAdapter );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS.

Calling Parameters:

         hDriver

           Handle of driver supplied when adapter was created.


         hAdapter

           Handle of the adapter to be destroyed.


                ----------------------------------



RMCreateDevice - Obtain an Device Handle


Purpose: This api allows a driver to register a devices with
         the resource manager and to assign the device to an adapter.
         A device handle (HDEVICE) is returned by this api to
         identify the device.

         Information about the device being registered is passed
         in a DEVICESTRUCT which is described below.

         When a device is registered, a list of resource handles
         representing hardware resources used by this device
         may be optionally assigned to the device.




Calling Sequence:


         rc = RMCreateDevice( (HDRIVER)       hDriver,
                              (PHDEVICE)      &hDevice,
                              (PDEVICESTRUCT) &DeviceStruct,
                              (HADAPTER)      hParentAdapter,
                              (PAHRESOURCE)   pahResource);

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS and an adapter handle of -1L.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver creating this device.


         &hDevice (PHDEVICE)

           Pointer to variable to receive the returned device
           handle.


         &DeviceStruct

           Pointer to the following structure:

           DEVICESTRUCT
           ------------
           struct
           {
             PSZ      DevDescriptName;
             USHORT   DevFlags;
             USHORT   DevType;
             PADJUNCT pAdjunctList;
           };

           DevDescriptName (PSZ)
               Pointer to an ASCIIZ string containing the device
               key and a brief description the device.

               Ex: "DSKT_#  1.44MB Diskette Drive"
                   "DISK_#   Fixed Disk"
                   "CDROM_#  MITSUMI CD-ROM FX001D D02"

               Note: Up to the first 16 non-blank characters of the
                     are used as a key to locate this device.

                     The RMCreateDevice API will substitute the "#"
                     character with the Device Number or SCSI Target/LUN
                     supplied in the Adjunct List.

                     Refer to "Adapter/Device Keys on page x" for
                     additional information concerning device/adapter
                     keys.


           DevFlags (USHORT)
               Device attribute flags. Unused flags must be set
               to zero by the caller.

               Valid flag values are:

               DS_REMOVEABLE_MEDIA
                   Device has removable media.

           DevType (USHORT)
               Device type.

               Valid device types include:

               DS_TYPE_DISK            All Direct Access Devices
               DS_TYPE_TAPE            Sequential Access Devices
               DS_TYPE_PRINTER         Printer Device
               DS_TYPE_PROCESSOR       Processor type device
               DS_TYPE_WORM            Write Once Read Many Device
               DS_TYPE_CDROM           CD-ROM Device
               DS_TYPE_SCANNER         Scanner Device
               DS_TYPE_OPT_MEM         Optical disk
               DS_TYPE_CHANGER         Changer device
               DS_TYPE_COMM            Communication devices
               DS_TYPE_ATAPI           ATAPI protocol device
               DS_TYPE_SCSI_ATT        SCSI Bus Attach (Bridge controller)
               DS_TYPE_SOCKET          PCMCIA Socket
               DS_TYPE_SLOT            ISA/uC/EISA/PCI Bus Slot
               DS_TYPE_PLANAR_CHIPSET  DMA/IRQ/TIMER Controllers
               DS_TYPE_IO              Input/Output
               DS_TYPE_AUDIO           Audio Device
               DS_TYPE_UNKNOWN         Unknown Device Type


           pAdjunctList (PADJUNCT)

               Pointer to a linked list of Adjunct Data structures.

               The following adjunct structures should be included
               in the list:

               ADD Drivers:

                 ADJ_ADD_UNIT
                     This adjunct contains the ADD Handle and ADD UnitNumber
                     the ADD driver will assign to the device.

               Non-SCSI Devices:

                 ADJ_DEVICE_NUMBER
                     This adjunct contains the zero based device number
                     for non-scsi devices.

                     For example, the nth CD-ROM supported by an adapter

               SCSI Devices:

                 ADJ_SCSI_TARGET_LUN
                     This adjunct contains the SCSI Target ID and Logical
                     Device Number (LUN) assigned to the device.

         hParentAdapter (HADAPTER)

           Indicates the handle of the parent Adapter for
           the device being being created.

         &ResourceList (PAHRESOURCE)

           Pointer to a structure containing a count and a
           list of resource handles to be assigned to this
           device.


           AHRESOURCE
           ----------
           struct
           {
             ULONG     NumResource;
             HRESOURCE hResource[1];
           }

           Note: Resources are normally assigned to the adapter
                 (parent) which owns the device. In some cases,
                 resources are used specifically by a particular
                 device rather than shared between multiple devices
                 supported by an adapter. In this case, resources
                 should be assigned to the device as appropriate.


                ----------------------------------



RMDestroyDevice - Destroy an Device Handle


Purpose: This api releases a device handle created by RMCreateDevice.

         Any resources assigned to the device are released the
         device is destroyed.



Calling Sequence:

         rc = RMDestroyDevice( (HDRIVER) hDriver
                               (HDEVICE) hDevice );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS.

Calling Parameters:

         hDriver

           Handle of driver supplied when device was created.


         hDevice

           Handle of the device to be destroyed.


                ----------------------------------



RMAllocResource - Obtain an Resource Handle


Purpose: This api allows a driver to register usage of a hardware
         resource.

         Resources which may be allocated include:

           I/O Port Range
           DMA Channel
           IRQ Level
           Timer Channel
           BIOS Memory Region

         A driver must issue this call and successfully obtain
         ownership of a resource prior to making any attempt
         to access the resource.

         Note: This includes non-destructive (read type) accesses.

         For I/O and BIOS Memory resources, searches to locate an
         available I/O or Memory region are supported.

         The resource to be allocated is described in a RESOURCESTRUCT
         which contains  C-union of structures which are resource
         type specific.

         This api returns a resource handle (HRESOURCE) which is
         used to identify usage of the resource by this driver.

         Resources are initially assigned to the driver issuing
         RMAllocResource request. This is done to facilitate
         driver doing hardware probing to determine if hardware
         it intends to support is installed.

         Once the driver determines that a supported adapter
         is present, it should register an adapter (RMCreateAdapter)
         and assign resource handles by providing a list
         of resource handles on the RMCreateAdapter API.

         If an adapter is not found, resources that are
         not assigned to a device or adapter must be released.
         See RMDeallocResource.


Calling Sequence:

         rc = RMAllocResource( (HDRIVER)         hDriver,
                               (PHRESOURCE)      &hResource,
                               (PRESOURCESTRUCT) &ResourceStruct );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS and an resource handle of -1L.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver requesting the resource.


         &hResource (PHRESOURCE)

           Pointer to variable to receive the returned resource
           handle.

         &ResourceStruct

           Pointer to the following structure:

           RESOURCESTRUCT
           --------------
           struct
           {
             ULONG ResourceType;
             union
             {
               IORESOURCE   IOResource;
               IRQRESOURCE  IRQResource;
               MEMRESOURCE  MEMResource;
               DMARESOURCE  DMAResource;
               TMRRESOURCE  TMRResource;
             };
             ULONG  Reserved;
           };

           ResourceType (ULONG)
               Indicates the type of resource being requested.

               Note: The resource structure contained in the union must
                      match the type of resource indicated by this field.

               Resource Requested  ResourceType    Resource Structure
               ------------------  ------------    ------------------
               I/O Port Range      RS_TYPE_I/O     IORESOURCE
               IRQ Level           RS_TYPE_IRQ     IRQRESOURCE
               BIOS Memory Region  RS_TYPE_MEM     MEMRESOURCE
               DMA Channel         RS_TYPE_DMA     DMARESOURCE
               Timer Channel       RS_TYPE_TIMER   TMRRESOURCE



           IOResource (IORESOURCE)

               For ResourceType = RS_TYPE_IO, the union contains the
               following structure:

               IORESOURCE
               ----------
               struct
               {
                 USHORT BaseIOPort;
                 USHORT NumIOPorts;
                 USHORT IOFlags;
                 USHORT IOAddressLines;
               };

               BaseIOPort
                  Specifies the start of the I/O Port range requested.
                  If a search is being performed, then this field
                  is considered the starting point for the search.

               NumIOPorts
                  Specifies number of contiguous I/O Ports requested.

               IOFlags
                  One of the following sharing mode flags
                  must be specified:

                    RS_IO_EXCLUSIVE
                    RS_IO_MULTIPLEXED
                    RS_IO_SHARED
                    RS_IO_GRANT_YIELD

                    Note: See section "Managing System Resources"
                          for a description on resource sharing
                          modes.

                  If a device driver and supported adapter is capable of
                  selecting a new I/O range and is participating
                  in Grant-Yield protocols, then the following flag
                  indicates the driver will accept reconfiguration
                  requests for this resource.

                    RS_IO_RECONFIGURE

                  If a search is to be performed the following
                  flag must be specified.

                    RS_SEARCH

                  Notes: When a search is performed and is successful, the
                         BaseIOPort field will be updated to indicate
                         the start of the allocated I/O Port range.

                         The port range returned will be aligned on
                         2^n boundary >= NumIOPorts.


               IOAddressLines
                  Specifies the number of address lines the adapter
                  can decode.

                  This field must contain the value 10 or 16.

                  Most current generation 16-bit adapters decode all
                  16 I/O address lines. PC-XT and some early 16-bit
                  adapters only decode 10 address lines.

                  Adapters which do not fully decode appear multiple
                  places in the IO Address space since they ignore
                  the high-order I/O address bits.

                  Note: Port allocations outside the ISA compatibility
                        range (100h - 3FFh) must indicate
                        IOAddressLines = 16.


           IRQResource (IRQRESOURCE)

               For ResourceType = RS_TYPE_IRQ, the union contains the
               following structure:

               IRQRESOURCE
               ----------
               struct
               {
                 USHORT          IRQLevel;
                 USHORT          PCIIrqPin;
                 USHORT          IRQFlags;
                 USHORT          Reserved;
                 PFNRMINTHANDLER pfnIntHandler;
               };

               IRQLevel
                  Specifies requested IRQ Level (0-15)

               PCIIrqPin
                  For PCI devices, set to one of the following
                  values based on the PCI Interrupt Pin assigned
                  to the device.

                  PCI Interrupt Pin          PCIIrqPin Value
                  -----------------          ---------------
                  None                       RS_PCI_INT_NONE
                  A                          RS_PCI_INT_A
                  B                          RS_PCI_INT_B
                  C                          RS_PCI_INT_C
                  D                          RS_PCI_INT_D

                  For non-PCI devices, this field must be set
                  to zero.

               IRQFlags
                  One of the following sharing mode flags
                  must be specified:

                    RS_IRQ_EXCLUSIVE
                    RS_IRQ_MULTIPLEXED
                    RS_IRQ_SHARED
                    RS_IRQ_GRANT_YIELD

                    Note: See section "Managing System Resources"
                          for a description on resource sharing
                          modes.

               pfnIntHandler
                  This field is reserved for future use and must
                  be set to zero.


           MEMResource (MEMRESOURCE)

               For ResourceType = RS_TYPE_MEM, the union contains the
               following structure:

               MEMRESOURCE
               ----------
               struct
               {
                 ULONG  MemBase;
                 ULONG  MemSize;
                 USHORT MemFlags;
                 USHORT ReservedAlign;
               };

               MemBase
                  Specifies the start of the BIOS Memory region requested
                  as physical address. If a search is being performed
                  then this is the starting point for the search.

               MemSize
                  Specifies the size of the BIOS Memory region requested
                  in bytes.

               MemFlags
                  One of the following sharing mode flags
                  must be specified:

                    RS_MEM_EXCLUSIVE
                    RS_MEM_MULTIPLEXED
                    RS_MEM_SHARED
                    RS_MEM_GRANT_YIELD

                    Note: See section "Managing System Resources"
                          for a description on resource sharing
                          modes.

                  If a device driver and adapter is capable of
                  selecting a new Memory Range and is participating
                  in Grant-Yield protocols, then the following flag
                  indicates the driver will accept reconfiguration
                  requests for this resource.

                    RS_MEM_RECONFIGURE

                  If a search is to be performed the following
                  flag must be specified.

                    RS_SEARCH

                  Notes: When a search is performed and is successful, the
                         MemBase field will be updated to indicate
                         the start of the allocated Memory range.

           DMAResource (DMARESOURCE)

               For ResourceType = RS_TYPE_DMA, the union contains the
               following structure:

               DMARESOURCE
               ----------
               struct
               {
                 USHORT DMAChannel;
                 USHORT DMAFlags;
               };

               DMAChannel
                  Specifies the number of the DMA Channel requested (0-7).

               DMAFlags
                  One of the following sharing mode flags
                  must be specified:

                    RS_DMA_EXCLUSIVE
                    RS_DMA_MULTIPLEXED
                    RS_DMA_SHARED
                    RS_DMA_GRANT_YIELD

                    Note: See section "Managing System Resources"
                          for a description on resource sharing
                          modes.

           TMRResource (TMRRESOURCE)

               For ResourceType = RS_TYPE_TIMER, the union contains the
               following structure:

               TMRRESOURCE
               ----------
               struct
               {
                 USHORT TMRChannel;
                 USHORT TMRFlags;
               };

               TMRChannel
                  Specifies the number of the Timer Channel requested (0-2).

               TMRFlags
                  One of the following sharing mode flags
                  must be specified:

                    RS_TMR_EXCLUSIVE
                    RS_TMR_MULTIPLEXED
                    RS_TMR_SHARED
                    RS_TMR_GRANT_YIELD

                    Note: See section "Managing System Resources"
                          for a description on resource sharing
                          modes.


                ----------------------------------



RMDeallocResource - Destroy an Resource Handle


Purpose: This api destroys a resource handle created by RMAllocResource.


Calling Sequence:

         rc = RMDeallocResourcer( (HDRIVER)  hDriver
                                  (HRESOURCE) hResource );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS.

Calling Parameters:

         hDriver

           Handle of driver supplied the resource was created.


         hResource

           Handle of the resource to be destroyed.


                ----------------------------------




RMClaimResources - Claim Grant/Yield Resources for an adapter


         Preliminary/Advance Information

         Note: This api is not currently supported in Resource Manager
               Version 1.01 and will return RMRC_NOT_SUPPORTED in all
               cases.


Purpose: This api indicates a driver requires the use of Grant/Yield
         resources for an adapter.

         The resource manager will attempt to assign resources
         to the driver issuing this request. If the requested
         resources are held by other drivers, then those drivers
         will be notified that a Grant/Yield request is in
         progress.

         If the resource manager cannot satisfy the RMClaimResource
         request in the time indicated, then the request will
         fail. In this case any pending resource requests to
         other drivers will be cancelled.



Calling Sequence:

         rc = RMClaimResources( (HDRIVER)  hDriver,
                                (HADAPTER) hAdapter,
                                (ULONG)    TimeoutMS );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver requesting the resource.


         hAdapter (HADAPTER)

           Handle of the adapter claiming its grant-yield resources.


         TimeoutMS (ULONG)

           Maximum time (milliseconds) to wait for RMClaimResources
           to be satisfied.

           Special timeout values:

           0L - Indicates that a RMClaimResources request should fail
                if resource are not immediately available.

          -1L - Indicates that a RMClaimResources request should wait
                indefinitely for resources to become available.


                ----------------------------------



RMReleaseResources - Release Grant/Yield Resources for an adapter


         Preliminary/Advance Information

         Note: This api is not currently supported in Resource Manager
               Version 1.01 and will return RMRC_NOT_SUPPORTED in all
               cases.


Purpose: This api indicates a driver no longer require use of Grant/Yield
         resources for an adapter.

         A driver may reclaim a grant-yield resource set for an
         adapter by issuing a RMClaimResources.


Calling Sequence:

         rc = RMReleaseResources( (HDRIVER)  hDriver,
                                  (HADAPTER) hAdapter );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver requesting the resource.


         hAdapter (HADAPTER)

           Handle of the adapter releasing its grant-yield resources.



                ----------------------------------



RMCreateLDev - Obtain a Logical Device Handle

Purpose: This api allows a driver to register a logical device with
         the resource manager. An logical device handle (HLDEV) is
         returned by this api to identify the logical device.

         Information about the logical device being registered is passed
         in an LDEVSTRUCT which is described below.


Calling Sequence:

         rc = RMCreateLDev( (HDRIVER)     hDriver,
                            (PHLDEV)      &hLDev,
                            (HDEVICE)     hAssocDevice,
                            (PLDEVSTRICT) &LDevStruct );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS and a logical device handle
               of -1L.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver creating this adapter.


         &hLDev (PHLDEV)

           Pointer to variable to receive the returned logical device
           handle.

         hAssocDevice (HDEVICE)

           Handle of the physical device/adapter that this logical
           device is aliasing.

           Note: This field may also contain an adapter handle
                 coerced to an HDEVICE type.

         &LDevStruct

           Pointer to the following structure:

           LDEVSTRUCT
           ----------
           struct
           {
             PSZ      LDevDescriptName;
             USHORT   LDevFlags;
             USHORT   LDevClass;
             HDEVICE  LDevHDevice;
             PADJUNCT pAdjunctList;
           };

           LDevDescriptName (PSZ)
               Pointer to an ASCIIZ string containing the logical device
               key and a brief description the device.

               Ex: "FIXDSK_#  Fixed Disk Drive"
                   "COMM_#    Serial Port"

               Note: Up to the first 16 non-blank characters of the
                     are used as a key to locate this device.

                     The RMCreateLDev API will substitute the "#"
                     character with the Device Number supplied in
                     the Adjunct List.

                     Refer to "Adapter/Device Keys on page x" for
                     additional information concerning device/adapter
                     keys.

           LDevFlags (USHORT)
               There currently no flags defined. This field must
               be initialized to zero by the called.

           LDevClass (USHORT)
               Specifies the type of logical device being created.

               The logical device returned will be made a child
               of resource manager node for the class of device
               specified.

               Logical Device Type            Class Node Name
               -------------------            ---------------
               LDEV_CLASS_DASD                DASD
               LDEV_CLASS_CDROM               CDROM
               LDEV_CLASS_SERIAL              SERIAL
               LDEV_CLASS_PARALLEL            PARALLEL
               LDEV_CLASS_TAPE                TAPE

               Refer to section on "Logical Device Management" for
               further information.

           LDevHDevice
               This field must be initialized to zero by the called.

               It is used to return the handle of physical device
               indicated by hAssocDevice, when a a copy of the logical
               device node is returned by RMGetNodeInfo.

           pAdjunctList (PADJUNCT)

               Pointer to a linked list of Adjunct Data structures.

               The following adjunct structures should be included
               in the list:

                 ADJ_DEVICE_NUMBER
                     This adjunct contains the zero based device number
                     for the logical device being created.


                ----------------------------------



RMDestroyLDev - Destroy a Logical Device Handle


Purpose: This api destroys a logical device handle created by
         RMCreateLDev.

         Destroying a logical device also destroys any system
         names associated with the logical device.


Calling Sequence:

         rc = RMDestroyLDev( (HDRIVER)  hDriver,
                             (HLDEV)    hLDev    );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created the logical
           device.


         hLDev (HLDEV)

           Handle of the logical device to be destroyed.


                ----------------------------------



RMCreateSysName - Obtain a System Name Handle

Purpose: This api allows a driver to register a system name with
         the resource manager and associate it with a logical device.
         A system name handle (HSYSNAME) is returned by this api
         to identify the system name.

         Information about the system name being registered is passed
         in an SYSNAMESTRUCT which is described below.


Calling Sequence:

         rc = RMCreateSysName( (HDRIVER)        hDriver,
                               (PHSYSNAME)      &hSysName,
                               (HLDEV)          hLDevParent,
                               (PSYSNAMESTRUCT) &SysNameStruct );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS and a system name handle
               of -1L.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver creating this adapter.


         &hSysName (PSYSNAME)

           Pointer to variable to receive the returned system name
           handle.

         hLDevParent (HLDEV)

           Handle of the logical device which the system name is
           associated, i.e. the parent of the system name.


         &SysNameStruct

           Pointer to the following structure:

           SYSNAMESTRUCT
           -------------
           struct
           {
             PSZ      SysDescriptName;
             PADJUNCT pAdjunctList;
             USHORT   SysFlags;
             USHORT   Reserved;
           };

           SysDescriptName (PSZ)
               Pointer to an ASCIIZ string containing the system name
               key and a brief description the system name.

               Ex: "C:    Logical DASD Volume"
                   "COM1: Communications Port"

           pAdjunctList
               Pointer to a linked list of Adjunct Data structures.

               The following adjunct structures should be included
               in the list:

                 ADJ_DASD_VOL
                     This adjunct is used for dasd type devices
                     to indicate the capacity and file system
                     type for drive letter indicated by the
                     system name.


                ----------------------------------



RMDestroySysName - Destroy a System Name Handle


Purpose: This api destroys a system name handle created by
         RMCreateSysName.


Calling Sequence:

         rc = RMDestroySysName( (HDRIVER)  hDriver,
                                (HSYSNAME) hSysName    );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_SUCCESS.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created the logical
           device.


         hSysName (HSYSNAME)

           Handle of the system name to be destroyed.


                ----------------------------------



RMADDToHDEVICE - Map an ADD/DM Handle to Resource Manager Device Handle


         Preliminary/Advance Information

         Note: This api will be removed in the next Resource Manager
               release.

               Use RMAdjToHandleList rather than this api to maintain
               compatibility with future Resource Manager releases.


Purpose: This api converts an ADD/DM ADD Handle and ADD/DM UnitHandle
         to a corresponding Resource Manager Device Handle. This is
         done by searching the Resource Manager physical device
         tree for a node that contains an ADJ_ADD_UNIT adjunct
         that matches the supplied ADD Handle and ADD UnitHandle.

Calling Sequence:

         rc = RMADDToHDEVICE( (PHDEVICE)  &hDevice,
                              (USHORT)    ADDHandle,
                              (USHORT)    UnitHandle );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED and will set hDevice
               to -1L.

Calling Parameters:

         &hDevice (PHDEVICE)

           Pointer to variable to receive device handle of device
           with a matching ADDHandle and UnitHandle.


         ADDHandle (USHORT)

           Handle of the ADD driver assigned by DevHelp_RegisterDeviceClass.


         UnitHandle (USHORT)

           UnitHandle the ADD driver assigned to this device.


         Note: Refer to "Storage Device Reference" for additional
               information on ADD/DM architecture.


                ----------------------------------



RMKeyToHandleList - Search for the specified Adapter/Device/LDev Key


Purpose: This api searches for Resource Manager nodes which match
         the key specified. A list of node handles found is returned
         in the HandleList structure provided by the caller.


Calling Sequence:

         rc = RMKeyToHandleList( (RMHANDLE)    hStartNode,
                                 (PSZ)         SearchKey,
                                 (PHANDLELIST) &HandleList );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.

Calling Parameters:


         hStartNode (RMHANDLE)

           Handle of resource manager node to start the search at. This
           node and all its descendents will be checked. The handle
           provided may be an adapter handle (HADAPTER) or logical
           device handle (HLDEV).

           The following 'pseudo handles' may also be used as
           a starting point for a search:

           Pseudo Handle             Nodes Searched
           -------------             --------------
           HANDLE_PHYS_TREE          Physical Device Nodes
           HANDLE_SYS_TREE           Logical Device Nodes
           HANDLE_DEFAULT_SYSBUS     System Bus Nodes (ISA/EISA/uC)
           HANDLE_X_BUS              Planar Bus Nodes
           HANDLE_PCI_BUS            PCI Bus Nodes


         SearchKey (PSZ)

           Pointer to an ASCIIZ string containing the key to be located.

           If the key supplied ends in a "*" then all keys which match
           the characters up to the "*" will be returned.

           Key searches are treated as case-insensitive.

           Ex: "AHA154X_*" will find all Adaptec adapters that
               are registered.

               "FIXDSK_*" will return all Fixed Disk logical device
               handles.

           Note: This api does not currently support full (regular
                 pattern matching), i.e. only "*" is supported.

           Note: Adapter keys values are chosen at the discretion of
                 the device driver supplier and may be subject to change.


         &HandleList (PHANDLELIST)

           Pointer to the following structure:

           HANDLELIST
           ----------
           struct
           {
             USHORT        cMaxHandles;
             USHORT        cHandles;
             HADAPTER      Handles[1];
           };

           cMaxHandles (USHORT)
               Number handles can be accepted in the Handles
               array. This field must be set by the caller.

               Note: The default HANDLELIST type provides room for one
                     handle. cMaxHandles must be set to 1 in this case.

               Example: Suppose 10 handles are expected.

                 #define MAX_HANDLE_COUNT 10

                 #define HLISTSIZE(c) ( sizeof(HANDLELIST) +  \
                                        (c-1) * sizeof(HADAPTER) )

                 UCHAR HandleList[HLISTSIZE(MAX_HANDLE_COUNT)];

                 PHANDLELIST pHndList = (PHANDLELIST) HandleList;

                 pHndList->cMaxHandles = MAX_HANDLE_COUNT;

           cHandles (USHORT)
               Actual handle count found. This field must be
               initially set to zero by the caller.

               Note: The number of handles reported by this field may
                     exceed cMaxHandles. This indicates that the
                     HandleList structure supplied was too small.
                     The count will be set to the number of handles
                     actually found.

           Handles[] (HADAPTER)
               Array containing the Resource Manager handles that
               match the specified key.


                ----------------------------------



RMHandleToType - Return the type of a Resource Manager handle.


Purpose: Returns the type of Resource Manager handle supplied.


Calling Sequence:

         rc = RMHandleToType( (RMHANDLE)    hHandle,
                              (PUSHORT)     &HandleType )

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hHandle (RMHANDLE)

           Handle whose type is to be determined.


         &HandleType (USHORT)

           Pointer to variable to contain the returned handle type.

           The following handle types can be returned:

           HandleType            Description         API
           ----------            -----------         ---
           HANDLE_TYPE_INVALID   Invalid Handle      None
           HANDLE_TYPE_DRIVER    Driver Handle       RMCreateDriver
           HANDLE_TYPE_ADAPTER   Adapter Handle      RMCreateAdapter
           HANDLE_TYPE_DEVICE    Device Handle       RMCreateDevice
           HANDLE_TYPE_RESOURCE  Resource Handle     RMAllocResource
           HANDLE_TYPE_LOGDEV    Logical Dev Handle  RMCreateLDev
           HANDLE_TYPE_SYSDEV    System Name Handle  RMCreateSysName


                ----------------------------------



RMHandleToParent - Return a parent handle.


Purpose: Returns the parent handle of the handle provided.


Calling Sequence:

         rc = RMHandleToParent( (RMHANDLE)    hHandle,
                                (PRMHANDLE)   &hParent );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hHandle (RMHANDLE)

           Handle whose parent is to be determined.

           Valid handle types for this api include:

           HandleType            Description
           ----------            -----------
           HANDLE_TYPE_ADAPTER   Adapter Handle
           HANDLE_TYPE_DEVICE    Device Handle
           HANDLE_TYPE_RESOURCE  Resource Handle
           HANDLE_TYPE_LOGDEV    Logical Dev Handle
           HANDLE_TYPE_SYSDEV    System Name Handle

           Note: The parent of a resource handle is considered
                 to be the owner of the resource.


         &hParent (PRMHANDLE)

           Handle of the parent of the specified handle.

                ----------------------------------



RMUpdateAdjunct - Update adjunct data structure.


Purpose: Update an existing adjunct structure.


Calling Sequence:

         rc = RMUpdateAdjunct( (HDRIVER)  hDriver,
                               (HDEVICE)  hDevice,
                               (USHORT)   AdjunctIndex,
                               (PADJUNCT) &AdjunctData   );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created
           the adjunct data.

         hDevice (HDEVICE)

           Device Handle which the adjunct data is associated
           with.

         AdjunctIndex (USHORT)

           Index to the adjunct structure to be replaced.

         &AdjunctData

           Pointer to an adjunct structure containing replacement
           data for the adjunct indicated.


           Note: For Resource Manager Version 1.01, the size of the
                 replacement adjunct structure must not exceed the
                 size of the existing adjunct.


                ----------------------------------



RMAdjToHandleList - Update adjunct data structure.


Purpose: This api searches for Resource Manager nodes which match
         the adjunct structure specified. A list of node handles
         and adjunct indices are in the HandleList structure provided
         by the caller.


Calling Sequence:

         rc = RMAdjToHandleList( (PADJUNCT)       &AdjunctData,
                                 (HADAPTER)       hStartNode
                                 (PAJDHANDLELIST) &AdjHandleList );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.

Calling Parameters:

         &AdjunctData (PADJUNCT)

           Pointer to a an adjunct structure to search for.

           Note: The ADJUNCT type contains a union of data structures
                 of varying lengths. When searching for a particular
                 adjunct, it is recommended to set the length field
                 of the AdjunctData structure passed to the exact
                 length of the adjunct structure being located.

                 For example:

                 /* Correct */

                 AdjData.AdjLength = ADJ_HEADER_SIZE + sizeof(ADD_UNIT);

                /* Incorrect */

                 AdjData.AdjLength = sizeof(ADJUNCT);


         hStartNode (HADAPTER)

           Handle of resource manager node to start the search at.


         &AdjHandleList (PADJHANDLELIST)

           Pointer to the following structure:

           ADJHANDLELIST
           -------------
           struct
           {
             USHORT        cMaxHandles;
             USHORT        cHandles;
             ADJINFO       Adj[1];
           };

           ADJINFO
           -------
           sturct
           {
             HADAPTER    hAdapter;
             USHORT      AdjIndex;
           };

           cMaxHandles (USHORT)
               Number handles can be accepted in the Handles
               array. This field must be set by the caller.

               Note: The default ADJHANDLELIST type provides room for one
                     handle. cMaxHandles must be set to 1 in this case.

                     Refer example in RMKeyToHandleList if more
                     than one Adjunct handle is expected.

           cHandles (USHORT)
               Actual handle count found. This field must be
               initially set to zero by the caller.

               Note: The number of handles reported by this field may
                     exceed cMaxHandles. This indicates that the
                     HandleList structure supplied was too small.
                     The count will be set to the number of handles
                     actually found.

           Adj[] (ADJINFO)
               Array of ADJINFO structures. The ADJINFO structure
               contains the following fields:

               hAdapter (HADAPTER)
                   Handle of the owner of adjunct data which matches
                   the adjunct specified.

               AdjIndex (USHORT)
                   Index of the adjunct structure found.



                ----------------------------------



RMHDevToHLDev - Return Physical Device associated with a Logical Device.


Purpose: Returns the Logical Device handle (HLDEV) that is associated
         with the physical device handle indicated.


Calling Sequence:

         rc = RMHandleToParent( (HDEVICE)    hDevice,
                                (HLDEV)      hStartLDev
                                (PHLDEV)     &hLDev       );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDevice

           Resource manager handle to the physical device. The
           logical device handle which is associated with
           this physical device handle will be returned.


         &hStartLDev (HLDEV)

           Handle of the logical device to start the search
           at. If all logical nodes are to be searched then
           HANDLE_LDEV_ROOT should be specified.


         &hLDev (PHLDEV)

           Pointer to variable to receive the logical device
           handle (HLDEV) associated with the physical device
           specified.



                ----------------------------------



RMResToHandleList - Return List of Adapter/Device Handles which own a
                    resource.


Purpose: Returns a list of Adapter/Device handles which own the
         resource indicated.


Calling Sequence:

         rc = RMResToHandleList( (PRESOURCESTRUCT) &ResStruct,
                                 (PHANDLELIST)     &HandleList );
                                                                 
         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         &ResStruct (PRESOURCESTRUCT)

           Pointer to a RESOURCESTRUCT to be whose owners are to be
           located.

           Refer to RMAllocResource for a description of the
           RESOURCESTRUCT datatype.


         &HandleList (PHANDLELIST)

           Structure of containing list of Adapter/Device handles
           which include the specified resource.

           Refer to RMKeyToHandleList for a description of the
           HANDLELIST datatype.


                ----------------------------------



RMActivateAdapter - Indicate adapter (re)activation.

         Preliminary/Advance Information

         Note: This api is not currently supported in Resource Manager
               Version 1.01 and will return RMRC_NOT_SUPPORTED in all
               cases.


Purpose: This API indicates that an adapter that was deactivated via
         RMDeactivateAdapter is now available.

         A device driver would use this api to notify other resource
         manager clients that a PCMCIA adapter (PCCard) which was
         removed without being properly quiesced has been reinserted
         and reinitialized. This allows the system to do a proper
         shutdown on devices attached to this adapter.


Calling Sequence:

         rc = RMActivateAdapter( (HDRIVER)  hDriver,
                                 (HADAPTER) hAdapter );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created
           the adapter.


         hAdapter (HADAPTER)

           Handle of the adapter to be activated.


                ----------------------------------



RMDeactivateAdapter - Indicate adapter deactivation.

         Preliminary/Advance Information

         Note: This api is not currently supported in Resource Manager
               Version 1.01 and will return RMRC_NOT_SUPPORTED in all
               cases.


Purpose: This API indicates that an adapter currently attached
         to the system is nolonger available.

         A device driver would use this api to notify other resource
         manager clients that a PCMCIA adapter (PCCard) which was
         removed from the system. The return code from this API
         will indicate whether the driver should wait for reactivation
         of the adapter or can proceed with destroying the Resource
         Manager handle for this adapter via RMDestroyAdapter.


Calling Sequence:

         rc = RMDeactivateAdapter( (HDRIVER)  hDriver,
                                   (HADAPTER) hAdapter );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created
           the adapter.


         hAdapter (HADAPTER)

           Handle of the adapter to be deactivated.


                ----------------------------------



RMCreateLinkDevice - Create a composite physical device

         Preliminary/Advance Information

         Note: This api is not currently supported in Resource Manager
               Version 1.01 and will return RMRC_NOT_SUPPORTED in all
               cases.


Purpose: This API indicate links a set of independent physical
         devices together to form a new composite device.

         An example of this would be a RAID DASD driver which
         would combine a number of independent physical
         devices together to form a new 'pseudo' device
         with the attributes of a DASD type device.


Calling Sequence:

         rc = RMCreateLinkDevice( (HDRIVER)       hDriver,
                                  (PHDEVICE)      &hLinkDevice,
                                  (PDEVICESTRUCT) &DeviceStruct,
                                  (PAHDEVICES)    &hDeviceList    );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created
           the composite device.


         &hLinkDevice (PHDEVICE)

           Pointer to variable to receive the device handle for the
           composite device to be created.


         &DeviceStruct (PDEVICESTRUCT)

           Pointer to a structure (DEVICESTRUCT) which describes
           the composite device to be created. Refer to RMCreateDevice
           for a description of the DEVICESTRUCT datatype.


         &hDeviceList (PAHDEVICES)

           Pointer to the following structure.

           AHDEVICES
           ---------
           struct
           {
             ULONG     NumDevices;
             HDEVICE   hDevice[1];
           };

           NumDevices (ULONG)
                Number of device handles in the hDevice array.

           hDevice[] (HDEVICE)
                An array of physical device handles which will comprise
                the composite device.


                ----------------------------------



RMModifyResources - Modify Adapter/Device resource sets.


Purpose: This API allow for modification of resources owned
         by an existing adapter or device. Resource handles
         may be deleted or added to an adapter or device
         using this api.


Calling Sequence:

         rc = RMModifyResources( (HDRIVER)   hDriver,
                                 (HADAPTER)  hAdapter,
                                 (USHORT)    ModifyAction,
                                 (HRESOURCE) hResource);

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         hDriver (HDRIVER)

           Driver handle of the device driver which created
           the adapter or device.


         &hAdapter (HADAPTER)

           Handle of the adapter or device whose resource set
           is to be modified.


         ModifyAction (USHORT)

           RM_MODIFY_ADD
                Add the resource handle indicated to the adapter
                or device.

           RM_MODIFY_DELETE
                Delete the resource handle indicated.

           Note: Deleting a resource implicitly causes an
                 RMDeallocResource to occur, i.e. the resource
                 handle is no longer valid.


         hResource (HRESOURCE)

           Handle of the resource to be added or deleted.


                ----------------------------------



RMGetNodeInfo - Return resource manager node information.


Purpose: This API returns the information content of the
         resource manager handle indicated.


Calling Sequence:

         rc = RMGetNodeInfo( (RMHANDLE)         hRMHandle,
                             (PRM_GETNODE_DATA) &NodeInfo,
                             (USHORT)           NodeInfoSize );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         &hRMHandle (RMHANDLE)

           Resource manager handle whose information is to be
           returned. The following handle types are allowed:

           HandleType            Description
           ----------            -----------
           HANDLE_TYPE_DRIVER    Driver Handle
           HANDLE_TYPE_ADAPTER   Adapter Handle
           HANDLE_TYPE_DEVICE    Device Handle
           HANDLE_TYPE_LOGDEV    Logical Device Handle
           HANDLE_TYPE_SYSDEV    System Name Handle


         &NodeInfo (PRM_GETNODE_DATA)

           Pointer to a buffer that will contain the resource manager
           node information.

           RM_GETNODE_DATA
           ---------------
           struct
           {
             ULONG          RMNodeSize;
             RM_NODE        RMNode;
           };

           RMNodeSize (ULONG)
               Total data length returned in bytes. If the buffer
               provided is too small to contain the Resource
               Manager node information, this field will contain
               the required buffer length.

           RMNode (RM_NODE)
               A structure containing information about the requested
               Resource Manager node.

           RM_NODE
           -------
           struct
           {
             ULONG             VersionInfo;
             ULONG             NodeType;
             RMHANDLE          DriverHandle;

             union
             {
               PADAPTERSTRUCT  pAdapterNode;
               PDEVICESTRUCT   pDeviceNode;
               PLDEVSTRUCT     pLDevNode;
               PSYSNAMESTRUCT  pSysNameNode;
               PDRIVERSTRUCT   pDriver;
             };
             PRESOURCELIST     pResourceList;
           }

           VersionInfo (ULONG)
               Version of the resource management driver.


           NodeType (ULONG)
               The type of node the handle provided refers to.


           pAdapterNode (PADAPTERSTRUCT)
               This field contains a pointer to a structure
               that describes the Resource Manager node. This
               structure is a copy of the structure that was
               provided when the node was created.

               The pointer type selected from the union should
               be based on the NodeType value returned.


               NodeType           Structure Pointer   API
               ----------         -----------------   ---
               RMTYPE_ADAPTER     pAdapterNode        RMCreateAdapter
               RMTYPE_DEVICE      pDeviceNode         RMCreateDevice
               RMTYPE_LDEV        pLDevNode           RMCreateLDev
               RMTYPE_SYSNAME     pSysNameNode        RMCreateSysName
               RMTYPE_DRIVER      pDriver             RMCreateDriver


           pResourceList (PRESOURCELIST)
               Pointer to a structure containing a count and list
               of resource assigned to this node.


           PRESOURCELIST
           -------------
           struct
           {
             ULONG          Count;
             RESOURCESTRUCT Resource[1];
           }

           Count (ULONG)
               Count of resource structures returned.

           Resource[] (RESOURCESTRUCT)
               Array of resource structures assigned to this
               node. Refer to RMAllocResource for a description
               of the RESOURCESTRUCT datatype.



                ----------------------------------



RMParseSCSIInquiry - Build SCSI device description.


Purpose: This api is provided as a convenience device drivers
         dealing with SCSI devices. It converts SCSI Inquiry
         Data for a device into a device key and description
         that may be used in RMCreateDevice.


Calling Sequence:

         rc = RMParseScsiInquiry( (PVOID)   &InquiryData,
                                  (PSZ)     DescBuffer,
                                  (USHORT)  DescBufferSize  );

         Note: On systems where the resource manager driver is
               not installed, the library interface code will
               return RMRC_NOT_INSTALLED.


Calling Parameters:

         &InquiryData (PVOID)

           Pointer a buffer containing SCSI Inquiry data for
           the device.


         DescBuffer (PSZ)

           Pointer to buffer which will receive the device key
           and device description built by this api.

           This data may be used as the device description
           field (DevDescriptName) of the DEVICESTRUCT used
           to create the device.

           Refer to the RMCreateDevice api description for further
           information.


         DescBufferSize (USHORT)

           Size of the DescBuffer in bytes.

                ----------------------------------



Return Codes
------------

This section describes Resource Manager return codes.

All Resource Manager APIs return a 16-bit return code.

RMRC_SUCCESS
   Indicates that the indicated Resource Manager api completed
   completed successfully.

   In cases where the resource management driver (RESOURCE.SYS)
   is not installed, some of the basic resource management calls
   will return RMRC_SUCCESS, but essentially are a no-operation.

   The purpose of this is to allow the use of the same device driver
   across various OS/2 versions without the driver needing to
   check specific return codes indicating whether or not the
   resource management facility is available.

RMRC_NOTINITIALIZED
   This indicates than a resource management library was not properly
   initialized.

   A device driver must call RMCreateDriver prior to issuing any
   other resource management call.

RMRC_BAD_DRIVERHANDLE
RMRC_BAD_ADAPTERHANDLE
RMRC_BAD_DEVICEHANDLE
RMRC_BAD_RESOURCEHANDLE
RMRC_BAD_LDEVHANDLE
RMRC_BAD_SYSNAMEHANDLE
   The expected Resource Manager handle was not provided:

   1. The handle was not a valid resource manager handle.
   2. The handle did not point to the type of object the api
      required.

   The individual return codes indicate the type of handle that
   was expected.

RMRC_BAD_DEVHELP
   The resource management library requires the C-variable
   (Device_Help) to initialized to the Device Help entry point
   prior to issuing the first resource management call.

RMRC_NULL_POINTER
   A resource manager api received a NULL value for a pointer
   that was expected to contain a valid 16:16 address.

RMRC_NULL_STRINGS
   A descriptive text pointer in a DRIVERSTRUCT, ADAPTERSTRUCT
   or DEVICESTRUCT datatype was found to be NULL rather than
   pointing to the expected ASCIIZ text data.

RMRC_BAD_VERSION
   The Resource Manager level indicated on the RMCreateDriver
   api is not supported by the resource management driver
   currently installed:

   Possible causes:

   1. Downlevel Resource Management driver (RESOURCE.SYS).
   2. MajorVer/MinorVer fields of DRIVERSTRUCT not properly
      initizalized.

   Refer to RMCreateDriver api description for further information.

RMRC_RES_ALREADY_CLAIMED
   The requested resource is allocated exclusively to another driver,
   or the requested sharing mode conflicts with the sharing mode
   with other owners of the resource.

RMRC_INVALID_PARM_VALUE
   A non-handle/non-pointer variable contains an invalid or out
   or range value.

   Possible causes:

   1. An invalid decode width specified when allocating
      an I/O Port range.
   2. A handle search being performed with cMaxHandles set to 0.

RMRC_OUT_OF_MEMORY
   The resource manager is out of memory.

RMRC_BUFFER_TOO_SMALL
   The buffer provided to receive information from a Resource Manager
   api was too small.

RMRC_IRQ_ENTRY_ILLEGAL
   A resource manager API was issued at "Interrupt Time". Resource
   manager api request may only be issued in at "Task Time" or
   "Init Time".

RMRC_NOT_IMPLEMENTED
   The resource manager API requested is not implement in the version
   of resource manager you are currently using.

RMRC_NOT_INSTALLED
   The Resource Management driver (RESOURCE.SYS) is required to service
   this API request but is not installed.


                ----------------------------------



Linking Resource Manager Services
---------------------------------

This section discusses the mechanics of adding Resource Management
services to your driver.

Overview
--------

OS/2 Resource Management consists of two components:

1. RESOURCE.SYS

   This is a base device driver. On OS/2 WARP and subsequent versions,
   this driver is provided as part of the product and is loaded
   automatically without an explicit CONFIG.SYS "BASEDEV=" statement.

2. RMCALLS.LIB

   This library is linked with your device driver and provides the
   interface code to communicate with the RESOURCE.SYS driver.

   In addition, the RMCALLS library will provide rudimentary support
   for the following subset of Resource Manager APIs.

   RMCreateDriver       RMDestroyDriver
   RMCreateAdapter      RMDestroyAdapter
   RMCreateDevice       RMDestroyDevice
   RMCreateLDev         RMDestroyLDev
   RMCreateSysName      RMDestroySysName
   RMAllocResource      RMDeallocResource

   In general this support consists of returning a handle value of -1L
   and a return code of RMRC_SUCCESS as applicable.

   This support is enabled when your driver is run on a system
   that does not have RESOURCE.SYS installed, such as an earlier
   version of OS/2.


RMCALLS Library Data
--------------------

The RMCALLS library references the following four variables:

   PFN Device_Help;

   This variable must be initialized by your driver prior to calling
   any resource manager APIs. It is expected to contain the
   Device Help entry point provided in the OS/2 Init Request
   Packet your driver receives.

   ULONG RMFlags   = NULL;
   PFNRM RM_Help0  = NULL;
   PFNRM RM_Help3  = NULL;

   These are data variables must be initialized to zero prior
   prior to calling any Resource Manager APIs. The recommended
   method is to specify C-initializers when declaring the variables.

These variables must be allocated by your driver. If you plan to
use Resource Manager services after your driver has completed
initialization you must insure that these variables are not discarded.

Note: If you do not declare these variables, you will get an linker
      error message indicating that they are missing.

RMCALLS Library Code
--------------------

The code portion of the RMCALLS library is included in a segment
named RMCode.

There are three alternatives in handling the code in this segment.

1. Combine RMCode with your driver's default code segment.

   This would be done if your driver does not intend to use Resource
   Manager services after initialization. Since the library code
   is linked after OBJ text, it would be discarded as your driver
   discards its initialization code.

2. Combine RMCode with your driver's swappable code segment.

   If your driver intends to use Resource Manager services after
   its initialization, and has a swappable code segment, then
   RMCode should be combined with this segment.

3. Place RMCode in its own swappable segment.

   If your driver does not have a swappable code segment then
   the RMCode will reside in its own swappable segment by
   default.



                ----------------------------------



Resource Manager IOCTLs
-----------------------

RESOURCE.SYS provides two IOCTLs that allow a ring 3 application
to obtain a 'snapshot' of the resource management data structures.

Obtaining a snapshot of the resource management data structures
consists of two steps:

1. A data structure representing a depth-first traversal of the
   resource manager node structure is obtained.

   For each node traversed the following information is provided:

   - A Resource Manager handle to access the node.
   - The depth of the node in the tree structure.

2. A copy of each resource manager node may be obtained
   by supplying the node handle returned in Step 1.



Category 80 - Resource Manager
------------------------------

Function 02  - Enumerate Resource Manager Nodes

This function traverses the Resource Manager node structure
and returns the results of the traversal as a list of
Resource Manager handles and traversal depth.

Parameter Packet Format

All Parameter packet fields are input fields for this function.

Field                   Length
-----                   ------
Command                 WORD

Command
     This field must be indicates the type of traversal being requested.

     RM_COMMAND_PHYS
        Traverse the Physical Devices tree. This traversal
        reports all Adapters and Devices registered with the
        Resource Manager.

     RM_COMMAND_LOG
        Traverse the Logical Device tree. This traversal
        reports all Logical Devices and System Names registered
        with the Resource Manager.

     RM_COMMAND_DRVR
        Traverse the Device Driver list. This traversal
        reports all device drivers registered and any adapters,
        devices, logical devices, or system names associated
        with each driver.


Data Packet Format

All data packet fields are output fields for this function.

Field                   Length
-----                   ------
NumEntries              ULONG
NodeEntry[]             8 * NumEntries


NumEntries
     This field reports the number of node entries traversed.

NodeEntry[]
     This field is an array of the following structure:

     NODEENTRY
     ---------
     struct
     {
       RMHANDLE RMHandle;
       ULONG    Depth;
     };

     RMHandle (RMHANDLE)
         Resource Manager handle of the node traversed.

     Depth (ULONG)
         Level of the tree structure the node resides on.



Category 80 - Resource Manager
------------------------------

Function 01  - Get Resource Manager Node Data

This function returns the contents of the Resource Manager
node indicated by the handle provided.

Parameter Packet Format

All Parameter packet fields are input fields for this function.


Field                   Length
-----                   ------
RMHandle                ULONG

RMHandle
     This field must be initialized to the handle of the Resource
     Manager Node to be interrogated.


Data Packet Format

All data packet fields are output fields for this function.

Field                   Length
-----                   ------
RMNodeSize              ULONG
RMNode                  ----


RMNodeSize (ULONG)
    Size of the Resource Manager node information returned.

RMNode
    This field is set to a structure describing the Resource
    Manager node and its associated resources.

    RM_NODE
    -------
    struct
    {
      ULONG             VersionInfo;
      ULONG             NodeType;
      RMHANDLE          DriverHandle;

      union
      {
        PADAPTERSTRUCT  pAdapterNode;
        PDEVICESTRUCT   pDeviceNode;
        PLDEVSTRUCT     pLDevNode;
        PSYSNAMESTRUCT  pSysNameNode;
        PDRIVERSTRUCT   pDriver;
      };
      PRESOURCELIST     pResourceList;
    }

    VersionInfo (ULONG)
        Version of the resource management driver.


    NodeType (ULONG)
        The type of node the handle provided refers to.


    pAdapterNode (PADAPTERSTRUCT)
        This field contains a pointer to a structure
        that describes the Resource Manager node. This
        structure is a copy of the structure that was
        provided when the node was created.

        The pointer type selected from the union should
        be based on the NodeType value returned.


        NodeType           Structure Pointer   API
        ----------         -----------------   ---
        RMTYPE_ADAPTER     pAdapterNode        RMCreateAdapter
        RMTYPE_DEVICE      pDeviceNode         RMCreateDevice
        RMTYPE_LDEV        pLDevNode           RMCreateLDev
        RMTYPE_SYSNAME     pSysNameNode        RMCreateSysName
        RMTYPE_DRIVER      pDriver             RMCreateDriver


    pResourceList (PRESOURCELIST)
        Pointer to a structure containing a count and list
        of resource assigned to this node.


    PRESOURCELIST
    -------------
    struct
    {
      ULONG          Count;
      RESOURCESTRUCT Resource[1];
    }

    Count (ULONG)
        Count of resource structures returned.

    Resource[] (RESOURCESTRUCT)
        Array of resource structures assigned to this
        node. Refer to RMAllocResource for a description
        of the RESOURCESTRUCT datatype.

