heap_create Kernel Service

Purpose

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.

Syntax

#include <sys/types.h>
#include <sys/malloc.h>
#include <sys/skeys.h>
#include <sys/kerrno.h>

kerrno_t heap_create (heapattr_t * heapattr, heapaddr_t * heapptr);

Parameters

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:
HPA_PAGED
The heap returns pageable memory.
HPA_PINNED
The heap returns pinned memory.
HPA_SHARED
The returned descriptor is backed by a common sub-heap.
HPA_PRIVATE
The returned descriptor is backed by isolated storage.
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.

Description

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.

Execution Environment

The heap_create kernel service can be called from the process environment only.

Return Values

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:
  • heapattr is NULL.
  • *heapptr != HPA_INVALID_HEAP.
  • heapattr->hpa_eyec != EYEC_HEAPATTR.
  • heapattr->hpa_version != HPA_VERSION.
  • Flags: Both the HPA_SHARED and the HPA_PRIVATE flags are specified.
  • Flags: Neither the HPA_SHARED nor the HPA_PRIVATE flag is specified.
  • Flags: Both the HPA_PINNED and the HPA_PAGED flags are specified.
  • Flags: Neither the HPA_PINNED nor the HPA_PAGED flag is specified.
  • Keys: kernel key specified is not valid.
  • Other: Size is specified with a shared heap.
  • Other: Limit is specified with a shared heap.
  • Other: Address specified is not NULL.
  • Other: Limit > size for private heap.
  • Other: Private heap size is too small (less than 8M).
ENOMEM_HEAP_CREATE Indicates insufficient memory available to complete the request.