Detailed Description

This module is responsible for handling of system time and time intervals.

Collaboration diagram for Time and Intervals:

Secure time conversion utilities
static sysinterval_t	chTimeS2I (time_secs_t secs)
	Seconds to time interval.
static sysinterval_t	chTimeMS2I (time_msecs_t msec)
	Milliseconds to time interval.
static sysinterval_t	chTimeUS2I (time_usecs_t usec)
	Microseconds to time interval.
static time_secs_t	chTimeI2S (sysinterval_t interval)
	Time interval to seconds.
static time_msecs_t	chTimeI2MS (sysinterval_t interval)
	Time interval to milliseconds.
static time_usecs_t	chTimeI2US (sysinterval_t interval)
	Time interval to microseconds.
static systime_t	chTimeAddX (systime_t systime, sysinterval_t interval)
	Adds an interval to a system time returning a system time.
static sysinterval_t	chTimeDiffX (systime_t start, systime_t end)
	Subtracts two system times returning an interval.
static bool	chTimeIsInRangeX (systime_t time, systime_t start, systime_t end)
	Checks if the specified time is within the specified time range.
static systimestamp_t	chTimeStampAddX (systimestamp_t stamp, sysinterval_t interval)
	Adds an interval to a time stamp returning a time stamp.
static sysinterval_t	chTimeStampDiffX (systimestamp_t start, systimestamp_t end)
	Subtracts two time stamps returning an interval.
static bool	chTimeStampIsInRangeX (systimestamp_t stamp, systimestamp_t start, systimestamp_t end)
	Checks if the specified time stamp is within the specified time stamps range.

Special time constants
#define	TIME_IMMEDIATE ((sysinterval_t)0)
	Zero interval specification for some functions with a timeout specification.
#define	TIME_INFINITE ((sysinterval_t)-1)
	Infinite interval specification for all functions with a timeout specification.
#define	TIME_MAX_INTERVAL ((sysinterval_t)-2)
	Maximum interval constant usable as timeout.
#define	TIME_MAX_SYSTIME ((systime_t)-1)
	Maximum system of system time before it wraps.

Fast time conversion utilities
#define	TIME_S2I(secs)
	Seconds to time interval.
#define	TIME_MS2I(msecs)
	Milliseconds to time interval.
#define	TIME_US2I(usecs)
	Microseconds to time interval.
#define	TIME_I2S(interval)
	Time interval to seconds.
#define	TIME_I2MS(interval)
	Time interval to milliseconds.
#define	TIME_I2US(interval)
	Time interval to microseconds.

Typedefs
typedef uint64_t	systime_t
	Type of system time.
typedef uint64_t	sysinterval_t
	Type of time interval.
typedef uint64_t	systimestamp_t
	Type of a time stamp.
typedef uint32_t	time_secs_t
	Type of seconds.
typedef uint32_t	time_msecs_t
	Type of milliseconds.
typedef uint32_t	time_usecs_t
	Type of microseconds.
typedef uint64_t	time_conv_t
	Type of time conversion variable.

Macro Definition Documentation

◆ TIME_IMMEDIATE

#define TIME_IMMEDIATE ((sysinterval_t)0)

Zero interval specification for some functions with a timeout specification.

Note: Not all functions accept TIME_IMMEDIATE as timeout parameter, see the specific function documentation.

Definition at line 46 of file chtime.h.

Referenced by chCondWaitTimeoutS(), chEvtWaitAllTimeout(), chEvtWaitAnyTimeout(), chEvtWaitOneTimeout(), chFifoSendObject(), chFifoSendObjectAhead(), chFifoSendObjectAheadS(), chFifoSendObjectS(), chJobPost(), chJobPostAhead(), chJobPostAheadS(), chJobPostS(), chMsgWaitTimeoutS(), chSemWaitTimeoutS(), chThdEnqueueTimeoutS(), chThdSleepS(), chThdSuspendTimeoutS(), chVTDoSetContinuousI(), and chVTDoSetI().

◆ TIME_INFINITE

#define TIME_INFINITE ((sysinterval_t)-1)

Infinite interval specification for all functions with a timeout specification.

Note: Not all functions accept TIME_INFINITE as timeout parameter, see the specific function documentation.

Definition at line 54 of file chtime.h.

Referenced by chJobDispatch(), chJobGet(), and chSchGoSleepTimeoutS().

◆ TIME_MAX_INTERVAL

#define TIME_MAX_INTERVAL ((sysinterval_t)-2)

Maximum interval constant usable as timeout.

Definition at line 59 of file chtime.h.

Referenced by chTimeMS2I(), chTimeS2I(), and chTimeUS2I().

◆ TIME_MAX_SYSTIME

#define TIME_MAX_SYSTIME ((systime_t)-1)

Maximum system of system time before it wraps.

Definition at line 64 of file chtime.h.

Referenced by chTimeAddX().

◆ TIME_S2I

#define TIME_S2I ( secs )

Value:

((sysinterval_t)((time_conv_t)(secs) * (time_conv_t)CH_CFG_ST_FREQUENCY))

CH_CFG_ST_FREQUENCY

#define CH_CFG_ST_FREQUENCY

System tick frequency.

Definition chconf.h:75

time_conv_t

uint64_t time_conv_t

Type of time conversion variable.

Definition chtime.h:154

sysinterval_t

uint64_t sysinterval_t

Type of time interval.

Definition chtime.h:118

Seconds to time interval.

Converts from seconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.; Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.

Parameters

[in] secs number of seconds

Returns: The number of ticks.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 184 of file chtime.h.

◆ TIME_MS2I

#define TIME_MS2I ( msecs )

Value:

  ((sysinterval_t)((((time_conv_t)(msecs) *                                 \
                     (time_conv_t)CH_CFG_ST_FREQUENCY) +                    \
                    (time_conv_t)999) / (time_conv_t)1000))

Milliseconds to time interval.

Converts from milliseconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.; Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.

Parameters

[in] msecs number of milliseconds

Returns: The number of ticks.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 200 of file chtime.h.

◆ TIME_US2I

#define TIME_US2I ( usecs )

Value:

  ((sysinterval_t)((((time_conv_t)(usecs) *                                 \
                     (time_conv_t)CH_CFG_ST_FREQUENCY) +                    \
                    (time_conv_t)999999) / (time_conv_t)1000000))

Microseconds to time interval.

Converts from microseconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.; Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.

Parameters

[in] usecs number of microseconds

Returns: The number of ticks.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 218 of file chtime.h.

◆ TIME_I2S

#define TIME_I2S ( interval )

Value:

  (time_secs_t)(((time_conv_t)(interval) +                                  \
                 (time_conv_t)CH_CFG_ST_FREQUENCY -                         \
                 (time_conv_t)1) / (time_conv_t)CH_CFG_ST_FREQUENCY)

Time interval to seconds.

Converts from system ticks number to seconds.

Note: The result is rounded up to the next second boundary.; Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.

Parameters

[in] interval interval in ticks

Returns: The number of seconds.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 236 of file chtime.h.

◆ TIME_I2MS

#define TIME_I2MS ( interval )

Value:

  (time_msecs_t)((((time_conv_t)(interval) * (time_conv_t)1000) +           \
                  (time_conv_t)CH_CFG_ST_FREQUENCY - (time_conv_t)1) /      \
                 (time_conv_t)CH_CFG_ST_FREQUENCY)

Time interval to milliseconds.

Converts from system ticks number to milliseconds.

Note: The result is rounded up to the next millisecond boundary.; Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.

Parameters

[in] interval interval in ticks

Returns: The number of milliseconds.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 254 of file chtime.h.

◆ TIME_I2US

#define TIME_I2US ( interval )

Value:

  (time_usecs_t)((((time_conv_t)(interval) * (time_conv_t)1000000) +        \
                  (time_conv_t)CH_CFG_ST_FREQUENCY - (time_conv_t)1) /      \
                 (time_conv_t)CH_CFG_ST_FREQUENCY)

Time interval to microseconds.

Converts from system ticks number to microseconds.

Note: The result is rounded up to the next microsecond boundary.; Use of this macro for large values is not secure because integer overflows, make sure your value can be correctly converted.

Parameters

[in] interval interval in ticks

Returns: The number of microseconds.

Function Class:: Normal API, this function can be invoked by regular system threads but not from within a lock zone.

Definition at line 272 of file chtime.h.

Typedef Documentation

◆ systime_t

typedef uint64_t systime_t

Type of system time.

Note: It is selectable in configuration between 16, 32 or 64 bits.

Definition at line 106 of file chtime.h.

◆ sysinterval_t

typedef uint64_t sysinterval_t

Type of time interval.

Note: It is selectable in configuration between 16, 32 or 64 bits.

Definition at line 118 of file chtime.h.

◆ systimestamp_t

typedef uint64_t systimestamp_t

Type of a time stamp.

Definition at line 128 of file chtime.h.

◆ time_secs_t

typedef uint32_t time_secs_t

Type of seconds.

Note: It is selectable in configuration between 16 or 32 bits.

Definition at line 135 of file chtime.h.

◆ time_msecs_t

typedef uint32_t time_msecs_t

Type of milliseconds.

Note: It is selectable in configuration between 16 or 32 bits.

Definition at line 141 of file chtime.h.

◆ time_usecs_t

typedef uint32_t time_usecs_t

Type of microseconds.

Note: It is selectable in configuration between 16 or 32 bits.

Definition at line 147 of file chtime.h.

◆ time_conv_t

typedef uint64_t time_conv_t

Type of time conversion variable.

Note: This type must have double width than other time types, it is only used internally for conversions.

Definition at line 154 of file chtime.h.

Function Documentation

◆ chTimeS2I()

sysinterval_t chTimeS2I ( time_secs_t secs )

inlinestatic

Seconds to time interval.

Converts from seconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.

Parameters

[in] secs number of seconds

Returns: The number of ticks.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 308 of file chtime.h.

References CH_CFG_ST_FREQUENCY, chDbgAssert, and TIME_MAX_INTERVAL.

◆ chTimeMS2I()

sysinterval_t chTimeMS2I ( time_msecs_t msec )

inlinestatic

Milliseconds to time interval.

Converts from milliseconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.

Parameters

[in] msec number of milliseconds

Returns: The number of ticks.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 329 of file chtime.h.

References CH_CFG_ST_FREQUENCY, chDbgAssert, and TIME_MAX_INTERVAL.

◆ chTimeUS2I()

sysinterval_t chTimeUS2I ( time_usecs_t usec )

inlinestatic

Microseconds to time interval.

Converts from microseconds to system ticks number.

Note: The result is rounded upward to the next tick boundary.

Parameters

[in] usec number of microseconds

Returns: The number of ticks.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 351 of file chtime.h.

References CH_CFG_ST_FREQUENCY, chDbgAssert, and TIME_MAX_INTERVAL.

◆ chTimeI2S()

time_secs_t chTimeI2S ( sysinterval_t interval )

inlinestatic

Time interval to seconds.

Converts from system interval to seconds.

Note: The result is rounded up to the next second boundary.

Parameters

[in] interval interval in ticks

Returns: The number of seconds.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 373 of file chtime.h.

References CH_CFG_ST_FREQUENCY, and chDbgAssert.

◆ chTimeI2MS()

time_msecs_t chTimeI2MS ( sysinterval_t interval )

inlinestatic

Time interval to milliseconds.

Converts from system interval to milliseconds.

Note: The result is rounded up to the next millisecond boundary.

Parameters

[in] interval interval in ticks

Returns: The number of milliseconds.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 396 of file chtime.h.

References CH_CFG_ST_FREQUENCY, and chDbgAssert.

◆ chTimeI2US()

time_usecs_t chTimeI2US ( sysinterval_t interval )

inlinestatic

Time interval to microseconds.

Converts from system interval to microseconds.

Note: The result is rounded up to the next microsecond boundary.

Parameters

[in] interval interval in ticks

Returns: The number of microseconds.

Function Class:: Special function, this function has special requirements see the notes.

Definition at line 419 of file chtime.h.

References CH_CFG_ST_FREQUENCY, and chDbgAssert.

◆ chTimeAddX()

systime_t chTimeAddX	(	systime_t	systime,
		sysinterval_t	interval )

inlinestatic

Adds an interval to a system time returning a system time.

Parameters

[in]	systime	base system time
[in]	interval	interval to be added

Returns: The new system time.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 441 of file chtime.h.

References chDbgCheck, and TIME_MAX_SYSTIME.

Referenced by chVTDoTickI(), vt_insert_first(), and vt_set_alarm().

◆ chTimeDiffX()

sysinterval_t chTimeDiffX	(	systime_t	start,
		systime_t	end )

inlinestatic

Subtracts two system times returning an interval.

Parameters

[in]	start	first system time
[in]	end	second system time

Returns: The interval representing the time difference.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 460 of file chtime.h.

Referenced by chThdSleepUntil(), chThdSleepUntilWindowed(), chVTDoResetI(), chVTDoTickI(), chVTGetRemainingIntervalI(), chVTGetTimersStateI(), chVTGetTimeStampI(), chVTTimeElapsedSinceX(), vt_enqueue(), vt_insert_first(), and vt_set_alarm().

◆ chTimeIsInRangeX()

bool chTimeIsInRangeX	(	systime_t	time,
		systime_t	start,
		systime_t	end )

inlinestatic

Checks if the specified time is within the specified time range.

Note: When start==end then the function returns always false because the time window has zero size.

Parameters

[in]	time	the time to be verified
[in]	start	the start of the time window (inclusive)
[in]	end	the end of the time window (non inclusive)

Return values

true	if the current time is within the specified time window.
false	if the current time is not within the specified time window.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 483 of file chtime.h.

Referenced by chThdSleepUntilWindowed(), chVTIsSystemTimeWithin(), and chVTIsSystemTimeWithinX().

◆ chTimeStampAddX()

systimestamp_t chTimeStampAddX	(	systimestamp_t	stamp,
		sysinterval_t	interval )

inlinestatic

Adds an interval to a time stamp returning a time stamp.

Parameters

[in]	stamp	base time stamp
[in]	interval	interval to be added

Returns: The new time stamp.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 500 of file chtime.h.

◆ chTimeStampDiffX()

sysinterval_t chTimeStampDiffX	(	systimestamp_t	start,
		systimestamp_t	end )

inlinestatic

Subtracts two time stamps returning an interval.

Note: Intervals can then be used for converting in absolute time.

Parameters

[in]	start	first time stamp
[in]	end	second time stamp

Returns: The interval representing the time stamps difference.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 516 of file chtime.h.

References chDbgAssert.

◆ chTimeStampIsInRangeX()

bool chTimeStampIsInRangeX	(	systimestamp_t	stamp,
		systimestamp_t	start,
		systimestamp_t	end )

inlinestatic

Checks if the specified time stamp is within the specified time stamps range.

Note: When start==end then the function returns always false because the time window has zero size.

Parameters

[in]	stamp	the time stamp to be verified
[in]	start	the start of the time stamp window (inclusive)
[in]	end	the end of the time stamp window (non inclusive)

Return values

true	if the current time stamp is within the specified time stamp window.
false	if the current time stamp is not within the specified time stamp window.

Function Class:: This is an X-Class API, this function can be invoked from any context.

Definition at line 551 of file chtime.h.

Detailed Description

Secure time conversion utilities

Special time constants

Fast time conversion utilities

Typedefs

Macro Definition Documentation

◆ TIME_IMMEDIATE

◆ TIME_INFINITE

◆ TIME_MAX_INTERVAL

◆ TIME_MAX_SYSTIME

◆ TIME_S2I

◆ TIME_MS2I

◆ TIME_US2I

◆ TIME_I2S

◆ TIME_I2MS

◆ TIME_I2US

Typedef Documentation

◆ systime_t

◆ sysinterval_t

◆ systimestamp_t

◆ time_secs_t

◆ time_msecs_t

◆ time_usecs_t

◆ time_conv_t

Function Documentation

◆ chTimeS2I()

◆ chTimeMS2I()

◆ chTimeUS2I()

◆ chTimeI2S()

◆ chTimeI2MS()

◆ chTimeI2US()

◆ chTimeAddX()

◆ chTimeDiffX()

◆ chTimeIsInRangeX()

◆ chTimeStampAddX()

◆ chTimeStampDiffX()

◆ chTimeStampIsInRangeX()