udi_usage_ind(3udi)


Indicate desired resource usage and trace levels

SYNOPSIS

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

ARGUMENTS 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.

PROXIES udi_static_usage

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


UDI Core Specification Contents