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.