CMSIS-RTOS2
Version 2.1.3
Real-Time Operating System: API and RTX Reference Implementation
|
Manage thread-safe fixed-size blocks of dynamic memory. More...
Data Structures | |
struct | osMemoryPoolAttr_t |
Attributes structure for memory pool. More... | |
Typedefs | |
typedef void * | osMemoryPoolId_t |
Functions | |
osMemoryPoolId_t | osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr) |
Create and Initialize a Memory Pool object. More... | |
const char * | osMemoryPoolGetName (osMemoryPoolId_t mp_id) |
Get name of a Memory Pool object. More... | |
void * | osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout) |
Allocate a memory block from a Memory Pool. More... | |
osStatus_t | osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block) |
Return an allocated memory block back to a Memory Pool. More... | |
uint32_t | osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id) |
Get maximum number of memory blocks in a Memory Pool. More... | |
uint32_t | osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id) |
Get memory block size in a Memory Pool. More... | |
uint32_t | osMemoryPoolGetCount (osMemoryPoolId_t mp_id) |
Get number of memory blocks used in a Memory Pool. More... | |
uint32_t | osMemoryPoolGetSpace (osMemoryPoolId_t mp_id) |
Get number of memory blocks available in a Memory Pool. More... | |
osStatus_t | osMemoryPoolDelete (osMemoryPoolId_t mp_id) |
Delete a Memory Pool object. More... | |
Memory Pools are fixed-size blocks of memory that are thread-safe. They operate much faster than the dynamically allocated heap and do not suffer from fragmentation. Being thread-safe, they can be accessed from threads and ISRs alike.
A Memory Pool can be seen as a linked list of available (unused) memory blocks of fixed and equal size. Allocating memory from a pool (using osMemoryPoolAlloc) simply unchains a block from the list and hands over control to the user. Freeing memory to the pool (using osMemoryPoolFree) simply rechains the block into the list.
Shared memory is one of the basic models to exchange information between threads. Using memory pools for exchanging data, you can share more complex objects between threads if compared to a Message Queue. Memory pool management functions are used to define and manage such fixed-sized memory pools.
struct osMemoryPoolAttr_t |
Attributes to configure a memory pool.
Refer to Memory Management for details about usage of
Data Fields | ||
---|---|---|
const char * | name |
name of the memory pool Pointer to a string with a human readable name of the memory pool object. |
uint32_t | attr_bits |
attribute bits Reserved for future use (set to '0'). |
void * | cb_mem |
memory for control block Pointer to a memory location for the memory pool control block object. This can optionally be used for custom memory management systems. |
uint32_t | cb_size |
size of provided memory for control block The size of the memory block passed with cb_mem. Must be the size of a memory pool control block object or larger. |
void * | mp_mem |
memory for data storage Pointer to a memory location for the data of the memory pool object. |
uint32_t | mp_size |
size of provided memory for data storage The size of the memory passed with mp_mem. |
osMemoryPoolId_t osMemoryPoolNew | ( | uint32_t | block_count, |
uint32_t | block_size, | ||
const osMemoryPoolAttr_t * | attr | ||
) |
[in] | block_count | maximum number of memory blocks in memory pool. |
[in] | block_size | memory block size in bytes. |
[in] | attr | memory pool attributes; NULL: default values. |
The function osMemoryPoolNew creates and initializes a memory pool object and returns the pointer to the memory pool object identifier or NULL in case of an error. It can be safely called before the RTOS is started (call to osKernelStart), but not before it is initialized (call to osKernelInitialize).
The total amount of memory needed is at least block_count * block_size
. Memory from the pool can only be allocated/freed in fixed portions of block_size
.
Code Example
const char * osMemoryPoolGetName | ( | osMemoryPoolId_t | mp_id | ) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
The function osMemoryPoolGetName returns the pointer to the name string of the memory pool identified by parameter mp_id or NULL in case of an error.
void * osMemoryPoolAlloc | ( | osMemoryPoolId_t | mp_id, |
uint32_t | timeout | ||
) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
[in] | timeout | Timeout Value or 0 in case of no time-out. |
The blocking function osMemoryPoolAlloc allocates the memory pool parameter mp_id and returns a pointer to the address of the allocated memory or 0 in case of an error.
The parameter timeout specifies how long the system waits to allocate the memory. While the system waits, the thread that is calling this function is put into the BLOCKED state. The thread will become READY as soon as at least one block of memory gets available.
The parameter timeout can have the following values:
The result is the pointer to the memory block allocated, or NULL if no memory is available.
Code Example
Refer to osMemoryPoolNew.
osStatus_t osMemoryPoolFree | ( | osMemoryPoolId_t | mp_id, |
void * | block | ||
) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
[in] | block | address of the allocated memory block to be returned to the memory pool. |
The function osMemoryPoolFree frees the memory pool block specified by the parameter block in the memory pool object specified by the parameter mp_id. The memory block is put back to the list of available blocks.
If another thread is waiting for memory to become available the thread is put to READY state.
Possible osStatus_t return values:
Code Example
Refer to osMemoryPoolNew.
uint32_t osMemoryPoolGetCapacity | ( | osMemoryPoolId_t | mp_id | ) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
The function osMemoryPoolGetCapacity returns the maximum number of memory blocks in the memory pool object specified by parameter mp_id or 0 in case of an error.
uint32_t osMemoryPoolGetBlockSize | ( | osMemoryPoolId_t | mp_id | ) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
The function osMemoryPoolGetBlockSize returns the memory block size in bytes in the memory pool object specified by parameter mp_id or 0 in case of an error.
uint32_t osMemoryPoolGetCount | ( | osMemoryPoolId_t | mp_id | ) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
The function osMemoryPoolGetCount returns the number of memory blocks used in the memory pool object specified by parameter mp_id or 0 in case of an error.
uint32_t osMemoryPoolGetSpace | ( | osMemoryPoolId_t | mp_id | ) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
The function osMemoryPoolGetSpace returns the number of memory blocks available in the memory pool object specified by parameter mp_id or 0 in case of an error.
osStatus_t osMemoryPoolDelete | ( | osMemoryPoolId_t | mp_id | ) |
[in] | mp_id | memory pool ID obtained by osMemoryPoolNew. |
The function osMemoryPoolDelete deletes a memory pool object specified by parameter mp_id. It releases internal memory obtained for memory pool handling. After this call, the mp_id is no longer valid and cannot be used. The memory pool may be created again using the function osMemoryPoolNew.
Possible osStatus_t return values: