CMSIS-RTOS: Memory Pool

| CMSIS-RTOS Version 1.02 CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.

- Main Page
- Usage and Description
- Reference

Macros | Functions
Memory Pool
Inter-Thread Communication and Resource Sharing

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

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

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

## 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.

- When osFeature_Pool is 1 memory pools are supported.
- When osFeature_Pool is 0 no memory pools are supported.

#define osPool | ( |  | name | ) | &os_pool_def_##name

Access a memory pool for the functions osPoolCreate.

Parameters

  name | name 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

  name | name of the memory pool.
  no | maximum number of blocks (objects) in the memory pool.
  type | data 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_id | memory 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_id | memory 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_def | memory 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_id | memory pool ID obtain referenced with osPoolCreate.
  [in] | block | address 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
}
}
}
}