|
|
| |
|
|
|
Memory Management
12.1 Overview
The UDI memory management services allow drivers to allocate and free blocks of region-local, virtually-contiguous memory. There are two types of virtually-contiguous memory allocation provided in UDI: (1) allocation of memory which is transferable, or movable, between regions (provides for memory which can either directly or indirectly be passed as an argument to a channel operation), and (2) allocation of memory which is not transferable between regions (may only be used within the context of the caller's region). In both cases the environment returns a region-local pointer to the allocated memory. In the transferable case it is up to the environment implementation of the channel operations to translate the region-local pointer being transferred to a region-local pointer in the target region. Non-transferable memory should be used wherever possible, as allocation of transferable memory may be more expensive in some environments.
Note - For memory copy, compare, and initialization utility functions, see Chapter 20, "String/Memory Utility Functions".
When using memory allocation services, care must be taken to avoid excessive use of memory resources. Memory is a finite system resource. It is the device driver's responsibility to allocate, track and release memory back to the environment in a responsible manner.
The driver must also be careful to keep its memory demands in tune with the capabilities of the platform. 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. When a driver region is created, it is provided with a set of platform-specific allocation limits (see udi_limits_t) to which it must conform. The resource managements operations in the Management Metalanguage provide additional resource utilization guidelines to the driver (see Section 24.4.2, "Resource Management").
Warning - Memory allocated by udi_mem_alloc is intended for access by driver software and must not be used for Direct Memory Access from devices. DMA-addressable memory allocation is described in the DMA chapter of the UDI Physical I/O Specification, for those environments that support DMA and other physical I/O.
12.2 Memory Management Service Calls
The memory management service calls, which consist of udi_mem_alloc and udi_mem_free, are described in the paragraphs that follow.
NAME udi_mem_alloc
Allocate memory for a virtually-contiguous object
#include <udi.h>void udi_mem_alloc ( udi_mem_alloc_call_t *callback, udi_cb_t *gcb, udi_size_t size, udi_ubit8_t flags ); typedef void udi_mem_alloc_call_t ( udi_cb_t *gcb, void *new_mem ); /* Values for flags */#define UDI_MEM_NOZERO (1U<<0) #define UDI_MEM_MOVABLE (1U<<1)ARGUMENTS callback, gcb are standard arguments described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
size is the number of bytes of space requested. See udi_limits_t for limits on allocation sizes.
flags is a bitmask of optional flags, which may include zero or more of the following:
UDI_MEM_NOZERO - Don't zero memory contents.
UDI_MEM_MOVABLE - Allocate movable memory.
new_mem is a pointer to the new memory object. The driver is expected to cast this to the appropriate type of struct, array, etc. If size is zero, new_mem will be NULL.
DESCRIPTION udi_mem_alloc allocates memory for a new virtually-contiguous object capable of storing at least size bytes. The newly allocated memory will be zeroed unless UDI_MEM_NOZERO is set, in which case the initial values are undefined.
The newly allocated memory will be aligned on the most restrictive alignment of the platform's natural alignments for long and pointer data types, allowing the allocated memory to be directly accessed as C structures.
If the UDI_MEM_MOVABLE flag is set, the memory will be allocated as movable memory. This means that it can be passed outside of the region from which it was allocated. Only movable memory may be pointed to by control block fields or channel operation parameters. UDI_MEM_MOVABLE should be used only if needed, as movable memory may be a more limited resource.
WARNINGS The memory allocated by this routine has no particular physical or I/O bus-related properties. It is intended only for access by driver software.
Control block usage must follow the rules described in the "Asynchronous Service Calls" section of "Calling Sequence and Naming Conventions".
The usage of memory allocated by this routine must follow the rules described in the "Memory Objects" section of "Data Model".
REFERENCES udi_mem_free, udi_cancel, udi_limits_t
NAME udi_mem_free
Free a memory object
#include <udi.h>void udi_mem_free ( void *target_mem );ARGUMENTS target_mem is a pointer to the memory object being deallocated.
DESCRIPTION udi_mem_free frees all resources associated with the specified memory object. The driver must not dereference the target_mem pointer once this function is called.
If target_mem is equal to NULL, explicitly or implicitly (zeroed by initial value or by using udi_memset), this function acts as a no-op. Otherwise, target_mem must have been allocated by udi_mem_alloc or passed to the driver as a movable memory block via a channel operation.
Note - The udi_init_context_t structure, the rest of the initial region data area, and any channel context structures pre-allocated by the environment, must not be freed by the driver and are not transferrable between regions.
| |
|
|
|