UDI driver coding basics

Region data definitions

Each region of a driver is allocated a ``region data'' structure, a per-instance region of memory that is only accessible by the associated region and is used by that region to store information relevant to the operation of that region. This region-specific information often includes: context pointers, state variables, request queues, PIO handles for accessing the device, and information about the channels connected to that region.

NOTE: The only data truly global to a driver (that is, data that can be read from any module, region, or operation context) is called ``module-global data''; see ``Module-global data''.)

The size of the memory area for region data allocated by the UDI environment is determined by the rdata_size member of a region's udi_primary_init_t(3udi) or udi_secondary_init_t(3udi), ass appropriate, in the driver's udi_init_info(3udi) structure. The udi_cmos and pseudod drivers have only one region (see ``Primary region initialization'').

The beginning of the region data area is always a udi_init_context_t(3udi) structure, and is initialized by the Management Agent (MA) when a region is created. If the size of the memory area allocated is larger than a udi_init_context_t structure, the remainder of the memory area is initialized to zero.

A pointer to the initial region data area in memory is made available to the driver as the channel context for the region's initial channel, which the driver can access via cb->gcb.context of any control block it receives over this channel.

Subsequently, when a channel operation or entry point is initiated by the UDI environment, the context pointer in the control block passed as part of the channel operation is set to point to the region data area in memory for the region associated with that channel. The channel context is the only information provided to the target region for a channel operation beyond the operation-specific data in the control block and associated parameters.

The region data definitions included in a driver are the driver's interpretation of the memory space allocated as region data by the MA.

A channel operation typically accesses the contents of the region data area by allocating a variable using the region data type declared by the driver, and initializing it to point to the region data area in memory. For example, a channel operation might use the following code to set a pointer to region data area in memory from the pointer passed as part of the channel operation control block:

   my_region_data_t *rdata = gcb->context;

where my_region_data_t is a previously declared type in the driver cource. Assuming a data field in the rregion data structure, we might want to set that field in the region data area in memory to a new value, so that a future channel operation can access that value:

   rdata->data = new_data;

This is how region data is typically used in the ``Channel operations'' for the sample drivers.