Memory Pool

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.

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

CMSIS-RTOS RTX Setting: osFeature_Pool is 1

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