udi_enumerate_req(3udi)

---

Request information regarding a child instance

SYNOPSIS

#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				6
 

ARGUMENTS 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