From 9f95ff5b6ba01db09552b84a0ab79607060a2666 Mon Sep 17 00:00:00 2001 From: Ali Labbene Date: Wed, 11 Dec 2019 08:59:21 +0100 Subject: Official ARM version: v5.4.0 Add CMSIS V5.4.0, please refer to index.html available under \docs folder. Note: content of \CMSIS\Core\Include has been copied under \Include to keep the same structure used in existing projects, and thus avoid projects mass update Note: the following components have been removed from ARM original delivery (as not used in ST packages) - CMSIS_EW2018.pdf - .gitattributes - .gitignore - \Device - \CMSIS - \CoreValidation - \DAP - \Documentation - \DoxyGen - \Driver - \Pack - \RTOS\CMSIS_RTOS_Tutorial.pdf - \RTOS\RTX - \RTOS\Template - \RTOS2\RTX - \Utilities - All ARM/GCC projects files are deleted from \DSP, \RTOS and \RTOS2 Change-Id: Ia026c3f0f0d016627a4fb5a9032852c33d24b4d3 --- docs/RTOS/html/group__CMSIS__RTOS__PoolMgmt.html | 495 +++++++++++++++++++++++ 1 file changed, 495 insertions(+) create mode 100644 docs/RTOS/html/group__CMSIS__RTOS__PoolMgmt.html (limited to 'docs/RTOS/html/group__CMSIS__RTOS__PoolMgmt.html') diff --git a/docs/RTOS/html/group__CMSIS__RTOS__PoolMgmt.html b/docs/RTOS/html/group__CMSIS__RTOS__PoolMgmt.html new file mode 100644 index 0000000..91e0af7 --- /dev/null +++ b/docs/RTOS/html/group__CMSIS__RTOS__PoolMgmt.html @@ -0,0 +1,495 @@ + + + + + +Memory Pool +CMSIS-RTOS: Memory Pool + + + + + + + + + + + + + + +
+
+ + + + + + + +
+
CMSIS-RTOS +  Version 1.03 +
+
Real-Time Operating System: API and RTX Reference Implementation.
+
+
+ +
+
    + +
+
+ + + +
+
+ +
+
+
+ +
+ + + + +
+ +
+ +
+
+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. 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. +
  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.

+ +

CMSIS-RTOS RTX Setting: osFeature_Pool is 1

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