CMSIS-RTOS: Memory Pool Management

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

- CMSIS
- CORE
- DSP
- RTOS API
- SVD

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Macros | Functions
Memory Pool Management
CMSIS-RTOS API

Define and manage fixed-size memory pools. 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

The Memory Pool Management function group is used to define and manage fixed-sized memory pools.

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

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.

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.

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.

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