CMSIS-RTOS RTX: Memory Pool Management

| CMSIS-RTOS RTX Version 4.80 CMSIS-RTOS RTX: Real-Time Operating System for Cortex-M processor-based devices

- 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 (RTX)

Define and manage fixed-size memory pools. More...

## Macros
#define | osFeature_Pool 1
| Memory Pools 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

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

## Macro Definition Documentation

#define osFeature_Pool 1

CMSIS-RTOS RTX supports fixed-size memory pools.

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

Access a memory pool for the functions osPoolCreate.

Parameters

  name | name of the memory pool

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

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

Allocate a memory block from the memory pool.

Note
  Interrupt Service Routines can call this function.

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.

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

Note
  Interrupt Service Routines can call this function.

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.

Create and initialize a memory pool.

Note
  Cannot be called from Interrupt Service Routines.

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.

Return a memory block to a memory pool.

Note
  Interrupt Service Routines can call this function.

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