General Description

Helper APIs to create heaps and pools and allocate/free buffers from those pools or heaps.

When a heap or a pool is created, this utility allocates required chunk of memory from the system and manages it for the creator.

Data Structures
struct	wiced_bt_pool_statistics_t
	AIROC Bluetooth buffer pool statistics. More...

struct	wiced_bt_heap_statistics_t
	AIROC Bluetooth heap statistics. More...

struct	wiced_bt_buffer_q_t
	This queue is a general purpose buffer queue, for application use. More...

Macros
#define	WICED_DEFAULT_HEAP ((wiced_bt_heap_t *)NULL)
	If an application wants to get a buffer from the default heap, he can use this. More...

#define	wiced_bt_get_buffer(size) wiced_bt_get_buffer_from_heap(WICED_DEFAULT_HEAP, (size))
	Allocates a buffer from the DEFAULT heap . More...

Typedefs
typedef void	wiced_bt_buffer_t
	AIROC Bluetooth Buffer.

typedef struct t_wiced_bt_pool	wiced_bt_pool_t
	AIROC Bluetooth Pool.

typedef struct t_wiced_bt_heap	wiced_bt_heap_t
	AIROC Bluetooth Heap.

Functions
uint32_t	wiced_memory_get_free_bytes (void)
	Returns the number of free bytes of RAM available for allocation from the dynamic memory allocation of the Bluetooth Controller firmware. More...

wiced_bt_heap_t *	wiced_bt_create_heap (const char name, void p_area, int size, wiced_bt_lock_t *p_lock, wiced_bool_t b_make_default)
	Initializes dynamic memory area. More...

void	wiced_bt_delete_heap (wiced_bt_heap_t *p_heap)
	Deletes the heap created with wiced_bt_create_heap. More...

wiced_bt_pool_t *	wiced_bt_create_pool (const char name, uint32_t buffer_size, uint32_t buffer_cnt, wiced_bt_lock_t p_lock)
	Creates a buffer pool for application usage. More...

void	wiced_bt_delete_pool (wiced_bt_pool_t *p_pool)
	Deletes a buffer pool created using wiced_bt_create_pool. More...

wiced_bt_buffer_t *	wiced_bt_get_buffer_from_pool (wiced_bt_pool_t *p_pool)
	Get buffer from requested pool. More...

wiced_bt_buffer_t *	wiced_bt_get_buffer_from_heap (wiced_bt_heap_t *p_heap, uint32_t size)
	Allocates a buffer from the requested heap. More...

uint32_t	wiced_bt_get_pool_free_count (wiced_bt_pool_t *p_pool)
	To get the number of buffers available in the pool. More...

uint32_t	wiced_bt_get_largest_heap_buffer (wiced_bt_heap_t *p_heap)
	To get the size of the largest buffer available in the heap. More...

uint32_t	wiced_bt_get_largest_stack_heap_buffer (void)
	To get the size of the largest buffer available in the stack heap. More...

void	wiced_bt_free_buffer (wiced_bt_buffer_t *p_buf)
	Frees a buffer back to the pool or heap it came from. More...

uint32_t	wiced_bt_get_buffer_size (wiced_bt_buffer_t *p_buf)
	Gets the buffer size. More...

void	wiced_bt_init_q (wiced_bt_buffer_q_t p_q, wiced_bt_lock_t p_lock)
	Called by an application to initialize a AIROC buffer queue. More...

void	wiced_bt_enqueue (wiced_bt_buffer_q_t p_q, wiced_bt_buffer_t p_buf)
	Enqueue a buffer at the tail of the queue. More...

void	wiced_bt_enqueue_head (wiced_bt_buffer_q_t p_q, wiced_bt_buffer_t p_buf)
	Enqueue a buffer at the head of the queue. More...

wiced_bt_buffer_t *	wiced_bt_dequeue (wiced_bt_buffer_q_t *p_q)
	Dequeues a buffer from the head of a queue. More...

wiced_bt_buffer_t *	wiced_bt_remove_from_queue (wiced_bt_buffer_q_t p_q, wiced_bt_buffer_t p_buf)
	Dequeue a buffer from the middle of the queue. More...

wiced_bt_buffer_t *	wiced_bt_getfirst (wiced_bt_buffer_q_t *p_q)
	Return a pointer to the first buffer in a queue. More...

wiced_bt_buffer_t *	wiced_bt_getlast (wiced_bt_buffer_q_t *p_q)
	Return a pointer to the last buffer in a queue. More...

wiced_bt_buffer_t *	wiced_bt_getnext (wiced_bt_buffer_t *p_buf)
	Return a pointer to the next buffer in a queue. More...

uint32_t	wiced_bt_queue_is_empty (wiced_bt_buffer_q_t *p_q)
	Check the status of a queue. More...

uint32_t	wiced_bt_queue_get_count (wiced_bt_buffer_q_t *p_q)
	Get the number of items in the queue. More...

wiced_bt_buffer_t *	wiced_memory_alloc_long_term_mem_block (int size, const char *block_name)
	Allocate long term memory, typically used for control blocks allocated through config, not expected to be freed during the lifetime of the application. More...

void	wiced_memory_free_long_term_mem_block (wiced_bt_buffer_t *p_mem)
	Free long term memory, used to free memory allocated with wiced_memory_alloc_long_term_mem_block, typically called during application shutdown. More...

wiced_bool_t	wiced_bt_get_heap_statistics (void p_heap, wiced_bt_heap_statistics_t p_stats)
	Get heap stats. More...

wiced_bool_t	wiced_bt_get_heap_statistics_with_index (int index, wiced_bt_heap_statistics_t *p_stats)
	Get heap stats of heap at index. More...

wiced_result_t	wiced_bt_get_pool_statistics (wiced_bt_pool_t p_pool, wiced_bt_pool_statistics_t p_stats)
	Get pool stats. More...

void	wiced_set_exception_callback (pf_wiced_exception pf_handler)
	Set the exception callback for stack, controller, and porting layer exceptions: More...

Macro Definition Documentation

◆ WICED_DEFAULT_HEAP

#define WICED_DEFAULT_HEAP ((wiced_bt_heap_t *)NULL)

If an application wants to get a buffer from the default heap, he can use this.

◆ wiced_bt_get_buffer

#define wiced_bt_get_buffer ( size ) wiced_bt_get_buffer_from_heap(WICED_DEFAULT_HEAP, (size))

Allocates a buffer from the DEFAULT heap .

Parameters

[in] size : size to be allocated

Returns: the pointer to the buffer or NULL on failure

Function Documentation

◆ wiced_memory_get_free_bytes()

uint32_t wiced_memory_get_free_bytes ( void )

Returns the number of free bytes of RAM available for allocation from the dynamic memory allocation of the Bluetooth Controller firmware.

Note: This API is valid only for embedded platforms where the application,stack and controller memory is allocated from a common dynamic memory area.

Returns: the number of free bytes of RAM left

◆ wiced_bt_create_heap()

wiced_bt_heap_t* wiced_bt_create_heap	(	const char *	name,
		void *	p_area,
		int	size,
		wiced_bt_lock_t *	p_lock,
		wiced_bool_t	b_make_default
	)

Initializes dynamic memory area.

Application reserves an area for dynamic variable memory allocations with this call. Application can now allocate variable sized buffers as against fixed sized buffer allocations from the pools initialized with calls to wiced_bt_create_pool and allocated using wiced_bt_get_buffer_from_pool.

Parameters

[in]	name	: Friendly name of the heap
[in]	p_area	: Pointer to area to use for the heap. If NULL, AIROC will allocate the area.
[in]	size	: Size the area passed in. If no area passed in, this is the size of the heap desired.
[in]	p_lock	: Pointers to lock functions to use during heap manipulation. If NULL, then it is assumed that the application handles disabling of preemption.
[in]	b_make_default	Flag as to whether the heap will be the default heap.

Returns: wiced_bt_heap_t * - pointer to heap, or NULL if the heap creation failed.

◆ wiced_bt_delete_heap()

void wiced_bt_delete_heap ( wiced_bt_heap_t * p_heap )

Deletes the heap created with wiced_bt_create_heap.

The heap area is freed back to the platform in case the wiced_bt_create_heap was called with p_area set to NULL.

Parameters

[in] p_heap : Heap created with wiced_bt_create_heap

Returns: void

◆ wiced_bt_create_pool()

wiced_bt_pool_t* wiced_bt_create_pool	(	const char *	name,
		uint32_t	buffer_size,
		uint32_t	buffer_cnt,
		wiced_bt_lock_t *	p_lock
	)

Creates a buffer pool for application usage.

Parameters

[in]	name	: Friendly name of the heap
[in]	buffer_size	Size of the buffers in the pool
[in]	buffer_cnt	: Number of buffers in the pool
[in]	p_lock	: Pointers to lock functions to use during heap manipulation. If NULL, then it is assumed that the application handles disabling of preemption.

Returns: pointer to the created pool on success, or NULL on failure

◆ wiced_bt_delete_pool()

void wiced_bt_delete_pool ( wiced_bt_pool_t * p_pool )

Deletes a buffer pool created using wiced_bt_create_pool.

Parameters

[in] p_pool : pointer of type wiced_bt_pool_t returned through a call to wiced_bt_create_pool

Returns: void

◆ wiced_bt_get_buffer_from_pool()

wiced_bt_buffer_t* wiced_bt_get_buffer_from_pool ( wiced_bt_pool_t * p_pool )

Get buffer from requested pool.

Allocates a buffer from the requested pool.

Parameters

[in] p_pool : pointer to pool from which to get the buffer

Returns: the pointer to the buffer or NULL on failure

◆ wiced_bt_get_buffer_from_heap()

wiced_bt_buffer_t* wiced_bt_get_buffer_from_heap	(	wiced_bt_heap_t *	p_heap,
		uint32_t	size
	)

Allocates a buffer from the requested heap.

Parameters

[in]	p_heap	: pointer to heap from which to get the buffer
[in]	size	: size to be allocated

Returns: the pointer to the buffer or NULL on failure

◆ wiced_bt_get_pool_free_count()

uint32_t wiced_bt_get_pool_free_count ( wiced_bt_pool_t * p_pool )

To get the number of buffers available in the pool.

Parameters

[in] p_pool : pool pointer

Returns: the number of buffers available in the pool

◆ wiced_bt_get_largest_heap_buffer()

uint32_t wiced_bt_get_largest_heap_buffer ( wiced_bt_heap_t * p_heap )

To get the size of the largest buffer available in the heap.

Parameters

[in] p_heap : heap pointer

Returns: the size of the largest buffer available in the heap

◆ wiced_bt_get_largest_stack_heap_buffer()

uint32_t wiced_bt_get_largest_stack_heap_buffer ( void )

To get the size of the largest buffer available in the stack heap.

Returns: the size of the largest buffer available in the stack heap

◆ wiced_bt_free_buffer()

void wiced_bt_free_buffer ( wiced_bt_buffer_t * p_buf )

Frees a buffer back to the pool or heap it came from.

Parameters

[in] p_buf : pointer to the start of the (pool/heap) buffer to be freed

Returns: None

◆ wiced_bt_get_buffer_size()

uint32_t wiced_bt_get_buffer_size ( wiced_bt_buffer_t * p_buf )

Gets the buffer size.

Parameters

[in] p_buf : pointer to the start of the buffer

Returns: the buffer size

◆ wiced_bt_init_q()

void wiced_bt_init_q	(	wiced_bt_buffer_q_t *	p_q,
		wiced_bt_lock_t *	p_lock
	)

Called by an application to initialize a AIROC buffer queue.

Pointers to lock and unlock functions may be NULL if application has handled preemption outside of the queue management code.

Returns: void

◆ wiced_bt_enqueue()

void wiced_bt_enqueue	(	wiced_bt_buffer_q_t *	p_q,
		wiced_bt_buffer_t *	p_buf
	)

Enqueue a buffer at the tail of the queue.

Parameters

[in]	p_q	: pointer to a queue.
[in]	p_buf	: address of the buffer to enqueue

Returns: void

◆ wiced_bt_enqueue_head()

void wiced_bt_enqueue_head	(	wiced_bt_buffer_q_t *	p_q,
		wiced_bt_buffer_t *	p_buf
	)

Enqueue a buffer at the head of the queue.

Parameters

[in]	p_q	: pointer to a queue.
[in]	p_buf	: address of the buffer to enqueue

Returns: void

◆ wiced_bt_dequeue()

wiced_bt_buffer_t* wiced_bt_dequeue ( wiced_bt_buffer_q_t * p_q )

Dequeues a buffer from the head of a queue.

Parameters

[in] p_q : pointer to a queue.

Returns: NULL if queue is empty, else buffer

◆ wiced_bt_remove_from_queue()

wiced_bt_buffer_t* wiced_bt_remove_from_queue	(	wiced_bt_buffer_q_t *	p_q,
		wiced_bt_buffer_t *	p_buf
	)

Dequeue a buffer from the middle of the queue.

Parameters

[in]	p_q	: pointer to a queue.
[in]	p_buf	: address of the buffer to dequeue

Returns: NULL if queue is empty, else buffer

◆ wiced_bt_getfirst()

wiced_bt_buffer_t* wiced_bt_getfirst ( wiced_bt_buffer_q_t * p_q )

Return a pointer to the first buffer in a queue.

Parameters

[in] p_q : pointer to a queue.

Returns: NULL if queue is empty, else buffer address

◆ wiced_bt_getlast()

wiced_bt_buffer_t* wiced_bt_getlast ( wiced_bt_buffer_q_t * p_q )

Return a pointer to the last buffer in a queue.

Parameters

[in] p_q : pointer to a queue.

Returns: NULL if queue is empty, else buffer address

◆ wiced_bt_getnext()

wiced_bt_buffer_t* wiced_bt_getnext ( wiced_bt_buffer_t * p_buf )

Return a pointer to the next buffer in a queue.

Parameters

[in] p_buf : pointer to the buffer to find the next one from.

Returns: NULL if no more buffers in the queue, else next buffer address

◆ wiced_bt_queue_is_empty()

uint32_t wiced_bt_queue_is_empty ( wiced_bt_buffer_q_t * p_q )

Check the status of a queue.

Parameters

[in] p_q : pointer to a queue.

Returns: TRUE if queue is empty, else FALSE

◆ wiced_bt_queue_get_count()

uint32_t wiced_bt_queue_get_count ( wiced_bt_buffer_q_t * p_q )

Get the number of items in the queue.

Parameters

[in] p_q : pointer to a queue.

Returns: number of items in the queue

◆ wiced_memory_alloc_long_term_mem_block()

wiced_bt_buffer_t* wiced_memory_alloc_long_term_mem_block	(	int	size,
		const char *	block_name
	)

Allocate long term memory, typically used for control blocks allocated through config, not expected to be freed during the lifetime of the application.

Parameters

[in]	size	: size of memory to be allocated
[in]	block_name	friendly name of memory block to be allocated.

Returns: pointer to the allocated memory

◆ wiced_memory_free_long_term_mem_block()

void wiced_memory_free_long_term_mem_block ( wiced_bt_buffer_t * p_mem )

Free long term memory, used to free memory allocated with wiced_memory_alloc_long_term_mem_block, typically called during application shutdown.

Parameters

[in] p_mem : pointer memory to be freed

Returns: none

◆ wiced_bt_get_heap_statistics()

wiced_bool_t wiced_bt_get_heap_statistics	(	void *	p_heap,
		wiced_bt_heap_statistics_t *	p_stats
	)

Get heap stats.

Parameters

[in]	p_heap	: heap pointer (output of wiced_bt_create_heap)
[out]	p_stats	: pointer to receive the heap statistics

Returns: TRUE in case of valid stats returned in p_stats

◆ wiced_bt_get_heap_statistics_with_index()

wiced_bool_t wiced_bt_get_heap_statistics_with_index	(	int	index,
		wiced_bt_heap_statistics_t *	p_stats
	)

Get heap stats of heap at index.

Application calls the function in a loop incrementing the index till the function returns WICED_FALSE

Parameters

[in]	index	: index of heap, starts from 0
[out]	p_stats	: pointer to receive the heap statistics

Returns: TRUE in case of valid stats returned in p_stats

◆ wiced_bt_get_pool_statistics()

wiced_result_t wiced_bt_get_pool_statistics	(	wiced_bt_pool_t *	p_pool,
		wiced_bt_pool_statistics_t *	p_stats
	)

Get pool stats.

Parameters

[in]	p_pool	: pool pointer (output of wiced_bt_create_pool)
[out]	p_stats	: pointer to receive the pool statistics

Returns: TRUE in case of valid stats returned in p_stats

◆ wiced_set_exception_callback()

void wiced_set_exception_callback ( pf_wiced_exception pf_handler )

Set the exception callback for stack, controller, and porting layer exceptions:

Note: wiced_set_exception_callback() needs to be defined in porting layer of each platform where pf_handler callback function is also defined.

Parameters

[in] pf_handler : Exception callback function

Returns: void

General Description

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

◆ WICED_DEFAULT_HEAP

◆ wiced_bt_get_buffer

Function Documentation

◆ wiced_memory_get_free_bytes()

◆ wiced_bt_create_heap()

◆ wiced_bt_delete_heap()

◆ wiced_bt_create_pool()

◆ wiced_bt_delete_pool()

◆ wiced_bt_get_buffer_from_pool()

◆ wiced_bt_get_buffer_from_heap()

◆ wiced_bt_get_pool_free_count()

◆ wiced_bt_get_largest_heap_buffer()

◆ wiced_bt_get_largest_stack_heap_buffer()

◆ wiced_bt_free_buffer()

◆ wiced_bt_get_buffer_size()

◆ wiced_bt_init_q()

◆ wiced_bt_enqueue()

◆ wiced_bt_enqueue_head()

◆ wiced_bt_dequeue()

◆ wiced_bt_remove_from_queue()

◆ wiced_bt_getfirst()

◆ wiced_bt_getlast()

◆ wiced_bt_getnext()

◆ wiced_bt_queue_is_empty()

◆ wiced_bt_queue_get_count()

◆ wiced_memory_alloc_long_term_mem_block()

◆ wiced_memory_free_long_term_mem_block()

◆ wiced_bt_get_heap_statistics()

◆ wiced_bt_get_heap_statistics_with_index()

◆ wiced_bt_get_pool_statistics()

◆ wiced_set_exception_callback()