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
 185 */
 186
 187 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 188 /**
 189 \def osRtxErrorStackOverflow
 190 \brief Stack overflow, i.e. stack pointer below its lower memory limit for descending stacks.
 191 \details
 192 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects a thread stack overflow.
 193 The object_id announced along this error can be used to identify the affected thread.
 194
 195 \ref threadConfig_watermark used together with larger stack sizes can help to figure out actual
 196 memory requirements for threads.
 197
 198 \attention Whenever this error identifier is signaled memory corruption has already happened.
 199 */
 200
 201 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 202 /**
 203 \def osRtxErrorISRQueueOverflow
 204 \brief ISR Queue overflow detected when inserting object.
 205 \details
 206 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects an overflow of the
 207 interrupt post processing message queue. The object_id can be used to identify the affected
 208 object.
 209
 210 \attention Whenever this error identifier is signaled the system state is already inconsistent.
 211 */
 212
 213 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 214 /**
 215 \def osRtxErrorTimerQueueOverflow
 216 \brief User Timer Callback Queue overflow detected for timer.
 217 \details
 218 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects an overflow of the
 219 timer callback queue. The object_id can be used to identify the affected timer.
 220
 221 \attention Whenever this error identifier is signaled a timer callback is already lost.
 222 */
 223
 224 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 225 /**
 226 \def osRtxErrorClibSpace
 227 \brief Standard C/C++ library libspace not available.
 228 \details
 229 This error identifier is used with \ref osRtxErrorNotify when RTX5 detects usage of libspace
 230 but not enough memory was reserved using \c OS_THREAD_LIBSPACE_NUM.
 231 */
 232
 233 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 234 /**
 235 \def osRtxErrorClibMutex
 236 \brief Standard C/C++ library mutex initialization failed.
 237 \details
 238 This error identifier is used with \ref osRtxErrorNotify when RTX5 fails to create mutexes needed
 239 to lock global C/C++ library resources.
 240 */
 241
 242 /**
 243 @}
 244 */
 245
 246 /**
 247 \defgroup rtx5_specific_functions Functions
 248 \brief RTX5 functions
 249 \details
 250 @{
 251 */
 252
 253 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 254 /**
 255 \fn uint32_t osRtxErrorNotify (uint32_t code, void *object_id);
 256 \param[in] code The code to identify the error condition.
 257 \param[in] object_id A reference to any RTX object to identify the object that caused the issue, can be \token{NULL}.
 258 \details
 259 Some system error conditions can be detected during runtime. If the RTX kernel detects a runtime error, it calls the runtime
 260 error function \b osRtxErrorNotify for an object specified by parameter \a object_id.
 261
 262 The parameter \a code passes the actual error code to this function:
 263 | Error Code                        | Description                                                                       |
 264 |-----------------------------------|-----------------------------------------------------------------------------------|
 265 | \ref osRtxErrorStackOverflow      | Stack overflow detected for thread (thread_id=object_id)                          |
 266 | \ref osRtxErrorISRQueueOverflow   | ISR Queue overflow detected when inserting object (object_id)                     |
 267 | \ref osRtxErrorTimerQueueOverflow | User Timer Callback Queue overflow detected for timer (timer_id=object_id)        |
 268 | \ref osRtxErrorClibSpace          | Standard C/C++ library libspace not available: increase \c OS_THREAD_LIBSPACE_NUM |
 269 | \ref osRtxErrorClibMutex          | Standard C/C++ library mutex initialization failed                                |
 270
 271 The function \b osRtxErrorNotify must contain an infinite loop to prevent further program execution. You can use an emulator
 272 to step over the infinite loop and trace into the code introducing a runtime error. For the overflow errors this means you
 273 need to increase the size of the object causing an overflow.
 274
 275 <b>Code Example</b>
 276 \code
 277 #include "rtx_os.h"
 278
 279 uint32_t osRtxErrorNotify (uint32_t code, void *object_id) {
 280   (void)object_id;
 281
 282   switch (code) {
 283     case osRtxErrorStackOverflow:
 284       // Stack overflow detected for thread (thread_id=object_id)
 285       break;
 286     case osRtxErrorISRQueueOverflow:
 287       // ISR Queue overflow detected when inserting object (object_id)
 288       break;
 289     case osRtxErrorTimerQueueOverflow:
 290       // User Timer Callback Queue overflow detected for timer (timer_id=object_id)
 291       break;
 292     case osRtxErrorClibSpace:
 293       // Standard C/C++ library libspace not available: increase OS_THREAD_LIBSPACE_NUM
 294       break;
 295     case osRtxErrorClibMutex:
 296       // Standard C/C++ library mutex initialization failed
 297       break;
 298     default:
 299       break;
 300   }
 301   for (;;) {}
 302 //return 0U;
 303 }
 304 \endcode
 305 */
 306
 307 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
 308 /**
 309 \fn void osRtxIdleThread (void *argument);
 310 \param[in] argument Unused parameter, always set to \token{NULL}.
 311 \details
 312 The function \b osRtxIdleThread is executed by the RTX kernel when no other threads are ready to run.
 313
 314 By default, this thread is an empty end-less loop that does nothing. It only waits until another task
 315 becomes ready to run. You may change the code of the \b osRtxIdleThread function to put the CPU into
 316 a power-saving or idle mode, see \ref TickLess.
 317
 318 The default stack size for this thread is defined in the file RTX_Config.h. Refer to \ref threadConfig.
 319
 320 \attention
 321 The idle thread should never be blocked nor terminated!
 322 <b>Do not</b> call
 323 <ul>
 324   <li>blocking functions,</li>
 325   <li>\ref osThreadTerminate, or </li>
 326   <li>\ref osThreadExit</li>
 327 </ul>
 328 and <b>do not</b> return from this function when providing a user defined implementation.
 329
 330 <b>Code Example</b>
 331 \code
 332 #include "rtx_os.h"
 333
 334 __NO_RETURN void osRtxIdleThread (void *argument) {
 335   (void)argument;
 336
 337   for (;;) {}
 338 }
 339 \endcode
 340 */
 341
 342 /**
 343 @}
 344 */
 345
 346 /// @}