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

   1
   2 /**
   3 \addtogroup rtx5_specific RTX v5 Specific API
   4 \brief RTX v5 implementation specific definitions and functions defined in <b>%rtx_os.h</b>.
   5 \details
   6
   7 The RTX5 kernel can be customized for different application requirements:
   8
   9 - The function \ref osRtxIdleThread implements the idle thread and allows set the system into sleep modes for \ref lowPower or
  10   \ref TickLess for ultra-low power operation.
  11
  12 - The function \ref osRtxErrorNotify may be extended to handle system runtime errors.
  13
  14 RTX5 interfaces to the <a href="https://www.keil.com/pack/doc/compiler/EventRecorder/html/index.html" target="_blank"><b>Event Recorder</b></a>
  15 and provides event information that helps to analyze the operation. Refer to \ref rtx_evr for more information.
  16
  17
  18 @{
  19 */
  20
  21 /**
  22 \defgroup rtx5_specific_defines Macros
  23 \brief RTX5 macros
  24 \details
  25 @{
  26 */
  27
  28 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  29 /**
  30 \def osRtxThreadCbSize
  31 \brief Thread Control Block size
  32 \details
  33 This macro exposes the minimum amount of memory needed for an RTX5 Thread Control Block,
  34 see osThreadAttr_t::cb_mem and \ref osThreadAttr_t::cb_size.
  35
  36 Example:
  37 \code
  38 // Used-defined memory for thread control block
  39 static uint32_t thread_cb[osRtxThreadCbSize/4U];
  40 \endcode
  41 */
  42
  43 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  44 /**
  45 \def osRtxTimerCbSize
  46 \brief Timer Control Block size
  47 \details
  48 This macro exposes the minimum amount of memory needed for an RTX5 Timer Control Block,
  49 see osTimerAttr_t::cb_mem and \ref osTimerAttr_t::cb_size.
  50
  51 Example:
  52 \code
  53 // Used-defined memory for timer control block
  54 static uint32_t timer_cb[osRtxTimerCbSize/4U];
  55 \endcode
  56 */
  57
  58 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  59 /**
  60 \def osRtxEventFlagsCbSize
  61 \brief Event Flags Control Block size
  62 \details
  63 This macro exposes the minimum amount of memory needed for an RTX5 Event Flags Control Block,
  64 see osEventFlagsAttr_t::cb_mem and \ref osEventFlagsAttr_t::cb_size.
  65
  66 Example:
  67 \code
  68 // Used-defined memory for event flags control block
  69 static uint32_t evflags_cb[osRtxEventFlagsCbSize/4U];
  70 \endcode
  71 */
  72
  73 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  74 /**
  75 \def osRtxMutexCbSize
  76 \brief Mutex Control Block size
  77 \details
  78 This macro exposes the minimum amount of memory needed for an RTX5 Mutex Control Block,
  79 see osMutexAttr_t::cb_mem and \ref osMutexAttr_t::cb_size.
  80
  81 Example:
  82 \code
  83 // Used-defined memory for mutex control block
  84 static uint32_t mutex_cb[osRtxMutexCbSize/4U];
  85 \endcode
  86 */
  87
  88 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  89 /**
  90 \def osRtxSemaphoreCbSize
  91 \brief Semaphore Control Block size
  92 \details
  93 This macro exposes the minimum amount of memory needed for an RTX5 Semaphore Control Block,
  94 see osSemaphoreAttr_t::cb_mem and osSemaphoreAttr_t::cb_size.
  95
  96 Example:
  97 \code
  98 // Used-defined memory for semaphore control block
  99 static uint32_t sema_cb[osRtxSemaphoreCbSize/4U];
 100 \endcode
 101 */
 102
 103 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 104 /**
 105 \def osRtxMemoryPoolCbSize
 106 \brief Memory Pool Control Block size
 107 \details
 108 This macro exposes the minimum amount of memory needed for an RTX5 Memory Pool Control Block,
 109 see osMemoryPoolAttr_t::cb_mem and osMemoryPoolAttr_t::cb_size.
 110
 111 Example:
 112 \code
 113 // Used-defined memory for memory pool control block
 114 static uint32_t mempool_cb[osRtxMemoryPoolCbSize/4U];
 115 \endcode
 116 */
 117
 118 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 119 /**
 120 \def osRtxMessageQueueCbSize
 121 \brief Message Queue Control Block size
 122 \details
 123 This macro exposes the minimum amount of memory needed for an RTX5 Message Queue Control Block,
 124 see osMessageQueueAttr_t::cb_mem and osMessageQueueAttr_t::cb_size.
 125
 126 Example:
 127 \code
 128 // Used-defined memory for message queue control block
 129 static uint32_t msgqueue_cb[osRtxMessageQueueCbSize/4U];
 130 \endcode
 131 */
 132
 133 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 134 /**
 135 \def osRtxMemoryPoolMemSize
 136 \brief Memory Pool Memory size
 137 \details
 138 This macro exposes the minimum amount of memory needed for an RTX5 Memory Pool Memory,
 139 see osMemoryPoolAttr_t::mp_mem and osMemoryPoolAttr_t::mp_size.
 140
 141 Example:
 142 \code
 143 // Maximum number of objects
 144 #define OBJ_COUNT 8U
 145
 146 // Object type
 147 typedef struct {
 148    uint32_t value1;
 149    uint8_t  value2;
 150 } object_t;
 151
 152 // Used-defined memory for memory pool memory
 153 static uint32_t mempool_mem[osRtxMemoryPoolMemSize(OBJ_COUNT, sizeof(object_t))/4U];
 154 \endcode
 155 */
 156
 157 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 158 /**
 159 \def osRtxMessageQueueMemSize
 160 \brief Message Queue Memory size
 161 \details
 162 This macro exposes the minimum amount of memory needed for an RTX5 Message Queue Memory,
 163 see osMessageQueueAttr_t::mq_mem and osMessageQueueAttr_t::mq_size.
 164
 165 Example:
 166 \code
 167 // Maximum number of messages
 168 #define MSG_COUNT 16U
 169
 170 // Message data type
 171 typedef struct {
 172    uint32_t value1;
 173    uint8_t  value2;
 174 } msg_item_t;
 175
 176 // Used-defined memory for message queue
 177 static uint32_t mq_mem[osRtxMessageQueueMemSize(MSG_COUNT, sizeof(msg_item_t))/4U];
 178 \endcode
 179 */
 180
 181 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 182 /**
 183 \def osRtxErrorStackUnderflow
 184 \brief Stack overflow, i.e. stack pointer below its lower memory limit for descending stacks.
 185 \details
 186 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects a thread stack overflow.
 187 The object_id announced along this error can be used to identify the affected thread.
 188
 189 \ref threadConfig_watermark used together with larger stack sizes can help to figure out actual
 190 memory requirements for threads.
 191
 192 \attention Whenever this error identifier is signaled memory corruption has already happened.
 193 */
 194
 195 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 196 /**
 197 \def osRtxErrorISRQueueOverflow
 198 \brief ISR Queue overflow detected when inserting object.
 199 \details
 200 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects an overflow of the
 201 interrupt post processing message queue. The object_id can be used to identify the affected
 202 object.
 203
 204 \attention Whenever this error identifier is signaled the system state is already inconsistent.
 205 */
 206
 207 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 208 /**
 209 \def osRtxErrorTimerQueueOverflow
 210 \brief User Timer Callback Queue overflow detected for timer.
 211 \details
 212 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects an overflow of the
 213 timer callback queue. The object_id can be used to identify the affected timer.
 214
 215 \attention Whenever this error identifier is signaled a timer callback is already lost.
 216 */
 217
 218 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 219 /**
 220 \def osRtxErrorClibSpace
 221 \brief Standard C/C++ library libspace not available.
 222 \details
 223 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects usage of libspace
 224 but not enough memory was reserved using \c OS_THREAD_LIBSPACE_NUM.
 225 */
 226
 227 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 228 /**
 229 \def osRtxErrorClibMutex
 230 \brief Standard C/C++ library mutex initialization failed.
 231 \details
 232 This error identifier is used with \ref osRtxErrorNotify when RTX5 fails to create mutexes needed
 233 to lock global C/C++ library resources.
 234 */
 235
 236 /**
 237 @}
 238 */
 239
 240 /**
 241 \defgroup rtx5_specific_functions Functions
 242 \brief RTX5 functions
 243 \details
 244 @{
 245 */
 246
 247 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 248 /**
 249 \fn uint32_t osRtxErrorNotify (uint32_t code, void *object_id);
 250 \param[in] code The code to identify the error condition.
 251 \param[in] object_id A reference to any RTX object to identify the object that caused the issue, can be \token{NULL}.
 252 \details
 253 Some system error conditions can be detected during runtime. If the RTX kernel detects a runtime error, it calls the runtime
 254 error function \b osRtxErrorNotify for an object specified by parameter \a object_id.
 255
 256 The parameter \a code passes the actual error code to this function:
 257 | Error Code                        | Description                                                                       |
 258 |-----------------------------------|-----------------------------------------------------------------------------------|
 259 | \ref osRtxErrorStackUnderflow     | Stack overflow detected for thread (thread_id=object_id)                          |
 260 | \ref osRtxErrorISRQueueOverflow   | ISR Queue overflow detected when inserting object (object_id)                     |
 261 | \ref osRtxErrorTimerQueueOverflow | User Timer Callback Queue overflow detected for timer (timer_id=object_id)        |
 262 | \ref osRtxErrorClibSpace          | Standard C/C++ library libspace not available: increase \c OS_THREAD_LIBSPACE_NUM |
 263 | \ref osRtxErrorClibMutex          | Standard C/C++ library mutex initialization failed                                |
 264
 265 The function \b osRtxErrorNotify must contain an infinite loop to prevent further program execution. You can use an emulator
 266 to step over the infinite loop and trace into the code introducing a runtime error. For the overflow errors this means you
 267 need to increase the size of the object causing an overflow.
 268
 269 <b>Code Example</b>
 270 \code
 271 #include "rtx_os.h"
 272
 273 uint32_t osRtxErrorNotify (uint32_t code, void *object_id) {
 274   (void)object_id;
 275
 276   switch (code) {
 277     case osRtxErrorStackUnderflow:
 278       // Stack overflow detected for thread (thread_id=object_id)
 279       break;
 280     case osRtxErrorISRQueueOverflow:
 281       // ISR Queue overflow detected when inserting object (object_id)
 282       break;
 283     case osRtxErrorTimerQueueOverflow:
 284       // User Timer Callback Queue overflow detected for timer (timer_id=object_id)
 285       break;
 286     case osRtxErrorClibSpace:
 287       // Standard C/C++ library libspace not available: increase OS_THREAD_LIBSPACE_NUM
 288       break;
 289     case osRtxErrorClibMutex:
 290       // Standard C/C++ library mutex initialization failed
 291       break;
 292     default:
 293       break;
 294   }
 295   for (;;) {}
 296 //return 0U;
 297 }
 298 \endcode
 299 */
 300
 301 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 302 /**
 303 \fn void osRtxIdleThread (void *argument);
 304 \param[in] argument Unused parameter, always set to \token{NULL}.
 305 \details
 306 The function \b osRtxIdleThread is executed by the RTX kernel when no other threads are ready to run.
 307
 308 By default, this thread is an empty end-less loop that does nothing. It only waits until another task
 309 becomes ready to run. You may change the code of the \b osRtxIdleThread function to put the CPU into
 310 a power-saving or idle mode, see \ref TickLess.
 311
 312 The default stack size for this thread is defined in the file RTX_Config.h. Refer to \ref threadConfig.
 313
 314 \attention
 315 The idle thread should never be blocked nor terminated!
 316 <b>Do not</b> call
 317 <ul>
 318   <li>blocking functions,</li>
 319   <li>\ref osThreadTerminate, or </li>
 320   <li>\ref osThreadExit</li>
 321 </ul>
 322 and <b>do not</b> return from this function when providing a user defined implementation.
 323
 324 <b>Code Example</b>
 325 \code
 326 #include "rtx_os.h"
 327
 328 __NO_RETURN void osRtxIdleThread (void *argument) {
 329   (void)argument;
 330
 331   for (;;) {}
 332 }
 333 \endcode
 334 */
 335
 336 /**
 337 @}
 338 */
 339
 340 /// @}