Xenomai  3.1
Clocks and timers

Cobalt/POSIX clock and timer services. More...

Collaboration diagram for Clocks and timers:

Functions

int clock_getres (clockid_t clock_id, struct timespec *tp)
 
Get the resolution of the specified clock. More...
 
int clock_gettime (clockid_t clock_id, struct timespec *tp)
 
Read the specified clock. More...
 
int clock_settime (clockid_t clock_id, const struct timespec *tp)
 
Set the specified clock. More...
 
int clock_nanosleep (clockid_t clock_id, int flags, const struct timespec *rqtp, struct timespec *rmtp)
 
Sleep some amount of time. More...
 
int nanosleep (const struct timespec *rqtp, struct timespec *rmtp)
 
Sleep some amount of time. More...
 
int timer_create (clockid_t clockid, const struct sigevent *__restrict__ evp, timer_t *__restrict__ timerid)
 
Create a timer More...
 
int timer_delete (timer_t timerid)
 
Delete a timer object. More...
 
int timer_settime (timer_t timerid, int flags, const struct itimerspec *__restrict__ value, struct itimerspec *__restrict__ ovalue)
 
Start or stop a timer More...
 
int timer_gettime (timer_t timerid, struct itimerspec *value)
 
Get timer next expiration date and reload value. More...
 
int timer_getoverrun (timer_t timerid)
 
Get expiration overruns count since the most recent timer expiration signal delivery. More...
 

Detailed Description

Cobalt/POSIX clock and timer services.

Cobalt supports three built-in clocks:

CLOCK_REALTIME maps to the nucleus system clock, keeping time as the amount of time since the Epoch, with a resolution of one nanosecond.

CLOCK_MONOTONIC maps to an architecture-dependent high resolution counter, so is suitable for measuring short time intervals. However, when used for sleeping (with clock_nanosleep()), the CLOCK_MONOTONIC clock has a resolution of one nanosecond, like the CLOCK_REALTIME clock.

CLOCK_MONOTONIC_RAW is Linux-specific, and provides monotonic time values from a hardware timer which is not adjusted by NTP. This is strictly equivalent to CLOCK_MONOTONIC with Cobalt, which is not NTP adjusted either.

In addition, external clocks can be dynamically registered using the cobalt_clock_register() service. These clocks are fully managed by Cobalt extension code, which should advertise each incoming tick by calling xnclock_tick() for the relevant clock, from an interrupt context.

Timer objects may be created with the timer_create() service using any of the built-in or external clocks. The resolution of these timers is clock-specific. However, built-in clocks all have nanosecond resolution, as specified for clock_nanosleep().

See also
Specification.

Function Documentation

◆ clock_getres()

int clock_getres ( clockid_t  clock_id,
struct timespec *  tp 
)


Get the resolution of the specified clock.

This service returns, at the address res, if it is not NULL, the resolution of the clock clock_id.

For both CLOCK_REALTIME and CLOCK_MONOTONIC, this resolution is the duration of one system clock tick. No other clock is supported.

Parameters
clock_idclock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC;
tpthe address where the resolution of the specified clock will be stored on success.
Return values
0on success;
-1with errno set if:
  • EINVAL, clock_id is invalid;
See also
Specification.
Tags
unrestricted

◆ clock_gettime()

int clock_gettime ( clockid_t  clock_id,
struct timespec *  tp 
)


Read the specified clock.

This service returns, at the address tp the current value of the clock clock_id. If clock_id is:

  • CLOCK_REALTIME, the clock value represents the amount of time since the Epoch, with a precision of one system clock tick;
  • CLOCK_MONOTONIC or CLOCK_MONOTONIC_RAW, the clock value is given by an architecture-dependent high resolution counter, with a precision independent from the system clock tick duration.
  • CLOCK_HOST_REALTIME, the clock value as seen by the host, typically Linux. Resolution and precision depend on the host, but it is guaranteed that both, host and Cobalt, see the same information.
Parameters
clock_idclock identifier, either CLOCK_REALTIME, CLOCK_MONOTONIC, or CLOCK_HOST_REALTIME;
tpthe address where the value of the specified clock will be stored.
Return values
0on success;
-1with errno set if:
  • EINVAL, clock_id is invalid.
See also
Specification.
Tags
unrestricted

◆ clock_nanosleep()

int clock_nanosleep ( clockid_t  clock_id,
int  flags,
const struct timespec *  rqtp,
struct timespec *  rmtp 
)


Sleep some amount of time.

This service suspends the calling thread until the wakeup time specified by rqtp, or a signal is delivered to the caller. If the flag TIMER_ABSTIME is set in the flags argument, the wakeup time is specified as an absolute value of the clock clock_id. If the flag TIMER_ABSTIME is not set, the wakeup time is specified as a time interval.

If this service is interrupted by a signal, the flag TIMER_ABSTIME is not set, and rmtp is not NULL, the time remaining until the specified wakeup time is returned at the address rmtp.

The resolution of this service is one system clock tick.

Parameters
clock_idclock identifier, either CLOCK_REALTIME or CLOCK_MONOTONIC.
flagsone of:
  • 0 meaning that the wakeup time rqtp is a time interval;
  • TIMER_ABSTIME, meaning that the wakeup time is an absolute value of the clock clock_id.
rqtpaddress of the wakeup time.
rmtpaddress where the remaining time before wakeup will be stored if the service is interrupted by a signal.
Returns
0 on success;
an error number if:
  • EPERM, the caller context is invalid;
  • ENOTSUP, the specified clock is unsupported;
  • EINVAL, the specified wakeup time is invalid;
  • EINTR, this service was interrupted by a signal.
See also
Specification.
Tags
xthread-only, switch-primary

◆ clock_settime()

int clock_settime ( clockid_t  clock_id,
const struct timespec *  tp 
)


Set the specified clock.

This allow setting the CLOCK_REALTIME clock.

Parameters
clock_idthe id of the clock to be set, only CLOCK_REALTIME is supported.
tpthe address of a struct timespec specifying the new date.
Return values
0on success;
-1with errno set if:
  • EINVAL, clock_id is not CLOCK_REALTIME;
  • EINVAL, the date specified by tp is invalid.
See also
Specification.
Tags
unrestricted

◆ nanosleep()

int nanosleep ( const struct timespec *  rqtp,
struct timespec *  rmtp 
)


Sleep some amount of time.

This service suspends the calling thread until the wakeup time specified by rqtp, or a signal is delivered. The wakeup time is specified as a time interval.

If this service is interrupted by a signal and rmtp is not NULL, the time remaining until the specified wakeup time is returned at the address rmtp.

The resolution of this service is one system clock tick.

Parameters
rqtpaddress of the wakeup time.
rmtpaddress where the remaining time before wakeup will be stored if the service is interrupted by a signal.
Return values
0on success;
-1with errno set if:
  • EPERM, the caller context is invalid;
  • EINVAL, the specified wakeup time is invalid;
  • EINTR, this service was interrupted by a signal.
See also
Specification.
Tags
xthread-only, switch-primary

◆ timer_create()

int timer_create ( clockid_t  clockid,
const struct sigevent *__restrict__  evp,
timer_t *__restrict__  timerid 
)


Create a timer

This service creates a timer based on the clock clockid.

If evp is not NULL, it describes the notification mechanism used on timer expiration. Only thread-directed notification is supported (evp->sigev_notify set to SIGEV_THREAD_ID).

If evp is NULL, the current Cobalt thread will receive the notifications with signal SIGALRM.

The recipient thread is delivered notifications when it calls any of the sigwait(), sigtimedwait() or sigwaitinfo() services.

If this service succeeds, an identifier for the created timer is returned at the address timerid. The timer is unarmed until started with the timer_settime() service.

Parameters
clockidclock used as a timing base;
evpdescription of the asynchronous notification to occur when the timer expires;
timeridaddress where the identifier of the created timer will be stored on success.
Return values
0on success;
-1with errno set if:
  • EINVAL, the clock clockid is invalid;
  • EINVAL, the member sigev_notify of the sigevent structure at the address evp is not SIGEV_THREAD_ID;
  • EINVAL, the member sigev_signo of the sigevent structure is an invalid signal number;
  • EAGAIN, the maximum number of timers was exceeded, recompile with a larger value.
See also
Specification.
Tags
thread-unrestricted

Referenced by pthread_make_periodic_np().

◆ timer_delete()

int timer_delete ( timer_t  timerid)


Delete a timer object.

This service deletes the timer timerid.

Parameters
timerididentifier of the timer to be removed;
Return values
0on success;
-1with errno set if:
  • EINVAL, timerid is invalid;
  • EPERM, the timer timerid does not belong to the current process.
See also
Specification.
Tags
thread-unrestricted

◆ timer_getoverrun()

int timer_getoverrun ( timer_t  timerid)


Get expiration overruns count since the most recent timer expiration signal delivery.

This service returns timerid expiration overruns count since the most recent timer expiration signal delivery. If this count is more than DELAYTIMER_MAX expirations, DELAYTIMER_MAX is returned.

Parameters
timeridTimer identifier.
Returns
the overruns count on success;
-1 with errno set if:
  • EINVAL, timerid is invalid;
  • EPERM, the timer timerid does not belong to the current process.
See also
Specification.
Tags
unrestricted

◆ timer_gettime()

int timer_gettime ( timer_t  timerid,
struct itimerspec *  value 
)


Get timer next expiration date and reload value.

This service stores, at the address value, the expiration date (member it_value) and reload value (member it_interval) of the timer timerid. The values are returned as time intervals, and as multiples of the system clock tick duration (see note in section Clocks and timers services for details on the duration of the system clock tick). If the timer was not started, the returned members it_value and it_interval of value are zero.

Parameters
timeridtimer identifier;
valueaddress where the timer expiration date and reload value are stored on success.
Return values
0on success;
-1with errno set if:
  • EINVAL, timerid is invalid. For timerid to be valid, it must belong to the current process.
See also
Specification.
Tags
unrestricted

◆ timer_settime()

timer_settime ( timer_t  timerid,
int  flags,
const struct itimerspec *__restrict__  value,
struct itimerspec *__restrict__  ovalue 
)


Start or stop a timer

This service sets a timer expiration date and reload value of the timer timerid. If ovalue is not NULL, the current expiration date and reload value are stored at the address ovalue as with timer_gettime().

If the member it_value of the itimerspec structure at value is zero, the timer is stopped, otherwise the timer is started. If the member it_interval is not zero, the timer is periodic. The current thread must be a Cobalt thread (created with pthread_create()) and will be notified via signal of timer expirations.

When starting the timer, if flags is TIMER_ABSTIME, the expiration value is interpreted as an absolute date of the clock passed to the timer_create() service. Otherwise, the expiration value is interpreted as a time interval.

Expiration date and reload value are rounded to an integer count of nanoseconds.

Parameters
timerididentifier of the timer to be started or stopped;
flagsone of 0 or TIMER_ABSTIME;
valueaddress where the specified timer expiration date and reload value are read;
ovalueaddress where the specified timer previous expiration date and reload value are stored if not NULL.
Return values
0on success;
-1with errno set if:
  • EINVAL, the specified timer identifier, expiration date or reload value is invalid. For timerid to be valid, it must belong to the current process.
See also
Specification.
Tags
xcontext, switch-primary

Referenced by pthread_make_periodic_np().