Kernel Time Management API#

1. OSTimeTickRateHzGet()

2. OSTimeDly()

3. OSTimeDlyHMSM()

4. OSTimeDlyResume()

5. OSTimeGet()

OSTimeTickRateHzGet()#

Description#

Gets kernel tick rate, in Hertz.

Files#

os.h/os_time.c

Prototype#

OS_RATE_HZ OSTimeTickRateHzGet (RTOS_ERR *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

Kernel tick rate, in Hertz.

OSTimeDly()#

Description#

Delays the execution of the currently running task until the specified number of system ticks expires. This directly equates to delaying the current task for some time to expire. No delay will result if the specified delay is 0. If the specified delay is greater than 0, this results in a context switch.

Files#

os.h/os_time.c

Prototype#

void  OSTimeDly (OS_TICK    dly,
                 OS_OPT     opt,
                 RTOS_ERR  *p_err)

Arguments#

dly

Value in 'clock ticks' that the task for which will either delay, the target matches the value of the tick counter (OSTickCtr). Note that setting this to 0 means that no delay will be applied to the task.

Depending on the option argument, the task will wake up when OSTickCtr reaches:

OS_OPT_TIME_DLY        OSTimeGet() + dly
OS_OPT_TIME_TIMEOUT    OSTimeGet() + dly
OS_OPT_TIME_PERIODIC   OSTCBCurPtr.TickCtrPrev + dly

opt

Specifies whether 'dly' represents absolute or relative time; default option is OS_OPT_TIME_DLY:

• OS_OPT_TIME_DLY Specifies a relative time from the current count tick retrieved with OSTimeGet().

• OS_OPT_TIME_TIMEOUT Same as OS_OPT_TIME_DLY.

• OS_OPT_TIME_PERIODIC Indicates that 'dly' specifies the periodic value that current tick count (retrieved with OSTimeGet()) must reach before the task will be resumed.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_ARG

• RTOS_ERR_OS_SCHED_LOCKED

Returned Value#

None.

Notes / Warnings#

None.

OSTimeDlyHMSM()#

Description#

Delay execution of the currently running task until some time expires. This call allows you to specify the delay time in HOURS, MINUTES, SECONDS, and MILLISECONDS instead of ticks.

Files#

os.h/os_time.c

Prototype#

void  OSTimeDlyHMSM (CPU_INT16U   hours,
                     CPU_INT16U   minutes,
                     CPU_INT16U   seconds,
                     CPU_INT32U   milli,
                     OS_OPT       opt,
                     RTOS_ERR    *p_err)

Arguments#

hours

Specifies the number of hours that the task will be delayed (max. is 999 if the tick rate is 1000 Hz or less otherwise, a higher value would overflow a 32-bit unsigned counter). (max. 99 if 'opt' is OS_OPT_TIME_HMSM_STRICT)

minutes

Specifies the number of minutes. (max. 59 if 'opt' is OS_OPT_TIME_HMSM_STRICT)

seconds

Specifies the number of seconds. (max. 59 if 'opt' is OS_OPT_TIME_HMSM_STRICT)

milli

Specifies the number of milliseconds. (max. 999 if 'opt' is OS_OPT_TIME_HMSM_STRICT)

opt

Specifies time delay bit-field options logically OR'd; default options marked with *** :

• *** OS_OPT_TIME_DLY Specifies a relative time from the current time returned by OSTimeGet().

• OS_OPT_TIME_TIMEOUT Same as OS_OPT_TIME_DLY.

• OS_OPT_TIME_PERIODIC Indicates that the delay specifies the periodic value that the current count tick (retrieved with OSTimeGet()) must reach before the task will be resumed.

• *** OS_OPT_TIME_HMSM_STRICT Strictly allows only

  • hours (0...99)

  • minutes (0...59)

  • seconds (0...59)

  • milliseconds (0...999)

• OS_OPT_TIME_HMSM_NON_STRICT Allows any value of

  • hours (0...999)

  • minutes (0...9999)

  • seconds (0...65535)

  • milliseconds (0...4294967295)

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_INVALID_ARG

• RTOS_ERR_OS_SCHED_LOCKED

Returned Value#

None.

Notes / Warnings#

1. The resolution of milliseconds depends on the tick rate. For example, you cannot do a 10 mS delay if the ticker interrupts every 100 mS. In this case, the delay would be set to 0. The actual delay is rounded to the nearest tick.

2. Although this function allows you to delay a task for many hours, it is not recommended to put a task to sleep for that long.

OSTimeDlyResume()#

Description#

Resumes a task that has been delayed through a call to either OSTimeDly() or OSTimeDlyHMSM(). Note that you cannot call this function to resume a task that is waiting for an event with timeout.

Files#

os.h/os_time.c

Prototype#

void  OSTimeDlyResume (OS_TCB    *p_tcb,
                       RTOS_ERR  *p_err)

Arguments#

p_tcb

Pointer to the TCB of the task to resume.

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

• RTOS_ERR_OS_TASK_SUSPENDED

• RTOS_ERR_INVALID_STATE

Returned Value#

None.

Notes / Warnings#

None.

OSTimeGet()#

Description#

Used by your application to obtain the current value of the counter to keep track of the number of clock ticks.

Files#

os.h/os_time.c

Prototype#

OS_TICK  OSTimeGet (RTOS_ERR  *p_err)

Arguments#

p_err

Pointer to the variable that will receive one of the following error code(s) from this function:

• RTOS_ERR_NONE

Returned Value#

The current tick count.

Notes / Warnings#

None.