|
|
| |
|
|
|
Management Metalanguage
24.1 Overview
This chapter defines the channel operations and associated service calls of the Management Metalanguage, which is used by the environment's Management Agent (MA) to communicate with the primary region of each driver instance for configuration and other system management purposes. The MA uses the Management Metalanguage to communicate binding information between driver instances including initial channels between related driver instances, according to system configuration information. The MA uses the Management Metalanguage to enumerate device presence or loss, as well as to manage changes in state for hot plugging and power management. The MA may also participate in cleanup operations by indicating that various channels are to be closed via indirect requests or direct operations.
All UDI drivers must support the Management Metalanguage.
Each subsection defines the channel operations, associated control blocks and service calls, constraints and guidelines for the use of each operation, and any error conditions that can occur.
Management Metalanguage operations are not abortable with udi_channel_op_abort.
24.2 Management Agent
The MA is an abstract entity within the UDI environment; it represents the environment's control and configuration mechanisms. All device configuration, driver instantiation, and initial channel creation is driven and controlled by the MA. The MA is an integral part of the environment and is always present in any UDI environment implementation.
The Management Metalanguage defines the communication between a driver instance and the MA and is used for the management channel (sometimes abbreviated "mgmt channel"), which is a channel that is always present between the MA and the driver's primary region. When the MA wishes to instruct a driver instance to perform a management-related operation it will generate a Management Metalanguage request to that driver instance over its management channel. The driver will respond via a Management Metalanguage acknowledgement.
The driver can indicate system-level events by generating responses to corresponding Management Metalanguage inquiries, but the driver will never initiate an operation to the MA. Asynchronous event indication in the Management Metalanguage is handled by posting a request to the driver; that is, the MA sends a request to the driver asking for future event notification, and the driver holds on to the control block indefinitely, sending a reply only when the (first such) asynchronous event occurs.
24.2.1 Driver Instantiation
The MA is responsible for controlling the creation of new driver instances, and determining when to do so. The MA combines information obtained from the enumeration responses of a parent driver instance with the information provided by candidate child drivers' static driver properties to make this decision. The environment then uses information from the selected child driver's udi_init_info to set up appropriate linkages between the driver and the rest of the system. The process of creating new driver instances is referred to as driver instantiation.
The MA is also responsible for creating new orphan driver instances, which are drivers which have no parent instance. In order to instantiate an orphan driver instance, the MA must have instructions from the system administrator or system configuration files describing the orphan instance and its enumeration parameters since there is no enumeration of that instance by a parent.
The following model describes the typical sequence of events surrounding the instantiation of a driver instance. The actual sequence of operations and MA functionality may differ but the events described by this model will be valid from the driver's perspective for any environment:
- ... the parent driver instance has previously been instantiated and has a management channel established between its primary region and the MA.
- The MA issues an enumeration request (udi_enumerate_req) to the parent driver instance.
- The parent driver returns an enumeration response (udi_enumerate_ack) with information describing an instance of a "child"1 to the MA.
- The MA locates a driver that corresponds to the instance attribute information provided by the parent in the enumeration response.
- The selected driver may have been previously loaded or it may be dynamically loaded at this time. In either case, once it is loaded, its udi_init_info structure will be processed.
- The MA creates a new driver instance for the child, including a primary region, optional secondary regions, a management channel connecting the MA to the child's primary region, internal bind channels connecting secondary regions to the primary region, and a bind channel between the parent and child driver instances to be used for initial parent/child communications. All of these channels are pre-anchored. The MA also creates internal configuration information and prepares any necessary resources.
- The MA issues a usage indication (udi_usage_ind) to the newly created driver to allow it to perform preliminary initialization of internal data structures and adjust resource usage and trace levels. This is guaranteed to be the first operation the driver instance receives on any of its channels. Further, no additional operations will be received until the driver calls udi_usage_res for this first operation. The driver may examine its instance attributes to assist in initialization; the instance attributes primarily consist of the enumeration attributes specified by its parent when it was enumerated.
- If the driver has requested any static secondary regions or any dynamic regions for this binding, it will receive a UDI_CHANNEL_BOUND event indication (see udi_channel_event_cb_t on page 17-10) on one end of the internal bind channel for each such region. No external bind operations or additional management operations will be delivered until the driver has processed all the internal bind events and called udi_channel_event_complete for each one.
- The MA then begins the child/parent bind sequence by generating UDI_CHANNEL_BOUND channel event indication on the new child's end of the bind channel to its parent. This event may be delivered to the primary region or to a secondary region, depending on the region index value in the corresponding "parent_bind_ops" declaration (see Chapter 31, "Static Driver Properties").
- The child now performs internal initialization, completing the examination of any needed enumeration and configuration attributes (using udi_instance_attr_get), and then issues a metalanguage-specific bind request to the parent instance via the bind channel.
- The parent instance processes the child's bind request and then returns a bind response via the same bind channel.
- The child completes initialization and then issues a udi_channel_event_complete corresponding to the parent bind event indication, to let the MA know that the parent/child initialization process has completed (successfully or unsuccessfully). On receipt of a successful completion notification, the parent and child are considered "open for business" and should expect to perform normal activities.
- The MA may then repeat this sequence with the new child taking on the parent role, and issue an enumeration request to this new child instance to determine if it has children of its own. If this driver has no children of its own, the enumeration response to the MA indicates this fact and the configuration of this driver instance is complete.
The sequence for instantiating orphan drivers is similar to the above, although it begins at Step 4 with enumeration information that is provided by the system administrator or system configuration rather than by a parent instance, and Step 9 through Step 12 are skipped.
A multi-parent (multiplexer) driver may receive additional parent bindings after the above sequence has completed. In this case, the bind sequence begins with Step 7.
24.3 Management Metalanguage Considerations
Because of its unique nature, the Management Metalanguage differs in a number of ways from other UDI metalanguages:
- The management channel is always created by the MA and exists prior to invocation of the driver's primary region.
- There is only one management channel per driver instance, regardless of the number of regions for that instance, and it is automatically anchored in the driver's primary region.
- There is no way for the driver to create a management channel.
- Management control blocks must always be sent back to the channel over which they were received, since there is only one management channel per driver. Therefore, drivers must not modify or even reference the channel member of a management control block.
- There is only one role the driver may play for the Management Metalanguage since the other end is always handled by the MA; therefore only one channel ops vector is defined for this metalanguage.
- There is no <<meta>>_<<role>>_OPS_NUM for management operations since the single management ops vector is supplied via udi_primary_init_t (see page 10-5).
- There are no <<meta>>_<<cbgroup>>_CB_NUM values for management agent control blocks since all management control blocks are allocated by the MA and passed to the driver via the single Management Channel (i.e. all Management Metalanguage requests are initiated by the MA).
- The mgmt_scratch_size value in udi_primary_init_t determines the scratch space size for all control blocks used on the management channel.
- There is no channel_event_ind_op in the Management Metalanguage ops vector, since the MA will never close the management channel while the driver instance exists, no constraints will be propagated across the management channel, and the MA will never be terminated.
24.4 Initialization
This section describes the system calls that are performed to register this module for communications with the Management Agent and the operations that are used on that channel to initialize the driver.
24.4.1 Tracing Control Operations
One of the functions of the Management Metalanguage is to implement control over the tracing operations performed by a driver. When the system (or user) wishes to obtain specific classes of tracing information from a driver a management operation is issued to the driver over the Management Metalanguage channel. The driver updates its internal tracing operations accordingly and acknowledges the update back to the Management Agent.
For more information on generating trace information please consult the UDI Tracing and Logging Chapter of this specification.
24.4.2 Resource Management
The UDI environment handles resource management (passively) through the udi_limits_t information and actively through the selective control and completion of individual driver resource allocation requests. Both of these activities primarily focus on the ability of the UDI environment to restrict the initial and ongoing supply of new resources to a driver but do not have any effect on the amount of resources that the driver is currently maintaining.
As an ultimate measure, the UDI environment may choose to kill and unload driver instances in an attempt to deal with critical resource availability conditions. However, it is frequently desirable to manage resources in a more graceful manner that will allow the driver to voluntarily release resources back to the UDI environment while continuing to operate.
To support this, the UDI Management Metalanguage provides the ability for the UDI environment to indicate the current level of environment-supplied resource availability to a driver instance for resources.
NAME udi_mgmt_ops_t
Management Meta channel ops vector
#include <udi.h>typedef const struct { udi_usage_ind_op_t *usage_ind_op; udi_enumerate_req_op_t *enumerate_req_op; udi_devmgmt_req_op_t *devmgmt_req_op; udi_final_cleanup_req_op_t *final_cleanup_req_op; } udi_mgmt_ops_t;DESCRIPTION udi_mgmt_ops_t is an ops vector structure that contains function pointers for all of the Management Metalanguage entry point routines for the driver. It is used in the driver's udi_init_info to register these entry points with the environment. For additional information on ops vectors, see "Channel Operations Vectors" on page 7-6.
For the udi_usage_ind and udi_enumerate_req entry points, the driver can specify environment-provided proxy functions. See the corresponding reference pages for information on these proxy functions and when they may be used.
Note - The udi_mgmt_ops_t deviates from other channel ops vectors, in that it does not have a udi_channel_event_ind operation.
REFERENCES udi_init_info, udi_primary_init_t
NAME udi_mgmt_cb_t
Common Management Control Block
#include <udi.h>typedef struct { udi_cb_t gcb; } udi_mgmt_cb_t;MEMBERS gcb is a generic control block header, which includes a pointer to the scratch space associated with this control block. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations.
DESCRIPTION The udi_mgmt_cb_t defines a control block which is used in Management Metalanguage operations that do not require any additional parameters in the control block. This control block is used for requests or indications from the Management Agent to the target driver and is passed back to the Management Agent in the acknowledgement or response operation.
Scratch space size for all Management Metalanguage control blocks is determined by the setting of mgmt_scratch_requirement in the driver's udi_primary_init_t in its udi_init_info. Management Metalanguage control blocks are allocated only by the MA, not by drivers.
REFERENCES udi_cb_t, udi_primary_init_t, udi_init_info
NAME udi_usage_cb_t
Resource indication and trace level control block
#include <udi.h>typedef struct { udi_cb_t gcb; udi_trevent_t trace_mask; udi_index_t meta_idx; } udi_usage_cb_t;MEMBERS gcb is a generic control block header, which includes a pointer to the scratch space associated with this control block. The driver may use the scratch space while it owns the control block, but the values are not guaranteed to persist across channel operations.
trace_mask is a bitmask describing the types of trace events that the driver is to report. Setting one of the trace mask bits enables tracing for all events of that type. Some event types are selectable on a metalanguage basis using the meta_idx field.
For the definition of the udi_trevent_t type and the corresponding trace events that may be enabled, see udi_trevent_t on page 17-3 of the UDI Tracing and Logging Chapter.meta_idx is a metalanguage index that indicates to which metalanguage the metalanguage-selectable trace_mask bits apply. It must match the value of <meta_idx> in the corresponding "meta" declaration of the driver's static driver properties (see Chapter 31), or be zero for the Management Metalanguage.
DESCRIPTION This control block is used with the udi_usage_ind and udi_usage_res operations to indicate the types of events to be traced by the driver and the resource level to which it should comply.
Scratch space size for all Management Metalanguage control blocks is determined by the setting of mgmt_scratch_requirement in the driver's udi_primary_init_t in its udi_init_info. Management Metalanguage control blocks are allocated only by the MA, not by drivers.
REFERENCES udi_cb_t, udi_primary_init_t, udi_init_info, udi_trevent_t, udi_usage_ind, udi_usage_res
NAME udi_usage_ind
Indicate desired resource usage and trace levels
#include <udi.h>void udi_usage_ind ( udi_usage_cb_t *cb, udi_ubit8_t resource_level ); /* Values for resource_level */#define UDI_RESOURCES_CRITICAL 1 #define UDI_RESOURCES_LOW 2 #define UDI_RESOURCES_NORMAL 3 #define UDI_RESOURCES_PLENTIFUL 4ARGUMENTS cb is a pointer to a Management Metalanguage usage control block.
resource_level is an indication of the current resource level to which the driver should adhere.
TARGET CHANNEL The affected driver instance's management channel.
Proxy for udi_usage_ind
udi_usage_ind_op_t udi_static_usage;Drivers that do not adjust their resource utilization levels and do not support tracing may specify udi_static_usage as the entry point for this operation.
DESCRIPTION The udi_usage_ind operation is used to provide advisory information to the target driver regarding the current level of system resources and the desired level of tracing information to be reported by the driver.
This is the first operation that will be issued to a newly instantiated driver instance. The Management Agent may also call this operation any time it wishes to change the level of trace output from the driver or if the system resource levels change significantly.
When used as the driver's first operation, the environment guarantees that no additional channel operations will be delivered to the driver instance on any channel until the driver calls udi_usage_res for this first operation.
This operation is used to activate and deactivate tracing of particular types of events. The Management Agent issues this request to the driver when it is to activate or deactivate tracing according to the values set in the trace_mask and meta_idx fields of the cb, as described for udi_usage_cb_t.
The resource_level argument is used by the UDI Management Agent to indicate the UDI environment's current resource levels to the UDI driver. The UDI driver may use this information to reduce or increase its resource allocation and utilization as appropriate to assist in overall UDI resource management. Driver may treat some or all of the resource levels as the same.
Resource levels that may be indicated by the resource_level argument are:
UDI_RESOURCES_CRITICAL - Indicates that UDI resource levels are critically low and that the driver should release any and all resources that are not absolutely essential to its operation. It is expected that drivers that receive and respond to this indication will operate in reduced capability and/or reduced performance modes.
UDI_RESOURCES_LOW - Indicates that UDI resource levels are below a system threshold level. This is typically an indication that resource allocation requests will begin to be delayed and that system performance may be beginning to be affected due to the resource restrictions. The driver should return any extra resources that it is currently holding but it is not expected to release any resources that would adversely affect its operational state to any great degree.
UDI_RESOURCES_NORMAL - Indicates that UDI resource levels are normal and system resources are still readily available. This is the default state that drivers may assume on startup until indicated otherwise. This indication is most frequently used to undo the effects of a previous UDI_RESOURCES_LOW or UDI_RESOURCES_CRITICAL indication.
UDI_RESOURCES_PLENTIFUL - Indicates that UDI resource usage levels are low relative to the amount of total available resources. Drivers receiving this indication should operate in an "extravagant" mode to achieve absolute peak performance and functionality levels, acquiring additional resources if necessary.
The MA is not required to notify the driver of resource level changes nor is it restricted to indicating updates levels in any particular sequence. The UDI environment may unload UDI drivers whether or not they have reduced their resource allocations levels if the environment determines that this driver should be unloaded to retrieve needed resources.
WARNING Drivers must not invoke this operation.
Resource levels and corresponding low and plentiful thresholds are somewhat arbitrary and may be set or modified by the UDI environment via automatic means or by the system administrator. Driver notification is purely optional.
REFERENCES udi_usage_cb_t, udi_usage_res
NAME udi_usage_res
Resource usage and trace level response operation
#include <udi.h>void udi_usage_res ( udi_usage_cb_t *cb );ARGUMENTS cb is a pointer to a Management Metalanguage usage control block.
TARGET CHANNEL The affected driver instance's management channel.
DESCRIPTION The udi_usage_res operation is used by the driver to respond to update information provided by the Management Agent from a udi_usage_ind operation.
If the driver does not support one or more of the requested trace event types, it must clear the corresponding bits in the trace_mask field of the control block in the acknowledgement. In particular, if tracing is entirely unsupported, trace_mask must be set to zero.
This operation is also used to acknowledge the receipt of the resource indication; it does not indicate to the Management Agent that the driver has completed any internal resource adjustements as a result of the resource indication, but merely indicates that the driver is aware of the new resource levels.
warnings The control block must be the same control block as passed to the driver in the corresponding udi_usage_ind operation.
REFERENCES udi_usage_cb_t, udi_usage_ind
24.5 Enumeration Operations
This subsection of the Management Metalanguage defines child enumeration operations. As described in "Driver Instantiation", each driver instance is given the opportunity to enumerate the presence, number, and initial instance attributes of any child devices (actual or pseudo) associated with the current driver instance. The typical response of the MA to an enumerated child device is to create one or more driver instances and initiate a bind operation between each child instance and the current driver instance (which becomes the parent of that new child).
This process begins with the MA issuing a sequence of enumeration requests to the driver, to instruct it to respond with information regarding each child device present. The enumeration request and acknowledgement operation, along with associated data objects, are described in this subsection.
24.5.1 Enumeration Attributes
Each child device instance is described by a set of enumeration attributes. These attributes are a set of driver instance attributes that serve to identify the specific child instance. The set of attributes needed to identify a child instance are defined by the associated metalanguage and represent the set of attributes initially attached to the child instance when it is instantiated. If multiple child driver instances are associated with the same device instance, the same enumerated attributes will be used for all of those instances.
24.5.2 Child ID
Each child device instance is also identified by a child ID. The child ID is a value that uniquely refers to a given child device instance with respect to its parent. This allows communications between the environment and the parent driver to refer to specific child devices.
When a new child instance is enumerated, the parent driver specifies the child ID, the enumeration attributes for the child device, and a channel ops index indicating the metalanguage and entry points to use for the bind channel between this child and its parent. If the parent driver supports multiple metalanguages for a given child device, it can enumerate the same child_ID multiple times with different ops index values. The child_ID value must not be reused for a new device until the MA tells the parent to release it.
24.5.3 Enumeration Filters
In cases where the Management Agent wishes to query the target driver for information about a specific range of child devices instead of obtaining information about any and all children, it may use an enumeration filter to specify this restricted level of interest to the target driver. The target driver may use this enumeration filter as a hint to indicate which child or children the Management Agent is interested in. The enumeration filter specification is only a hint, however, and the target driver is free to ignore it and return information about any or all known children that make up the same set or a superset of those specified by the filter.
Enumeration filters are especially useful in situations where the child enumeration can be quite large or when enumeration can take significant amounts of time to probe for each child. If the Management Agent knows about these characteristics it can provide appropriate enumeration filter hints to limit the scope of the enumeration query. Environment implementations that are not concerned with the size of the child instance space or the amount of time taken to enumerate that space will typically not provide any filter hints to the target driver.
An enumeration filter is specified as one or more enumeration attributes and the desired range and granularity of values for those attributes. The associated metalanguage is responsible for providing information about the interpretation of enumeration attribute filters as well as defining the enumeration attributes. Any enumeration attribute not specified in the filter is "unfiltered" and will match any value.
24.5.4 Parent ID
When a driver instance is bound to (one of) its parent(s), the MA provides a parent ID, which is a number that can later be used to identify this particular parent, relative to the target driver instance. The same parent ID value is passed back to the driver to request it to unbind from a specific parent. Drivers that don't support multiple parents can ignore the parent ID.
In cases where the Management Agent wishes to query the target driver instance for information about which of its children would be affected by the unbinding of a particular parent of the driver instance, it may specify a parent ID. In this case, the parent ID can logically be thought of as an enumeration filter where the filter is the identified parent. However, this is not a hint. The driver must enumerate all children that would become dysfunctional if the instances' parent were to be unbound. The driver must not enumerate children that can continue unabated once the parent binding is lost. It is acceptable for both parent ID and enumeration filters to be specified. If so, the driver is to enumerate only those children that would be affected by the unbinding of the indicated parent, but is allowed to further reduce this set based on application of the enumeration filters.
Enumeration based on parent ID will normally be used during instance unbinding and hardware hot plug scenarios. It is used to determine the portion of the topology tree that will be unbound or affected by the hot plugging of a component or set of components.
Drivers that have only a single parent per instance have a direct relationship between the loss of a parent binding and the ability to service I/O requests from their children: all children will be affected. As such, the MA does not need to query such a driver to enumerate its affected children. On the other hand, if a driver has multiple parents, the MA cannot know the relationship between that driver's parents and its children, so it will query the driver instance for the set of affected child devices.
24.5.5 Dynamic Enumeration (Hot Plug)
As described above, the MA issues enumeration requests to the driver when it wishes to obtain information regarding child devices that are present. The same mechanism is used by the MA to obtain information about any subsequent topology changes. Once the known devices have been enumerated to the MA the MA will typically issue an enumeration request to the driver instructing the driver to tell it about any new enumeration events.
The driver will hold this enumeration request indefinitely until one of the following events occurs:
- A child device is added or removed.
- The enumeration request is overridden with a new enumeration request.
- The driver instance is shutdown and removed.
In this manner, the MA keeps an enumeration request "posted" to the driver that the driver can use to inform the MA about any changes in the child topology of the driver.
The driver instance is only expected to maintain one posted enumeration request from the MA per parent_ID. If the MA issues another enumeration request the enumeration request being held must be acknowledged with a "no child events" status and the new enumeration request must be processed and (if necessary) held to use for future enumeration notifications to the MA. The MA will typically override a posted enumeration request when it wishes to rescan all known children or when it wishes to change the enumeration filter of the posted request.
24.5.6 Unenumeration
The converse to the enumeration operation is the case where a child has "gone away" from the perspective of the parent driver, such as when a device is unplugged or turned off. In UDI, this is handled by an unenumeration operation. This operation is performed as a variation of the enumeration operation: the child ID value indicates which child has gone away and there are no enumeration attributes specified. This response to the enumeration request indicates to the Management Agent that the corresponding child instance is no longer valid and that the Management Agent should initiate cleanup operations for that child driver instance.
24.5.7 Directed Enumeration
The children of a particular driver instance may not always be determined by performing a physical scan or other specific determination. In some cases the children are determined by the presence of other modules in the system, and in other cases the children are determined by system configuration, possibly resulting from input from the system administrator. This is typically true of pseudo-drivers and especially orphan drivers which have no parent regions.
To accomodate this type of configuration, UDI implements the concept of directed enumeration wherein the target driver is "directed" to enumerate a specific child instance by the Management Agent. The Management Agent will use the operations described in this section to request the target driver to enumerate a specific child; the resulting actions are identical to those that would be performed for a physically enumerated child: the target parent driver prepares internal management structures and then generates an enumeration acknowledgement for the new child. Subsequent child instance creation and binding operations then proceed normally.
NAME udi_filter_element_t
Enumeration filter element structure
#include <udi.h>typedef struct { char attr_name[UDI_MAX_ATTR_NAMELEN]; udi_ubit8_t attr_min[UDI_MAX_ATTR_SIZE]; udi_ubit8_t attr_min_len; udi_ubit8_t attr_max[UDI_MAX_ATTR_SIZE]; udi_ubit8_t attr_max_len; udi_instance_attr_type_t attr_type; udi_ubit32_t attr_stride; } udi_filter_element_t;MEMBERS attr_name is the name of the attribute to be filtered.
attr_min is the minimum acceptable value for the attribute in this filter. When combined with the attr_max value an inclusive range of valid attribute values for the filter is specified.
attr_min_len specifies the valid length (in bytes) of the attr_min value. Must not be zero.
attr_max is the maximum acceptable value for the attribute in this filter.
attr_max_len specifies the valid length (in bytes) of the attr_max value. Must not be zero.
attr_type is the attribute type as specified for udi_instance_attr_type_t on page 16-7. Must not be UDI_ATTR_NONE or UDI_ATTR_FILE.
attr_stride specifies the periodicity of the filter match values starting at attr_min and ending at or above attr_max.
DESCRIPTION The udi_filter_element_t structure is used to specify an attribute being filtered and the valid range and periodicity of the values for that filter. This can be used to reduce the amount of work a driver needs to go through to scan for child devices.
The interpretation of attr_stride is unique to each attr_name attribute and is specified by the metalanguage when describing that attribute.
The interpretation of attr_min and attr_max values will be determined by the attr_type specified for that attr_name attribute when the attribute is being enumerated.
If attr_type is UDI_ATTR_UBIT32, the 32-bit value is encoded as a little-endian value in the first four bytes of attr_min and attr_max, and attr_min_len and attr_max_len must be 4. In this case, UDI_ATTR32_GET (page 16-14) must be used to extract values from attr_min and attr_max.
EXAMPLE If the current target driver instance is a SCSI HD that is enumerating SCSI Metalanguage children (SCSI peripheral devices) for the MA, the following filter specification (as initialized by the MA):
#define udi_filter_element_t f = { "scsi_target", UDI_ATTR32_INIT(2), 1, UDI_ATTR32_INIT(15), 1, UDI_ATTR_UBIT32, 3 };indicates that the MA only cares about SCSI targets with one of the following SCSI Target ID values: 2, 5, 8, 11, 14.
REFERENCES udi_instance_attr_type_t, udi_instance_attr_list_t, UDI_ATTR32_GET, UDI_ATTR32_INIT, udi_enumerate_req
NAME udi_enumerate_cb_t
Enumeration operation control block
#include <udi.h>typedef struct { udi_cb_t gcb; udi_ubit32_t child_ID; void *child_data; udi_instance_attr_list_t *attr_list; udi_ubit8_t attr_valid_length; const udi_filter_element_t *filter_list; udi_ubit8_t filter_list_length; udi_ubit8_t parent_ID; } udi_enumerate_cb_t; /* Special parent_ID filter values */#define UDI_ANY_PARENT_ID 0MEMBERS gcb is the standard control block information structure.
parent_ID is the parent ID that identifies a specific parent of the current driver instance. When this value is not UDI_ANY_PARENT_ID then the current driver must only enumerate children that relate to this indicated parent. This is used most often for multiplexer drivers which have multiple parents and children and an enumeration event needs to determine which children will be affected by a change in a parent's status.
The parent_ID value will match a value previously passed to the driver via a udi_channel_event_ind operation of type UDI_CHANNEL_BOUND. Drivers must not change parent_ID.
child_ID is the child ID that identifies a specific child instance. When the driver enumerates a new child device, it assigns a unique child_ID to identify that device in subsequent operation.
The child_ID field is only valid in certain enumeration operations:
1. The child_ID field is valid in the udi_enumerate_req operation only for the UDI_ENUMERATE_RELEASE enumeration level.
2. The child_ID field is valid in the udi_enumerate_ack operation only for the UDI_ENUMERATE_OK and UDI_ENUMERATE_REMOVED enumeration levels.
The child_ID value is unspecified and must be ignored in all other situations.
child_data is a pointer to pre-allocated movable memory for per-child data, if any. If child_data_size in the driver's udi_primary_init_t is non-zero, that many bytes of memory will be allocated, as if by udi_mem_alloc with the UDI_MEM_NOZERO and UDI_MEM_MOVABLE flags set, for each call to udi_enumerate_req with any enumeration level except UDI_ENUMERATE_RELEASE. Otherwise, child_data will be NULL.
If the driver responds in udi_enumerate_ack with any result besides UDI_ENUMERATE_OK, it must leave child_data unmodified and the environment will free the memory automatically. Otherwise, the driver must free the child_data using udi_mem_free when it is through with it.
attr_list is a pointer to an array of udi_instance_attr_list_t structures (see page 16-13), allocated and owned by the MA. This attribute list is used to describe the initial set of instance attributes being enumerated by this driver or the desired set of child attributes for a directed enumeration operation. The length of this array shall be equal to the value of enumeration_attr_list_length from the driver's udi_primary_init_t.
attr_valid_length indicates the number of valid attribute values currently stored in the control block's attr_list. This is initialized by the MA to zero, or the number of attributes specified by the MA for directed enumeration. Attribute list elements beyond the first attr_valid_length elements are ignored and their values are unspecified.
filter_list is a pointer to an array of udi_filter_element_t structures, allocated and owned by the MA, used to specify the attributes filter to be applied to this enumeration request by the target driver.
filter_list_length is the number of elements in the filter_list array.
DESCRIPTION The udi_enumerate_cb_t is the control block used for the udi_enumerate_req and udi_enumerate_ack channel operations. This control block is allocated by the MA when the MA issues the udi_enumerate_req and is to be returned to the MA by the driver in the udi_enumerate_ack response.
The filter_list passed to the driver in this control block on the enumeration request must be returned to the MA in the acknowledgement operation and must not be used after that acknowledgement has been issued.
The driver fills in the attribute list passed in this control block with the attributes of the child node for the udi_enumerate_ack operation. If this is used for a directed enumeration operation, the attribute list is also used to specify the minimum set of enumeration attributes for the child that the driver is being directed to enumerate; these initial attributes must be preserved for the acknowledgement although additional attributes may be added.
All attribute names in both attr_list and filter_list must be enumeration attribute names and so must not have any special prefix characters.
Scratch space size for all Management Metalanguage control blocks is determined by the setting of mgmt_scratch_requirement in the driver's udi_primary_init_t in its udi_init_info. Management Metalanguage control blocks are allocated only by the MA, not by drivers.
warnings Drivers must not use pointer values as child_ID values, since pointer values are larger than 32 bits on some platforms.
REFERENCES udi_cb_t, udi_instance_attr_list_t, udi_primary_init_t, udi_init_info, udi_enumerate_req, udi_enumerate_ack, udi_ops_init_t, udi_child_chan_context_t
NAME udi_enumerate_req
Request information regarding a child instance
#include <udi.h>void udi_enumerate_req ( udi_enumerate_cb_t *cb, udi_ubit8_t enumeration_level ); /* Values for enumeration_level */#define UDI_ENUMERATE_START 1 #define UDI_ENUMERATE_START_RESCAN 2 #define UDI_ENUMERATE_NEXT 3 #define UDI_ENUMERATE_NEW 4 #define UDI_ENUMERATE_DIRECTED 5 #define UDI_ENUMERATE_RELEASE 6ARGUMENTS cb is a pointer to an enumeration control block.
enumeration_level is a value describing the relationship of this enumeration request to previous enumeration requests (see below).
TARGET CHANNEL The affected driver instance's management channel.
PROXIES udi_enumerate_no_children
Proxy for udi_enumerate_req
udi_enumerate_req_op_t udi_enumerate_no_children;udi_enumerate_no_children may be used as a driver's udi_enumerate_req entry point if the driver never needs to enumerate any child devices. It will simply acknowledge the request with UDI_ENUMERATE_LEAF, to indicate that there are and never will be any children of this device.
DESCRIPTION The Management Agent issues this request to obtain enumeration information about child devices of the current driver instance's device. If there is information that may be returned for child devices, the receiving driver fills in an array of udi_instance_attr_list_t structures to describe that child device.
The enumeration_level argument indicates the relationship of this enumeration request to any previous enumeration requests based on the following values:
UDI_ENUMERATE_START - The Management Agent is starting a new enumeration cycle. The target driver must provide information about at least all child devices that match the filter, regardless of whether those children were previously enumerated (or are currently actively bound). Subsequent enumeration requests are expected to have an enumeration_level of UDI_ENUMERATE_NEXT to obtain information about more child devices; receipt of another UDI_ENUMERATE_START will restart the enumeration back at the beginning.
UDI_ENUMERATE_START_RESCAN - This enumeration level is the same as the UDI_ENUMERATE_START enumeration level except that with this level the driver must not use any previously obtained or cached information to report child devices and must instead perform physical verification as appropriate to obtain the filtered list of children. The physical scan must only be sufficient to satisfy the specified filter; an exhaustive physical scan is not necessary unless indicated by the filter (or lack thereof).
UDI_ENUMERATE_NEXT - The target driver shall return information about the next child device relative to the one described in the previous successful udi_enumerate_ack operation with a UDI_ENUMERATE_START, UDI_ENUMERATE_RESCAN, or UDI_ENUMERATE_NEW enumeration level that was relative to the same parent ID. When all children have been enumerated the udi_enumerate_ack operation shall indicate an enumeration_flag of UDI_ENUMERATE_DONE. The driver is expected to maintain the context (in its region data and, if a multiple-parent driver instance, in its parent context data) necessary to implement the UDI_ENUMERATE_NEXT operations properly.
Although the enumeration filter_list is passed to the driver each time the udi_enumerate_req is called, the MA will not change the filter specification from the previous udi_enumerate_req call if the UDI_ENUMERATE_NEXT enumeration level is specified.UDI_ENUMERATE_NEW - The target driver shall return information about any child device changes (i.e. new or removed children) that have been detected since the completion of any previous enumeration cycles. The MA will typically issue a udi_enumerate_req of this type to the target driver that will be held by the target driver for an indefinite period of time until such a child event occurs, at which point the target driver will indicate the event by completing this request with a udi_enumerate_ack operation.
UDI_ENUMERATE_DIRECTED - This enumeration level is an indication to the target driver that it must create a child with the specific attributes indicated in the associated attribute list. This is used when the Management Agent needs to instantiate children as a result of external configuration information rather than hardware probed configuration.
UDI_ENUMERATE_RELEASE - This enumeration level is an indication to the target driver that it should release resources associate with the indicated child (as specified by the child_ID member of the control block). This is used when the Management Agent has terminated all child instances for this child_ID and is no longer planning to use this child device. This may occur whether or not the target driver has unenumerated the device instance (with UDI_ENUMERATE_REMOVED). This signals the current driver that the child_ID value for the indicated child and any associated context information may now be deallocated or re-used for future enumerations.
If a UDI_ENUMERATE_NEW is received after a UDI_ENUMERATE_START (and zero or more UDI_ENUMERATE_NEXT's), but before the driver has provided information regarding all child devices, it will be treated as if it were a UDI_ENUMERATE_NEXT.
UDI_ENUMERATE_DIRECTED and UDI_ENUMERATE_RELEASE may be invoked independently of other enumeration sequences. They do not affect the behavior of UDI_ENUMERATE_NEXT.
If a previous UDI_ENUMERATE_NEW for the same parent_ID is still pending, the driver must call udi_enumerate_ack with UDI_ENUMERATE_FAILED to "cancel" the previous request and then process the new enumeration request.
The filter_list specified in the enumeration control block specifies the attribute filter hints to be applied to the enumeration by the target driver. The target driver may use these hints to select which child instances to return information about, or it may ignore these hints and return a superset of the filtered children.
If the parent_ID in the enumeration control block is not UDI_ANY_PARENT_ID, then it identifies the specific parent of the current driver instance with respect to which the enumeration is to be performed.
WARNING Drivers must not invoke this operation.
REFERENCES udi_enumerate_ack, udi_instance_attr_list_t, udi_enumerate_cb_t
NAME udi_enumerate_ack
Provide child instance information
#include <udi.h>void udi_enumerate_ack ( udi_enumerate_cb_t *cb, udi_ubit8_t enumeration_result, udi_index_t ops_idx ); /* Values for enumeration_result */#define UDI_ENUMERATE_OK 0 #define UDI_ENUMERATE_LEAF 1 #define UDI_ENUMERATE_DONE 2 #define UDI_ENUMERATE_RESCAN 3 #define UDI_ENUMERATE_REMOVED 4 #define UDI_ENUMERATE_REMOVED_SELF 5 #define UDI_ENUMERATE_RELEASED 6 #define UDI_ENUMERATE_FAILED 255ARGUMENTS cb is a pointer to an enumeration control block.
enumeration_result is a value indicating what type of enumeration acknowledgement is being generated.
ops_idx indicates (one of) the child binding ops index(es)-with associated metalanguage(s)-useable with this child device. If a driver calls udi_enumerate_ack multiple times with the same child_ID then each must have a different ops_idx, corresponding to a different meta_idx, and the environment may bind child drivers using any or all corresponding metalanguages. If enumeration_result is not UDI_ENUMERATE_OK, ops_idx is ignored and may be set to any value.
TARGET CHANNEL The affected driver instance's management channel.
DESCRIPTION The udi_enumerate_ack channel operation is used in response to a udi_enumerate_req channel operation and provides information about a particular child device instance.
The attr_list in the control block specifies the enumeration instance attributes that will be present for corresponding child driver instance(s) when created. These enumeration attributes may be obtained by a child driver via calls to udi_instance_attr_get, to obtain additional information about the instance being created. All child devices that match the filter_list in the enumeration request control block must be included in the set of enumeration acknowledgements. Other children may also be included.
The enumeration_result argument must be one of the following values and indicates the type of enumeration response being generated by the driver and how the associated child_ID and attr_list values in the control block should be interpreted:
UDI_ENUMERATE_OK - Indicates that the enumeration is returning a valid child instance enumeration and that no special cases apply. The attr_valid_length value is adjusted accordingly and the child_ID field is filled in by the driver with a value that uniquely identifies this child. This value will be used to identify the bind channel to that child in the udi_child_chan_context_t structure (if the udi_ops_init_t chan_context_size is non-zero).
UDI_ENUMERATE_LEAF - Indicates that there are not and never will be any child devices for the current device.
UDI_ENUMERATE_DONE - Indicates that all children have already been enumerated and no more child devices exist. This response does not actually enumerate a child.
UDI_ENUMERATE_RESCAN - Indicates that the Management Agent should re-scan the entire set of children via UDI_ENUMERATE_START and UDI_ENUMERATE_NEXT operations. This can be returned in situations where there are multiple changes to the set of child devices, where the set has changed part way through the enumeration process, or when the target driver is unable to determine the exact change that has occurred.
This response does not actually enumerate a child.
This value must only be returned for UDI_ENUMERATE_NEW and UDI_ENUMERATE_NEXT requests.UDI_ENUMERATE_REMOVED - Indicates that the specified child device has been removed (as opposed to added) and that the Management Agent should initiate handling of a device removal. The child_ID indicates which child has been removed by passing the same value that the child was originally enumerated with.
This value must only be returned for UDI_ENUMERATE_NEW requests.
It is important to note that the use of UDI_ENUMERATE_REMOVED for a UDI_ENUMERATE_NEW request is an explicit unenumeration of a child device. A child device may also be implicitly unenumerated by not listing it as part of a UDI_ENUMERATE_START / UDI_ENUMERATE_NEXT scan.
Whether explicitly or implicitly unenumerated, the driver must maintain the validity of the child_ID associated with this child until the Management Agent acknowledges the unenumeration with a udi_enumerate_req operation with an enumeration level of UDI_ENUMERATE_RELEASE.UDI_ENUMERATE_REMOVED_SELF - Treated like UDI_ENUMERATE_REMOVED, except that this indicates that the enumerating device itself has been removed.
UDI_ENUMERATE_RELEASED - The response from the driver when it has released all resources associated with a removed child device. This response must only be used with the UDI_ENUMERATE_RELEASE request and indicates that the driver has released all resources associated with the indicated child.
UDI_ENUMERATE_FAILED - Indicates that the dynamic or directed enumeration cannot be satisfied by this target driver. This may only be returned for UDI_ENUMERATE_NEW and UDI_ENUMERATE_DIRECTED requests.
In all cases except UDI_ENUMERATE_OK, the contents of attr_list is ignored and returned unchanged. The attr_valid_length member of the control block must always be zero except for the UDI_ENUMERATE_OK case, where it indicates the number of child enumeration attributes. In all cases except UDI_ENUMERATE_OK and UDI_ENUMERATE_REMOVED, the child_ID value is ignored.
warnings The control block must be the same control block as passed to the driver in the corresponding udi_enumerate_req operation.
REFERENCES udi_enumerate_req, udi_instance_attr_list_t, udi_enumerate_cb_t, udi_primary_init_t
24.6 Device Management Operations
This subsection of the Management Metalanguage is used to manage the flow of I/O operations within a driver instance during hot plug scenarios. In addition to controlling further I/O operations, the Management Metalanguage also allows the driver instance to communicate its operational state to the MA. A driver instance may indicate that it cannot currently support the suspension of activity. The MA could then decide to discontinue the hot plug operation, or forcibly continue. The driver instance may indicate that it can suspend internally and will queue all new I/O requests. The MA could then decide to no longer propagate the hot plug operation to the driver instance's children, leaving them unaffected.
The following model describes the typical sequence of events surrounding a hot plug operation. The actual sequence of operations and MA functionality may differ but the events described by this model will be valid from the driver's perspective for any environment:
- ... a hot plug event occurs and the driver instance is determined to be in the set of affected driver instances.
- The MA issues a Prepare_To_Suspend operation to the driver instance. The driver instance takes appropriate action (see 20.8.1) and acknowledges the operation. Note: if the MA were to subsequently cancel the hot plug operation, it would issue a Resume operation to the driver instance.
- The MA issues a Suspend operation to the driver instance. The driver instance takes appropriate action (see 20.8.2) and acknowledges the operation. Note: if the MA were to subsequently cancel the hot plug operation, it would issue a Resume operation to the driver instance.
- If the instance is to be unbound, the MA will cause all children to unbind from the driver instance. Note: if the MA were to subsequently cancel the hot plug operation, it would cause the children to rebind to the driver instance.
- If parent instance(s) are to be unbound, the MA will request the driver instance to unbind from the respective parent(s).
- If the instance is to be removed from the system, after unbinding all parents and children, the MA will invoke udi_final_cleanup_req to cause the instance to be fully removed.
- ... the affected hardware is powered down, swapped, and re-enabled. The MA starts normal attachment. The hardware is identified as belonging to the driver.
- If the driver was removed from the system, the instance is recreated and re-bound to its parent(s).
- The MA enumerates the driver instance's children. If the children were unbound, the MA will initiate re-binding to each of the children. If the children were not unbound, the MA will issue a Resume operation to the driver instance.
24.6.1 Prepare To Suspend
This device management operation serves as an informational notice that a Suspend operation is about to be performed relative to the indicated parent. It serves the following purposes:
Relative to the driver instance:
- If the instance cannot support suspending operation and/or unbinding, it shall return the proper error code in the acknowledgment.
- As a configuration change is about to take place, changes to the instance's configuration, state, etc that may conflict with a configuration change must be avoided or kept track of.
- To minimize the generation of new I/O traffic based on the receipt of unsolicited inbound requests, the instance should take action, if possible, to turn off unsolicited inbound traffic (for example, a network driver should turn off the reception of new packets).
- To minimize the length of time that the Suspend operation will take, the instance should avoid, if possible, issuing new I/O requests to its parent.
Relative to the MA and the environment:
- Based on the response of the driver instance, the MA is given an indication as to whether the hot plug operation can succeed. This allows the MA to determine if it should cancel the operation or whether it must forcibly remove this portion of the tree. If the MA is to cancel the operation, it can simply Resume operation on the device instances previously sent a Prepare To Suspend. This early failure notification allows the MA to avoid the costly unbinding and rebinding process on the portion of the topology that was traversed prior to the failure.
24.6.2 Suspend
This management operation instructs the driver instance to suspend all activity via the indicated parent. The instance is to no longer initiate transactions to the indicated parent. In addition, prior to acknowledging the Suspend operation, it is to wait for all transactions outstanding with the indicated parent to complete (successfully or otherwise). The instance is to also take whatever actions necessary to prevent the delivery of unsolicited inbound requests. This may involve disabling the reception of new packets, disabling interrupts, exerting flow control, etc.
If the instance determines that it is in a state that cannot be suspended, it shall return a proper error status in the acknowledgment.
If the instance receives new requests (from its children) that are targeted for the indicated parent, the instance can either queue the requests or discard the requests as appropriate for the instance's device model. If the instance is queuing requests, it must continue to process them in as much as it is capable relative to the metalanguage definition. In any case, the driver must ensure that the suspension is not directly apparent to its children, though there may be indirect effects, such as extended delays or additional retry requirements.
24.6.3 Shutdown
This management operation is identical to a Suspend operation with the addition that it also instructs the driver instance to shutdown and detach as much as possible with its associated hardware. All communication connections should be terminated. The Shutdown operation is commonly used when no further device activity is desired but the device itself will remain powered on (e.g. when the operating system is to be rebooted).
Unlike Suspend, Shutdown will not be followed by a Resume, but may be followed by an Unbind.
24.6.4 Parent Suspended
This management operation is a notification that is used by the MA to affect some level of flow control over resources and requests that are issued by instances that are descendants of a suspended or shutdown instance. Typically, this will be used when the MA determines it no longer needs to propagate the Suspend operation because it has encountered an instance that sufficiently queues new requests such that its children are no longer affected by the hot plug operation.
An instance that receives this operation should throttle its operation. The MA will send this instance a Resume operation once the ancestor has been resumed.
24.6.5 Resume
This management operation is used by the MA to resume normal operation after Prepare To Suspend, Suspend, or Parent Suspended. It may be issued when the MA encounters a scenario in which the MA needs to abort the hot plug operation, or when sufficient hardware has been rebound such that I/O should resume.
If resuming from a suspend, a different parent device may have been re-bound, and this driver must adapt to all device property changes, such as those indicated by a constraints propagation. If the driver cannot, or chooses not to, maintain sufficient state to reprogram the (replacement) device when it is resumed, then it must respond to Prepare To Suspend with an indication that it does not support transparent resume. The MA may choose to abort the hot plug operation or continue with a non-transparent Suspend/Resume.
24.6.6 Abrupt Unbind
Instead of going through the normal device management unbind scenario, the MA may sometimes need to abruptly unbind a driver instance. This may happen as a result of an abrupt hot removal of a device (i.e. removing a device without informing the operating system). It may also happen as a result of "region-kill" as a result of a driver software failure. In either case, the event will propagate to neighboring driver instances as udi_channel_event_ind operations of type UDI_CHANNEL_CLOSED.
NAME udi_devmgmt_req
Device Management request
#include <udi.h>void udi_devmgmt_req ( udi_mgmt_cb_t *cb, udi_ubit8_t mgmt_op, udi_ubit8_t parent_ID ); /* Values for mgmt_op */#define UDI_DMGMT_PREPARE_TO_SUSPEND 1 #define UDI_DMGMT_SUSPEND 2 #define UDI_DMGMT_SHUTDOWN 3 #define UDI_DMGMT_PARENT_SUSPENDED 4 #define UDI_DMGMT_RESUME 5 #define UDI_DMGMT_UNBIND 6ARGUMENTS cb is a pointer to a miscellaneous Management Metalanguage control block.
mgmt_op is a value that selects the operation type.
parent_ID is the parent ID that indicates the parent for which the operation is to take place. This will match the value originally supplied by the MA when the parent was bound to the current driver via the udi_channel_event_ind operation of type UDI_CHANNEL_BOUND.
TARGET CHANNEL The Management Agent's management channel to the parent driver.
DESCRIPTION The Management Agent issues this request to manage I/O transfers within a driver instance during hot plug operations.
The mgmt_op argument must be one of the following values and indicates the type of management operation being requested:
UDI_DMGMT_PREPARE_TO_SUSPEND - Indicates that a Suspend operation is about to take place relative to the indicated parent.
UDI_DMGMT_SUSPEND - Requests the instance to suspend all operation relative to the indicated parent, and queue or fail new requests that are received. The instance must not acknowledge the request until all outstanding requests to the indicated parent are complete. The device must be put in a state that is prepared for the possibility of having power removed (for example, disk caches must be flushed), but device state and communications connections should not be completely shut down.
UDI_DMGMT_SHUTDOWN - Treated as UDI_DMGMT_SUSPEND, with the addition that the device must be completely shut down (in particular, all communications connections should be terminated).
UDI_DMGMT_PARENT_SUSPENDED - Indicates that outbound traffic via the indicated parent has been suspended.
UDI_DMGMT_RESUME - Indicates that the instance is to cancel any suspended or throttled state and is to resume full operation. I/O shall resume onto the then-active set of parents; if a multi-parent driver has parent-specific routing requirements, it must compare parent_ID against the set of currently-bound parents and fail if that parent is no longer (re-)bound.
UDI_DMGMT_UNBIND - Indicates that the driver must unbind from the indicated parent. The driver must first complete a metalanguage-specific unbind sequence with its parent and free resources related to that parent (it may choose to defer freeing some resources until it receives a udi_final_cleanup_req). As much as possible, the device should be shut down, as if it might be removed or powered off after this operation completes if this is the last parent. Communications connections should be terminated. Storage device write-back caches should be flushed to permanent storage, for example. When the unbinding is complete (and not before), the driver must respond to the UDI_DMGMT_UNBIND request with a corresponding udi_devmgmt_ack.
WARNING Drivers must not invoke this operation.
REFERENCES udi_devmgmt_ack, udi_mgmt_cb_t
NAME udi_devmgmt_ack
Acknowledge a device management request
#include <udi.h>void udi_devmgmt_ack { udi_mgmt_cb_t *cb, udi_ubit8_t flags, udi_status_t status } /* Values for flags */#define UDI_DMGMT_NONTRANSPARENT (1U<<0)/* Meta-Specific Status Codes */#define UDI_DMGMT_STAT_ROUTING_CHANGE (UDI_STAT_META_SPECIFIC|1)ARGUMENTS cb is a pointer to a miscellaneous Management Metalanguage control block.
status indicates the success or failure of the operation.
TARGET CHANNEL The parent driver's primary region management channel.
DESCRIPTION The udi_devmgmt_ack channel operation is used in response to a udi_devmgmt_req channel operation and provides information about a device management function requested of an instance.
The flags argument may include:
UDI_DMGMT_NONTRANSPARENT - Indicates that the requested UDI_DMGMT_PREPARE_TO_SUSPEND or UDI_DMGMT_SUSPEND operation has been complied with. The instance is also indicating that it does not support transparent resume.
STATUS VALUES UDI_OK - Indicates that the device management operation was handled successfully by the driver and that no exceptions are indicated.
UDI_STAT_NOT_SUPPORTED - Indicates that the instance has failed the UDI_DMGMT_PREPARE_TO_SUSPEND, UDI_DMGMT_SUSPEND, or UDI_DMGMT_SHUTDOWN request, because it does not maintain sufficient state to be able to suspend.
UDI_STAT_INVALID_STATE - Indicates that the instance has failed the UDI_DMGMT_PREPARE_TO_SUSPEND, UDI_DMGMT_SUSPEND, or UDI_DMGMT_SHUTDOWN request because its hardware, configuration state, coding level, etc, do not allow it to be suspended at this time.
UDI_DMGMT_STAT_ROUTING_CHANGE - Indicates that the instance has failed the UDI_DMGMT_SUSPEND or UDI_DMGMT_SHUTDOWN request. The instance is indicating that the set of children related to the indicated parent has changed since it was last enumerated. The MA is to re-enumerate and resume the operation. Drivers that do not support multiple parents need not check for this condition and must not use this status code.
warnings The control block must be the same control block as passed to the driver in the corresponding udi_devmgmt_req operation.
REFERENCES udi_devmgmt_req, udi_devmgmt_cb_t
NAME udi_final_cleanup_req
Release final resources prior to instance unload
#include <udi.h>void udi_final_cleanup_req ( udi_mgmt_cb_t *cb);ARGUMENTS cb is a pointer to a miscellaneous Management Metalanguage control block.
TARGET CHANNEL The affected driver instance's management channel
DESCRIPTION The MA issues this operation to request that the driver fully remove all resources and region instance context. The MA will only invoke this request after all parents and children have been unbound from the instance and the instance is now to fully be removed from the system. The driver must fully return any resources allocated on behalf of the instance, including closing any channels that the driver explicitly spawned.
Upon completion of this request, the driver must perform a udi_final_cleanup_ack operation, passing it the same control block as was passed to udi_final_cleanup_req. After sending the ack, it should logically appear as if the driver instance had not appeared in the system.
WARNING Drivers must not invoke this operation.
REFERENCES udi_final_cleanup_ack
NAME udi_final_cleanup_ack
Acknowledge completion of a final cleanup request
#include <udi.h>void udi_final_cleanup_ack ( udi_mgmt_cb_t *cb );ARGUMENTS cb is a pointer to a miscellaneous Management Metalanguage control block.
TARGET CHANNEL The affected driver instance's management channel
DESCRIPTION Handshakes a udi_final_cleanup_req operation. This indicates to the MA that the removal operation has completed.
The driver must free all of its resources before calling udi_final_cleanup_ack, regardless of its current state.
warnings The control block must be the same control block as passed to the driver in the corresponding udi_final_cleanup_req operation.
REFERENCES udi_final_cleanup_req
24.7 Metalanguage-Specific Trace Events
The following defines the rules and conventions in the Management Metalanguage for the use of the metalanguage-selectable trace events (see the "Metalanguage Trace Events" in the 17-3 of the UDI Core Specification).
- UDI_TREVENT_IO_SCHEDULED,
UDI_TREVENT_IO_COMPLETED- UDI_TREVENT_META_SPECIFIC_1
- This trace event is used to track the start and completion of scans for child devices (regardless of whether this causes any enumeration/denumeration operations with the management agent or whether it was triggered by a udi_enumerate_req). The driver may post trace events indicating the existence or non-existence of hardware as determined by the internal scan operations.
- UDI_TREVENT_META_SPECIFIC_2
UDI_TREVENT_META_SPECIFIC_3,
UDI_TREVENT_META_SPECIFIC_4,
UDI_TREVENT_META_SPECIFIC_5Note - All returned status values other than UDI_OK that indicate exceptional conditions must be logged and, when enabled, may also be traced, even if such events are expected.
24.8 Management Metalanguage States
The following states, along with the state diagram shown in Figure 25-1, define the valid states for a UDI driver relative to the Management Metalanguage and the allowed operations in each of the states.
Operations or events that cause a state change are indicated by a character label on the associated state change path in the state diagram; the character labels refer to events as shown in Table 25-2 below. If the operation is a success or failure indication, the success path is indicated by the single-character label and the failure path is indicated by a hash mark (`#') following the single-character label. Operations and events that are not listed in the state diagram do not cause state changes to occur.
24.8.1 Management Metalanguage States
START This is the initial state for any newly instantiated driver instance. A driver instance in this state has been newly created along with a management channel and is being prepared for I/O operations, but is not yet bound to any parents or children. This is the only state wherein secondary regions will be automatically instantiated and all secondary regions will be instantiated before leaving this state.
OPERATIONAL This is the primary state for a driver instance. In this state, parent and child channels may be bound to the instance and normal I/O channel operations and functionality may occur.
CLEANUP This is the final state for a driver instance and is entered from any state that has no parents or children bound, when udi_final_cleanup_req is received on that driver's management channel. Any remaining resources held by the driver must be released, preparatory to this driver instance being removed from the system.
24.8.1.1 Operational Sub-States
BINDING A driver in the BINDING state is in the process of satisfying a UDI_CHANNEL_BOUND event for a newly created parent bind channel. This is a transition state into the ACTIVE state.
ACTIVE This is the normal functional state for the driver instance. When in this state, the instance is bound to one or more parents and may also be bound to one or more child instances. The driver instance is expected to be able to handle I/O traffic and any associated device activity.
UNBINDING A driver instance enters this state when it has received a UDI_DMGMT_UNBIND request for a particular parent. In this state the driver is expected to complete any pending I/O to that parent and clean up any resources associated with that parent. Upon completion of this state (signalled by a corresponding udi_devmgmt_ack operation) the parent channel will be deallocated by the MA. The MA may later re-use the parent ID to enter the BINDING state but the target driver should treat this binding as a completely new binding.
THROTTLED This state is entered when the MA has suspended (or is in the process of suspending) a parent of the current driver instance; the driver should throttle operations and generate as little traffic as possible to the parent channel(s).
SUSPENDING This state is entered when the MA is preparing to handle a device shutdown/suspension in order to replace the device or perform some other device management operation.
SUSPENDED This state is entered when the MA issues a device management operation instructing the driver to temporarily halt I/O activities with respect to this parent.
CLOSING This state is entered when a UDI_CHANNEL_CLOSED event indication has been received on the parent bind channel to this parent. This indicates that the parent was abruptly removed as part of a region kill or other catastrophic event. In CLOSING state the target driver must clean up all resources relative to the parent immediately without exchanging further channel operations with that parent driver instance.
UNBOUND This state is reached when the last parent and child are unbound from this instance.
1The child represents a physical or logical entity that can be accessed via the parent device instance and for which a corresponding driver should be instantiated. Examples of parent/child relationships are: (1) a PCI Bus/PCI Card, a SCSI HBA/SCSI Disk, etc.
| |
|
|
|
