|
|
| |
|
|
|
Initialization
10.1 Overview
There are two general phases to the initialization process for a UDI device driver: per driver initialization, and per instance (device) initialization.
10.1.1 Per-Driver Initialization
Per-driver initialization starts once the driver has been loaded and/or linked into the system, is handled entirely by the environment, and completes before any driver code is called. The driver communicates its per-driver or per-module initialization requirements to the environment by declaring a global symbol named udi_init_info in each separately loadable module of the driver. The udi_init_info structure specifies all of the parameters required to create the primary region and any secondary regions used by this driver, all channel operations vectors for each metalanguage used by the driver module, and parameters for metalanguage-specific control block groups as well as generic control blocks.
10.1.2 Per-Instance Initialization
Per-instance initialization for the driver starts when the driver receives the udi_usage_ind operation on its management channel. Following this general resource level and tracing indication, the driver instance will receive a udi_channel_event_ind operations of type UDI_CHANNEL_BOUND for each statically-allocated secondary region and for binding to its parent. The driver will usually respond to this with a metalanguage-specific bind operation to its parent driver and the parent will respond by propagating its constraints to the child (see Chapter 12, "Constraints Management") and then acknowleding the bind operation. Per-instance initialization is required to be complete when the new driver instance calls udi_channel_event_complete with the original control block(s).
See Chapter 24, "Management Metalanguage", for more details on the management operations mentioned above.
10.1.3 Per-Region Initialization
Each driver instance is composed of one or more regions. Each region is automatically created with an initial region data area which begins with a udi_init_context_t structure. This structure helps bootstrap the region to the point were it can allocate its own data structures.
10.2 Per-Driver Initialization Structure
Every UDI driver module must contain a global variable named udi_init_info, of type udi_init_t. This structure contains information describing the module's entry points, control block usage, and other information necessary to initialize the driver. The environment processes the information contained in this structure before executing any driver code.
This section contains descriptions of the various components of the udi_init_info structure.
NAME udi_init_info
Module initialization structure
#include <udi.h>typedef const struct { udi_primary_init_t *primary_init_info; udi_secondary_init_t *secondary_init_list; udi_ops_init_t *ops_init_list; udi_cb_init_t *cb_init_list; udi_gcb_init_t *gcb_init_list; udi_cb_select_t *cb_select_list; } udi_init_t; udi_init_t udi_init_info;MEMBERS primary_init_info is a pointer to a structure containing information about the driver's primary region, used in the driver's primary module. For secondary modules, this must be set to NULL.
secondary_init_list is a pointer to a list of structures containing information about each type of secondary region implemented in this module, if any. The list is terminated with an entry containing a zero region_idx. A NULL pointer is treated the same as an empty list.
ops_init_list is a pointer to a list of structures containing information about channel operations usage for each ops vector implemented in this module. The list is terminated with an entry containing a zero ops_idx. ops_init_list must contain at least one entry, and must include at least one entry for each metalanguage used in this module.
cb_init_list is a pointer to a list of structures containing information about each control block type used by this module. The list is terminated with an entry containing a zero cb_idx. A NULL pointer is treated the same as an empty list.
gcb_init_list is a pointer to a list of structures containing information about generic control block usage in this module, if any. The list is terminated with an entry containing a zero cb_idx. A NULL pointer is treated the same as an empty list.
cb_select_list is a pointer to a list of structures containing information about special overrides for scratch requirements when using specific control blocks with specific ops vectors. The list is terminated with an entry containing a zero cb_idx. A NULL pointer is treated the same as an empty list.
DESCRIPTION The udi_init_info structure contains pointers to constant information the environment needs to initialize a driver. Each driver module must include a constant initialized structure of type udi_init_t named udi_init_info.
Exactly one module in a multi-module driver must be the primary module, identified in the driver's Static Driver Properties as the module with a "region" declaration for region index zero, which is the primary region. The primary module of any driver must have a non-NULL primary_init_info. If the primary module also manages some secondary regions, the module must also include a non-empty secondary_init_list.
See udi_cb_init_t for details on how cb_select_list is used.
REFERENCES udi_primary_init_t, udi_secondary_init_t, udi_ops_init_t, udi_cb_init_t, udi_gcb_init_t, udi_cb_select_t
NAME udi_primary_init_t
Primary region initialization structure
#include <udi.h>typedef const struct { udi_mgmt_ops_t *mgmt_ops; const udi_ubit8_t *mgmt_op_flags; udi_size_t mgmt_scratch_requirement; udi_ubit8_t enumeration_attr_list_length; udi_size_t rdata_size; udi_size_t child_data_size; udi_ubit8_t per_parent_paths; } udi_primary_init_t; /* Maximum Legal Scratch Requirement */#define UDI_MAX_SCRATCH 4000/* Operation Flags */#define UDI_OP_LONG_EXEC (1U<<0)MEMBERS mgmt_ops is a pointer to an ops vector of driver entry points for the required Management Metalanguage channel operation routines. See Chapter 24, "Management Metalanguage" for details on Management Metalanguage and its channel operations.
mgmt_op_flags is a pointer to an array of flag values with a one-for-one correspondence between entries in the mgmt_op_flags array and entries in the mgmt_ops array. This array may be used to indicate characteristics of the implementation of the corresponding operation to the environment:
UDI_OP_LONG_EXEC - indicates to the environment that the corresponding operation will execute for an extended period of time (relative to normal operations within this driver). This is a hint to the environment and allows the environment to make implementation specific decisions when scheduling the driver to perform this operation.
mgmt_scratch_requirement specifies in bytes the driver's requirements for scratch area size in Management Metalanguage control blocks received over its management channel. The scratch size specified here must be the maximum of the driver's scratch size needs across the various control blocks in the Management Metalanguage. This value must not exceed UDI_MAX_SCRATCH (4000 bytes).
enumeration_attr_list_length is the number of elements of the udi_instance_attr_list_t array that the driver requires for attr_list in udi_enumerate_cb_t control blocks during udi_enumerate_req. This may be zero if the driver uses udi_enumerate_no_children for its udi_enumerate_req entry point routine.
rdata_size is the size, in bytes, of the region data area to be allocated for the primary region of each driver instance. rdata_size must be at least sizeof(udi_init_context_t) and must not exceed UDI_MIN_ALLOC_LIMIT (see udi_limits_t).
child_data_size is the size, in bytes, of child data to be allocated for each call to udi_enumerate_req. child_data_size must not exceed UDI_MIN_ALLOC_LIMIT.
per_parent_paths specifies the number of path handles that the environment should supply for each parent that is bound to this driver instance. The path handles are supplied to the driver in the udi_channel_event_cb_t control block for each UDI_CHANNEL_BOUND event.
DESCRIPTION The udi_primary_init_t structure contains information the environment needs to subsequently create a new primary region and associated management channel when each driver instance for this driver is instantiated. This structure is part of udi_init_info.
The primary 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.
When the Management Agent in the environment creates a driver instance, it will automatically create a primary region according to the parameters provided in the udi_primary_init_t structure. A management channel will also be created and anchored to this region. The channel context for this channel will be set to point to the region's region data area.
The primary region's end of the management channel will be anchored using mgmt_ops as the ops vector and mgmt_scratch_requirement as the scratch size requirement for all Management Metalanguage control blocks.
Drivers may also request the creation of secondary regions within a driver instance, by using udi_secondary_init_t.
REFERENCES udi_init_info, udi_mgmt_ops_t, udi_init_context_t, udi_secondary_init_t, udi_instance_attr_list_t, udi_enumerate_cb_t, udi_enumerate_req, udi_limits_t
NAME udi_secondary_init_t
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
NAME udi_ops_init_t
Ops vector initialization structure
#include <udi.h>typedef void udi_op_t(void); typedef udi_op_t * const udi_ops_vector_t; typedef const struct { udi_index_t ops_idx; udi_index_t meta_idx; udi_index_t meta_ops_num; udi_size_t chan_context_size; udi_ops_vector_t *ops_vector; const udi_ubit8_t *op_flags; } udi_ops_init_t;MEMBERS ops_idx is a non-zero channel ops index number, assigned by the driver to uniquely identify this set of entry-point related properties for use in other initialization structures and service calls, or zero to terminate the ops_init_list list to which this structure belongs (see udi_init_info). If ops_idx is zero, all other members of this structure are ignored.
meta_idx is a non-zero metalanguage index number, assigned by the driver to uniquely identify a set of metalanguage related properties for a particular metalanguage.
meta_ops_num is a metalanguage-specific number, defined in the corresponding metalanguage specification, that uniquely identifies a type of ops vector with respect to other ops vector types in the same metalanguage.
chan_context_size is the size, in bytes, of a context area that will be automatically allocated, if non-zero, whenever this ops_idx is used to bind a child or parent instance to a driver instance or to bind a secondary region to the primary region for this driver. If non-zero, the value must be at least sizeof(udi_child_chan_context_t) for child bind channels or sizeof(udi_chan_context_t) for other bind channels and must not exceed UDI_MIN_ALLOC_LIMIT (see udi_limits_t).
ops_vector is a pointer to the metalanguage-specific <<meta>>_<<role>>_ops_t channel ops vector structure containing pointers to the various entry point routines for this type of channel. The structure pointed to by ops_vector must be a constant initialized variable. The address of this structure must be cast to (udi_ops_vector_t *) in order to be used as an initializer for ops_vector.
op_flags is a pointer to an array of flag values with a one-for-one correspondence between entries in the op_flags array and entries in the ops_vector array. This member is used in the same way as the mgmt_op_flags member of the udi_primary_init_t structure.
DESCRIPTION The udi_ops_init_t structure contains information the environment needs to subsequently create channel endpoints for a particular type of ops vector and control block usage. This structure is part of udi_init_info.
If non-zero, the ops_idx value must be unique with respect to all other udi_ops_init_t structures for the same driver (even for separate modules in a multi-module driver). Each module's udi_init_info for a particular metalanguage must include a set of udi_ops_init_t structures exactly matching the set of ops vectors used in that module.
If non-zero, the meta_idx value must match a meta_idx value from a "meta" declaration in the driver's static driver properties and must be unique with respect to all other meta_idx values for the same driver.
The meta_ops_num values in metalanguage definitions are typically named <<meta>>_<<role>>_OPS_NUM and each correspond to an ops vector type, typically named <<meta>>_<<role>>_ops_t. The ops_vector member must point to a constant initialized structure of this ops vector type.
When chan_context_size is non-zero and this ops_idx is used for a child, parent, or internal binding (as indicated by a matching "child_bind_ops", "parent_bind_ops", or "internal_bind_ops" declaration in the driver's static driver properties), a new context structure of this size is automatically allocated. For the parent's end of a parent-child bind channel, the new context structure will begin with a udi_child_chan_context_t; for all other channels it will begin with a udi_chan_context_t. The requested chan_context_size must be at least as large as the size of the appropriate header structure. Any remaining bytes will be initialized to zero.
chan_context_size is ignored for driver-spawned channels.
REFERENCES udi_init_info, udi_limits_t, udi_chan_context_t, udi_child_chan_context_t
NAME udi_cb_init_t
Control block initialization structure
#include <udi.h>typedef const struct { udi_index_t cb_idx; udi_index_t meta_idx; udi_index_t meta_cb_num; udi_size_t scratch_requirement; udi_size_t inline_size; udi_layout_t *inline_layout; } udi_cb_init_t; /* Maximum Legal Scratch Requirement */#define UDI_MAX_SCRATCH 4000MEMBERS cb_idx is a non-zero control block index number, assigned by the driver to uniquely identify this set of control block related properties for use in other initialization structures and service calls, or zero to terminate the cb_init_list list to which this structure belongs (see udi_init_info). If cb_idx is zero, all other members of this structure are ignored.
meta_idx is a non-zero metalanguage index number, assigned by the driver to uniquely identify a set of metalanguage related properties for a particular metalanguage.
meta_cb_num is a metalanguage-specific number, defined in the corresponding metalanguage specification, that uniquely identifies a control block group with respect to other control block groups in the same metalanguage.
scratch_requirement specifies in bytes the driver's requirements for scratch area size in control blocks allocated with this cb_idx or received via a channel operation of the appropriate type. The scratch size specified here must be the maximum of the driver's scratch size needs across the various control blocks in the control block group indicated by meta_cb_num. This value must not exceed UDI_MAX_SCRATCH (4000 bytes).
inline_size is the size, in bytes, of a piece of inline memory to allocate and associate with the control block. This value must not exceed UDI_MIN_ALLOC_LIMIT (see udi_limits_t)
inline_layout is a pointer to a data layout specifier that describes the structure of the inline memory, if necessary.
DESCRIPTION The udi_cb_init_t structure contains information the environment needs to subsequently create and manage control blocks of a particular type. This structure is part of udi_init_info.
If non-zero, the cb_idx value must be unique with respect to all other udi_cb_init_t and udi_gcb_init_t structures for the same driver (even for separate modules in a multi-module driver). Each module's udi_init_info metalanguage must include a set of udi_cb_init_t structures exactly matching the set of control block groups used in that module. Even if the corresponding cb_idx is never directly referenced in the module, a udi_cb_init_t must be included for any meta_cb_num that might be received with a channel operation.
If non-zero, the meta_idx value must match a meta_idx value from a "meta" declaration in the driver's static driver properties and must be unique with respect to all other meta_idx values for the same driver.
The meta_cb_num values in metalanguage definitions are typically named <<meta>>_<<cbgroup>>_CB_NUM and each correspond to a control block group which consists of one or more control block types, typically named <<meta>>_<<cbtype>>_cb_t.
When control blocks are first allocated, their scratch size is determined by the scratch_requirement value for the specified cb_idx. When a control block is passed across a channel (using a channel operation), its scratch area may need to grow to meet the requirements of the target region. The environment determines the required minimum size by examining the cb_select_list for the udi_ops_init_t corresponding to the receiving channel endpoint. If an entry is found that matches the control block group for the control block that is being passed, then the scratch_requirement value for that cb_idx will be used; otherwise, the maximum of all scratch_requirement values for all udi_cb_init_t structures with the appropriate meta_cb_num will be used.
Inline memory pieces, if any, are allocated when a control block is first allocated, and are not resized or reshaped for the life of the control block, regardless of the cb_idx values with which the control block becomes associated when it is passed across channels. This memory is automatically transferred to the target region with the control block.
The inline_size member is used if the control block group includes a control block type that has any inline pointers (i.e. one whose layout specifier includes UDI_DL_INLINE_UNTYPED, UDI_DL_INLINE_TYPED, or UDI_DL_INLINE_DRIVER_TYPED) and the driver allocates a control block using this cb_idx; otherwise inline_size must be zero. The corresponding inline pointer in each allocated control block will be set to point to memory of the appropriate size, or NULL if inline_size is zero. Drivers must not modify inline pointers.
The inline_layout member is used if the structure of the inline memory is driver-dependent (as indicated by a UDI_DL_INLINE_DRIVER_TYPED in the control block layout specifier) and inline_size is not zero, otherwise, inline_layout must be NULL.
If inline_size is zero and the layout specifier contains a corresponding UDI_DL_INLINE_DRIVER_TYPED layout element, the cb_idx may be used with udi_cb_alloc_dynamic instead of udi_cb_alloc, to provide the inline size and layout dynamically.
REFERENCES udi_init_info, udi_meta_init_t, udi_ops_init_t, udi_gcb_init_t, udi_layout_t, udi_mei_op_template_t, udi_limits_t, udi_cb_alloc, udi_cb_alloc_dynamic
NAME udi_cb_select_t
Control block selections for incoming channel ops
#include <udi.h>typedef const struct { udi_index_t ops_idx; udi_index_t cb_idx; } udi_cb_select_t;MEMBERS cb_idx is a control block index number that must match a cb_idx value in a udi_cb_init_t associated with the udi_meta_init_t from which this structure is referenced, or must be zero to terminate a cb_select_list list to which this structure belongs (see udi_init_info).
DESCRIPTION The udi_cb_select_t structure contains information the environment needs to subsequently manage scratch requirements of control blocks that are passed across channels. This structure is part of udi_init_info.
udi_cb_select_t entries can be used to override the default algorithm for determining scratch requirements for control blocks that are received via channel operations when there are multiple udi_cb_init_t structures for the same meta_cb_num and meta_idx. By default, the scratch requirement is computed as the maximum from all matching udi_cb_init_t structures. However, if a udi_cb_select_t entry is present for the appropriate ops_idx that has a cb_idx matching one of the candidate udi_cb_init_t structures, then the scratch requirement from that structure is used instead.
udi_cb_select_t entries are optional and will not be needed by most drivers.
In all cases, control block allocation (with udi_cb_alloc) uses the specific properties associated with a control block index parameter, and is unaffected by udi_cb_select_t entries.
REFERENCES udi_init_info, udi_cb_init_t, udi_ops_init_t, udi_cb_alloc
NAME udi_gcb_init_t
Generic control block initialization properties
#include <udi.h>typedef const struct { udi_index_t cb_idx; udi_size_t scratch_requirement; } udi_gcb_init_t; /* Maximum Legal Scratch Requirement */#define UDI_MAX_SCRATCH 4000MEMBERS cb_idx is a non-zero control block index number, assigned by the driver to uniquely identify this set of control block related properties for use in other initialization structures and service calls, or zero to terminate the gcb_init_list list to which this structure belongs (see udi_init_info). If cb_idx is zero, all other members of this structure are ignored.
scratch_requirement specifies in bytes the driver's requirements for scratch area size in generic control blocks allocated with this cb_idx. This value must not exceed UDI_MAX_SCRATCH (4000 bytes).
DESCRIPTION Control blocks that are to be used only for asynchronous environment service calls, such as udi_mem_alloc, and not for any channel operations, may be allocated using a control block index that is initialized with a udi_gcb_init_t. This structure is part of udi_init_info.
Such control blocks have no metalanguage-specific visible part and are directly referenced by the udi_cb_t generic control block pointer. As a result, these control blocks must not be used (or defined for use) in channel operations.
If non-zero, the cb_idx value must be unique with respect to all other udi_cb_init_t and udi_gcb_init_t structures for the same driver (even for separate modules in a multi-module driver).
REFERENCES udi_init_info, udi_cb_init_t, udi_cb_t, udi_cb_alloc
10.3 Initial Region Data Structures
The initial region data structure provided to the driver include a system limits structure (udi_limits_t) along with space for the driver's private per-region data. This structure is allocated by the UDI environment according to the rdata_size member of the appropriate udi_primary_init_t or udi_secondary_init_t in udi_init_info.
A pointer to the initial region data structure (udi_init_context_t) 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. The channel handle is available via cb->gcb.channel.
NAME udi_init_context_t
Initial context for new regions
#include <udi.h>typedef struct { udi_index_t region_idx; udi_limits_t limits; } udi_init_context_t;MEMBERS region_idx is a region index value that indicates the type of this region. For a driver's primary region, it will be zero. For secondary regions, it will be the value from the udi_secondary_init_t that was used to create this region.
limits is a structure that describes system resource limits. See udi_limits_t.
DESCRIPTION The udi_init_context_t structure is stored at the front of the region data area of each newly created region, providing initial data that a driver will need to begin executing in the region. A pointer to this structure (and therefore the region data area as a whole) is made available to the driver as the initial channel context for its first channel.
For primary regions, the first channel will be the management channel for the driver instance (see Chapter 24, "Management Metalanguage"). For secondary regions, the first channel will be the initial channel between this secondary region and the primary region, using either the Generic I/O Metalanguage (see Chapter 25) or a custom metalanguage.
REFERENCES udi_init_info, udi_limits_t
NAME udi_limits_t
Platform-specific allocation and access limits
#include <udi.h>typedef struct { udi_size_t max_legal_alloc; udi_size_t max_safe_alloc; udi_size_t max_trace_log_formatted_len; udi_size_t max_instance_attr_len; udi_ubit32_t min_curtime_res; udi_ubit32_t min_timer_res; } udi_limits_t; /* architectural minimums */#define UDI_MIN_ALLOC_LIMIT 4000 #define UDI_MIN_TRACE_LOG_LIMIT 200 #define UDI_MIN_INSTANCE_ATTR_LIMIT 64MEMBERS max_legal_alloc is the maximum legal memory allocation size for this system. Any larger size passed to udi_mem_alloc will produce indeterminate results, which could include termination of the driver or region, or even a complete system abort.
max_safe_alloc is the maximum memory allocation size that must be passed to udi_mem_alloc without being prepared to cancel an unsuccessful allocation (see definition of "safe limits" below).
max_trace_log_formatted_len is the maximum legal size of the formatted result of a call to udi_trace_write or udi_log_write.
max_instance_attr_len is the maximum legal size of an instance attribute value.
min_curtime_res is the minimum time difference, in nanoseconds, between successive unique values returned by udi_time_current.
min_timer_res is the minimum resolution, in nanoseconds, of timers registered with udi_timer_start_repeating or udi_timer_start. See udi_timer_start for details on how min_timer_res affects timer operation.
DESCRIPTION udi_limits_t reflects implementation-dependent system limits, such as memory allocation and timer resolution limits, for a particular region. These limits may vary from region to region, but will remain constant for the life of a region.
The udi_limits_t structure is passed to a driver instance via the udi_init_context_t in its initial region data.
Since UDI can be implemented on a wide variety of systems from small embedded systems to large server systems, the memory available for drivers can vary widely. udi_limits_t allows drivers to adjust their allocation algorithms to best fit their environment.
There are two types of allocation limits: legal limits and safe limits. Legal limits represent the absolute upper bound on a single allocation. Drivers must not make requests that would exceed the legal limits.
Safe limits represent the maximum amount that a driver may safely request without arranging to deal with unsuccessful allocations. For any size greater than the safe limit (but not exceeding the legal limit), drivers must cancel the request (using udi_cancel) after a reasonable amount of time has expired. To do this, the driver may set a timer using udi_timer_start or udi_timer_start_repeating. Drivers are expected to be coded as if allocations below the safe limit will always eventually succeed.
The max_legal_alloc and max_safe_alloc limits affect the size of virtually-contiguous driver memory allocations via udi_mem_alloc. These allocation limits are guaranteed to be greater than or equal to UDI_MIN_ALLOC_LIMIT in all UDI environments. This means drivers don't need to check these limits for requests that don't exceed UDI_MIN_ALLOC_LIMIT bytes. C language structures that need to be dynamically allocated should be limited to UDI_MIN_ALLOC_LIMIT bytes in size, so they can be allocated directly with a simple udi_mem_alloc call.
The max_trace_log_formatted_len limit specifies the maximum size, in bytes, of strings resulting from formatting messages passed to udi_trace_write or udi_log_write. This limit is guaranteed to be greater than or equal to UDI_MIN_TRACE_LOG_LIMIT in all UDI environments.
The max_instance_attr_len parameter specifies the maximum size, in bytes, of a device instance attribute value (see Chapter 15, "Instance Attribute Management") that can be handled by the environment. This limit is guaranteed to be greater than or equal to UDI_MIN_INSTANCE_ATTR_LIMIT in all UDI environments.
The min_curtime_res and min_timer_res parameters specify the corresponding resolution of the system chronological timer and system timeout timer, respectively (see Chapter 14, "Time Management"). Current time values will change no faster than the amount of time specified by min_curtime_res, and timers will not be scheduled with any better resolution or granularity than the min_timer_res specification.
REFERENCES udi_mem_alloc, udi_cancel, udi_timer_start, udi_timer_start_repeating, udi_init_context_t, udi_instance_attr_set, udi_trace_write, udi_log_write
NAME udi_chan_context_t
Initial context for bind channels
#include <udi.h>typedef struct { void *rdata; } udi_chan_context_t;MEMBERS rdata is a pointer to the driver instance's initial region data.
DESCRIPTION The udi_chan_context_t structure is stored at the front of the channel context structure pre-allocated for new bind channels whose chan_context_size is non-zero (see udi_ops_init_t), except for child-bind channels, which use udi_child_chan_context_t.
A pointer to this structure is made available to the driver as the initial channel context for the corresponding bind channel. Drivers may subsequently change the channel context, but must not free this structure; the environment will free it when the channel is unbound.
REFERENCES udi_init_info, udi_child_chan_context_t, udi_init_context_t, udi_ops_init_t
NAME udi_child_chan_context_t
Initial channel context for child-bind channels
#include <udi.h>typedef struct { void *rdata; udi_ubit32_t child_ID; } udi_child_chan_context_t;MEMBERS rdata is a pointer to the driver instance's initial region data.
child_ID is the child ID value initially supplied by this driver in the udi_enumerate_ack operation which enumerated this child. This value allows the parent to uniquely determine which child this new bind channel is connected to.
DESCRIPTION The udi_child_chan_context_t structure is stored at the front of the channel context structure pre-allocated for new bind channels whose chan_context_size is non-zero (see udi_ops_init_t).
A pointer to this structure is made available to the driver as the initial channel context for the corresponding bind channel. Drivers may subsequently change the channel context, but must not free this structure; the environment will free it when the channel is unbound.
REFERENCES udi_init_info, udi_chan_context_t, udi_init_context_t, udi_ops_init_t, udi_enumerate_ack
| |
|
|
|