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 \b Shared \b memory is one of the basic models to exchange information between threads. Using memory pools for exchanging
  12 data, you can share more complex objects between threads if compared to a \ref CMSIS_RTOS_Message. Memory pool management
  13 functions are used to define and manage such fixed-sized memory pools.
  14
  15 \note The functions \ref osMemoryPoolAlloc, \ref osMemoryPoolFree, \ref osMemoryPoolGetCapacity,
  16 \ref osMemoryPoolGetBlockSize, \ref osMemoryPoolGetCount, \ref osMemoryPoolGetSpace can be called from
  17 \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  18 \note Refer to \ref memPoolConfig for RTX5 configuration options.
  19
  20 @{
  21 */
  22
  23 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  24 /**
  25 \typedef osMemoryPoolId_t
  26 \details
  27 */
  28
  29 /**
  30 \struct osMemoryPoolAttr_t
  31 \details
  32 */
  33
  34 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  35 /**
  36 \fn osMemoryPoolId_t osMemoryPoolNew (uint32_t block_count, uint32_t block_size, const osMemoryPoolAttr_t *attr)
  37 \details
  38 The function \b osMemoryPoolNew creates and initializes a memory pool object and returns the pointer to the memory pool
  39 object identifier or \token{NULL} in case of an error.
  40
  41 The parameter \a block_count specifies the maximum number of memory blocks in the pool.
  42
  43 The parameter \a block_size sets memory size in bytes.
  44
  45 The parameter \a attr specifies additional memory pool attributes. Default attributes will be used if set to \token{NULL}.
  46
  47 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  48 */
  49
  50 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  51 /**
  52 \fn const char *osMemoryPoolGetName (osMemoryPoolId_t mp_id)
  53 \details
  54 The function \b osMemoryPoolGetName returns the pointer to the name string of the memory pool identified by parameter \a
  55 mp_id or \token{NULL} in case of an error.
  56
  57 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  58 */
  59
  60 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  61 /**
  62 \fn void *osMemoryPoolAlloc (osMemoryPoolId_t mp_id, uint32_t timeout)
  63 \details
  64 The blocking function \b osMemoryPoolAlloc allocates the memory pool parameter \a mp_id and returns a pointer to the address
  65 of the allocated memory or \token{0} in case of an error.
  66
  67 The parameter \a timeout specifies how long the system waits to allocate the memory. While the system waits, the thread
  68 that is calling this function is put into the \b BLOCKED state. The parameter \ref CMSIS_RTOS_TimeOutValue "timeout" can have
  69 the following values:
  70  - when \a timeout is \token{0}, the function returns instantly.
  71  - when \a timeout is set to \b osWaitForever the function will wait for an infinite time until the memory is allocated.
  72  - all other values specify a time in kernel ticks for a timeout.
  73
  74 \note May be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines" if the parameter \a timeout is set to
  75 \token{0}.
  76 */
  77
  78 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  79 /**
  80 \fn osStatus_t osMemoryPoolFree (osMemoryPoolId_t mp_id, void *block)
  81 \details
  82 The function \b osMemoryPoolFree frees the memory pool block specified by the parameter \a block in the memory pool object
  83 specified by the parameter \a mp_id.
  84
  85 Possible \ref osStatus_t return values:
  86  - \em osOK: the memory has been freed.
  87  - \em osErrorParameter: parameter \a mp_id is \token{NULL} or invalid.
  88  - \em osErrorResource: the memory pool specified by parameter \a mp_id is in an invalid memory pool state.
  89
  90 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  91 */
  92
  93 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  94 /**
  95 \fn uint32_t osMemoryPoolGetCapacity (osMemoryPoolId_t mp_id)
  96 \details
  97 The function \b osMemoryPoolGetCapacity returns the maximum number of memory blocks in the memory pool object specified by
  98 parameter \a mp_id or \token{0} in case of an error.
  99
 100 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 101 */
 102
 103 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 104 /**
 105 \fn uint32_t osMemoryPoolGetBlockSize (osMemoryPoolId_t mp_id)
 106 \details
 107 The function \b osMemoryPoolGetBlockSize returns the memory block size in bytes in the memory pool object specified by
 108 parameter \a mp_id or \token{0} in case of an error.
 109
 110 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 111 */
 112
 113 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 114 /**
 115 \fn uint32_t osMemoryPoolGetCount (osMemoryPoolId_t mp_id)
 116 \details
 117 The function \b osMemoryPoolGetCount returns the number of memory blocks used in the memory pool object specified by
 118 parameter \a mp_id or \token{0} in case of an error.
 119
 120 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 121 */
 122
 123 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 124 /**
 125 \fn uint32_t osMemoryPoolGetSpace (osMemoryPoolId_t mp_id)
 126 \details
 127 The function \b osMemoryPoolGetSpace returns the number of memory blocks available in the memory pool object specified by
 128 parameter \a mp_id or \token{0} in case of an error.
 129
 130 \note This function may be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 131 */
 132
 133 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 134 /**
 135 \fn osStatus_t osMemoryPoolDelete (osMemoryPoolId_t mp_id)
 136 \details
 137 The function \b osMemoryPoolDelete deletes a memory pool object specified by parameter \a mp_id. It releases internal
 138 memory obtained for memory pool handling. After this call, the \a mp_id is no longer valid and cannot be used. The
 139 memory pool may be created again using the function \ref osMemoryPoolNew.
 140
 141 Possible \ref osStatus_t return values:
 142  - \em osOK: the memory pool object has been deleted.
 143  - \em osErrorParameter: parameter \a mp_id is \token{NULL} or invalid.
 144  - \em osErrorResource: the memory pool specified by parameter \a mp_id is in an invalid memory pool state.
 145  - \em osErrorISR: \b osMemoryPoolDelete cannot be called from interrupt service routines.
 146
 147 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
 148 */
 149 /// @}