PDDREF:Linking Resource Manager Services

From EDM2
Jump to: navigation, search
Physical Device Driver Reference
  1. Introduction
  2. Physical Device Driver Overview
  3. Physical Device Driver Architecture and Structure
  4. OS/2 Physical Device Driver Operations
  5. OS/2 Physical Device Driver Design Issues
  6. Character Device Monitors
  7. Installation of External Loadable Device Drivers
  8. Physical Device Driver Strategy Commands
  9. Device Helper (DevHlp) Services
  10. Resource Management
  11. Linking Resource Manager Services
  12. Generic IOCtl Commands
Appendixes
OS/2 Version Compatibility Considerations
Running OS/2 Version 1.3 16-Bit PDDs on OS/2
Using Advanced Bios
Notices
Glossary

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

The OS/2 Resource Manager consists of three components: RESOURCE.SYS, RMCALLS.LIB, and RMINFO.DLL.

RESOURCE.SYS

RESOURCE.SYS is a base device driver. In 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.

RMCALLS.LIB

The RMCALLS library code linked to a driver will provide rudimentary support for cases in which RESOURCE.SYS is not loaded on a system. Typically, a handle value of -1L and a return code of RMRC_SUCCESS will occur. In this manner, the driver code might not need to know about the presence of RESOURCE.SYS on a system, and can assume that all resources are available. This was the behavior previous to implementing Resource Manager.

RMADDToHDevice       RMAdjToHandleList    RMAllocResource
RMConvertID          RMCreateAdapter      RMCreateDetected
RMCreateDevice       RMCreateDriver       RMCreateLDev
RMCreateSysName      RMDeAllocResource    RMDestroyAdapter
RMDestroyDetected    RMDestroyDevice      RMDestroyDriver
RMDestroyLDev        RMDestroySysName     RMDevIDToHandleList
RMGetCommandLine     RMGetDriverName      RMGetNodeInfo
RMGetVersion         RMHandleToParent     RMHandleToResourceHandleList
RMHandleToType       RMHDevToHLDev        RMKeyToHandleList
RMModifyNodeFlags    RMModifyResources    RMParseSCSIInquiry
RMResToHandleList    RMUpdateAdjunct

RMCALLS Library Data

The RMCALLS library references the following four variables:

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

The PFN Device_Help variable must be initialized by your driver prior to calling any Resource Manager services. It is expected to contain the Device Help entry point provided in the OS/2 Init Request Packet your driver receives.

Prior to calling any Resource Manager services, the remaining data variables must be initialized to zero. 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 ensure that these variables are not discarded.

Note
If you do not declare these variables, a linker error message will occur, 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:

  • Combine RMCode with your driver's default code segment if your driver does not intend to use Resource Manager services after initialization. Because the library code is linked after OBJ text, it would be discarded as your driver discards its initialization code.
  • 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 combine RMCode with this segment.
  • 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.

RMINFO.DLL

The RMINFO.DLL is dynamically linked with ring 3 applications to provide an interface with RESOURCE.SYS. The interfaces listed in the following table can be called from 16- and 32-bit applications.

RMAllocResource                RMConvertID              RMCreateAdapter
RMCreateDetected               RMCreateDriver           RMDeAllocResource
RMDeleteDetectedData           RMDestroyDetected        RMDestroyDriver
RMDevIDToHandleList            RMGetNodeInfo            RMGetSnoopLevel
RMHandleToResourceHandleList   RMSaveDetectedData       RMSetSnoopLevel

Resource Manager Services

This section lists and describes the Resource Manager services and their return codes.

The following Resource Manager services are grouped functionally and are provided by a library. The information in this library can be found in Linking Resource Manager Services.

Auto Detection Services

The following services create or destroy a detected device node:

The following rminfo.dll services manage the detection (or snoop) levels and the detected data used for future boots:

The following services are used to search the detected devices and convert plug-and-play device IDs.

Physical Node Management

The following services create driver, adapter, and device nodes:

The following services delete driver, adapter, and device nodes:

Resource Management

The following services allocate or deallocate resources:

The following service edits existing device or adapter resource sets by adding or removing resources:

Node Searches

The following service searches for nodes matching a particular key:

The following service searches for nodes using a particular resource:

The following service searches for nodes containing matching adjunct data:

The following service returns the LDEV associated with a physical device node:

Node Information

The following service provides the type of node with which the handle is associated:

The following service returns the handle of the node's parent:

The following service returns the contents of the Resource Manager node indicated by the handle:

Logical Node Management

The following services create or destroy a logical device node:

The following services create or destroy a system name node:

Miscellaneous

The following calls represent miscellaneous services.

Return Codes

This section describes Resource Manager return codes. All Resource Manager services return a 16-bit return code.

RMRC_SUCCESS
The Resource Manager service is successfully completed.
In cases where the Resource Management driver (RESOURCE.SYS) is not installed, some of the basic Resource Management services will return RMRC_SUCCESS, but do not perform an operation.
The purpose of the use of this return code, however, is to allow the use of the same device driver across various OS/2 versions without the driver having to check specific return codes indicating whether the Resource Manager is available.
RMRC_BAD_ADAPTERHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.
The individual return codes indicate the type of handle that was expected.
RMRC_BAD_DETECTHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service 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 be initialized to the Device Help entry point prior to issuing the first Resource Management service call.
RMRC_BAD_DEVICEHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.
The individual return codes indicate the type of handle that was expected.
RMRC_BAD_DRIVERHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.
The individual return codes indicate the type of handle that was expected.
RMRC_BAD_FLAGS
The flag value provided is not valid for the specific interface.
RMRC_BAD_LDEVHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.
The individual return codes indicate the type of handle that was expected.
RMRC_BAD_RESOURCEHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.
The individual return codes indicate the type of handle that was expected.
RMRC_BAD_SYSNAMEHANDLE
The expected Resource Manager handles were not provided because the handle was not a valid Resource Manager handle or the handle did not point to the type of object the service required.
The individual return codes indicate the type of handle that was expected.
RMRC_BAD_VERSION
The Resource Manager level indicated on the RMCreateDriver service is not supported by the Resource Management driver currently installed because it is a a downlevel version of the Resource Management driver (RESOURCE.SYS), or the MajorVer/MinorVer fields of DRIVERSTRUCT were not properly initialized.
Refer to RMCreateDriver for further information.
RMRC_BUFFER_TOO_SMALL
The buffer provided to receive information from a Resource Manager service was too small.
RMRC_INVALID_PARM_VALUE
A nonhandle or nonpointer variable contains an invalid or out-of-range value because an invalid decode width was specified when allocating an I/O port range, or a handle search is being performed with cMaxHandles set to 0.
RMRC_IRQ_ENTRY_ILLEGAL
A Resource Manager service was issued at interrupt time. The Resource Manager service request can be issued only at task time or INIT time.
RMRC_NO_DETECTED_DATA
The detected data file was not found. An RMSaveDetectedData must be issued to save detected data.
RMRC_NOT_IMPLEMENTED
The Resource Manager service requested is not implemented in the version of the Resource Manager you are currently using.
RMRC_NOTINITIALIZED
A Resource Management library was not properly initialized. A device driver must call RMCreateDriver prior to issuing any other Resource Management service.
RMRC_NOT_INSTALLED
The Resource Management driver (RESOURCE.SYS) is required to service this request but is not installed.
RMRC_NULL_POINTER
A Resource Manager service 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_OUT_OF_MEMORY
The Resource Manager is out of memory.
RMRC_RES_ALREADY_CLAIMED 
The requested resource is allocated exclusively to another driver, or the requested sharing mode conflicts with the sharing mode of other owners of the resource.
RMRC_SEARCH_FAILED
The search was not successful.