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

   1
   2 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
   3 //  ==== Generic Wait Functions ====
   4 /**
   5 \addtogroup CMSIS_RTOS_Wait Generic Wait Functions
   6 \ingroup CMSIS_RTOS
   7 \brief Wait for a certain period of time.
   8 \details
   9 The generic wait functions provide means for a time delay.
  10
  11 \note Generic wait functions cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  12 @{
  13 */
  14
  15 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  16 /**
  17 \fn osStatus_t osDelay (uint32_t ticks)
  18 \details
  19 The function \b osDelay waits for a time period specified in kernel \a ticks. For a value of \token{1} the system waits
  20 until the next timer tick occurs. The actual time delay may be up to one timer tick less than specified, i.e. calling
  21 \c osDelay(1) right before the next system tick occurs the thread is rescheduled immediately.
  22
  23 The delayed thread is put into the \ref ThreadStates "BLOCKED" state and a context switch occurs immediately. The thread
  24 is automatically put back to the \ref ThreadStates "READY" state after the given amount of ticks has elapsed. If the thread
  25 will have the highest priority in \ref ThreadStates "READY" state it will be scheduled immediately.
  26
  27 Possible \ref osStatus_t return values:
  28  - \em osOK: the time delay is executed.
  29  - \em osErrorParameter: the time cannot be handled (zero value).
  30  - \em osErrorISR: \ref osDelay cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  31  - \em osError: \ref osDelay cannot be executed (kernel not running or no \ref ThreadStates "READY" thread exists).
  32
  33 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  34
  35 <b>Code Example</b>
  36 \code
  37 #include "cmsis_os2.h"
  38
  39 void Thread_1 (void *arg) {             // Thread function
  40   osStatus_t status;                    // capture the return status
  41   uint32_t   delayTime;                 // delay time in milliseconds
  42
  43   delayTime = 1000U;                    // delay 1 second
  44   status = osDelay(delayTime);          // suspend thread execution
  45 }
  46 \endcode
  47 */
  48
  49 /*=======0=========1=========2=========3=========4=========5=========6=========7=========8=========9=========0=========1====*/
  50 /**
  51 \fn osStatus_t osDelayUntil (uint32_t ticks)
  52 \details
  53 The function \b osDelayUntil waits until an absolute time (specified in kernel \a ticks) is reached.
  54
  55 The corner case when the kernel tick counter overflows is handled by \b osDelayUntil. Thus it is absolutely legal
  56 to provide a value which is lower than the current tick value, i.e. returned by \ref osKernelGetTickCount. Typically
  57 as a user you do not have to take care about the overflow. The only limitation you have to have in mind is that the
  58 maximum delay is limited to (2<sup>31</sup>)-1 ticks.
  59
  60 The delayed thread is put into the \ref ThreadStates "BLOCKED" state and a context switch occurs immediately. The thread
  61 is automatically put back to the \ref ThreadStates "READY" state when the given time is reached. If the thread will
  62 have the highest priority in \ref ThreadStates "READY" state it will be scheduled immediately.
  63
  64 Possible \ref osStatus_t return values:
  65  - \em osOK: the time delay is executed.
  66  - \em osErrorParameter: the time cannot be handled (out of bounds).
  67  - \em osErrorISR: \ref osDelayUntil cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  68  - \em osError: \ref osDelayUntil cannot be executed (kernel not running or no \ref ThreadStates "READY" thread exists).
  69
  70 \note This function \b cannot be called from \ref CMSIS_RTOS_ISR_Calls "Interrupt Service Routines".
  71
  72 <b>Code Example</b>
  73 \code
  74 #include "cmsis_os2.h"
  75
  76 void Thread_1 (void *arg) {             // Thread function
  77   uint32_t tick;
  78
  79   tick = osKernelGetTickCount();        // retrieve the number of system ticks
  80   for (;;) {
  81     tick += 1000U;                      // delay 1000 ticks periodically
  82     osDelayUntil(tick);
  83     // ...
  84   }
  85 }
  86 \endcode
  87 */
  88 /// @}