HAP Memory APIs. More...

#include <stdlib.h>
#include "AEEStdDef.h"
#include "AEEStdErr.h"

Classes
struct	HAP_mem_stats
	Statistics of user heap memory. More...

struct	HAP_mem_heap_info_t
	RequestID/Response for HAP_mem_get_heap_info. More...

Macros
HAP_PROT
These macros define the permissions on memory block described by the file descriptor. It is passed as input parameter 'prot' to HAP_mmap(). These can be ORed to set the required permissions.
#define	HAP_PROT_NONE 0x00 /* no permissions */
	Passing HAP_PROT_NONE as input results in setting 'NO' permissions on the buffer.

#define	HAP_PROT_READ 0x01 /* pages can be read */
	Passing HAP_PROT_READ as input results in setting 'Read' permissions on the buffer.

#define	HAP_PROT_WRITE 0x02 /* pages can be written */
	Passing HAP_PROT_WRITE as input results in setting 'Write' permissions on the buffer.

#define	HAP_PROT_EXEC 0x04 /* pages can be executed */
	Passing HAP_PROT_EXEC as input results in setting 'Execute' permissions on the buffer. Currently not supported.

HAP_MEM_CACHE
These macros define the cache policies for mapping memory pages to DSP MMU. Default cache policy is cache writeback. It is passed as input parameter 'prot', or-ed with page protections to HAP_mmap().
#define	HAP_MEM_CACHE_WRITEBACK (0x10) /* cache write back */
	Passing HAP_MEM_CACHE_WRITEBACK as input results in mapping memory as cache writeback.

#define	HAP_MEM_CACHE_NON_SHARED (0x20) /* normal uncached memory */
	Passing HAP_MEM_CACHE_NON_SHARED as input results in mapping memory as uncached.

#define	HAP_MEM_CACHE_WRITETHROUGH (0x40) /* write through memory */
	Passing HAP_MEM_CACHE_WRITETHROUGH as input results in mapping memory as cache write through.

HAP_MEM_FLAGS
These macros define the buffer attribute flags for allocating APPS memory from the DSP. It is passed as input parameter 'flags' to HAP_apps_mem_request().
#define	HAP_MEM_FLAGS_SKIP_DSP_MAP 0
	Allocate memory on HLOS but skip DSP mapping.

#define	HAP_MEM_FLAGS_DSP_MAP 1
	Allocate memory on HLOS and map on DSP.

#define	HAP_MEM_FLAGS_EXTENDED_MAP 2
	Allocate memory on HLOS and map beyond 4GB virtual address range on DSP. More...

#define	HAP_MEM_FLAGS_MAX (HAP_MEM_FLAGS_EXTENDED_MAP + 1)
	Max number of flags supported by HAP_apps_mem_request.

Enumerations
enum	HAP_mem_stats_request { USAGE_STATS = 1, MAX_USED }
	Enum for reqID for HAP_mem_get_heap_info()

Functions
static int	HAP_malloc (uint32 bytes, void **pptr)

static int	HAP_free (void *ptr)

int	HAP_mem_get_stats (struct HAP_mem_stats *stats)

int	HAP_mem_get_heap_info (HAP_mem_heap_info_t *payload)

int	HAP_mem_set_grow_size (uint64 min, uint64 max)

int	HAP_mem_set_heap_thresholds (unsigned int low_largest_block_size, unsigned int high_largest_block_size)

void *	HAP_mmap (void *addr, int len, int prot, int flags, int fd, long offset)

void *	HAP_mmap2 (void *addr, size_t len, int prot, int flags, int fd, long offset)

int	HAP_munmap (void *addr, int len)

int	HAP_munmap2 (void *addr, size_t len)

int	HAP_mmap_get (int fd, void *vaddr, uint64 paddr)

int	HAP_mmap_put (int fd)

uint64	HAP_mem_available_stack (void)

int	HAP_apps_mem_request (size_t len, uint32_t flags, int fd, uint64_t dsp_va)

int	HAP_apps_mem_release (int fd)

Detailed Description

HAP Memory APIs.

Macro Definition Documentation

◆ HAP_MEM_FLAGS_EXTENDED_MAP

#define HAP_MEM_FLAGS_EXTENDED_MAP 2

Allocate memory on HLOS and map beyond 4GB virtual address range on DSP.

Unsupported currently. Reserved for future use.

Function Documentation

◆ HAP_apps_mem_release()

int HAP_apps_mem_release ( int fd )

Release previously allocated APPS memory from DSP. Releases memory from HLOS. Also unmaps memory from DSP if HAP_MEM_FLAGS_DSP_MAP was previously passed while requesting memory.

Parameters

[in] fd previously returned file descriptor of buffer

Returns: 0 on success

◆ HAP_apps_mem_request()

int HAP_apps_mem_request	(	size_t	len,
		uint32_t	flags,
		int *	fd,
		uint64_t *	dsp_va
	)

Allocate and map APPS memory from DSP

Usage of this API over malloc() is recommended when client wants greater control over DSP virtual address space as free() does not necessarily free the allocated memory depending on heap thresholds. HAP_apps_mem_request and HAP_apps_mem_release guarantee freeing of the allocated memory.

Parameters

[in]	len	size of memory to be allocated
[in]	flags	Buffer attribute flags HAP_MEM_FLAGS_SKIP_DSP_MAP, HAP_MEM_FLAGS_DSP_MAP or HAP_MEM_FLAGS_EXTENDED_MAP
[out]	fd	file descriptor of buffer
[out]	dsp_va	DSP mapped virtual address

Returns: 0 on success

◆ HAP_free()

static int HAP_free ( void * ptr )

inlinestatic

Free the memory block allocated through HAP_malloc().

Parameters

[in] ptr pointer to the memory block

Returns: int AEE_EBADCLASS if ptr is NULL AEE_SUCCESS if ptr is not NULL

◆ HAP_malloc()

static int HAP_malloc	(	uint32	bytes,
		void **	pptr
	)

inlinestatic

Allocate a block of memory.

Parameters

[in]	bytes	size of memory block in bytes.
[out]	pptr	pointer to the memory block

Returns: int AEE_SUCCESS for success and AEE_ENOMEMORY for failure.

◆ HAP_mem_available_stack()

uint64 HAP_mem_available_stack ( void )

Get the stack size (in bytes) available for current thread Supported only on Lahaina and Cedros

Returns: available stack for current thread, on success AEE_EINVALIDTHREAD if unable to get current thread id AEE_ERESOURCENOTFOUND if unable to get stack for current thread

◆ HAP_mem_get_heap_info()

int HAP_mem_get_heap_info ( HAP_mem_heap_info_t * payload )

Get the heap info.

Parameters

payload,pointer to store the request/response

Return values

◆ HAP_mem_get_stats()

int HAP_mem_get_stats ( struct HAP_mem_stats * stats )

Get the current statistics from the heap.

Parameters

[in,out] stats pointer to stats structure

Return values

AEE_SUCCESS

◆ HAP_mem_set_grow_size()

int HAP_mem_set_grow_size	(	uint64	min,
		uint64	max
	)

Set the minimum and maximum size by which the user heap should grow when it is exhausted and needs to add memory from the HLOS on the Apps processor.

This API allows to configure the minimum and maximum size that should be added to the DSP user heap when an allocation fails and more memory needs to be obtained from the HLOS. Using this API is optional. If not used, the runtime will try to choose reasonable growth sizes based on allocation history.

Parameters

[in]	min	minimum bytes to grow the heap by when requesting a new segment
[in]	max	maximum bytes to grow the heap by when requesting a new segment

Return values

AEE_SUCCESS

◆ HAP_mem_set_heap_thresholds()

int HAP_mem_set_heap_thresholds	(	unsigned int	low_largest_block_size,
		unsigned int	high_largest_block_size
	)

Set low and high memory thresholds for heap

Thresholds must be tuned according to the memory requirements

Improper thresholds might led to heap failure

Parameters

[in]	low_largest_block_size	(in bytes) - the heap will grow if size of the largest free block is less than this threshold. Currently, setting this parameter will have no impact on the heap.
[in]	high_largest_block_size	(in bytes) - the heap manager will release all unused sections if size of the largest free block is greater than this threshold. The recommended value for this, is the size of largest single allocation possible in your application.

Returns: AEE_SUCCESS on success AEE_EBADPARM on failure

◆ HAP_mmap()

void* HAP_mmap	(	void *	addr,
		int	len,
		int	prot,
		int	flags,
		int	fd,
		long	offset
	)

Map buffer associated with the file descriptor to DSP memory. The reference count gets incremented if the file descriptor is already mapped. This API is limited to buffer size less then 2 GB. Recommendation is to use HAP_mmap2 for buffer of size > 2 power(8*sizeof(size_t))

Parameters

[in]	addr	mapping at fixed address, not supported currently. This has to be set to NULL
[in]	len	size of the buffer to be mapped
[in]	prot	protection flags - supported are only HAP_PROT_READ and HAP_PROT_WRITE. HAP_PROT_EXEC is not supported
[in]	flags	HAP_MAP_NO_MAP - Increment reference count with no mapping 0 - map the buffer and increment the reference count
[in]	fd	file descriptor for the buffer
[in]	offset	offset into the buffer

Return values

mapped address -1 on failure

◆ HAP_mmap2()

void* HAP_mmap2	(	void *	addr,
		size_t	len,
		int	prot,
		int	flags,
		int	fd,
		long	offset
	)

Map buffer associated with the file descriptor to DSP memory. The reference count gets incremented if the file descriptor is already mapped.

Parameters

[in]	addr	mapping at fixed address, not supported currently. This has to be set to NULL
[in]	len	size of the buffer to be mapped
[in]	prot	protection flags - supported are only HAP_PROT_READ and HAP_PROT_WRITE. HAP_PROT_EXEC is not supported
[in]	flags	HAP_MAP_NO_MAP - Increment reference count with no mapping 0 - map the buffer and increment the reference count
[in]	fd	file descriptor for the buffer
[in]	offset	offset into the buffer

Return values

mapped address -1 on failure

◆ HAP_mmap_get()

int HAP_mmap_get	(	int	fd,
		void **	vaddr,
		uint64 *	paddr
	)

Get virtual and physical address associated with the buffer and increments the reference count.

Parameters

[in]	fd	file descriptor for the buffer
[out]	vaddr	virtual address associated with the buffer
[out]	paddr	physical address associated with the buffer

Return values

0	on success AEE_ENOSUCHMAP if fd is invalid

◆ HAP_mmap_put()

int HAP_mmap_put ( int fd )

Decrements the reference count of the file descriptor.

Parameters

[in] fd file descriptor of the buffer

Return values

0	on success AEE_ENOSUCHMAP if fd is invalid AEE_EBADMAPREFCNT if map refcount is <=0

◆ HAP_munmap()

int HAP_munmap	(	void *	addr,
		int	len
	)

Decrements the reference count and unmaps the buffer from memory if the reference count goes to 0. This API is used for buffer size less then 2 GB. Recommendation is to use HAP_munmap2 for buffer of size > 2 power(8*sizeof(size_t)).

Parameters

[in]	addr	mapped address
[in]	len	size of the mapped buffer

Returns: 0 on success AEE_NOSUCHMAP in input addr is invalid

◆ HAP_munmap2()

int HAP_munmap2	(	void *	addr,
		size_t	len
	)

Decrements the reference count and unmaps the buffer from memory if the reference count goes to 0.

Parameters

[in]	addr	mapped address
[in]	len	size of the mapped buffer

Returns: 0 on success AEE_NOSUCHMAP in input addr is invalid

Classes

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ HAP_MEM_FLAGS_EXTENDED_MAP

Function Documentation

◆ HAP_apps_mem_release()

◆ HAP_apps_mem_request()

◆ HAP_free()

◆ HAP_malloc()

◆ HAP_mem_available_stack()

◆ HAP_mem_get_heap_info()

◆ HAP_mem_get_stats()

◆ HAP_mem_set_grow_size()

◆ HAP_mem_set_heap_thresholds()

◆ HAP_mmap()

◆ HAP_mmap2()

◆ HAP_mmap_get()

◆ HAP_mmap_put()

◆ HAP_munmap()

◆ HAP_munmap2()