begriffs open source - cmsis/blob - CMSIS/DoxyGen/RTOS2/src/cmsis_os2_MemPool.txt

   1 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   2 //  ==== Memory Pool Management ====
   3 /**
   4 \addtogroup CMSIS_RTOS_PoolMgmt Memory Pool
   5 \ingroup CMSIS_RTOS
   6 \brief Manage thread-safe fixed-size blocks of dynamic memory.
   7 \details
   8 \b Memory \b Pools are fixed-size blocks of memory that are thread-safe. They operate much faster than the dynamically
   9 allocated heap and do not suffer from fragmentation. Being thread-safe, they can be accessed from threads and ISRs alike.
  10
  11 A Memory Pool can be seen as a linked list of available (unused) memory blocks of fixed and equal size. Allocating memory
  12 from a pool (using \ref osMemoryPoolAlloc) simply unchains a block from the list and hands over control to the user. Freeing
  13 memory to the pool (using \ref osMemoryPoolFree) simply rechains the block into the list.
  14
  15 \image html "mempool.png" "CMSIS-RTOS Memory Pools"
  16
  17 \note One must not write to freed block. It is up to the implementation to reuse the memory of unused blocks for internal
  18 control data, i.e. linked list pointers.
  19
  20 \b Shared \b memory is one of the basic models to exchange information between threads. Using memory pools for exchanging
  21 data, you can share more complex objects between threads if compared to a \ref CMSIS_RTOS_Message. Memory pool management
  22 functions are used to define and manage such fixed-sized memory pools.
  23
  24 \note The functions \ref osMemoryPoolAlloc, \ref osMemoryPoolFree, \ref osMemoryPoolGetCapacity,
  25 \ref osMemoryPoolGetBlockSize, \ref osMemoryPoolGetCount, \ref osMemoryPoolGetSpace can be called from
  26 \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  27 \note Refer to \ref memPoolConfig for RTX5 configuration options.
  28
  29 @{
  30 */
  31
  32 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  33 /**
  34 \typedef osMemoryPoolId_t
  35 \details
  36 Returned by:
  37 - \ref osMemoryPoolNew
  38 */
  39
  40 /**
  41 \struct osMemoryPoolAttr_t
  42 \details
  43 Attributes to configure a memory pool.
  44
  45 Refer to \ref CMSIS_RTOS_MemoryMgmt for details about usage of
  46  - osMemoryPoolAttr_t::cb_mem
  47  - osMemoryPoolAttr_t::cb_size
  48  - osMemoryPoolAttr_t::mp_mem
  49  - osMemoryPoolAttr_t::mp_size
  50 */
  51
  52 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  53 /**
  54 \fn osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr)
  55 \details
  56 The function \b osMemoryPoolNew creates and initializes a memory pool object and returns the pointer to the memory pool
  57 object identifier or \token{NULL} in case of an error. It can be safely called before the RTOS is
  58 started (call to \ref osKernelStart), but not before it is initialized (call to \ref osKernelInitialize).
  59
  60 The total amount of memory needed is at least <code>block_count * block_size</code>. Memory from the pool can only be
  61 allocated/freed in fixed portions of \c block_size.
  62
  63 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  64
  65 \b Code \b Example
  66 \code
  67 #include "cmsis_os2.h"                                        // CMSIS RTOS header file
  68
  69 /*----------------------------------------------------------------------------
  70  *      Memory Pool creation & usage
  71  *---------------------------------------------------------------------------*/
  72
  73 #define MEMPOOL_OBJECTS      16                               // number of Memory Pool Objects
  74
  75 typedef struct {                                              // object data type
  76   uint8_t Buf[32];
  77   uint8_t Idx;
  78 } MEM_BLOCK_t;
  79
  80 void Thread_MemPool (void *argument);                         // thread function
  81 osThreadId_t tid_Thread_MemPool;                              // thread id
  82
  83 osMemoryPoolId_t mpid_MemPool;                                // memory pool id
  84
  85 int Init_MemPool (void)
  86 {
  87
  88   mpid_MemPool = osMemoryPoolNew(MEMPOOL_OBJECTS,sizeof(MEM_BLOCK_t), NULL);
  89   if (mpid_MemPool == NULL) {
  90     ; // MemPool object not created, handle failure
  91   }
  92
  93   tid_Thread_MemPool = osThreadNew (Thread_MemPool,NULL , NULL);
  94   if (tid_Thread_MemPool == NULL) {
  95     return(-1);
  96   }
  97
  98   return(0);
  99 }
 100
 101 void Thread_MemPool (void *argument)
 102 {
 103   osStatus_t     status;
 104   MEM_BLOCK_t *pMem = 0;
 105
 106   while (1) {
 107     ; // Insert thread code here...
 108
 109     pMem = (MEM_BLOCK_t *)osMemoryPoolAlloc (mpid_MemPool, NULL);    // get Mem Block
 110     if (pMem) {                                                      // Mem Block was available
 111       pMem->Buf[0] = 0x55;                                           // do some work...
 112       pMem->Idx    = 0;
 113
 114       status = osMemoryPoolFree (mpid_MemPool, pMem);                // free mem block
 115       switch (status)  {
 116       case osOK:
 117         break;
 118       case osErrorParameter:
 119         break;
 120       case osErrorNoMemory:
 121         break;
 122       default:
 123         break;
 124       }
 125     }
 126
 127     osThreadYield ();                                                // suspend thread
 128   }
 129 }
 130 \endcode
 131 */
 132
 133 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 134 /**
 135 \fn const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id)
 136 \details
 137 The function \b osMemoryPoolGetName returns the pointer to the name string of the memory pool identified by parameter \a
 138 mp_id or \token{NULL} in case of an error.
 139
 140 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 141 */
 142
 143 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 144 /**
 145 \fn void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout)
 146 \details
 147 The blocking function \b osMemoryPoolAlloc allocates the memory pool parameter \a mp_id and returns a pointer to the address
 148 of the allocated memory or \token{0} in case of an error.
 149
 150 The parameter \a timeout specifies how long the system waits to allocate the memory. While the system waits, the thread
 151 that is calling this function is put into the \ref ThreadStates "BLOCKED" state. The thread will become \ref ThreadStates "READY"
 152 as soon as at least one block of memory gets available.
 153
 154 The parameter \ref CMSIS_RTOS_TimeOutValue "timeout" can have the following values:
 155  - when \a timeout is \token{0}, the function returns instantly (i.e. try semantics).
 156  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the memory is allocated (i.e. wait semantics).
 157  - all other values specify a time in kernel ticks for a timeout (i.e. timed-wait semantics).
 158
 159 The result is the pointer to the memory block allocated, or NULL if no memory is available.
 160
 161 \note It is in the responsibility of the user to respect the block size, i.e. not access memory beyond the blocks limit.
 162
 163 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
 164 \token{0}.
 165
 166 \b Code \b Example
 167
 168 Refer to \ref osMemoryPoolNew.
 169 */
 170
 171 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 172 /**
 173 \fn osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block)
 174 \details
 175 The function \b osMemoryPoolFree frees the memory pool block specified by the parameter \a block in the memory pool object
 176 specified by the parameter \a mp_id. The memory block is put back to the list of available blocks.
 177
 178 If another thread is waiting for memory to become available the thread is put to \ref ThreadStates "READY" state.
 179
 180 Possible \ref osStatus_t return values:
 181  - \em osOK: the memory has been freed.
 182  - \em osErrorParameter: parameter \a mp_id is \token{NULL} or invalid, \a block points to invalid memory.
 183  - \em osErrorResource: the memory pool specified by parameter \a mp_id is in an invalid memory pool state.
 184
 185 \note \b osMemoryPoolFree may perform certain checks on the \a block pointer given. But using \b osMemoryPoolFree
 186 with a pointer other than one received from \ref osMemoryPoolAlloc has \b UNPREDICTED behaviour.
 187
 188 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 189
 190 \b Code \b Example
 191
 192 Refer to \ref osMemoryPoolNew.
 193 */
 194
 195 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 196 /**
 197 \fn uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id)
 198 \details
 199 The function \b osMemoryPoolGetCapacity returns the maximum number of memory blocks in the memory pool object specified by
 200 parameter \a mp_id or \token{0} in case of an error.
 201
 202 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 203 */
 204
 205 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 206 /**
 207 \fn uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id)
 208 \details
 209 The function \b osMemoryPoolGetBlockSize returns the memory block size in bytes in the memory pool object specified by
 210 parameter \a mp_id or \token{0} in case of an error.
 211
 212 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 213 */
 214
 215 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 216 /**
 217 \fn uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id)
 218 \details
 219 The function \b osMemoryPoolGetCount returns the number of memory blocks used in the memory pool object specified by
 220 parameter \a mp_id or \token{0} in case of an error.
 221
 222 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 223 */
 224
 225 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 226 /**
 227 \fn uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id)
 228 \details
 229 The function \b osMemoryPoolGetSpace returns the number of memory blocks available in the memory pool object specified by
 230 parameter \a mp_id or \token{0} in case of an error.
 231
 232 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 233 */
 234
 235 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 236 /**
 237 \fn osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id)
 238 \details
 239 The function \b osMemoryPoolDelete deletes a memory pool object specified by parameter \a mp_id. It releases internal
 240 memory obtained for memory pool handling. After this call, the \a mp_id is no longer valid and cannot be used. The
 241 memory pool may be created again using the function \ref osMemoryPoolNew.
 242
 243 Possible \ref osStatus_t return values:
 244  - \em osOK: the memory pool object has been deleted.
 245  - \em osErrorParameter: parameter \a mp_id is \token{NULL} or invalid.
 246  - \em osErrorResource: the memory pool specified by parameter \a mp_id is in an invalid memory pool state.
 247  - \em osErrorISR: \b osMemoryPoolDelete cannot be called from interrupt service routines.
 248
 249 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 250 */
 251 /// @}
 252
 253 // these struct members must stay outside the group to avoid double entries in documentation
 254 /**
 255 \var osMemoryPoolAttr_t::attr_bits
 256 \details
 257 Reserved for future use (set to '0').\n
 258 Default: \token{0}.
 259
 260 \var osMemoryPoolAttr_t::cb_mem
 261 \details
 262 Pointer to a memory location for the memory pool control block object. This can optionally be used for custom memory management systems.\n
 263 Default: \token{NULL} (uses kernel memory management).
 264
 265 \var osMemoryPoolAttr_t::cb_size
 266 \details
 267 The size of the memory block passed with \ref cb_mem. Must be the size of a memory pool control block object or larger.
 268
 269 \var osMemoryPoolAttr_t::name
 270 \details
 271 Pointer to a string with a human readable name of the memory pool object.\n
 272 Default: \token{NULL}.
 273
 274 \var osMemoryPoolAttr_t::mp_mem
 275 \details
 276 Pointer to a memory location for the data of the memory pool object.\n
 277 Default: \token{NULL}.
 278
 279 \var osMemoryPoolAttr_t::mp_size
 280 \details
 281 The size of the memory passed with \ref mp_mem.
 282 */