Specifications

Accessing Device Interface Registers
2.5 Allocating CRAMs
Even though a driver can reuse CRAMs, a driver should not reuse a CRAM until
it has checked the return status from IOC$CRAM_IO.
2.5.1 Preallocating CRAMs to a Device Unit or Device Controller
An OpenVMS AXP device driver can preallocate CRAMs and store them in
a linked list associated with some data structure. It accomplishes this by
repeatedly calling IOC$ALLOCATE_CRAM and inserting the address of
the CRAM returned by this routine in the CRAM list. Or, CRAMS can be
automatically preloaded by driver loading as described here.
Drivers often preallocate CRAMs to perform I/O operations on device unit
registers or device controller registers. To facilitate the allocation of CRAMs for
these purposes, the OpenVMS AXP driver loading procedure examines two fields
in the DPT, DPT$W_IDB_CRAMS and DPT$W_UCB_CRAMS, for an indication
of how many CRAMs the driver plans on using. Although the default value of
both fields is zero, you can insert the number of CRAMs a driver requires to
address device unit registers and device controller registers by specifying the
idb_crams and ucb_crams arguments in the driver’s DPTAB macro invocation.
IDB CRAMs are available for use by a controller or unit initialization routine;
UCB CRAMs are available for use by a unit initialization routine.
The driver loading procedure calls IOC$ALLOCATE_CRAM for each requested
CRAM and inserts it in either of two singly linked lists: UCB$PS_CRAM as the
header of a list of device unit CRAMs, and IDB$PS_CRAM as the header of a list
of device controller CRAMs.
2.5.2 Calling IOC$ALLOCATE_CRAM to Obtain a CRAM
To allocate a single CRAM, a driver calls IOC$ALLOCATE_CRAM, specifying
a location to receive the address of the allocated CRAM and, optionally, the
addresses of the IDB, UCB, or ADP.
IOC$ALLOCATE_CRAM allocates the CRAM and initializes it as follows:
CRAM$W_SIZE Size of CRAM structure in bytes
CRAM$B_TYPE Structure type (DYN$C_MISC)
CRAM$B_SUBTYPE Structure type (DYN$C_CRAM)
CRAM$Q_RBADR Address of remote I/O interconnect location (from IDB$Q_
CSR)
CRAM$B_HOSE Remote I/O interconnect number (from ADP$B_HOSE_
NUM)
CRAM$L_IDB IDB address
CRAM$L_UCB UCB address
Normally, an OpenVMS AXP device driver can use the DPTAB macro to allocate
CRAMs and associate them with a UCB or IDB; drivers that need to associate
CRAMs with other structures may elect to allocate them from within a suitable
fork thread.
IOC$ALLOCATE_CRAM cannot be called from above IPL$_SYNCH. Therefore,
controller and unit initialization routines (which are called by the driver-loading
procedure at IPL$_POWER) cannot allocate CRAMs. For CRAMS needed in or
managed by controller or unit initialization routines, Digital recommends the
DPTAB parameters as the means for CRAM allocation.
2–5