Management metalanguage operations vector

All device configuration, driver instantiation, and initial channel creation is driven and controlled by the UDI ``Management Agent'' (MA), which is always present in any UDI environment implementation. All UDI drivers must provide entry points (really, callback functions) for the MA into the driver, in a management metalanguage operations vector.

The Management Metalanguage defines the communication between a driver instance and the MA and is used for the ``management channel'', which is a channel that is always present between the MA and the driver's primary region.

The MA generates a Management Metalanguage request to a driver over the management channel when it needs that driver to perform some management-related function. The driver must define the required callback functions to send data back to the MA. This is a one-way realtionship, meaning that the driver never generates any requests over this channel, it only responds to requests from the MA.

The udi_mgmt_ops_t structure is the management operations vector.

   typedef 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 ;

This structure contains pointers to routines required to answer queries from the MA as it sets up a primary region.

For an overview of the Management Metalanguage and the role of the MA in the UDI environment, see Management Metalanguage in the UDI Core Specification. The exact sequence of events that occurs when a region is intialized is documented in the Core Specification, under Driver Instantiation.

Here we will summarize what each required routine must do, and the udi_mgmt_ops_t structures provided by the sample drivers. Shown below are the management operations vectors for the udi_cmos and pseudod drivers.

cmos_udi.c sample code (cont.)
/* * Driver entry points for the Management Metalanguage. */ static udi_devmgmt_req_op_t cmos_devmgmt_req; static udi_final_cleanup_req_op_t cmos_final_cleanup_req; static udi_mgmt_ops_t cmos_mgmt_ops = { udi_static_usage, udi_enumerate_no_children, cmos_devmgmt_req, cmos_final_cleanup_req };
pseudod.c sample code (cont.)
/* * Management Metalanguage/Pseudo Driver entry points */ static udi_devmgmt_req_op_t pseudo_devmgmt_req; static udi_final_cleanup_req_op_t pseudo_final_cleanup_req; static udi_mgmt_ops_t pseudo_mgmt_ops = { udi_static_usage, udi_enumerate_no_children, pseudo_devmgmt_req, pseudo_final_cleanup_req };

The usage_ind_op element either contains a driver-specific function name, or the proxy function udi_static_usage. The driver-specific function name starts with a unique identifier usually associated with the driver, and followed by _usage_ind. It's syntax follows the udi_usage_ind(3udi) management metalanguage function, and it specifies how the driver adjusts resource utilization levels and whether it supports tracing. Drivers like the udi_cmos and psedudod drivers that do not adjust their resource utilization levels and do not support tracing specify udi_static_usage as the entry point for this operation.

The enumerate_req_op element either contains a driver-specific function name, or the proxy function udi_enumerate_no_children. The driver-specific function name starts with a unique identifier usually associated with the driver, and followed by _enumerate_req. It's syntax follows the udi_enumerate_req(3udi) management metalanguage function, and it specifies the presence, number, and initial instance attributes of any child devices (actual or pseudo) associated with the current driver instance. The enumeration request and acknowledgement operation, along with associated data objects is described in the section Enumeration Operations in the Core Specification. Drivers like the udi_cmos and psedudod drivers that do not need to enumerate any children can use the UDI-environment proxy function udi_enumerate_no_children as the entry point for this operation.

The devmgmt_req_op and final_cleanup_req_op elements are required to contain the name of a driver-specific function. These functions will respond to MA requests to, respectively, manage I/O transfers within a driver instance during hot plug operations, and perform final cleanup operations when an instance is being unloaded by the MA. The cmos_devmgmt_req and pseudo_devmgmt_req functions perform the acknowlegdement operations that the driver will use to respond a udi_devmgmt_req call from the MA. Similarly, the cmos_final_cleanup_req and pseudo_final_cleanup_req functions respond to a udi_final_cleanup_req call from the MA.

These functions will be discussed further under ``udi_cmos child channel operations''.

For an overview of UDI function naming conventions and calling sequences, see Calling Sequence and Naming Conventions in the Core Specification.