udi_enumerate_cb_t(3udi)

---

Enumeration operation control block

SYNOPSIS

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

MEMBERS 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