POSAL API’s

posal_cache

This file contains utilities for cache operations.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef void *posal_mem_addr_t

Functions

ar_result_t posal_cache_flush(uint32_t virt_addr, uint32_t mem_size)

Flushes the cache (data) of the specified memory region.

: Nonzero — Failure

Parameters:

virt_addr – [in] Starting virtual address.
mem_size – [in] Size of the region to flush.

Returns:

0 — Success

ar_result_t posal_cache_flush_v2(posal_mem_addr_t virt_addr, uint32_t mem_size)

Flushes the cache (data) of the specified memory region.

: Nonzero — Failure

Parameters:

virt_addr – [in] Starting virtual address.
mem_size – [in] Size of the region to flush.

Returns:

0 — Success

ar_result_t posal_cache_invalidate(uint32_t virt_addr, uint32_t mem_size)

Invalidates the cache (data) of the specified memory region.

: Nonzero — Failure

Parameters:

virt_addr – [in] Starting virtual address.
mem_size – [in] Size of the region to invalidate.

Returns:

0 — Success

ar_result_t posal_cache_invalidate_v2(posal_mem_addr_t virt_addr, uint32_t mem_size)

Invalidates the cache (data) of the specified memory region.

: Nonzero — Failure

Parameters:

virt_addr – [in] Starting virtual address.
mem_size – [in] Size of the region to invalidate.

Returns:

0 — Success

ar_result_t posal_cache_flush_invalidate(uint32_t virt_addr, uint32_t mem_size)

Flushes and invalidates the cache (data) of the specified memory region.

: Nonzero — Failure

Parameters:

virt_addr – [in] Starting virtual address.
mem_size – [in] Size of the region to flush.

Returns:

0 — Success

ar_result_t posal_cache_flush_invalidate_v2(posal_mem_addr_t virt_addr, uint32_t mem_size)

Flushes and invalidates the cache (data) of the specified memory region.

: Nonzero — Failure

Parameters:

virt_addr – [in] Starting virtual address.
mem_size – [in] Size of the region to flush.

Returns:

0 — Success

posal_data_log

Posal data log apis.

Defines

SPF_LOG_PREFIX

Typedefs

typedef enum posal_data_log_format_t posal_data_log_format_t: Log data formats.

typedef enum posal_data_log_mode_t posal_data_log_mode_t

typedef struct posal_data_log_pcm_info_t posal_data_log_pcm_info_t: PCM data information for the logging utility user.

typedef struct posal_data_log_fmt_info_t posal_data_log_fmt_info_t: Format of the data being logged: PCM or bitstream.

typedef struct posal_data_log_info_t posal_data_log_info_t: Log header and data payload information for the logging utility user.

Enums

enum posal_data_log_format_t

Log data formats.

Values:

enumerator LOG_DATA_FMT_PCM: PCM data format.

enumerator LOG_DATA_FMT_BITSTREAM: Bitstream data format.

enumerator LOG_DATA_FMT_RAW: Raw data format.

enum posal_data_log_mode_t

Values:

enumerator LOG_DEFAULT

enumerator LOG_IMMEDIATE

Functions

bool_t posal_data_log_code_status(uint32_t log_code)

This function checks if the cog code is enabled .

Dependencies: None

Returns:: TRUE if the log code is enabled and FALSE if it is disabled.

uint32_t posal_data_log_get_max_buf_size()

This function gives the maximum packet size allowed for logging.

Dependencies: None

void *posal_data_log_alloc(uint32_t buf_Size, uint32_t log_code, posal_data_log_format_t data_fmt)

Allocates a log packet for PCM/bitstream data logging.

Associated data types: #log_data_format
Dependencies: None.

Parameters:

buf_Size – [in] Size of the data payload, excluding the log header.
log_code – [in] Log code for this log packet.
data_fmt – [in] PCM or bitstream data format.

Returns:

Pointer to payload of the allocated log packet. Returns NULL if buffer allocation fails or log code is disabled.

ar_result_t posal_data_log_commit(void *log_pkt_payload_ptr, posal_data_log_info_t *log_info_ptr)

Populates the log header and data payload of an allocated log packet and commits the packet for logging.

: Nonzero — Failure
Dependencies: None

Parameters:

log_pkt_payload_ptr – [in] Pointer to payload of the allocated log packet.
log_tap_id – [in] Tap point ID of the log packet.
session_id – [in] Session ID of the log packet.
buf_size – [in] Payload size of the log packet.

Returns:

0 — Success

ar_result_t posal_data_log_alloc_commit(posal_data_log_info_t *log_info_ptr)

Allocates the log packet, populates the log header and data payload, and commits the packet for logging.

Associated data types: #log_info
: Nonzero — Failure
Dependencies: None

Parameters:: log_info_ptr – [in] Pointer to the object containing the log header and data payload information for the logging utility client.
Returns:: 0 — Success

void posal_data_log_free(void *log_pkt_payload_ptr)

This function frees the data log buffer in case of error scenerio.

Dependencies: None

Parameters:: log_ptr – [in] : payload of the data log buffer to be freed
Returns:: None.

struct posal_data_log_pcm_info_t

#include <posal_data_log.h>

PCM data information for the logging utility user.

Public Members

uint32_t sampling_rate: PCM sampling rate. 8000 Hz, 48000 Hz, etc.

uint16_t num_channels: Number of channels in the PCM stream.

uint8_t bits_per_sample: Bits per sample for the PCM data.

uint8_t interleaved: Specifies whether the data is interleaved.

uint8_t q_factor: q factor information for log packet.

uint8_t data_format: data_format information for log packet.

uint16_t *channel_mapping: Array of channel mappings.

struct posal_data_log_fmt_info_t

#include <posal_data_log.h>

Format of the data being logged: PCM or bitstream.

Public Members

posal_data_log_pcm_info_t pcm_data_fmt: Format of the PCM data.

uint32_t media_fmt_id: Format of the bitstream data.

struct posal_data_log_info_t

#include <posal_data_log.h>

Log header and data payload information for the logging utility user.

Public Members

uint32_t log_code: log code for the log packet.

int8_t *buf_ptr: Pointer to the buffer to be logged.

uint32_t buf_size: Size of the payload to be logged, in bytes.

uint32_t session_id: Session ID for the log packet.

uint32_t log_tap_id: GUID for the tap point.

uint64_t log_time_stamp: Timestamp in microseconds.

posal_data_log_format_t data_fmt: Data format for the log packet.

posal_data_log_fmt_info_t data_info: Pointer to the data packet information.

uint32_t *seq_number_ptr: Reference to sequence number variable shared by client.

posal_globalstate

This file contains the global state structure for the posal environment. This state includes system-wide information such as the number of active threads and malloc counters.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef struct posal_globalstate_t posal_globalstate_t

typedef struct posal_memorymap_client_t posal_memorymap_client_t

Variables

posal_globalstate_t posal_globalstate: Instance of the global state structure.

struct posal_mem_stats_t

#include <posal_globalstate.h>

Memory usage statistics obtained during a test case run.

Public Members

uint32_t num_mallocs: Total number of memory allocations up to the current point in the test.

uint32_t num_frees: Total number of times memory is freed to the current point in the test.

uint32_t curr_heap: Current heap usage at the current point in the test.

uint32_t peak_heap: Peak heap usage up to the current point in the test.

struct posal_globalstate_t

#include <posal_globalstate.h>

Global structure used to track resources, such as threads and queues. This structure is intended for use in such tasks as debugging and checking for leaks.

Public Members

posal_mem_stats_t avs_stats[POSAL_HEAP_MGR_MAX_NUM_HEAPS + 1]

Heap statistics for Audio-Voice Subsystem (AVS) threads.

This number comprises one default heap plus the #POSAL_HEAP_MGR_MAX_NUM_HEAPS non-default heap.

posal_mem_stats_t non_avs_stats: Heap statistics for non-AVS threads.

int32_t nSimulatedMallocFailCount: If the failure count > 0, counts memory allocations down to zero, and then simulates out-of-memory. This count is used for testing.

posal_atomic_word_t nMsgQs: Counter of queues to help generate unique names.

posal_atomic_word_t nMemRegions: Counter of the number of memory regions in a system.

posal_mutex_t mutex: Mutex for thread safety of this structure.

posal_memorymap_client_t *mem_map_client_list[POSAL_MEMORY_MAP_MAX_CLIENTS]: Linked list of memory map clients in the system.

uint32_t num_registered_memmap_clients

uint32_t bEnableQLogging: Logs the commands going into queues and coming out of queues.

uint32_t uSvcUpStatus: Specifies whether the aDSP static services are up and ready.

bool_t is_global_init_done: Flag to set if global init is done.

struct posal_memorymap_client_t

#include <posal_globalstate.h>

Maintains a linked list of clients registered with posal_memorymap.

Public Members

posal_memorymap_node_t *pMemMapListNode: List of memory map nodes for this client.

posal_mutex_t mClientMutex: Mutex to access the list.

uint32_t client_id: Client ID.

posal_heapmgr

This file contains utilities for memory allocation and release. This file provides memory allocation functions and macros for both C and C++.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef uint32_t posal_heap_tcm_handle_t

Functions

ar_result_t posal_memory_heapmgr_create(POSAL_HEAP_ID *heap_id_ptr, void *heap_start_ptr, uint32_t heap_size, bool_t is_init_heap_needed)

Initializes the heap manager for a specified heap.

Associated data types: POSAL_HEAP_ID
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

heap_id_ptr – [in] Pointer to the heap ID.
heap_start_ptr – [in] Pointer to the start address of the heap.
heap_size – [in] Size of the heap.
is_init_heap_needed – [in] Set to TRUE for heap management doing within SPF. Set to FALSE if heap management is doing in non SPF code(like coretech) for eg,TCM heap mgr where heap managemnet done by sysdrivers.

Returns:

Status of the heap manager creation.

ar_result_t posal_memory_heapmgr_create_v2(POSAL_HEAP_ID *heap_id_ptr, void *heap_start_ptr, uint32_t heap_size, bool_t is_init_heap_needed, uint32_t heap_type, posal_heap_tcm_handle_t *tcm_handle_ptr, char *tcm_name, uint32_t tcm_name_len)

Initializes the heap manager for a specified heap.

Associated data types: POSAL_HEAP_ID
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

heap_id_ptr – [in] Pointer to the heap ID.
heap_start_ptr – [in] Pointer to the start address of the heap.
heap_size – [in] Size of the heap.
is_init_heap_needed – [in] Set to TRUE for heap management doing within SPF. Set to FALSE if heap management is doing in non SPF code(like coretech) for eg,TCM heap mgr where heap managemnet done by sysdrivers.
heap_type – [in] type of Heap being created (default/ddr, lpm, island)
tcm_handle_ptr – [out] ptr to tcm heap handle
tcm_name – [in] name of tcm pool heap
tcm_name_len – [in] length of tcm_name

Returns:

Status of the heap manager creation.

ar_result_t posal_memory_heapmgr_destroy(POSAL_HEAP_ID heap_id)

De-initializes the heap manager of a specified heap ID.

Associated data types: POSAL_HEAP_ID
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: heap_id – [in] ID of the heap.
Returns:: Status of the heap manager deletion.

posal_internal_inline

Internal definitions. Helps optimize by making inline calls. Must not be used by shared libraries due to backward compatibility concerns.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

QURT_SIGNAL(api, sig_obj, ...)

QURT_SIGNAL_OBJ

Functions

static inline uint32_t posal_channel_wait_inline(posal_channel_t pChannel, uint32_t unEnableBitfield)

static inline uint32_t posal_channel_poll_inline(posal_channel_t pChannel, uint32_t unEnableBitfield)

static inline bool_t posal_island_get_island_status_inline(void)

static inline void posal_mutex_unlock_inline(posal_mutex_t posal_mutex)

static inline void posal_mutex_lock_inline(posal_mutex_t posal_mutex)

static inline posal_channel_t posal_signal_get_channel_inline(posal_signal_t p_signal)

static inline uint32_t posal_signal_get_channel_bit_inline(posal_signal_t p_signal)

static inline void posal_signal_clear_inline(posal_signal_t p_signal)

static inline bool_t posal_signal_is_set_inline(posal_signal_t p_signal)

struct posal_channel_internal_t

#include <posal_internal_inline.h>

Public Members

QURT_SIGNAL_OBJ anysig: Any 32-bit signal channel.

uint32_t unBitsUsedMask

Mask bookkeeping for used bits.

1 — Used
0 — Available

struct posal_signal_internal_t

#include <posal_internal_inline.h>

Signal to be triggered by events, or used to trigger events. The signal coalesces on a channel bit. The only way to receive a signal is through its associated channel.

Public Members

posal_channel_internal_t *pChannel: Pointer to the associated channel.

uint32_t unMyChannelBit: Channel bitfield of this signal.

posal_island

This file contains island utilities’ declarations.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Enums

enum posal_island_heap_t

Values:

enumerator POSAL_ISLAND_HEAP_Q6_TCM

enumerator POSAL_ISLAND_HEAP_LPASS_TCM

enumerator POSAL_ISLAND_HEAP_LLC

enumerator POSAL_ISLAND_HEAP_NUM_SUPPORTED

Functions

POSAL_HEAP_ID posal_private_get_island_heap_id_v2(uint32_t island_heap_type): Private Api for getting island heap id

posal_mem_t posal_private_get_mem_type_from_heap_type(uint32_t island_heap_type): Private Api for getting posal mem type

ar_result_t posal_island_trigger_island_exit(void)

This function process island exit.

Dependencies: None.

Returns:: Indication of success (0) or failure (nonzero).

static inline ar_result_t posal_island_trigger_island_exit_inline(void)

Inline function to exit island when USES_AUDIO_IN_ISLAND is not defined

Dependencies: None.

Returns:: Indication of success (0) or failure (nonzero).

bool_t posal_island_get_island_status(void)

This function Get island mode status.

Returns a value indicating whether the underlying system is executing in island mode.

Dependencies: None.

Returns:: 0 - Normal mode. 1 - Island mode.

static inline POSAL_HEAP_ID posal_get_island_heap_id(void)

static inline POSAL_HEAP_ID posal_get_island_heap_id_v2(posal_island_heap_t heap_type)

static inline POSAL_HEAP_ID posal_get_heap_id(posal_mem_t mem_type)

static inline posal_mem_t posal_get_mem_type_from_heap_type(posal_island_heap_t heap_type)

Variables

POSAL_HEAP_ID spf_mem_island_heap_id: Default island heap = Q6 TCM by default.

posal_memorymap

This file contains utilities for memory mapping and unmapping of shared memory.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef struct posal_memorymap_node_t posal_memorymap_node_t

Enums

enum POSAL_MEMORYPOOLTYPE

Valid memory map pool IDs.

Values:

enumerator POSAL_MEMORYMAP_DEFAULTPHY_POOL: Default physical pool.

enumerator POSAL_MEMORYMAP_AUDIO_DYNAMIC_POOL: Dynamic Pool - created during usecase

enumerator POSAL_MEMORYMAP_SMI_POOL: Stacked memory interface pool.

enumerator POSAL_MEMORYMAP_SHMEM8_4K_POOL: Shared memory; 8-byte addressable, 4 KB aligned memory pool.

enumerator POSAL_MEMORYMAP_POOL_OUT_OF_RANGE: Out of range.

enum posal_memorymap_mapping_mode_t

Valid memory mapping modes.

Values:

enumerator POSAL_MEMORYMAP_PHYSICAL_ADDR_MAPPING: Physical memory is mapped.

enumerator POSAL_MEMORYMAP_PHYSICAL_OFFSET_MAPPING

enumerator POSAL_MEMORYMAP_VIRTUAL_ADDR_MAPPING: Virtual memory is mapped.

enumerator POSAL_MEMORYMAP_VIRTUAL_OFFSET_MAPPING

Functions

ar_result_t posal_memorymap_register(uint32_t *client_token_ptr, POSAL_HEAP_ID heap_id)

Registers a client with posal_memorymap.

: Nonzero — Failure
Dependencies: None.

Parameters:

client_token_ptr – [out] Pointer to an instance of posal_memorymap_client_t
that is created and returned as a handle/token to the client.

This handle uniquely identifies the client, and the client must use this handle for future communication with posal_memorymap.
heap_id – [in] Heap id used for malloc.

Returns:

0 — Success

ar_result_t posal_memorymap_unregister(uint32_t client_token)

Deletes all regions tagged to this client and unregisters this client from posal_memorymap.

: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered.

Parameters:: client_token – [in] Client token.
Returns:: 0 — Success

ar_result_t posal_memorymap_shm_mem_map(uint32_t client_token, posal_memorymap_shm_region_t *shm_mem_reg_ptr, uint16_t num_shm_reg, bool_t is_cached, bool_t is_offset_map, POSAL_MEMORYPOOLTYPE pool_id, uint32_t *shm_mem_map_handle_ptr, POSAL_HEAP_ID heap_id)

Maps the shared memory and adds the memory region to the client linked list. This function enables physical address mapping only.

Associated data types: posal_memorymap_shm_region_t POSAL_MEMORYPOOLTYPE
: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered.

Parameters:

client_token – [in] Client token.
shm_mem_reg_ptr – [in] Pointer to an array of shared memory regions to map.
num_shm_reg – [in] Number of shared memory regions in the array.
is_cached – [in] Indicates if mem is cached or uncached
is_offset_map – [in] Indicates if the mapping is offset based as opposed to pointer based.
pool_id – [in] Memory pool ID to which this region is mapped.
shm_mem_map_handle_ptr – [out] Pointer to the memory map handle of the shared memory region created. This handle can be used later to unmap the shared memory.
heap_id – [in] Heap id used for malloc.

Returns:

0 — Success

ar_result_t posal_memorymap_virtaddr_mem_map(uint32_t client_token, posal_memorymap_shm_region_t *shm_mem_reg_ptr, uint16_t num_shm_reg, bool_t is_cached, bool_t is_offset_map, POSAL_MEMORYPOOLTYPE pool_id, uint32_t *shm_mem_map_handle_ptr, POSAL_HEAP_ID heap_id)

Maps the shared virtual address and adds the memory region to the client linked list. This function must be used to map a virtual address.

Associated data types: posal_memorymap_shm_region_t POSAL_MEMORYPOOLTYPE
: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered.

Parameters:

client_token – [in] Client token.
shm_mem_reg_ptr – [in] Pointer to an array of shared memory regions to map.
num_shm_reg – [in] Number of shared memory regions in the array.
is_cached – [in] Indicates if mem is cached or uncached
is_offset_map – [in] Indicates if the mapping is offset based as opposed to pointer based.
pool_id – [in] Memory pool ID to which this region is mapped.
shm_mem_map_handle_ptr – [out] Pointer to the memory map handle of the shared memory region created. This handle can be used later to unmap the shared memory.
heap_id – [in] heap id required for malloc.

Returns:

0 — Success

ar_result_t posal_memorymap_set_shmem_id(uint32_t client_token, uint32_t shm_mem_map_handle, uint32_t shmem_id)

Maps the shmem_id to the mem_map_handle for a given client.

: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered and valid shared memory regions should be created with shared_mem_map_handle.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created.
shmem_id – [in] shared memory id set by the client.

Returns:

0 — Success

ar_result_t posal_memorymap_get_shmem_id(uint32_t client_token, uint32_t shm_mem_map_handle, uint32_t *shmem_id_ptr)

Gets the associated shmem_id from the mem_map_handle for a given client.

: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered and valid shared memory regions should be created with shared_mem_map_handle.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created.
shmem_id_ptr – [out] shared memory id set by the client.

Returns:

0 — Success

ar_result_t posal_memorymap_get_mem_map_handle(uint32_t client_token, uint32_t shmem_id, uint32_t *shm_mem_map_handle_ptr)

Gets the associated mem_map_handle for a given client based on the shmem_id.

: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered and valid shared memory regions should be created with shmem_id.

Parameters:

client_token – [in] Client token.
shmem_id – [in] Shared memory id set by the client.
shm_mem_map_handle_ptr – [out] Pointer to the memory map handle of the shared memory region created.

Returns:

0 — Success

ar_result_t posal_memorymap_get_mapping_mode(uint32_t client_token, uint32_t shm_mem_map_handle, posal_memorymap_mapping_mode_t *mapping_mode_ptr)

Gets the memory mapping mode for a specified memory map handle.

Associated data types: posal_memorymap_mapping_mode_t
: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling one of the following:
- posal_memorymap_shm_mem_map()
- posal_memorymap_virtaddr_mem_map()
mapping_mode_ptr – [out] Pointer to the memory mapping mode.

Returns:

0 — Success

ar_result_t posal_memorymap_shm_mem_unmap(uint32_t client_token, uint32_t shm_mem_map_handle)

Unmaps the memory region and deletes the entry from the client-given memory map handle.

: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered, and the corresponding memory must be mapped.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling posal_memorymap_shm_mem_map().

Returns:

0 — Success

ar_result_t posal_memorymap_get_virtual_addr_from_shm_handle(uint32_t client_token, uint32_t shm_mem_map_handle, uint32_t shm_addr_lsw, uint32_t shm_addr_msw, uint32_t reg_size, bool_t is_ref_counted, uint32_t *virt_addr_ptr)

Gets the corresponding virtual address for a specified shared memory address and memory map handle. If “is_ref_count” is set to TRUE then increments the reference count each time a virtual address is requested from the memory map handle. Client must decrement reference count using posal_memorymap_shm_decr_refcount() to release reference to the virtual addr.

: Nonzero — Failure
Dependencies: If is_ref_counted= TRUE, must decrement the reference count to free the virtual address. posal_memorymap_shm_decr_refcount(). If is_ref_counted= FALSE, should not decrememnt ref count later.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling posal_memorymap_shm_mem_map().
shm_addr_lsw – [in] LSW of the mapped region for any shared memory address.
shm_addr_msw – [in] MSW of the mapped region for any shared memory address.
is_ref_counted – [in] Flag to indicate if ref count needs to be incremented. If set to TRUE, need to decrement the ref count at the time of release.
virt_addr_ptr – [out] Pointer to the equivalent virtual address returned.

Returns:

0 — Success

ar_result_t posal_memorymap_get_virtual_addr_from_shm_handle_v2(uint32_t client_token, uint32_t shm_mem_map_handle, uint32_t shm_addr_lsw, uint32_t shm_addr_msw, uint32_t reg_size, bool_t is_ref_counted, void *virt_addr_ptr)

Gets the corresponding virtual address for a specified shared memory address and memory map handle. If “is_ref_count” is set to TRUE then increments the reference count each time a virtual address is requested from the memory map handle. Client must decrement reference count using posal_memorymap_shm_decr_refcount() to release reference to the virtual addr.

: Nonzero — Failure
Dependencies: If is_ref_counted= TRUE, must decrement the reference count to free the virtual address. posal_memorymap_shm_decr_refcount(). If is_ref_counted= FALSE, should not decrememnt ref count later.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling posal_memorymap_shm_mem_map().
shm_addr_lsw – [in] LSW of the mapped region for any shared memory address.
shm_addr_msw – [in] MSW of the mapped region for any shared memory address.
is_ref_counted – [in] Flag to indicate if ref count needs to be incremented. If set to TRUE, need to decrement the ref count at the time of release.
virt_addr_ptr – [out] Pointer to the equivalent virtual address returned.

Returns:

0 — Success

ar_result_t posal_memorymap_get_shmm_handle_and_offset_from_va_offset_map(uint32_t client_token, uint32_t va, uint32_t *mem_handle_ptr, uint32_t *offset_ptr)

Gets the corresponding mem_map_handle for a specified VA address. It also returns the offset from the base virt_addr of the node.

: Nonzero — Failure

Parameters:

client_token – [in] Client token.
va – [in] Queried VA.
mem_handle_ptr – [out] Pointer to the needed mem_handle of which the VA is a part of.
offset_ptr – [out] Pointer to the needed offset of the VA from the base va.

Returns:

0 — Success

ar_result_t posal_memorymap_get_mem_region_attrib_from_shmm_handle(uint32_t client_token, uint32_t shm_mem_map_handle, uint32_t shm_addr_lsw, uint32_t shm_addr_msw, bool_t is_ref_counted, posal_memorymap_mem_region_attrib_t *mem_reg_attrib_ptr)

Gets the region attributes for a specified shared memory address and memory map handle.

Associated data types: posal_memorymap_mem_region_attrib_t
: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered, and the corresponding memory must be mapped.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling posal_memorymap_shm_mem_map().
shm_addr_lsw – [in] LSW of the mapped region for any shared memory address.
shm_addr_msw – [in] MSW of the mapped region for any shared memory address.
mem_reg_attrib_ptr – [out] Pointer to the memory region attribute whose fields are filled by this function.

Returns:

0 — Success

ar_result_t posal_memorymap_util_region_delete(posal_memorymap_node_t *mem_map_node_ptr, bool_t enable_debug_logs): This function deletes a memory region using QURT APIs. This function is not thread safe. The caller must provide thread safety.

ar_result_t posal_memorymap_unmap_all(uint32_t client_token)

Unmaps all memory regions and deletes all nodes of the requested client.

: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered.

Parameters:: client_token – [in] Client token.
Returns:: 0 — Success

void posal_memorymap_global_unmap_all()

Unmaps all memory regions for all clients, and deletes all of their nodes.

Dependencies: Before calling this function, the client’s objects must be registered.

uint64_t posal_memorymap_get_physical_addr(uint32_t virt_addr)

Given a virtual address, this function does the following:

Retrieves the corresponding mapping entry from the page table
Adjusts the offset based on the page size
Returns the full 64-bit physical address back to the user

Dependencies: Before calling this function, the client object must be registered, and the corresponding memory must be mapped.

Parameters:: virt_addr – [in] Starting virtual address.
Returns:: Physical address if the address is mapped; otherwise, 0.

uint64_t posal_memorymap_get_physical_addr_v2(posal_mem_addr_t virt_addr)

Given a virtual address, this function does the following:

Retrieves the corresponding mapping entry from the page table
Adjusts the offset based on the page size
Returns the full 64-bit physical address back to the user

Dependencies: Before calling this function, the client object must be registered, and the corresponding memory must be mapped.

Parameters:: virt_addr – [in] Starting virtual address.
Returns:: Physical address if the address is mapped; otherwise, 0.

ar_result_t posal_memorymap_shm_incr_refcount(uint32_t client_token, uint32_t shm_mem_map_handle)

Increments the reference count of the memory map handle of a client.

Detailed description: Incrementing this reference count suggests that the memory region abstracted by this memory map handle is in use.
: A nonzero reference count prevents the aDSP client from unmapping specific memory map regions.
: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered, and the corresponding memory must be mapped.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling posal_memorymap_shm_mem_map().

Returns:

0 — Success

ar_result_t posal_memorymap_shm_decr_refcount(uint32_t client_token, uint32_t shm_mem_map_handle)

Decrements the reference count of the memory map handle of a client.

Detailed description: Decrementing this reference count suggests that this client is relinquishing the memory region abstracted by this memory map handle (the client no longer requires this region).
: The reference count must reach zero for the memory region to be unmapped.
: Nonzero — Failure
Dependencies: Before calling this function, the client object must be registered, and the corresponding memory must be mapped.

Parameters:

client_token – [in] Client token.
shm_mem_map_handle – [in] Memory map handle of the shared memory region created when calling posal_memorymap_shm_mem_map().

Returns:

0 — Success

Variables

const char posal_memorymap_pool_name[][32]

struct posal_memorymap_node_t

#include <posal_memorymap.h>

Linked list of memory regions.

Public Members

uint32_t shmem_id: A unique identifier to map with this shared memory regions

uint32_t MemPool: Memory pool from which the memory region is created.

uint16_t unNumContPhysReg: Number of physical memory regions in this node.

int16_t ref_count

Reference count that the client can increment to lock this memory map handle.

Unmapping can only be performed if ref_count reaches zero.

The client must decrement ref_count when it does not use this memory map handle.

uint32_t mapping_mode: Specifies whether the mapping is physical or virtual, or if it is a physical offset.

uint32_t reserved: reserved field to ensure this structure size is 64 bytes aligned.

posal_memorymap_node_t *pNext

Pointer to the next node in the linked list.

{If unNumContPhysReg is greater than 1} In addition to the number of posal_memorymap_region_record_t structures following this structure, one more ContPhysReg follows to represent the master region for all ContPhysRegs (called the virtual memory region).

When freeing the regions, all of the following space is also freed.

struct posal_memorymap_shm_region_t

#include <posal_memorymap.h>

Contiguous shared memory region, with the start address and size.

Public Members

uint32_t shm_addr_lsw: Lower 32 bits of the shared memory address of the memory region to map.

uint32_t shm_addr_msw

Upper 32 bits of the shared memory address of the memory region to map.

The 64-bit number formed by shm_addr_lsw and shm_addr_msw word must be contiguous memory, and it must be 4 KB aligned.

For a 32-bit shared memory address, this field must be set to 0.
For a 36-bit shared memory address, bits 31 to 4 must be set to 0.
For a 64-bit shared memory address, any 32 bit value.

uint32_t mem_size

Size of the shared memory region.

Number of bytes in the shared memory region.

Multiples of 4 KB

Underlying operating system must always map the regions as virtual contiguous memory, but the memory size must be in multiples of 4 KB to avoid gaps in the virtually contiguous mapped memory.

struct posal_memorymap_mem_region_attrib_t

#include <posal_memorymap.h>

Memory mapped region attributes.

Public Members

uint32_t base_phy_addr_lsw: Lower 32 bits of the 64-bit memory region start (base) physical address.

uint32_t base_phy_addr_msw

Upper 32 bits of the 64-bitmemory region start (base) physical address.

The 64-bit number formed by mem_reg_base_phy_addr_lsw and mem_reg_base_phy_addr_msw word must be contiguous memory, and it must be 4 KB aligned.

For a 32-bit shared memory address, this field must be set to 0.
For a 36-bit shared memory address, bits 31 to 4 must be set to 0.
For a 64-bit shared memory address, any 32-bit value.

uint32_t mem_reg_size

Size of the shared memory region.

Number of bytes in the shared memory region.

Multiples of 4 KB

Underlying operating system must always map the regions as virtual contiguous memory, but the memory size must be in multiples of 4 KB to avoid gaps in the virtually contiguous mapped memory.

uint32_t base_virt_addr: Memory region start (base) virtual address.

uint32_t req_virt_adrr: Virtual address that corresponds to the requested physical address.

uint32_t rem_reg_size

Remaining memory region size from the requested physical address, including the requested physical address:

([mem_reg_base_phy_addr_msw,mem_reg_base_phy_addr_lsw] + mem_reg_size - [requested physical address])

posal_mutex

This file contains mutex utilites. Recursive mutexes are always used for thread-safe programming.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef void *posal_mutex_t: posal mutex data type

Functions

ar_result_t posal_mutex_create(posal_mutex_t *pposal_mutex, POSAL_HEAP_ID heap_id)

Creates and initializes a mutex. Recursive mutexes are always used.

Associated data types: posal_mutex_t
: Nonzero — Failure
Dependencies: None.

Parameters:: posal_mutex – [in] pointer to the mutex object handle.
Returns:: 0 — Success

void posal_mutex_destroy(posal_mutex_t *posal_mutex)

Deletes a mutex. This function must be called for each corresponding posal_mutex_create() function to clean up all resources.

Associated data types: posal_mutex_t
Dependencies: Before calling this function, the object must be created.

Parameters:: posal_mutex – [in] mutex object handle.
Returns:: None.

void posal_mutex_lock(posal_mutex_t posal_mutex)

Locks a mutex. Recursive mutexes are always used.

Associated data types: posal_mutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: posal_mutex – [in] mutex object handle.
Returns:: None.

ar_result_t posal_mutex_try_lock(posal_mutex_t posal_mutex)

Attempts to lock a mutex. If the mutex is already locked and unavailable, a failure is returned.

Associated data types: posal_mutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: posal_mutex – [in] mutex object handle.
Returns:: An indication of success (0) or failure (nonzero).

void posal_mutex_unlock(posal_mutex_t posal_mutex)

Unlocks a mutex. Recursive mutexes are always used.

Associated data types: posal_mutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: posal_mutex – [in] mutex object handle.
Returns:: None.

posal_power_mgr

Lite Wrapper for PM. Mainly to serve profiling. goal is not to hide MMPM/PM details.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

PM_SERVER_CLIENT_TOKEN_PREFIX

PM_SERVER_CLIENT_TOKEN_LENGTH

PM_SERVER_CLIENT_NAME_LENGTH

PM_SERVER_CLIENT_NAME_MAX_LENGTH

Typedefs

typedef void *posal_pm_handle_t

typedef enum posal_pm_mode_t posal_pm_mode_t: PM island types

typedef enum posal_pm_island_type_t posal_pm_island_type_t: PM island Vote

typedef enum posal_pm_island_vote_type_t posal_pm_island_vote_type_t

typedef enum posal_pm_cpu_lpr_id_t posal_pm_cpu_lpr_id_t: PM CPU LPR Vote type

typedef enum posal_pm_cpu_lpr_vote_type_t posal_pm_cpu_lpr_vote_type_t: Register information

typedef struct posal_pm_register_t posal_pm_register_t

typedef struct posal_pm_mpps_t posal_pm_mpps_t

typedef struct posal_pm_bw_t posal_pm_bw_t

typedef struct posal_pm_sleep_latency_t posal_pm_sleep_latency_t

typedef struct posal_pm_island_vote_t posal_pm_island_vote_t

typedef struct posal_pm_cpu_lpr_vote_t posal_pm_cpu_lpr_vote_t

typedef struct posal_pm_resources_t posal_pm_resources_t

typedef struct posal_pm_request_info_t posal_pm_request_info_t

typedef struct posal_pm_release_info_t posal_pm_release_info_t

Enums

enum posal_pm_mode_t

Values:

enumerator PM_MODE_DEFAULT: Non-island, non-suppressible

enumerator PM_MODE_ISLAND: Island, suppressible

enumerator PM_MODE_ISLAND_DUTY_CYCLE: Not an Island container but only BW votes are suppressible (Mainly used in BT A2DP use case)

enum posal_pm_island_type_t

Values:

enumerator PM_ISLAND_TYPE_DEFAULT

enumerator PM_ISLAND_TYPE_LOW_POWER: < default island type island type to enter STD island

enumerator PM_ISLAND_TYPE_LOW_POWER_2: island type to enter LLC island

enum posal_pm_island_vote_type_t

Values:

enumerator PM_ISLAND_VOTE_ENTRY: Island vote to be casted for island entry state

enumerator PM_ISLAND_VOTE_EXIT: Island vote to be casted for island exit sate

enumerator PM_ISLAND_VOTE_DONT_CARE: Island vote to be casted for island dont care state

enum posal_pm_cpu_lpr_id_t

Values:

enumerator PM_LPR_CPU_SS_SLEEP

enumerator PM_LPR_CPU_MAX

enum posal_pm_cpu_lpr_vote_type_t

Values:

enumerator PM_VOTE_FOR_CPU_LPR_SUB_SYSTEM_SLEEP

enumerator PM_VOTE_AGAINST_CPU_LPR_SUB_SYSTEM_SLEEP

enumerator PM_VOTE_NUM_CPU_LPR

Functions

ar_result_t posal_power_mgr_request(posal_pm_request_info_t *request_info_ptr)

Sends request to ADSPPM

Dependencies: None.

Returns:: returns error code.

ar_result_t posal_power_mgr_release(posal_pm_release_info_t *release_info_ptr)

Sends release to ADSPPM

Dependencies: None.

Returns:: returns error code.

ar_result_t posal_power_mgr_register(posal_pm_register_t register_info, posal_pm_handle_t *pm_handle_pptr, posal_signal_t wait_signal, uint32_t log_id)

Registers for kpps and bw

Dependencies: None.

Returns:: returns error code.

ar_result_t posal_power_mgr_deregister(posal_pm_handle_t *pm_handle_pptr, uint32_t log_id)

Deregisters with ADSPPM

Dependencies: None.

Returns:: returns error code.

bool_t posal_power_mgr_is_registered(posal_pm_handle_t pm_handle_ptr): returns true if the client is registered.

ar_result_t posal_power_mgr_request_max_out(posal_pm_handle_t pm_handle_ptr, posal_signal_t wait_signal, uint32_t log_id): bumps up the bus and Q6 clocks.

ar_result_t posal_power_mgr_release_max_out(posal_pm_handle_t pm_handle_ptr, uint32_t log_id, uint32_t delay_ms): releases the bus and Q6 clocks.

void posal_power_mgr_init(): initalises structures and mutex (if any)

void posal_power_mgr_deinit(): de-initalises structures and mutex (if any)

ar_result_t posal_power_mgr_send_command(uint32_t msg_opcode, void *payload_ptr, uint32_t payload_size): To Send message commands to PM SERVER

struct posal_pm_register_t

#include <posal_power_mgr.h>

Public Members

posal_pm_mode_t mode: PM mode

posal_pm_island_type_t island_type: Island type

struct posal_pm_mpps_t

#include <posal_power_mgr.h>

Public Members

bool_t is_valid

uint32_t value

uint64_t floor_clk

struct posal_pm_bw_t

#include <posal_power_mgr.h>

Public Members

bool_t is_valid

uint32_t value

struct posal_pm_sleep_latency_t

#include <posal_power_mgr.h>

Public Members

bool_t is_valid

uint32_t value

struct posal_pm_island_vote_t

#include <posal_power_mgr.h>

Public Members

bool_t is_valid

posal_pm_island_vote_type_t island_vote_type

posal_pm_island_type_t island_type

struct posal_pm_cpu_lpr_vote_t

#include <posal_power_mgr.h>

Public Members

bool_t is_valid

posal_pm_cpu_lpr_id_t lpr_id

posal_pm_cpu_lpr_vote_type_t cpu_lpr_vote_type

struct posal_pm_resources_t

#include <posal_power_mgr.h>

Public Members

posal_pm_mpps_t mpps

posal_pm_bw_t bw

posal_pm_sleep_latency_t sleep_latency

posal_pm_island_vote_t island_vote

posal_pm_cpu_lpr_vote_t cpu_lpr_vote[PM_LPR_CPU_MAX]

struct posal_pm_request_info_t

#include <posal_power_mgr.h>

Public Members

posal_pm_handle_t pm_handle_ptr

uint32_t client_log_id

posal_signal_t wait_signal_ptr

posal_pm_resources_t resources

struct posal_pm_release_info_t

#include <posal_power_mgr.h>

Public Members

posal_pm_handle_t pm_handle_ptr

uint32_t client_log_id

posal_signal_t wait_signal_ptr

uint32_t delay_ms

posal_pm_resources_t resources

posal_root_msg

Defines

POSAL_ROOT_VA_NUM_ARGS_IMPL(a, b, c, d, e, f, g, h, i, j, _N, ...)

POSAL_ROOT_VA_NUM_ARGS(...)

POSAL_ROOT_TOKENPASTE(x, y)

POSAL_ROOT_MSG_x(_N)

POSAL_ROOT_MSG(xx_ss_mask, xx_fmt, ...)

POSAL_ROOT_MSG_ISLAND(xx_ss_mask, xx_fmt, ...)

posal_signal

This file contains signal utilities.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef void *posal_signal_t

typedef void *posal_channel_t

Functions

ar_result_t posal_signal_create(posal_signal_t *pp_sigobj, POSAL_HEAP_ID heap_id)

Creates a signal.

Associated data types: posal_signal_t
: Nonzero — Failure
Dependencies: None.

Parameters:: ppSignal – [out] Double pointer to the signal.
Returns:: 0 — Success

void posal_signal_destroy(posal_signal_t *pp_sigobj)

Destroys a signal

Associated data types: posal_signal_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: pSignal – [in] Pointer to the signal.
Returns:: None.

posal_channel_t posal_signal_get_channel(posal_signal_t p_sigobj)

Queries a signal for its channel.

Associated data types: posal_signal_t
Dependencies: Before calling this function, the signal group must be created and initialized.

Parameters:: pSignal – [in] Pointer to the signal.
Returns:: A handle to the channel containing the signal.

uint32_t posal_signal_get_channel_bit(posal_signal_t p_sigobj)

Queries a signal for its channel bitfield.

Associated data types: posal_signal_t
Detailed description: Use this function to find the values to be ORed together to form an enable bitfield for a combination of signals in a channel.
Dependencies: Before calling this function, the signal group must be created and initialized.

Parameters:: pSignal – [in] Pointer to the signal to query.
Returns:: A 32-bit value with a single bit=1.

void posal_signal_send(posal_signal_t p_sigobj)

Sends a signal.

Associated data types: posal_signal_t
Dependencies: Before calling this function, the signal group must be created and initialized.

Parameters:: pSignal – [in] Pointer to the signal.
Returns:: None.

void posal_signal_clear(posal_signal_t p_sigobj)

Clears a signal that is active in a channel.

Associated data types: posal_signal_t
Dependencies: Before calling this function, the signal group must be created and initialized.

Parameters:: pSignal – [in] Pointer to the signal.
Returns:: None.

bool_t posal_signal_is_set(posal_signal_t p_sigobj)

returns true if the signal is set

Associated data types: posal_signal_t
Dependencies: Before calling this function, the signal group must be created and initialized.

Parameters:: pSignal – [in] Pointer to the signal.
Returns:: None.

posal_thread

This file contains utilities for threads. Threads must be joined to avoid memory leaks. This file provides functions to create and destroy threads, and to change thread priorities.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef void *posal_thread_t: Handle to a thread.

typedef int32_t posal_thread_prio_t: thread priority number

Functions

ar_result_t posal_thread_launch(posal_thread_t *pTid, char *pzThreadName, size_t nStackSize, posal_thread_prio_t nPriority, ar_result_t (*pfStartRoutine)(void*), void *arg, POSAL_HEAP_ID heap_id)

Creates and launches a thread.

Associated data types: posal_thread_t POSAL_HEAP_ID
Detailed description: The thread stack can be passed in as the pStack argument, or pStack=NULL indicates that posal allocates the stack internally. If the caller provides the stack, the caller is responsible for freeing the stack memory after joining the thread.
: Pre-allocated stacks must be freed after the dying thread is joined. The caller must specify the heap in which the thread stack is to be allocated.
Dependencies: None.

Parameters:

pTid – [out] Pointer to the thread ID.
pzThreadName – [in] Pointer to the thread name.
pStack – [in]
Pointer to the location of the pre-allocated stack (NULL causes a new allocation).

pStack must point to the lowest address in the stack.
nStackSize – [in] Size of the thread stack.
nPriority – [in] Thread priority, where 0 is the lowest priority and 255 is the highest priority.
pfStartRoutine – [in] Pointer to the entry function of the thread.
arg – [in] Pointer to the arguments passed to the entry function. An argument can be to any pointer type.
heap_id – [in] ID of the heap to which the thread stack is allocated.

Returns:

An indication of success (0) or failure (nonzero).

ar_result_t posal_thread_launch2(posal_thread_t *pTid, char *pzThreadName, size_t nStackSize, size_t nrootStackSize, posal_thread_prio_t nPriority, ar_result_t (*pfStartRoutine)(void*), void *arg, POSAL_HEAP_ID heap_id)

Creates and launches a island thread with nrootStackSize stack size used for guest mode.

Associated data types: posal_thread_t POSAL_HEAP_ID
Detailed description: The thread stack can be passed in as the pStack argument, or pStack=NULL indicates that posal allocates the stack internally. If the caller provides the stack, the caller is responsible for freeing the stack memory after joining the thread.
: Pre-allocated stacks must be freed after the dying thread is joined. The caller must specify the heap in which the thread stack is to be allocated.
Dependencies: None.

Parameters:

pTid – [out] Pointer to the thread ID.
pzThreadName – [in] Pointer to the thread name.
pStack – [in]
Pointer to the location of the pre-allocated stack (NULL causes a new allocation).

pStack must point to the lowest address in the stack.
nStackSize – [in] Size of the thread stack.
nrootStackSize – [in] Size of the island thread stack used for guest mode.
nPriority – [in] Thread priority, where 0 is the lowest priority and 255 is the highest priority.
pfStartRoutine – [in] Pointer to the entry function of the thread.
arg – [in] Pointer to the arguments passed to the entry function. An argument can be to any pointer type.
heap_id – [in] ID of the heap to which the thread stack is allocated.

Returns:

An indication of success (0) or failure (nonzero).

ar_result_t posal_thread_launch3(posal_thread_t *posal_obj_ptr, char *threadname, size_t stack_size, size_t root_stack_size, posal_thread_prio_t nPriority, ar_result_t (*pfStartRoutine)(void*), void *arg, POSAL_HEAP_ID heap_id, uint32_t sched_policy, uint32_t affinity)

void posal_thread_join(posal_thread_t nTid, ar_result_t *nStatus)

Waits for a specified thread to exit, and collects the exit status.

Associated data types: posal_thread_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

nTid – [in] Thread ID to wait on.
nStatus – [out] Pointer to the value returned by pfStartRoutine called in posal_thread_launch().

Returns:

None.

int32_t posal_thread_get_tid(posal_thread_t thread_obj)

Queries the thread id of the given thread object.

Dependencies

Returns:: The thread id which is integer value.

int64_t posal_thread_get_tid_v2(posal_thread_t thread_obj)

int32_t posal_thread_get_curr_tid(void)

Queries the thread id of the caller.

Dependencies

Returns:: The thread id which is integer value.

int64_t posal_thread_get_curr_tid_v2(void)

void posal_thread_get_name(char *name, unsigned char max_len)

Get the thread name.

Dependencies: None.

Returns:: None.

posal_thread_prio_t posal_thread_prio_get(void)

Queries the thread priority of the caller.

Dependencies: Before calling this function, the object must be created and initialized.

Returns:: The thread priority of the caller, where 0 is the lowest priority and 255 is the highest priority.

posal_thread_prio_t posal_thread_prio_get2(posal_thread_t tObj)

Queries the thread priority of the specified thread.

Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: tObj – [in] Thread Object
Returns:: The thread priority of the specified thread, where 0 is the lowest priority and 255 is the highest priority.

void posal_thread_set_prio(posal_thread_prio_t nPrio)

Changes the thread priority of the caller.

Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: nPrio – [in] New priority, where 0 is the lowest priority and 255 is the highest priority.
Returns:: None.

void posal_thread_set_prio2(posal_thread_t tObj, posal_thread_prio_t nPrio)

Changes the thread priority of the specified thread.

Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

tObj – [in] Thread Object
nPrio – [in] New priority, where 0 is the lowest priority and 255 is the highest priority.

Returns:

None.

ar_result_t posal_thread_allocate_stack(uint32_t nStackSize, char **pStackpointer, POSAL_HEAP_ID heap_id)

Parameters:

pStackpointer – [in] Pointer to the stack pointer
nStackSize – [in] Size of the thread stack.
heap_id – [in] Heap ID

Returns:

Indication of success (0) or failure (nonzero).

posal_thread_profiling

This file contains PUBLIC utilities for thread profiling.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Functions

ar_result_t posal_thread_profiling_get_stack_info(uint32_t tid, uint32_t *current_stack_usage_ptr, uint32_t *stack_size_ptr)

posal_bufpool

Header file for buffer pool functionality for small allocations.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

POSAL_BUFPOOL_INVALID_HANDLE

Typedefs

typedef enum posal_bufpool_align_t posal_bufpool_align_t

Enums

enum posal_bufpool_align_t

Values:

enumerator FOUR_BYTE_ALIGN

enumerator EIGHT_BYTE_ALIGN

Functions

uint32_t posal_bufpool_pool_create(uint16_t node_size, POSAL_HEAP_ID heap_id, uint32_t num_arrays, posal_bufpool_align_t alignment, uint16_t nodes_per_arr)

void *posal_bufpool_get_node(uint32_t pool_handle)

void posal_bufpool_return_node(void *node_ptr)

void posal_bufpool_pool_destroy(uint32_t pool_handle)

void posal_bufpool_pool_reset_to_base(uint32_t pool_handle)

void posal_bufpool_pool_free_unused_lists(uint32_t pool_handle)

bool_t posal_bufpool_is_address_in_bufpool(void *ptr, uint32_t pool_handle)

uint32_t posal_bufpool_profile_all_mem_usage()

ar_result_t posal_bufpool_profile_mem_usage(uint32_t pool_handle, uint32_t *bytes_used_ptr, uint32_t *bytes_allocated_ptr)

posal_condvar

This file contains the ConditionVariables utilities.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef void *posal_condvar_t

Functions

ar_result_t posal_condvar_create(posal_condvar_t *p_cndvar, POSAL_HEAP_ID heap_id)

Creates a condition variable object.

Associated data types: posal_condvar_t
: Nonzero — Failure
Dependencies: None.

Parameters:: condition_var_ptr – [in] Pointer to the condition variable.
Returns:: 0 — Success

void posal_condvar_signal(posal_condvar_t p_cndvar)

Signals a condition variable object. This utility is used to awaken a single waiting thread.

Associated data types: posal_condvar_t
Dependencies: Before calling this function, the object must be created.

Parameters:: condition_var_ptr – [in] Pointer to the condition variable.
Returns:: None.

void posal_condvar_broadcast(posal_condvar_t p_cndvar)

Broadcasts a condition variable object. This utility is used to awaken multiple threads waiting for a condition variable.

Associated data types: posal_condvar_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: condition_var_ptr – [in] Pointer to the condition variable.
Returns:: None.

void posal_condvar_wait(posal_condvar_t p_cndvar, posal_nmutex_t nmutex)

Waits for a condition variable object. This utility suspends the current thread until the specified condition is true.

Associated data types: posal_condvar_t posal_nmutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

condition_var_ptr – [in] Pointer to the condition variable.
nmutex – [in] Normal mutex associated with the condition variable.

Returns:

None.

void posal_condvar_destroy(posal_condvar_t *pp_cndvar)

Destroys a condition variable object.

Associated data types: posal_condvar_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: condition_var_ptr – [in] Pointer to the condition variable.
Returns:: None.

posal_err_fatal

Contains API to call force crash.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Functions

void posal_err_fatal(const char *err_str)

posal

This is the top-level include file for the posal utilities. This file includes all header files required for using posal functions. The user of posal should only include this file to call the posal functions.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Functions

void posal_init(void)

void posal_deinit(void)

static inline uint32_t posal_cmn_divide(uint32_t num, uint32_t den)

posal_inline_mutex

Typedefs

typedef qurt_mutex_t posal_inline_mutex_t

Functions

static inline ar_result_t posal_inline_mutex_init(posal_inline_mutex_t *pposal_mutex)

Initializes a mutex. Recursive mutexes are always used.

Associated data types: posal_mutex_t
: Nonzero — Failure
Dependencies: None.

Parameters:: posal_mutex – [in] pointer to the mutex object handle.
Returns:: 0 — Success

static inline void posal_inline_mutex_deinit(posal_inline_mutex_t *pposal_mutex)

Deinits a mutex. This function must be called for each corresponding posal_mutex_init() function to clean up all resources.

Associated data types: posal_mutex_t
Dependencies: The object must have been created and initialized before calling this function.

Parameters:: pposal_mutex – [in] Pointer to the mutex to destroy.
Returns:: None.

posal_interrupt

This file contains utilities for registering with interrupts.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Typedefs

typedef void *posal_interrupt_ist_t

Functions

ar_result_t posal_interrupt_register(posal_interrupt_ist_t *ist_ptr, uint16_t intr_id, void (*callback_ptr)(void*), void *arg_ptr, char_t *thread_name, uint32_t stack_size, POSAL_HEAP_ID heap_id)

Registers an interrupt. The client must allocate the memory for the posal_interrupt_ist_t structure.

Associated data types: posal_interrupt_ist_t
: Nonzero — Failure
Dependencies: None.

Parameters:

ist_ptr – [in] Pointer to the IST.
intr_id – [in] Interrupt number to register.
callback_ptr – [in] Pointer to the callback function when an interrupt occurs.
arg_ptr – [in] Pointer to the arguments sent by the client.
thread_name – [in] Pointer to the IST thread name.
stack_size – [in] Size of the IST stack.

Returns:

0 — Success

ar_result_t posal_interrupt_deregister(posal_interrupt_ist_t *ist_ptr)

Deregisters an interrupt.

Associated data types: posal_interrupt_ist_t
: Nonzero — Failure
Dependencies: Before calling this function, the interrupt object must be registered.

Parameters:: ist_ptr – [in] Pointer to the IST.
Returns:

posal_memory

  This file contains utilities for memory allocation and release. This file provides memory allocation functions

and macros for both C and C++.

Copyright: Copyright (c) Qualcomm Innovation Center, Inc. All Rights Reserved. SPDX-License-Identifier: BSD-3-Clause

Defines

POSAL_HEAP_ID_ISLAND_BIT_MASK

HEAP_ID_MASK

HEAP_ID_SHIFT

HEAP_ID_MASK_WITH_ISLAND_INFO

GET_ACTUAL_HEAP_ID(heapId)

GET_HEAP_ID_WITH_ISLAND_INFO(heapId)

GET_TRACKING_ID_FROM_HEAP_ID(heapId)

MODIFY_HEAP_ID_FOR_MEM_TRACKING(tracking_id, actual_heap_id)

MODIFY_STATIC_MODULE_HEAP_ID_FOR_MEM_TRACKING(module_id, actual_heap_id)

MODIFY_HEAP_ID_FOR_FWK_ALLOC_FOR_MEM_TRACKING(actual_heap_id)

POSAL_DEFAULT_HEAP_INDEX: Index of the default heap.

POSAL_HEAP_MGR_HEAP_INDEX_START

POSAL_HEAP_MGR_HEAP_INDEX_END

IS_MALLOC

IS_FREE

HEAP_ID_FROM_HEAP_TABLE_INDEX(index)

HEAP_TABLE_INDEX_FROM_HEAP_ID(actual_heap_id)

POSAL_IS_ISLAND_HEAP_ID(heap_id)

Enums

enum posal_mem_t

Values:

enumerator POSAL_MEM_TYPE_DEFAULT

enumerator POSAL_MEM_TYPE_LOW_POWER

enumerator POSAL_MEM_TYPE_LOW_POWER_2

enumerator POSAL_MEM_TYPE_NUM_SUPPORTED

enum POSAL_HEAP_ID

ID of the available heap in the system.

Values:

enumerator POSAL_HEAP_DEFAULT: Default heap value.

enumerator POSAL_HEAP_OUT_OF_RANGE: Heap value is out of range.

enumerator POSAL_HEAP_INVALID

Functions

void *posal_memory_malloc(uint32_t unBytes, POSAL_HEAP_ID heapId)

Allocates memory with an option to specify a heap identifier.

Associated data types: POSAL_HEAP_ID
Dependencies: None

Parameters:

unBytes – [in] Number of bytes to allocate.
heapId – [in] ID of the heap from which to allocate memory.

Returns:

Pointer to the allocated block, or NULL if the request failed.

void posal_memory_free(void *ptr)

Frees memory that was allocated only with posal_memory_malloc().

Dependencies: None.

Parameters:: ptr – [in] Pointer to the memory to free.
Returns:: None.

void *posal_memory_aligned_malloc(uint32_t unBytes, uint32_t unAlignBits, POSAL_HEAP_ID heapId)

Allocates memory with options to align to a power of 2 and to specify a heap identifier.

Associated data types: POSAL_HEAP_ID
Dependencies: None.

Parameters:

unBytes – [in] Number of bytes to allocate.
unAlignBits – [in] Number of alignment bytes. This value must be a power of 2.
heapId – [in] ID of the heap from which to allocate memory.

Returns:

Pointer to the allocated block, or NULL if the request failed.

void posal_memory_aligned_free(void *ptr)

Frees memory that was allocated only with posal_memory_aligned_malloc().

Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: ptr – [in] - Pointer to the aligned memory to free.
Returns:: None.

bool_t posal_is_memory_in_tcm(void *ptr)

Determines if memory allocated was from Island heap id (TCM).

Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: ptr – [in] - Pointer to the memory to check.
Returns:: Boolean determining if memory was allocated from TCM

bool_t posal_check_addr_from_tcm_island_heap_mgr(void *virt_addr_ptr)

This function returns TRUE or FALSE whether the input VA falls in TCM memory or not.

Returns:: TRUE if address is within TCM heap manager addresses. FALSE if address is not in TCM heap manager addresses.

char *posal_tcm_island_heap_mgr_get_name(POSAL_HEAP_ID origheapId)

This function returns name of TCM island based on heap id

Returns:: char array representing name of TCM heap id

Variables

POSAL_HEAP_ID spf_mem_island_heap_id

posal_mem_prof

Typedefs

typedef struct posal_mem_prof_marker_t posal_mem_prof_marker_t: Structure to mark memory for tracking profiling (appended at the end of the momory) Hash node structure to hold heap-id to memory count mapping

typedef struct posal_mem_prof_node_t posal_mem_prof_node_t: Enum to indicate whether memory profiling started or not

typedef enum posal_mem_prof_state_t posal_mem_prof_state_t: Posal memory profiling main structure

typedef struct posal_mem_prof_t posal_mem_prof_t

Enums

enum posal_mem_prof_state_t

Values:

enumerator POSAL_MEM_PROF_STOPPED

enumerator POSAL_MEM_PROF_STARTED

Functions

ar_result_t posal_mem_prof_init(POSAL_HEAP_ID heap_id)

Initializes posal memory profiler, creates mutex.

Dependencies: None

Parameters:: heapId – [in] ID of the heap from which to allocate memory.
Returns:: Result.

ar_result_t posal_mem_prof_start()

Starts posal memory profiling, creates hashtable needed to store the heapid to mem count mapping.

Dependencies: None

Parameters:: None – [in]
Returns:: Result.

ar_result_t posal_mem_prof_stop()

Stops posal memory profiling, destroys hashtable needed to store the heapid to memory count mapping.

Dependencies: None

Parameters:: None – [in]
Returns:: Result.

void posal_mem_prof_deinit()

Deinits posal memory profiling, destroys profiling mutex.

Dependencies: None

Parameters:: None – [in]
Returns:: Result.

void posal_mem_prof_pre_process_malloc(POSAL_HEAP_ID orig_heap_id, POSAL_HEAP_ID *heap_id_ptr, uint32_t *bytes_ptr)

Extracts heap id from original heap id, updates bytes required.

Dependencies: None

Parameters:

orig_heap_id – [in] Heap id sent by the client.
heap_id_ptr – [in] Pointer to heap id which stores extracted from orig_heap_id.
heap_id_ptr – [in] Pointer to bytes to be allocated, if profiling has started, this will be + sizeof(uint64_t)

Returns:

None.

void posal_mem_prof_post_process_malloc(void *ptr, POSAL_HEAP_ID orig_heap_id, bool_t is_mem_tracked)

Updates heap id and magic number at the tail of the allocation, updates statistics if profiling is enabled.

Dependencies: None

Parameters:

ptr – [in] Pointer to the newly allocated memory.
orig_heap_id – [in] Heap id sent by the client.
is_mem_tracked – [in] Boolean to indicate of memory was tracked while allocation.

Returns:

None.

void posal_mem_prof_process_free(void *ptr)

Extracts heapid and mem size from the ptr, updates statistics.

Dependencies: None

Parameters:: ptr – [in] Pointer to the newly allocated memory.
Returns:: None.

void posal_mem_prof_query(POSAL_HEAP_ID heap_id, uint32_t *mem_usage_ptr)

Updates the mem usage query asked by a client if the statistics exists.

Dependencies: None

Parameters:

heap_id – [in] Heap id of the query.
mem_usage_ptr – [in] Pointer to which query update needs to be done.

Returns:

None.

uint32_t posal_mem_prof_get_mem_size(void *ptr, POSAL_HEAP_ID heap_id)

Use to get the memory size from a pointer.

Dependencies: None

Parameters:

ptr – [in] Pointer of the allocated memory.
heap_id – [in] Heap id of the query.

Returns:

Block size of the memory

struct posal_mem_prof_marker_t

#include <posal_mem_prof.h>

Structure to mark memory for tracking profiling (appended at the end of the momory)

Public Members

POSAL_HEAP_ID heap_id: Heap ID of the memory allocated

uint32_t magic_number: Magic number to verify mem tracking

struct posal_mem_prof_node_t

#include <posal_mem_prof.h>

Public Members

spf_hash_node_t hash_node: Hash node

POSAL_HEAP_ID heap_id: Key - heap id is used as a key to hashnode

uint32_t mem_count: Value - Count of memory allocations in Bytes

struct posal_mem_prof_t

#include <posal_mem_prof.h>

Public Members

spf_hashtable_t mem_ht: Hash table to hold heap id to memory count mapping

POSAL_HEAP_ID heap_id: Heap id to be used by posal memory profiler

posal_mutex_t prof_mutex: Mutex to be used by posal memory profiler

posal_mem_prof_state_t mem_prof_status: Flag to indicate whether profiling started or not

posal_nmutex

This file contains normal mutex utilities.

Typedefs

typedef void *posal_nmutex_t: posal normal mutex type structure.

Functions

ar_result_t posal_nmutex_create(posal_nmutex_t *pposal_nmutex, POSAL_HEAP_ID heap_id)

Initializes a normal mutex.

Associated data types: posal_nmutex_t
Dependencies: None.

Parameters:: pposal_nmutex – [in] Pointer to the normal mutex.
Returns:: None.

void posal_nmutex_lock(posal_nmutex_t posal_nmutex)

Locks a normal mutex.

Associated data types: posal_nmutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: pposal_nmutex – [in] Pointer to the normal mutex.
Returns:: None.

int posal_nmutex_try_lock(posal_nmutex_t posal_nmutex)

Attempts to lock a normal mutex. If the lock is already locked and unavailable, a failure is returned.

Associated data types: posal_nmutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: posal_nmutex – [in] Normal mutex.
Returns:: An indication of success (0) or failure (nonzero).

void posal_nmutex_unlock(posal_nmutex_t posal_nmutex)

Unlocks a normal mutex.

Associated data types: posal_nmutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: posal_nmutex – [in] Normal mutex.
Returns:: None.

void posal_nmutex_destroy(posal_nmutex_t *pp_posal_nmutex)

Destroys a normal mutex. This function must be called for each corresponding posal_nmutex_init() function to clean up all resources.

Associated data types: posal_nmutex_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: posal_nmutex – [in] Normal mutex.
Returns:: None.

posal_queue

This file contains the queue utilities. Queues must be created and added to a channel before they can be used. Queues are pushed from the back and can be popped from either front(FIFO) or back(LIFO). Queues must be destroyed when they are no longer needed.

Defines

POSAL_DEFAULT_NAME_LEN: Maximum number of characters to use in resource names (e.g., thread names).

Typedefs

typedef struct posal_queue_t posal_queue_t

Queue that transfers messages between threads. The queue implementation is signal based and thread safe. Each queue node is always 8 bytes. The number of queue nodes is sized up to powers of 2.

A queue must be associated with a channel.

typedef struct posal_queue_element_t posal_queue_element_t

typedef struct posal_queue_init_attr_t posal_queue_init_attr_t: Structure containing the attributes to be associated with type posal_queue_t

Functions

ar_result_t posal_queue_pool_setup(POSAL_HEAP_ID, uint32_t num_arrays, uint16_t nodes_per_arr)

void posal_queue_pool_reset(POSAL_HEAP_ID heap_id)

void posal_queue_pool_destroy(POSAL_HEAP_ID heap_id)

ar_result_t posal_queue_create_v1(posal_queue_t **queue_pptr, posal_queue_init_attr_t *attr_ptr)

Create a queue with specific attributes.

Associated data types: posal_queue_t, posal_queue_init_attr_t
: Nonzero — Failure
Dependencies: None.

Parameters:

attr_ptr – [in] Pointer to the attributes of the queue to be initialized
q_ptr – [inout] Pointer to the initialized queue.

Returns:

0 — Success

ar_result_t posal_queue_init(posal_queue_t *q_ptr, posal_queue_init_attr_t *attr_ptr)

Initializes queue with specific attributes at location q_ptr. Requires at least posal_queue_get_size() bytes allocated at q_ptr.

Associated data types: posal_queue_t, posal_queue_init_attr_t
: Nonzero — Failure
Dependencies: None.

Parameters:

q_ptr – [inout] Pointer to the initialized queue.
attr_ptr – [in] Pointer to the attributes of the queue to be initialized

Returns:

0 — Success

void posal_queue_destroy(posal_queue_t *q_ptr)

Destroys a queue.

This function will be deprecated in a future release, at which time posal_queue_deinit() must be used instead.

Associated data types: posal_queue_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [inout] Pointer to the queue.
Returns:: None.

void posal_queue_deinit(posal_queue_t *q_ptr)

Deinits a queue.

Associated data types: posal_queue_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [inout] Pointer to the queue.
Returns:: None.

ar_result_t posal_queue_disable(posal_queue_t *q_ptr)

Disables a queue.

Associated data types: posal_queue_t
: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [in] Pointer to the queue.
Returns:: 0 — Success

ar_result_t posal_queue_enable_disable_signaling(posal_queue_t *q_ptr, bool_t is_enable)

Enables/Disables the signing for a queue. By default, signaling is enabled.

Associated data types: posal_queue_t
: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
is_enable – [in] True: enables the signaling, False: disables the signaling

Returns:

0 — Success

ar_result_t posal_queue_push_back(posal_queue_t *q_ptr, posal_queue_element_t *payload_ptr)

Pushes an item onto a queue.

Associated data types: posal_queue_t
Detailed description: This function is nonblocking. The user is responsible for not overflowing the queue to avoid getting an unwanted assertion.
: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
pPayload – [in]
Pointer to the address (location) of the item.

The item is pushed (copied) onto the queue, not the queue address.

Returns:

0 — Success

ar_result_t posal_queue_push_back_with_priority(posal_queue_t *q_ptr, posal_queue_element_t *payload_ptr, uint32_t priority)

Pushes an item onto a priority queue.

Queue should have been initialized with priority attribute.

Associated data types: posal_queue_t
Detailed description: This function is nonblocking. The user is responsible for not overflowing the queue to avoid getting an unwanted assertion.

: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
pPayload – [in]
Pointer to the address (location) of the item.

The item is pushed (copied) onto the queue, not the queue address.
priority – [in] Priority number, higher value is higher priority.

Returns:

0 — Success

ar_result_t posal_queue_pop_front(posal_queue_t *q_ptr, posal_queue_element_t *payload_ptr)

Pops an item from the front of a queue.

Associated data types: posal_queue_t
Detailed description: This function is nonblocking and returns AR_ENOMORE if it is empty.
: Typically, the client calls this function only after waiting for a channel and checking whether this queue contains any items.
: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
pPayload – [in] Pointer to the target address (location) for the item that is popped.

Returns:

0 — Success

ar_result_t posal_queue_peek_forward(posal_queue_t *q_ptr, posal_queue_element_t **payload_ptr, void **iterator_pptr)

Peeks the next item in the queue based on the iterator position.

Associated data types: posal_queue_t
Detailed description: This function is nonblocking and returns AR_ENOMORE if queue empty or iterator reached to the last element.
: Client should keep the queue locked while using iterator, this is to prevent any other thread to push or pop from the queue.
: Nonzero — Failure
Dependencies: Before calling this function, queue object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
pPayload – [in] Pointer to the target address (location) for the address of the item that is peeked into.
iterator_pptr – [in] Pointer to the target address of iterator.

Returns:

0 — Success

ar_result_t posal_queue_peek_front(posal_queue_t *q_ptr, posal_queue_element_t **payload_ptr)

Peeks an item from the front of a queue.

Associated data types: posal_queue_t
Detailed description: This function is nonblocking and returns AR_ENOMORE if it is empty.
: Typically, the client calls this function only after waiting for a channel and checking whether this queue contains any items.
: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
pPayload – [in] Pointer to the target address (location) for the address of the item that is peeked into.

Returns:

0 — Success

ar_result_t posal_queue_pop_back(posal_queue_t *q_ptr, posal_queue_element_t *payload_ptr)

Pops an item from the back of a queue.

Associated data types: posal_queue_t
Detailed description: This function is for LIFO queues. It is nonblocking and returns AR_ENOMORE if it is empty.
: Typically, the client calls this function only after waiting for a channel and checking whether this queue contains any items.
: Nonzero — Failure
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:

q_ptr – [in] Pointer to the queue.
pPayload – [in] Pointer to the target address (location) for the item that is popped.

Returns:

0 — Success

posal_channel_t posal_queue_get_channel(posal_queue_t *q_ptr)

Queries a queue for its channel.

Associated data types: posal_queue_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [in] Pointer to the queue.
Returns:: A handle to the channel containing the queue.

uint32_t posal_queue_get_channel_bit(posal_queue_t *q_ptr)

Queries a queue for its channel bitfield.

Before calling this function, the object must be created and initialized.

Associated data types: posal_queue_t
Detailed description: This value is a 32-bit value with a single bit=1.
: Use this function to find the values to be ORed together to form an enable bitfield for a combination of queues in a channel.

Parameters:: q_ptr – [in] Pointer to the queue.
Returns:: A bitfield with this queue’s bit set to 1.

uint32_t posal_queue_poll(posal_queue_t *q_ptr)

Checks if a trigger is received for the queue.

Associated data types: posal_queue_t
Detailed description: This is a non blocking operation which polls/checks if a signal is set on the queue indicating that the queue is not empty.
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [in] Pointer to the queue.
Returns:: Returns a non zero value if the queue signal is set. The value is equal to queue’s bit mask.

uint32_t posal_queue_get_size()

Gets the memory size required by a queue.

Returns:: Returns the size in bytes required for the queue

static inline void posal_queue_attr_init(posal_queue_init_attr_t *attr_ptr): Setup the default attributes for the queue

static inline void posal_queue_attr_set_name(posal_queue_init_attr_t *attr_ptr, char_t *name_ptr): Setup the attribute ‘name’ for the queue

static inline void posal_queue_attr_set_max_nodes(posal_queue_init_attr_t *attr_ptr, int max_nodes): Setup the attribute ‘max_nodes’ for the queue

static inline void posal_queue_attr_set_prealloc_nodes(posal_queue_init_attr_t *attr_ptr, int prealloc_nodes): Setup the attribute ‘prealloc_nodes’ for the queue

static inline void posal_queue_attr_set_heap_id(posal_queue_init_attr_t *attr_ptr, POSAL_HEAP_ID heap_id): Setup the attribute ‘heap_id’ for the queue

static inline void posal_queue_attr_set_priority_queue_mode(posal_queue_init_attr_t *attr_ptr, bool_t is_priority_queue): Setup the attribute ‘heap_id’ for the queue

void posal_queue_lock_mutex(posal_queue_t *q_ptr)

Locks the mutext for the queue.

Associated data types: posal_queue_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [in] Pointer to the queue.

void posal_queue_unlock_mutex(posal_queue_t *q_ptr)

Unlocks the mutext for the queue.

Associated data types: posal_queue_t
Dependencies: Before calling this function, the object must be created and initialized.

Parameters:: q_ptr – [in] Pointer to the queue.

ar_result_t posal_queue_set_attributes(posal_queue_init_attr_t *q_attr_ptr, POSAL_HEAP_ID heap_id, uint32_t num_max_q_elem, uint32_t num_max_prealloc_q_elem, char_t *q_name_ptr): Function to set up all the available queue attributes

uint32_t posal_queue_get_queue_fullness(posal_queue_t *q_ptr)

function to get the fullness of queue

It returns the current number of element in the queue

struct posal_queue_init_attr_t

#include <posal_queue.h>

Structure containing the attributes to be associated with type posal_queue_t

Public Members

char_t name[POSAL_DEFAULT_NAME_LEN]: Name of the queue.

int32_t max_nodes: Max number of queue nodes.

int32_t prealloc_nodes: Number of preallocated nodes

POSAL_HEAP_ID heap_id: Heap ID from which nodes are to be allocated.

bool_t is_priority_queue: FALSE: default FIFO queue, TRUE: Priority queue.

posal_rtld

This file contains the Run-Time Linking (rtld) utilities.

Defines

POSAL_RTLD_LAZY

POSAL_RTLD_NOW

RTLD_DI_LOAD_ADDR: ideally dlfcn.h must define these macros. but in some targets they are not defined. this is a work-around.

RTLD_DI_LOAD_SIZE

Functions

void *posal_dlopen(const char *name, int flags)

Opens the specified dynamic lib

Associated data types: const char*, int
Dependencies: None.

Parameters:

name – [in] Name of the file to be opened
flags – [in] Flags for to indicate how the file should be opened. Possible values are POSAL_RTLD_LAZY and POSAL_RTLD_NOW

Returns:

Returns a pointer to the opened dynamic library, or 0 on failure

void *posal_dlopenbuf(const char *name, const char *buf, int len, int flags)

Opens the specified dynamic lib located in the given buffer

Associated data types: const char*, const char*, int
Dependencies: None.

Parameters:

name – [in] Name of the file to be opened
buf – [in] Buffer of the dynamic library
flags – [in] Flags for to indicate how the file should be opened. Possible values are POSAL_RTLD_LAZY and POSAL_RTLD_NOW

Returns:

Returns a pointer to the opened dynamic library, or 0 on failure

int posal_dlclose(void *handle)

Closes the specified dynamic lib

Associated data types: void *
Dependencies: None.

Parameters:: handle – [in] The handle of the dl to be closed
Returns:: 0 — Success

void *posal_dlsym(void *handle, const char *name)

Gets the pointer to the symbol within the dnamic lib

Associated data types: void *, const char *
Dependencies: None.

Parameters:

handle – [in] The handle of the dl with the symbol needed
name – [in] The name of the symbol

Returns:

Returns a pointer to the requested symbol, or 0 on failure

char *posal_dlerror(void)

Gives the string of the error if there is a problem in one of the dl functions

Dependencies: None.

Returns:: Returns a pointer to error string

int posal_dlinfo(void *handle, int request, void *p)

Gets info about the dynamic lib based on the request

Associated data types: void *, int, void *
Dependencies: None.

Parameters:

handle – [in] The handle of the dl in question
request – [in] The value of the request
p – [out] The output of the request

Returns:

0 — Success

posal_std

This file contains standard C functions.

Defines

AR_STD_MIN(a, b)

AR_STD_MAX(a, b)

Functions

uint32_t posal_strlcpy(char_t *dest_ptr, const char_t *src_ptr, uint32_t dest_len)

Copies the string from source pointer to a destination pointer.

Dependencies: None.

Parameters:

dest_ptr – [in] Pointer to the destination string.
src_ptr – [in] Pointer to the source string.
dest_len – [in] Length of the destination buffer.

Returns:

src_len — Source string size.

uint32_t posal_strnlen(const char_t *src_ptr, uint32_t size)

Determines the length of a string with a fixed maximum size.

Dependencies: None.

Parameters:

src_ptr – [in] Pointer to the destination string.
size – [in] Pointer to the source string.

Returns:

string length.

int32_t posal_strncmp(const char *s1, uint32_t s1_size, const char *s2, uint32_t s2_size)

Compares two strings, character wise bounded by length of the strings.

Dependencies: None.

Parameters:

s1 – [in] Pointer to the destination string.
s1_size – [in] Pointer to the source string.
s2 – [in] Length of the destination buffer.
s2_size – [in] Pointer to the destination string.

Returns:

<0 - if the first character that doesnt match has lower ASCII value in s1 than in s2 0 - if two strings are same >0 - if the first character that doesnt match has greater ASCII value in s1 than in s2

void *posal_memcpy(void *dst, uint32_t dst_size, const void *src, uint32_t src_size)

Copies src_size bytes from source pointer to the destination pointer. The number of bytes actually copied is bounded by dst_size, this avoids destination memory corruption if dst_size is less than src_size.

Dependencies: None.

Parameters:

dst – [in] - destination pointer.
dst_size – [in] - size of destination pointer in bytes.
src – [in] - source pointer
src_size – [in] - number of bytes to be copied from the source pointer.

Returns:

returns copy of destination pointer.

void *posal_memset(void *dst, int32_t c, uint32_t num_bytes)

Sets the first size bytes of the memory pointed by dst to the value ‘c’ [interpreted as unsigned char].

Dependencies: None.

Parameters:

dst – [in] - destination pointer
c – [in] - Value to be set. Pass as int32 but interpreted as unsigned char.
num_bytes – [in] - number of bytes to be set to value ‘c’

Returns:

returns a copy of the input pointer.

int32_t posal_snprintf(char_t *dst, uint32_t size, const char_t *format, ...)

Prints formated string in the destination pointer, the maximum number of characters printed is bounded by the size.

Dependencies: None.

Parameters:

dst – [in] - destination pointer where the string is printed.
size – [in] - maximum number of characters that could be printed.
format – [in] - pointer to the format string.

Returns:

Number of character that have been actually printed.

posal_thread_prio

This file contains the structures and function declarations that will be exposed to the framework to be invoked in order to retrieve the thread priority.

Typedefs

typedef enum spf_thread_prio_id_t spf_thread_prio_id_t

typedef struct prio_query_t prio_query_t: prio_query_t struct holds a (static_req_id, thread priority, frame duration) indicating the correct thread priority for a given frame duration (measured in microseconds) OR a req ID (indicates static/dynamic).

Enums

enum spf_thread_prio_id_t

Values:

enumerator SPF_THREAD_DYN_ID

enumerator SPF_THREAD_STAT_APM_ID

enumerator SPF_THREAD_STAT_CNTR_ID

enumerator SPF_THREAD_STAT_AMDB_ID

enumerator SPF_THREAD_STAT_IST_ID

enumerator SPF_THREAD_STAT_PRM_ID

enumerator SPF_THREAD_STAT_PM_SERVER_ID

enumerator SPF_THREAD_STAT_VOICE_TIMER_ID

enumerator SPF_THREAD_STAT_VCPM_ID

enumerator SPF_THREAD_STAT_ASPS_ID

enumerator SPF_THREAD_STAT_DLS_ID

enumerator SPF_THREAD_STAT_ID_MAX

Functions

ar_result_t posal_thread_calc_prio(prio_query_t *prio_query_ptr, posal_thread_prio_t *thread_prio_ptr)

ar_result_t posal_thread_determine_attributes(prio_query_t *prio_query_ptr, posal_thread_prio_t *thread_prio_ptr, uint32_t *sched_policy_ptr, uint32_t *cpu_set_ptr)

posal_thread_prio_t posal_thread_get_floor_prio(spf_thread_prio_id_t prio_id): Gets a default low priority for the passed in prio_id. Currently only implemented for SPF_THREAD_STAT_CNTR_ID.

struct prio_query_t

#include <posal_thread_prio.h>

prio_query_t struct holds a (static_req_id, thread priority, frame duration) indicating the correct thread priority for a given frame duration (measured in microseconds) OR a req ID (indicates static/dynamic).

Public Members

bool_t is_interrupt_trig

spf_thread_prio_id_t static_req_id

uint32_t frame_duration_us