From 76177aa280494bb36d7a0bcbda1078d4db717020 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Mon, 9 Dec 2019 11:25:19 +0100 Subject: Official ARM version: v4.5 --- .../group___c_m_s_i_s___r_t_o_s___pool_mgmt.html | 456 +++++++++++++++++++++ 1 file changed, 456 insertions(+) create mode 100644 Documentation/RTOS/html/group___c_m_s_i_s___r_t_o_s___pool_mgmt.html (limited to 'Documentation/RTOS/html/group___c_m_s_i_s___r_t_o_s___pool_mgmt.html') diff --git a/Documentation/RTOS/html/group___c_m_s_i_s___r_t_o_s___pool_mgmt.html b/Documentation/RTOS/html/group___c_m_s_i_s___r_t_o_s___pool_mgmt.html new file mode 100644 index 0000000..7a9d5dd --- /dev/null +++ b/Documentation/RTOS/html/group___c_m_s_i_s___r_t_o_s___pool_mgmt.html @@ -0,0 +1,456 @@ + + + + + +Memory Pool +CMSIS-RTOS: Memory Pool + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS +  Version 1.02 +
+
CMSIS-RTOS API: Generic RTOS interface for Cortex-M processor-based devices.
+
+
+ +
+
    + +
+
+ + +
+
+ +
+
+
+ +
+
+
+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. +
  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. +
  3. Then, create the memory pool in a thread:
    object_pool_id = osPoolCreate(osPool(object_pool));
    +
    4. +
  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;
    +
    5. +
+

Macro Definition Documentation

+ +
+
+ + + + +
#define osFeature_Pool   1
+
+

A CMSIS-RTOS implementation may support fixed-size memory pools.

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

Access a memory pool for the functions osPoolCreate.

+
Parameters
+ + +
namename 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
+ + + + +
namename of the memory pool.
nomaximum number of blocks (objects) in the memory pool.
typedata 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_idmemory 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_idmemory 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_defmemory 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_idmemory pool ID obtain referenced with osPoolCreate.
[in]blockaddress 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
+
}
+
}
+
}
+
}
+
+
+
+
+
+ + + + -- cgit