Initializes a new heap to be used with kernel memory management services. The heap_create kernel service replaces the init_heap kernel service. It returns a heap handle that can be used with the xmalloc and the xmfree kernel services.
Item | Description |
---|---|
heapattr | Points to an initialized heap attribute structure. See the sys/malloc.h file. This structure is initialized by the caller of heap_create. |
heapptr | Points to an external heap descriptor. The caller must initialize this parameter to the HPA_INVALID_HEAP value. |
The heapattr structure contains the following fields:
Item | Description |
---|---|
eye_catch8b_t hpa_eyec | Must be initialized to the EYEC_HEAPATTR value. |
short hpa_version | Must be initialized to the HPA_VERSION value. |
long hpa_flags | The following flags describe heap properties:
|
void * hpa_heapaddr | Must be set to NULL (reserved). |
size_t hpa_heapsize | Heap size in bytes. It is only used for private heaps. |
size_t hpa_limit | Usage barrier independent from size. Limits the amount available from a private heap that is less than or equal to the actual size of the private heap. |
long hpa_debug_level | Heap debug level. The HPA_DEFAULT_DEBUG value gives the heap the system debug level. |
uint hpa_kkey | Kernel key requested for the storage allocated. |
The heap_create service is a replacement for the init_heap service. It can be used to create private heaps, and to create shared sub-heaps. After this service creates a private heap or a handle to a shared sub-heap, the returned heapaddr_t value can be used with the xmalloc service or the xmfree service to allocate or free memory from that heap.
The most common usage for the heap_create service is to get a handle to a shared sub-heap. This is done by setting the HPA_SHARED flag in the input attribute structure. See the sys_malloc.h file.
Private heaps can be created by specifying the HPA_PRIVATE flag. This allows the heap_create service to initialize and manage an area of virtual memory as a private heap. The hpa_heapaddr field must be set to zero. The heap_create service provides the storage but this field is reserved for future use. The hpa_size field indicates the size of the private heap in bytes.
Private heaps can make use of the hpa_limit field. Use the hpa_size field to reserve a maximum effective address space. Then use the hpa_limit field to alter and control the amount of effective address space that is in use. The value of the hpa_limit field must be less than or equal to the value of the hpa_size field.
The hpa_debug and hpa_kkey fields are required for shared and private heaps. The hpa_debug level allows a component run-time debug level to be applied to allocations using the returned heap handle. The hpa_kkey field associates a kernel key with a sub-heap that can limit the kernel accessibility.
On a successful completion, the heapattr field contains the address of a heap structure. This can be used as a parameter to the xmalloc and the xmfree kernel services. The memory returned by these services and the internal heap structures are protected by the hpa_kkey field. When calling the xmalloc and the xmfree heap services, the caller must hold the key that was used when creating the heap.
The heap_create kernel service can be called from the process environment only.
Item | Description |
---|---|
0 | Indicates a successful completion. A descriptor is returned in the heapptr parameter. |
EINVAL_HEAP_CREATE | Indicates one or more of the following inputs that were not
valid:
|
ENOMEM_HEAP_CREATE | Indicates insufficient memory available to complete the request. |