RMAllocResource

From EDM2
Revision as of 12:55, 30 July 2018 by Martini (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

This service is supported by both rminfo.dll and rmcalls.lib. It obtains a resource handle and allows a driver to register usage of a hardware resource.

Syntax

RMAllocResource(hDriver, hResource, ResourceStruct);

Parameters

hDriver (HDRIVER) - input 
Driver handle of the device driver requesting the resource.
hResource (PHRESOURCE) - output 
Pointer to the variable to receive the returned resource handle.
ResourceStruct (PRESOURCESTRUCT) - output 
Pointer to the RESOURCETYPE structure.

Return Code

rc (APIRET) - returns 
On systems where the Resource Manager driver is not installed, the library interface code will return RMRC_SUCCESS and a resource handle of -1L.

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_NULL_POINTER : A Resource Manager service received a NULL value for a pointer that was expected to contain a valid 16:16 address.

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.

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.
  • A handle search is being performed with cMaxHandles set to 0.

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.

Remarks

Prior to making any attempt to access the resource, a driver must issue this call and successfully obtain ownership of a resource. This call includes non-destructive (read-type) accesses.

For I/O and BIOS memory resources, RMAllocResource searches to locate an available I/O or memory region that is supported. The resource to be allocated is described in a RESOURCESTRUCT, which contains a C-union of structures that are resource-type specific. This service returns a resource handle (HRESOURCE) that is used to identify usage of the resource by this driver.

Resources are initially assigned to the driver that is issuing the RMAllocResource request. By using hardware probing, the driver determines if the hardware it intends to support is installed.

When the driver determines that a supported adapter is present, it registers an adapter (RMCreateAdapter) and assigns resource handles by providing a list of resource handles in the RMCreateAdapter service request.

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

Example Code

C

#include <os2.h>
#include <rmcalls.h>

HDRIVER            hDriver;
PHRESOURCE         hResource;
PRESOURCESTRUCT    ResourceStruct;
APIRET             rc;

rc = RMAllocResource(hDriver, hResource, ResourceStruct);

Related Functions