udi_cmos region data structure

The cmos_udi driver defines a region data structure that includes the udi_init_context_t information automatically allocated in memory when the driver's primary region is intialized. This is followed by the necessary control block for bus binding, and two handles for PIO read and write for the CMOS RAM device. As region data, these definitions and values are available to all operations defined for the driver's primary region.

cmos_udi.c sample code (cont.)
/* * Region data structure for this driver. */ typedef struct { /* init_context is filled in by the environment: */ udi_init_context_t init_context; udi_bus_bind_cb_t *bus_bind_cb; /* PIO trans handles for reading and writing, respectively: */ udi_pio_handle_t trans_read; udi_pio_handle_t trans_write; } cmos_region_data_t; udi_cmos.c region data structure

init_context

When a region is created, the initial contents of the start of the region data area are initialized to be a udi_init_context_t structure (see udi_init_context_t(3udi)). Once initialized, region data is entirely under the control of the associated driver region code. The driver may choose to preserve this structure's content or overwrite it. This element is used by the subroutines in the sample drivers to pass context information back to the environment via channel operations.

A region's udi_init_context_t structure contains two pieces of data:

region_idx

a region index of type udi_index_t (matching an index from a region statement in the driver's udiprops.txt) that identifies this as the primary or a secondary region

limits

a structure of type udi_limits_t containing resource limits for the UDI implementation on the host system

Since the implementation of many system resource limits (for example, memory allocation and timer resolution limits) varies between systems on which a UDI driver might run, the limits structure provides a way for UDI drivers to query the region environment and adjust memory and other allocation algorithms to make best use of the UDI environment implementation on any host system. For more detail on this structure, see udi_limits_t(3udi).

bus_bind_cb

bus_bind_cb is the control block used for bus bridge binding operations. The udi_cmos driver needs to bind to the bus in order to issue channel requests to CMOS RAM, and needs to occasionally save this control block to region data for access by subsequent channel operations. The control block used as the bus binding control block is the generic control block type, udi_cb_t, which contains these members:

channel

is a handle to the channel currently associated with this control block.

context

is a pointer to state information within the driver region. On entry to a channel operation, the environment sets context to the channel's current context. Drivers may change it if needed.

scratch

is a pointer to the control block's scratch area. See ``Scratch space, offsets, and requirements'' for a description of scratch areas.

initiator_context

is a context pointer that the initiator of a request or indication operation can use to associate per-request context with this control block. If and when the control block is returned to the initiator via an acknowledgement, nak, or response operation, the initiator can use this context pointer to access any additional state data it needs to complete the operation.

See udi_cb_t(3udi) and udi_bus_bind_cb_t(3udi).

trans_read/trans_write

The Programmed I/O (PIO) handle type, udi_pio_handle_t, holds an opaque handle that refers to an environment object that contains addressing, data translation and access constraint information, as well as a PIO transaction list. The transaction list specifies the PIO operations to be invoked when the handle is passed to udi_pio_trans. The udi_cmos driver requires two handles for read and write operations on CMOS RAM.

See ``Programmed I/O (PIO)'' for more on how the PIO handles are used in the CMOS driver.

Note the pseudod driver does not use PIO, since there is no real device associated with the driver.