|
|
udi_secondary_init_t(3udi)
Secondary region initialization structure
#include <udi.h>typedef const struct { udi_index_t region_idx; udi_size_t rdata_size; } udi_secondary_init_t;MEMBERS region_idx is a non-zero driver-dependent index value that indirectly identifies a late-bound set of platform-dependent properties (address and capability domains, memory residence, priority, etc.) that will be attached to new secondary regions of this type, or zero to terminate the secondary_init_list list to which this structure belongs (see udi_init_info). If region_idx is zero, all other members of this structure are ignored. These properties are derived from the driver's region attributes (see Section 30.6.8, "Region Declaration"). Drivers typically define mnemonic constants associated with each region index that name the type of region being created (e.g., MY_INT_REGION, MY_INBOUND_REGION).
rdata_size is the size, in bytes, of the region data area to be allocated for secondary regions created with the given region index. rdata_size must be at least sizeof(udi_init_context_t) and must not exceed UDI_MIN_ALLOC_LIMIT (see udi_limits_t).
DESCRIPTION The udi_secondary_init_t structure contains information the environment needs to subsequently create a new secondary region and associated internal bind channel when each driver instance for this driver is instantiated or when new parents or children are bound to that instance. This structure is part of udi_init_info.
If non-zero, the region_idx value must match a region index in a "region" declaration in the driver's static driver properties that is associated with this module and must be unique with respect to all other udi_secondary_init_t structures for the same driver (even for separate modules in a multi-module driver). Each module's udi_init_info must include a set of udi_secondary_init_t structures exactly matching the set of secondary region types serviced by that module.
The secondary region's region data area is a memory area that is rdata_size bytes in size. It contains a udi_init_context_t structure at the front of this data area. When the region is created the bytes following the init context structure will be initialized to zero. The driver must never free this memory; it will be freed automatically when the region is destroyed.
The environment will automatically create secondary regions as needed, according to the parameters provided in the udi_secondary_init_t structure and associated static driver properties (see Chapter 30, "Static Driver Properties"). If the corresponding "region" declaration has its binding attribute set to dynamic, secondary regions of this type will be created as needed, dynamically, after the driver instance has been created, when a parent or child instance of the appropriate type is bound to this driver instance. Otherwise, exactly one secondary region of this type will be created as part of the initial driver instantiation.
In either case, a channel will also be created and anchored between the primary region and this secondary region as the secondary region's internal bind channel. The channel context for the primary end of this channel will be set to point to the primary region's region data area. The channel context for the secondary end of this channel will be set to point to the secondary region's region data area.
The primary region's end of the channel will be anchored using the ops vector selected by <primary_ops_idx> in the "internal_bind_ops" declaration that has the same region index value. The secondary region's end of the channel will be anchored using the ops vector selected by <secondary_ops_idx> from the same "internal_bind_ops" declaration. See udi_ops_init_t for details on how ops_idx values are used.
When the new region has been fully initialized, the environment delivers a udi_channel_event_ind with a UDI_CHANNEL_BOUND event code to one end of the new internal bind channel. Depending upon the metalanguage definition for the metalanguage indicated by the above ops_idx values, one end or the other will be considered the initiator and the other end will be the responder. It is the initiator end that receives the UDI_CHANNEL_BOUND event. This allows the initiator to receive the channel handle for its end of this channel (from the channel member of the control block structure).
As a recommended and expected (but not required) convention in the driver-internal metalanguage definition, the initiator should send some form of initialization operation (bind operation) to the responder over the internal bind channel. This allows the responder to determine the channel handle for its end of the channel, and can also be used to pass parameters that will help set up the region, choose structure sizes, initialize fields, etc., so that it can become ready to be "open for business".
REFERENCES udi_init_info, udi_init_context_t, udi_ops_init_t, udi_primary_init_t, udi_channel_event_ind, udi_cb_t, udi_limits_t