udi_cb_init_t(3udi)

---

Control block initialization structure

SYNOPSIS

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

MEMBERS 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