Memory Pool Management

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