udi_limits_t(3udi)

---

Platform-specific allocation and access limits

SYNOPSIS

#include <udi.h>

typedef struct {

	udi_size_t max_legal_alloc;

	udi_size_t max_safe_alloc;

	udi_size_t max_trace_log_formatted_len;

	udi_size_t max_instance_attr_len;

	udi_ubit32_t min_curtime_res;

	udi_ubit32_t min_timer_res;

} udi_limits_t;
 
/* architectural minimums */
 

#define  UDI_MIN_ALLOC_LIMIT				4000
 
#define  UDI_MIN_TRACE_LOG_LIMIT				200
 
#define  UDI_MIN_INSTANCE_ATTR_LIMIT				64
 

MEMBERS max_legal_alloc is the maximum legal memory allocation size for this system. Any larger size passed to udi_mem_alloc will produce indeterminate results, which could include termination of the driver or region, or even a complete system abort.

max_safe_alloc is the maximum memory allocation size that must be passed to udi_mem_alloc without being prepared to cancel an unsuccessful allocation (see definition of "safe limits" below).

max_trace_log_formatted_len is the maximum legal size of the formatted result of a call to udi_trace_write or udi_log_write.

max_instance_attr_len is the maximum legal size of an instance attribute value.

min_curtime_res is the minimum time difference, in nanoseconds, between successive unique values returned by udi_time_current.

min_timer_res is the minimum resolution, in nanoseconds, of timers registered with udi_timer_start_repeating or udi_timer_start. See udi_timer_start for details on how min_timer_res affects timer operation.

DESCRIPTION udi_limits_t reflects implementation-dependent system limits, such as memory allocation and timer resolution limits, for a particular region. These limits may vary from region to region, but will remain constant for the life of a region.

The udi_limits_t structure is passed to a driver instance via the udi_init_context_t in its initial region data.

Since UDI can be implemented on a wide variety of systems from small embedded systems to large server systems, the memory available for drivers can vary widely. udi_limits_t allows drivers to adjust their allocation algorithms to best fit their environment.

There are two types of allocation limits: legal limits and safe limits. Legal limits represent the absolute upper bound on a single allocation. Drivers must not make requests that would exceed the legal limits.

Safe limits represent the maximum amount that a driver may safely request without arranging to deal with unsuccessful allocations. For any size greater than the safe limit (but not exceeding the legal limit), drivers must cancel the request (using udi_cancel) after a reasonable amount of time has expired. To do this, the driver may set a timer using udi_timer_start or udi_timer_start_repeating. Drivers are expected to be coded as if allocations below the safe limit will always eventually succeed.

The max_legal_alloc and max_safe_alloc limits affect the size of virtually-contiguous driver memory allocations via udi_mem_alloc. These allocation limits are guaranteed to be greater than or equal to UDI_MIN_ALLOC_LIMIT in all UDI environments. This means drivers don't need to check these limits for requests that don't exceed UDI_MIN_ALLOC_LIMIT bytes. C language structures that need to be dynamically allocated should be limited to UDI_MIN_ALLOC_LIMIT bytes in size, so they can be allocated directly with a simple udi_mem_alloc call.

The max_trace_log_formatted_len limit specifies the maximum size, in bytes, of strings resulting from formatting messages passed to udi_trace_write or udi_log_write. This limit is guaranteed to be greater than or equal to UDI_MIN_TRACE_LOG_LIMIT in all UDI environments.

The max_instance_attr_len parameter specifies the maximum size, in bytes, of a device instance attribute value (see Chapter 15, "Instance Attribute Management") that can be handled by the environment. This limit is guaranteed to be greater than or equal to UDI_MIN_INSTANCE_ATTR_LIMIT in all UDI environments.

The min_curtime_res and min_timer_res parameters specify the corresponding resolution of the system chronological timer and system timeout timer, respectively (see Chapter 14, "Time Management"). Current time values will change no faster than the amount of time specified by min_curtime_res, and timers will not be scheduled with any better resolution or granularity than the min_timer_res specification.

REFERENCES udi_mem_alloc, udi_cancel, udi_timer_start, udi_timer_start_repeating, udi_init_context_t, udi_instance_attr_set, udi_trace_write, udi_log_write