Time services provided by the OS

---

Detailed Description

This set of API calls allows time related functions.

TiROS operates with high-resolution time. Sleep and timeouts are specified in absolute or relative time (using the O_RELATIVE_TIME option). Time is represented using the trtime_t structure. This structure consists of two elements:

1. A subsecond unit (could be milli-seconds, nano-seconds,etc.)
2. A supersecond unit ( could be a unit of 1 second, 10 secs, 1 minute etc.

This choice of time is kept deliberately vague, since the application is an embedded system, where these functions have to be fast, take advantage of the hardware, and cannot waste cycles converting time units from the hardware representation to a standard form. The actual representation of the time structure is specified by the platform specific port.

Functions
void	os_time_get (trtime_t *curr_time)
int8_t	os_time_set (const trtime_t *new_time)
int8_t	os_wake_at (const trtime_t *wake_time, uint8_t options)

---

Function Documentation

void os_time_get

(

trtime_t *

curr_time

)

Get the current time.

Calling Context:

1. From within a task.
2. From an ISR.

Parameters:

[out]

curr_time

Pointer to structure where the time should be stored.

int8_t os_time_set

(

const trtime_t *

new_time

)

Set the current time.

This sets the current time. This has to be used with care. This can affect tasks that have been sleeping or waiting for a lock. Such tasks will be woken up if the new time set is beyond their wakeup deadline. This system call may not be possible on some hardware ports.

Calling Context:

1. From within a task.
2. From an ISR.

To set the time before the os has started use the hal_time_set function directly, which is supplied by the hardware port.

Parameters:

new_time

Pointer to structure with the new time.

Returns:

{SUCCESS, ERR_FAILED}

int8_t os_wake_at	(	const trtime_t *	wake_time,
		uint8_t	options
	)

Wake the invoking task at a specific time.

The task can be woken up earlier by an explicit resume. The task is not allowed to sleep if it holds a mutex lock. This call is not allowed from an ISR.

Calling Context:

1. From within a task.
2. Call from ISR will result in an error.

Parameters:

[in]	wake_time	Time at which to be woken up.
	options	Default is absolute time. For relative time, set O_RELATIVE_TIME.

Returns:

{SUCCESS, ERR_RESUMED, ERR_WOULDBLOCK_MUTEX, ERR_WOULDBLOCK_ISR}

---