Specifications

Allocating Map Registers and Other Counted Resources
3.1 Allocating a Counted Resource Context Block
The following example illustrates a call to IOC$ALLOC_CRCTX that returns the
address of the allocated CRCTX to UCB$L_CRCTX, a field in an extended UCB:
70$: PUSHAL UCB$L_CRCTX(R5) ; Pass cell to receive CRCTX address
PUSHL ADP$L_CRAB(R1) ; Pass CRAB as argument
CALLS #2,IOC$ALLOC_CRCTX ; Initialize the CRCTX
BLBC R0,200$ ; Branch if failure status returned
To avoid the overhead of allocating (and deallocating) a CRCTX for each DMA
transfer, drivers often obtain multiple CRCTXs in their controller or unit
initialization routines, linking them from a data structure such as the UCB so
that they will be available for later use.
See OpenVMS AXP Device Support: Reference for a detailed description of
IOC$ALLOC_CRCTX.
3.2 Allocating Counted Resource Items
A driver calls IOC$ALLOC_CNT_RES to allocate a requested number of items
from a counted resource. IOC$ALLOC_CNT_RES requires the addresses of
both the CRAB and the CRCTX as input parameters. The resource request is
described in the CRCTX structure; the counted resource itself is described in the
CRAB.
A driver typically initializes the following fields of the CRCTX before calling
IOC$ALLOC_CNT_RES.
Field Description
CRCTX$L_ITEM_CNT Number of items to be allocated. When requesting map
registers, this value in this field should include two extra
map registers to be allocated and loaded as a guard page
to prevent runaway transfers. There may be additional
bus-specific requirements. See OpenVMS AXP Device
Support: Developer’s Guide.
CRCTX$L_CALLBACK Procedure value of the callback routine to be called when
the deallocation of resource items allows a stalled resource
request to be granted.
A value of 0 in this field indicates that, on an allocation
failure, control should return to the caller immediately
without queuing the CRCTX to the CRAM’s wait queue.
A caller can also specify the upper and lower bounds of the search for allocatable
resource items by supplying values for CRCTX$L_LOW_BOUND and CRCTX$L_
UP_BOUND.
IOC$ALLOC_CNT_RES always returns to its caller immediately, whether the
allocation request is granted immediately, is stalled, or is unsuccessful. If the
request is granted immediately, or when a stalled request is eventually granted,
IOC$ALLOC_CNT_RES returns the number of the first item granted to the
caller in CRCTX$L_ITEM_NUM and sets CRCTX$V_ITEM_VALID in CRCTX$L_
FLAGS.
If there are waiters for the counted resource, or if there are insufficient resource
items to satisfy the request, IOC$ALLOC_CNT_RES saves up to 3 quadwords
of caller-supplied context in the CRCTX. IOC$ALLOC_CNT_RES writes a –1
to CRCTX$L_ITEM_NUM, and inserts the CRCTX in the resource-wait queue
(headed by CRAB$L_WQFL). It then returns SS$_INSFMAPREG status to its
caller.
3–3