Clocks

C API clocks definitions. More...

Classes
struct	os_clock_s
	Clock object storage. More...

Typedefs
typedef struct os_clock_s	os_clock_t
	Clock object storage.

Clock Functions
const char *	os_clock_get_name (os_clock_t *clock)
	Get the clock name.
os_clock_timestamp_t	os_clock_now (os_clock_t *clock)
	Tell the current time, possibly adjusted for epoch.
os_clock_timestamp_t	os_clock_steady_now (os_clock_t *clock)
	Tell the current time since startup.
os_result_t	os_clock_sleep_for (os_clock_t *clock, os_clock_duration_t duration)
	Sleep for a relative duration.
os_result_t	os_clock_sleep_until (os_clock_t *clock, os_clock_timestamp_t timestamp)
	Sleep until an absolute timestamp.
os_result_t	os_clock_wait_for (os_clock_t *clock, os_clock_duration_t timeout)
	Timed wait for an event.
os_clock_offset_t	os_clock_get_offset (os_clock_t *clock)
	Get adjustment offset.
os_clock_offset_t	os_clock_set_offset (os_clock_t *clock, os_clock_offset_t offset)
	Set adjustment offset.
os_clock_t *	os_clock_get_sysclock (void)
	Get sysclock (the system clock).
os_clock_t *	os_clock_get_rtclock (void)
	Get rtclock (the real-time clock).
os_clock_t *	os_clock_get_hrclock (void)
	Get hrclock (the high resolution clock).
os_clock_timestamp_t	os_sysclock_now (void)
	Tell the current time since startup.
os_result_t	os_sysclock_sleep_for (os_clock_duration_t duration)
	Sleep for a relative duration.
os_result_t	os_sysclock_sleep_until (os_clock_timestamp_t timestamp)
	Sleep until an absolute timestamp.
os_result_t	os_sysclock_wait_for (os_clock_duration_t timeout)
	Timed wait for an event.
os_clock_duration_t	os_sysclock_ticks_cast (uint32_t microsec)
	Convert microseconds to ticks.
os_clock_duration_t	os_sysclock_ticks_cast_long (uint64_t microsec)
	Convert microseconds to ticks.

Clock handlers
void	os_systick_handler (void)
	SysTick interrupt handler.
void	os_rtc_handler (void)
	RTC interrupt handler.

Detailed Description

For the complete definition, see

RTOS C++ API

Examples

int
os_main (int argc, char* argv[])
{
    {
      os_sysclock_sleep_for (2);
 
      os_clock_timestamp_t ts;
      // Return number of ticks since epoch, or, if epoch not set, from startup.
      ts = os_sysclock_now ();
 
      os_sysclock_sleep_until (ts + 2);
 
      // Return the number of ticks since startup.
      ts = os_sysclock_steady_now ();
 
      // An event may resume the thread before the timeout expire.
      os_sysclock_wait_for (2);
    }
}

Typedef Documentation

os_clock_t

typedef struct os_clock_s os_clock_t

This C structure has the same size as the C++ os::rtos::clock object.

The members of this structure are hidden and should not be used directly, but only through specific functions.

See also

os::rtos::clock

Function Documentation

os_clock_get_hrclock()

os_clock_t * os_clock_get_hrclock

(

void

)

Returns

The address of the clock_highres instance.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::hrclock

Definition at line 1396 of file os-c-wrapper.cpp.

{
  return (os_clock_t*)&hrclock;
}

References os::rtos::hrclock.

os_clock_get_name()

const char * os_clock_get_name

(

os_clock_t *

clock

)

Parameters

[in]

clock

Pointer to clock object instance.

Returns

Null terminated string.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::name()

Definition at line 1257 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (reinterpret_cast<rtos::clock&> (*clock)).name ();
}

os_clock_get_offset()

os_clock_offset_t os_clock_get_offset

(

os_clock_t *

clock

)

Parameters

[in]

clock

Pointer to clock object instance.

Returns

Integer value representing the offset to epoch.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::adjustable_clock::offset()

Definition at line 1340 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (os_clock_offset_t)(reinterpret_cast<rtos::clock&> (*clock))
      .offset ();
}

os_clock_get_rtclock()

os_clock_t * os_clock_get_rtclock

(

void

)

Returns

The address of the clock_rtc instance.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::rtclock

Definition at line 1384 of file os-c-wrapper.cpp.

{
  return (os_clock_t*)&rtclock;
}

References os::rtos::rtclock.

os_clock_get_sysclock()

os_clock_t * os_clock_get_sysclock

(

void

)

Returns

The address of the clock_systick instance.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::sysclock

Definition at line 1372 of file os-c-wrapper.cpp.

{
  return (os_clock_t*)&sysclock;
}

References os::rtos::sysclock.

os_clock_now()

os_clock_timestamp_t os_clock_now

(

os_clock_t *

clock

)

Parameters

[in]

clock

Pointer to clock object instance.

Returns

The clock current timestamp (time units from startup plus the epoch offset).

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::now()

Definition at line 1270 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (os_clock_timestamp_t)(reinterpret_cast<rtos::clock&> (*clock))
      .now ();
}

os_clock_set_offset()

os_clock_offset_t os_clock_set_offset	(	os_clock_t *	clock,
		os_clock_offset_t	offset
	)

Parameters

[in]	clock	Pointer to clock object instance.
[in]	offset	Integer representing the offset to epoch (positive).

Returns

Integer value representing the previous offset to epoch.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::adjustable_clock::offset(os::rtos::clock::offset_t)

Definition at line 1357 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  assert (clock != nullptr);
  return (os_clock_offset_t)(reinterpret_cast<rtos::clock&> (*clock))
      .offset ((clock::offset_t)offset);
}

os_clock_sleep_for()

os_result_t os_clock_sleep_for	(	os_clock_t *	clock,
		os_clock_duration_t	duration
	)

Parameters

[in]	clock	Pointer to clock object instance.
[in]	duration	The number of clock units (ticks or seconds) to sleep.

Return values

ETIMEDOUT	The sleep lasted the entire duration.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINTR	The sleep was interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::sleep_for()

Definition at line 1298 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::clock&> (*clock))
      .sleep_for (duration);
}

os_clock_sleep_until()

os_result_t os_clock_sleep_until	(	os_clock_t *	clock,
		os_clock_timestamp_t	timestamp
	)

Parameters

[in]	clock	Pointer to clock object instance.
[in]	timestamp	The absolute moment in time, in clock units.

Return values

ETIMEDOUT	The sleep lasted the entire duration.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINTR	The sleep was interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::sleep_until()

Definition at line 1312 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::clock&> (*clock))
      .sleep_until (timestamp);
}

os_clock_steady_now()

os_clock_timestamp_t os_clock_steady_now

(

os_clock_t *

clock

)

Parameters

[in]

clock

Pointer to clock object instance.

Returns

The clock current timestamp (time units from startup).

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::steady_now()

Definition at line 1284 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (os_clock_timestamp_t)(reinterpret_cast<rtos::clock&> (*clock))
      .steady_now ();
}

os_clock_wait_for()

os_result_t os_clock_wait_for	(	os_clock_t *	clock,
		os_clock_duration_t	timeout
	)

Parameters

[in]	clock	Pointer to clock object instance.
[in]	timeout	The timeout in clock units.

Return values

os_ok	An event occurred before the timeout.
ETIMEDOUT	The wait lasted the entire duration.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINTR	The sleep was interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::wait_for()

Definition at line 1326 of file os-c-wrapper.cpp.

{
  assert (clock != nullptr);
  return (os_result_t)(reinterpret_cast<rtos::clock&> (*clock))
      .wait_for (timeout);
}

os_rtc_handler()

void os_rtc_handler

(

void

)

Must be called from the physical RTC interrupt handler.

Definition at line 95 of file os-clocks.cpp.

{
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
  // Prevent scheduler actions before starting it.
  if (scheduler::started ())
    {
      port::clock_rtc::internal_interrupt_service_routine ();
    }
#endif
 
#if defined(OS_TRACE_RTOS_RTC_TICK)
  trace_putchar ('!');
#endif
 
  {
    // ----- Enter critical section -------------------------------------------
    interrupts::critical_section ics;
 
    rtclock.internal_increment_count ();
    // ----- Exit critical section --------------------------------------------
  }
 
  rtclock.internal_check_timestamps ();
}

References os::rtos::adjustable_clock::internal_check_timestamps(), os::rtos::port::clock_rtc::internal_interrupt_service_routine(), os::rtos::rtclock, os::rtos::scheduler::started(), and trace_putchar().

Referenced by os_systick_handler().

os_sysclock_now()

os_clock_timestamp_t os_sysclock_now

(

void

)

Parameters

None.

Returns

The number of SysTick input clocks since startup.

Note

Can be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::now()

Definition at line 1410 of file os-c-wrapper.cpp.

{
  return (os_clock_timestamp_t)sysclock.now ();
}

References os::rtos::clock::now(), and os::rtos::sysclock.

os_sysclock_sleep_for()

os_result_t os_sysclock_sleep_for

(

os_clock_duration_t

duration

)

Parameters

[in]

duration

The number of clock units (ticks or seconds) to sleep.

Return values

ETIMEDOUT	The sleep lasted the entire duration.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINTR	The sleep was interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::sleep_for()

Definition at line 1422 of file os-c-wrapper.cpp.

{
  return (os_result_t)sysclock.sleep_for (duration);
}

References os::rtos::clock::sleep_for(), and os::rtos::sysclock.

os_sysclock_sleep_until()

os_result_t os_sysclock_sleep_until

(

os_clock_timestamp_t

timestamp

)

Parameters

[in]

timestamp

The absolute moment in time, in clock units.

Return values

ETIMEDOUT	The sleep lasted the entire duration.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINTR	The sleep was interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::sleep_until()

Definition at line 1434 of file os-c-wrapper.cpp.

{
  return (os_result_t)sysclock.sleep_until (timestamp);
}

References os::rtos::clock::sleep_until(), and os::rtos::sysclock.

os_sysclock_ticks_cast()

os_clock_duration_t os_sysclock_ticks_cast ( uint32_t  microsec )

inline

Parameters

[in]

microsec

The number of microseconds.

Returns

The number of ticks.

Definition at line 969 of file os-c-api.h.

  {
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#if defined(__cplusplus)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
#endif
    return (
        os_clock_duration_t)((((microsec)
                               * ((uint32_t)OS_INTEGER_SYSTICK_FREQUENCY_HZ))
                              + (uint32_t)1000000ul - 1)
                             / (uint32_t)1000000ul);
#pragma GCC diagnostic pop
  }

References OS_INTEGER_SYSTICK_FREQUENCY_HZ.

os_sysclock_ticks_cast_long()

os_clock_duration_t os_sysclock_ticks_cast_long ( uint64_t  microsec )

inline

Parameters

[in]

microsec

The number of microseconds.

Returns

The number of ticks.

Definition at line 992 of file os-c-api.h.

  {
#pragma GCC diagnostic push
#if defined(__clang__)
#elif defined(__GNUC__)
#if defined(__cplusplus)
#pragma GCC diagnostic ignored "-Wuseless-cast"
#endif
#endif
    return (
        os_clock_duration_t)((((microsec)
                               * ((uint64_t)OS_INTEGER_SYSTICK_FREQUENCY_HZ))
                              + (uint64_t)1000000ul - 1)
                             / (uint64_t)1000000ul);
#pragma GCC diagnostic pop
  }

References OS_INTEGER_SYSTICK_FREQUENCY_HZ.

os_sysclock_wait_for()

os_result_t os_sysclock_wait_for

(

os_clock_duration_t

timeout

)

Parameters

[in]

timeout

The timeout in clock units.

Return values

os_ok	An event occurred before the timeout.
ETIMEDOUT	The wait lasted the entire duration.
EPERM	Cannot be invoked from an Interrupt Service Routines.
EINTR	The sleep was interrupted.

Warning

Cannot be invoked from Interrupt Service Routines.

For the complete definition, see

os::rtos::clock::wait_for()

Definition at line 1446 of file os-c-wrapper.cpp.

{
  return (os_result_t)sysclock.wait_for (timeout);
}

References os::rtos::sysclock, and os::rtos::clock::wait_for().

os_systick_handler()

void os_systick_handler

(

void

)

Must be called from the physical interrupt handler.

Definition at line 36 of file os-clocks.cpp.

{
  using namespace os::rtos;
 
#if defined(OS_USE_RTOS_PORT_SCHEDULER)
  // Prevent scheduler actions before starting it.
  if (scheduler::started ())
    {
      port::clock_systick::internal_interrupt_service_routine ();
    }
#endif
 
#if defined(OS_TRACE_RTOS_SYSCLOCK_TICK)
  trace::putchar ('.');
#elif defined(OS_TRACE_RTOS_SYSCLOCK_TICK_BRACES)
  trace::printf ("{t ");
#endif
 
  {
    // ----- Enter critical section -------------------------------------------
    interrupts::critical_section ics;
 
    sysclock.internal_increment_count ();
    hrclock.internal_increment_count ();
    // ----- Exit critical section --------------------------------------------
  }
  sysclock.internal_check_timestamps ();
  hrclock.internal_check_timestamps ();
 
#if !defined(OS_INCLUDE_RTOS_REALTIME_CLOCK_DRIVER)
 
  // Simulate an RTC driver.
  static uint32_t ticks = clock_systick::frequency_hz;
 
  if (--ticks == 0)
    {
      ticks = clock_systick::frequency_hz;
 
      os_rtc_handler ();
    }
 
#endif /* !defined(OS_INCLUDE_RTOS_REALTIME_CLOCK_DRIVER) */
 
#if !defined(OS_USE_RTOS_PORT_SCHEDULER)
 
  port::scheduler::reschedule ();
 
#endif /* !defined(OS_USE_RTOS_PORT_SCHEDULER) */
 
#if defined(OS_TRACE_RTOS_SYSCLOCK_TICK_BRACES)
  trace::printf (" t}");
#endif
}

References os::rtos::clock_systick::frequency_hz, os::rtos::hrclock, os::rtos::clock_highres::internal_increment_count(), os::rtos::port::clock_systick::internal_interrupt_service_routine(), os_rtc_handler(), os::trace::printf(), os::trace::putchar(), os::rtos::port::scheduler::reschedule(), os::rtos::scheduler::started(), and os::rtos::sysclock.