CMSIS-RTOS  Version 1.03
Real-Time Operating System: API and RTX Reference Implementation.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages

Manage thread-safe fixed-size blocks of dynamic memory. More...

Macros

#define osFeature_Pool   1
 Memory Pools: 1=available, 0=not available. More...
 
#define osPoolDef(name, no, type)
 Define a Memory Pool. More...
 
#define osPool(name)   &os_pool_def_##name
 Access a Memory Pool definition. More...
 

Functions

osPoolId osPoolCreate (const osPoolDef_t *pool_def)
 Create and Initialize a memory pool. More...
 
void * osPoolAlloc (osPoolId pool_id)
 Allocate a memory block from a memory pool. More...
 
void * osPoolCAlloc (osPoolId pool_id)
 Allocate a memory block from a memory pool and set memory block to zero. More...
 
osStatus osPoolFree (osPoolId pool_id, void *block)
 Return an allocated memory block back to a specific memory pool. More...
 

Description

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.

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.

Working with Memory Pools

Follow these steps to create and use a memory pool:

  1. Declare a data structure that combines a number of elements:
    typedef struct {
    uint32_t length;
    uint32_t width;
    uint32_t height;
    uint32_t weight;
    } properties_t;
  2. Declare a memory pool of these objects as a block of memory:
    osPoolDef (object_pool, 10, properties_t); // Declare memory pool
    osPoolId (object_pool_id); // Memory pool ID
  3. Then, create the memory pool in a thread:
    object_pool_id = osPoolCreate(osPool(object_pool));
  4. Allocate the pool within a thread and fill it with data:
    properties_t *object_data;
    object_data = (properties_t *) osPoolAlloc(object_pool_id);
    object_data->length = 100;
    object_data->width = 10;
    object_data->height = 23;
    object_data->weight = 1000;

Macro Definition Documentation

#define osFeature_Pool   1

A CMSIS-RTOS implementation may support fixed-size memory pools.

CMSIS-RTOS RTX Setting: osFeature_Pool is 1

#define osPool (   name)    &os_pool_def_##name

Access a memory pool for the functions osPoolCreate.

Parameters
namename of the memory pool
Note
CAN BE CHANGED: The parameter to osPool shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.
#define osPoolDef (   name,
  no,
  type 
)

Define a memory pool that is referenced by osPool.

Parameters
namename of the memory pool.
nomaximum number of blocks (objects) in the memory pool.
typedata type of a single block (object).
Note
CAN BE CHANGED: The parameter to osPoolDef shall be consistent but the macro body is implementation specific in every CMSIS-RTOS.

Function Documentation

void * osPoolAlloc ( osPoolId  pool_id)
Parameters
[in]pool_idmemory pool ID obtain referenced with osPoolCreate.
Returns
address of the allocated memory block or NULL in case of no memory available.
Note
MUST REMAIN UNCHANGED: osPoolAlloc shall be consistent in every CMSIS-RTOS.

Allocate a memory block from the memory pool.

Note
Interrupt Service Routines can call this function.

Code Example

#include "cmsis_os.h"
typedef struct {
uint8_t Buf[32];
uint8_t Idx;
} MEM_BLOCK;
osPoolDef (MemPool, 8, MEM_BLOCK);
void AlocMemoryPoolBlock (void) {
osPoolId MemPool_Id;
MEM_BLOCK *addr;
MemPool_Id = osPoolCreate (osPool (MemPool));
if (MemPool_Id != NULL) {
:
// allocate a memory block
addr = (MEM_BLOCK *)osPoolAlloc (MemPool_Id);
if (addr != NULL) {
// memory block was allocated
:
}
}
}
void * osPoolCAlloc ( osPoolId  pool_id)
Parameters
[in]pool_idmemory pool ID obtain referenced with osPoolCreate.
Returns
address of the allocated memory block or NULL in case of no memory available.
Note
MUST REMAIN UNCHANGED: osPoolCAlloc shall be consistent in every CMSIS-RTOS.

Allocate a memory block from the memory pool. The block is initialized to zero.

Note
Interrupt Service Routines can call this function.

Code Example

#include "cmsis_os.h"
typedef struct {
uint8_t Buf[32];
uint8_t Idx;
} MEM_BLOCK;
osPoolDef (MemPool, 8, MEM_BLOCK);
void CAlocMemoryPoolBlock (void) {
osPoolId MemPool_Id;
MEM_BLOCK *addr;
MemPool_Id = osPoolCreate (osPool (MemPool));
if (MemPool_Id != NULL) {
:
// allocate a memory block
addr = (MEM_BLOCK *)osPoolCAlloc (MemPool_Id);
if (addr != NULL) {
// memory block was allocated
:
}
}
}
osPoolId osPoolCreate ( const osPoolDef_t pool_def)
Parameters
[in]pool_defmemory pool definition referenced with osPool.
Returns
memory pool ID for reference by other functions or NULL in case of error.
Note
MUST REMAIN UNCHANGED: osPoolCreate shall be consistent in every CMSIS-RTOS.

Create and initialize a memory pool.

Note
Cannot be called from Interrupt Service Routines.

Code Example

#include "cmsis_os.h"
typedef struct {
uint8_t Buf[32];
uint8_t Idx;
} MEM_BLOCK;
osPoolDef (MemPool, 8, MEM_BLOCK);
void CreateMemoryPool (void) {
osPoolId MemPool_Id;
MemPool_Id = osPoolCreate (osPool (MemPool));
if (MemPool_Id != NULL) {
// memory pool created
}
}
osStatus osPoolFree ( osPoolId  pool_id,
void *  block 
)
Parameters
[in]pool_idmemory pool ID obtain referenced with osPoolCreate.
[in]blockaddress of the allocated memory block that is returned to the memory pool.
Returns
status code that indicates the execution status of the function.
Note
MUST REMAIN UNCHANGED: osPoolFree shall be consistent in every CMSIS-RTOS.

Return a memory block to a memory pool.

Status and Error Codes

  • osOK: the memory block is released.
  • osErrorValue: block does not belong to the memory pool.
  • osErrorParameter: a parameter is invalid or outside of a permitted range.
Note
Interrupt Service Routines can call this function.

Code Example

#include "cmsis_os.h"
typedef struct {
uint8_t Buf[32];
uint8_t Idx;
} MEM_BLOCK;
osPoolDef (MemPool, 8, MEM_BLOCK);
void CAlocMemoryPoolBlock (void) {
osPoolId MemPool_Id;
MEM_BLOCK *addr;
osStatus status;
MemPool_Id = osPoolCreate (osPool (MemPool));
if (MemPool_Id != NULL) {
addr = (MEM_BLOCK *)osPoolCAlloc (MemPool_Id);
if (addr != NULL) {
:
// return a memory block back to pool
status = osPoolFree (MemPool_Id, addr);
if (status==osOK) {
// handle status code
}
}
}
}