Josep Vidal DISCA, Universidad Politecnica de Valencia

e-mail: jvidal@disca.upv.es

January 2002 2002 OCERA Consortium

Name POSIX Timers Description POSIX timers provides mechanisms to notify a thread when the time (measured by a particular clock) has reached a specified value, or when a specified amount of time has passed. Although RTLinux has good and accurate timing facilities, it do not provides general timer functionality. RTLinux defines only one timer for each thread, which is used to implement the periodic behaviour of the thread. This component implements the POSIX real-time extensions. Author Josep Vidal Canet (jvidal@disca.upv.es) Reviewer Ismael Ripoll Ripoll Layer Low-Level component. Version 0.2 Status Finished. Included in RTLinux-3.2pre2 release. Dependencies Psignals component and RTLinux-3.2pre1. Also tested/available for RTLinux-3.1, RTLinux-3.2pre2. Release Date M2

POSIX timers allows a mechanism that can notify a thread when the time as measured by a particular clock has reached or passed a specified value, or when a specified amount of time has passed. Facilities supported by POSIX timers that are desirable for real-time operating systems: Support for additional clocks. Allowance for greater time resolution (modern timers are capable of nanosecond resolution; the hardware should support it) Ability to use something other than SIGALARM to indicate timer expiration (in particular, a POSIX.4 real-time extended signal would be nice) Therefore POSIX timers allows greater time resolution, implementation-defined timers, and more flexibility in signal delivery.

Here is a simple and portable way of creating a timer: #include #define A_DESCRIPTIVE_NAME 13 int err; struct sigevent signal_specification; timer_t created_timer; /* Contains the ID of the created timer */ /* What signal should be generated when this timer expires ? */ signal_specification.sigev_signo= RTL_SIGUSR1; signal_specification.sigev_value.sival_int = A_DESCRIPTIVE_NAME err=timer_create(CLOCK_REALTIME, &signal_specification, &created_timer); ]]> The code snipped creates a timer based upon the system clock called CLOCK_REALTIME. CLOCK_REALTIME exists on all POSIX.4-conformant systems, so it can be used. A machine may define other clocks, corresponding perhaps to extra, dedicated hardware resources on a particular target machine. The POSIX.4 conformance statement should indicate what clocks are available on a particular system. The evp argument, if non-NULL, points to a sigevent structure. This structure, allocated by the application, defines the asynchronous notification to occur as specified in Signal Generation and Delivery when the timer expires. If the evp argument is NULL, the effect is as if the evp argument pointed to a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, the sigev_signo having a default signal number, and the sigev_value member having the value of the timer ID. If you want to specify a particular signal to be delivered on timer expirations, use the struct sigevent, as defined in signal.h: This structure contains three members: sigev_notify is a flag value that specifies what sort of notification should be used upon timer expiration (signals, nothing, or something else). Currently, only two values are defined for sigev_notify: SIGEV_SIGNAL means to send the signal described by the remainder of the struct sigevent, and SIVEV_NONE means to send no notification at all upon timer expiration. The third parameter is where the system stored th ID of the created timer. You will need this ID in order to use the timer.

Once there is a timer ID, it can be set as in the following example: struct itimerspec new_setting, old_setting; new_setting.it_value.tv_sec=1; new_setting.it_value.tv_nsec=0; new_setting.it_interval.tv_sec=0; new_setting.it_interval.tv_nsec=100*1000; err=timer_settime(created_timer, 0, &new_setting, &old_setting); ]]> This example sets the interval timer to expire in 1 second, and every 100.000 nanoseconds thereafter. The old timer setting is returned in the structure old_setting. With the second parameter, you tell the system to interpret the interval timer setting as an absolute (TIMER_ABSTIME) or as a relative setting, like in the above example. Two timer types are required for a system to support realtime applications: One-shot: A one-shot timer is a timer that is armed with an initial expiration time, either relative to the current time or at an absolute time (based on some timing base, such as time in seconds and nanoseconds since the Epoch). The timer expires once and then is disarmed. With the specified facilities, this is accomplished by setting the it_value member of the value argument to the desired expiration time and the it_interval member to zero. Periodic: A periodic timer is a timer that is armed with an initial expiration time, again either relative or absolute, and a repetition interval. When the initial expiration occurs, the timer is reloaded with the repetition interval and continues counting. With the specified facilities, this is accomplished by setting the it_value member of the value argument to the desired initial expiration time and the it_interval member to the desired repetition interval. For both of these types of timers, the time of the initial timer expiration can be specified in two ways: Relative (to the current time). Absolute.

Many of the timing facility functions accept or return time value specifications. A time value structure timespec specifies a single time value and includes at least the following members: Member type Member name Description time_t tv_sec Seconds long tv_nsec Nanoseconds The tv_nsec member is only valid if greater than or equal to zero, and less than the number of nanoseconds in a second (1000 million). The time interval described by this structure is (tv_sec * 10^9 + tv_nsec) nanoseconds. A time value structure itimerspec specifies an initial timer value and a repetition interval for use by the per-process timer functions. This structure includes at least the following members: Member type Member name Description struct itimerspec it_interval Timer period struct timespec it_value Timer expiration If the value described by it_value is non-zero, it indicates the time to or time of the next timer expiration (for relative and absolute timer values, respectively). If the value described by it_value is zero, the timer shall be disarmed. If the value described by it_interval is non-zero, it specifies an interval which shall be used in reloading the timer when it expires; that is, a periodic timer is specified. If the value described by it_interval is zero, the timer is disarmed after its next expiration; that is, a one-shot timer is specified.

This component provides all the functionalities described by the POSIX standard, but the one related to real-time signals, because the signals component does not provide it. /* Creating a timer. Timer created is returned in timer_id location */ int timer_create clockid_t clockid struct sigevent *restrict evp timer_t *restrict timer_id /* Removing timer referenced by timer_id */ int timer_delete timer_t *timer_id /* Setting timer referenced by location timer_id */ int timer_settime timer_t timer_id int flags const struct itimerspec *new_setting struct itimerspec *old_setting /* Getting time remainning until next expiration*/ int timer_gettime timer_t timer_id struct itimerspec *expires int timer_getoverrun timer_t timer_id Timers implementation supports both CLOCK_MONOTONIC and CLOCK_REALTIME.

In RTLinux timer_t type is implemented as a pointer to the timer structure. When a timer is created, the memory required to store the timer_struct is dynamically allocated. For this reason, timer_create() can only be called while in Linux space, that is, all timers must be created in the init_module(). For the same reason, timers can only be deleted in cleaun_module(). This implementation follows the general style of RTLinux used in mutex, semaphores, threads, etc; all data is preallocated before the threads are started. Timers are stored in a linked list sorted by thread owner priority, which speeds-up the code that finds the next timer to expire. Right now, following files of the RTLinux version 3.2pre1 has been modified/added. Modifications are in-crusted with : In schedulers directory: In include directory: Timers implementation supports both CLOCK_MONOTONIC and CLOCK_REALTIME.

We have used several test sets to validate the component. Next a brief description of each test suit is provided: Self built test suite: Among other things these programs checks: Timers resolution for both absolute and relative specs. Timers emulation of multitasking. POSIX timers API. Timers effects over RTLinux scheduler API functions (pthread_make_periodic_np(), pthread_wait_np()). POSIX Test Suite: Recently the Open POSIX Test Suite released a test suite with timers coverage. We have used these tests slightly modified to run on RTLinux. These tests are divided into four directories. Each one corresponding with the functionality to test (timer_create(),timer_delete(), timer_settime(), timer_gettime()). High Resolution Timers Linux implementation test suite. Slightly modified to run on RTLinux.

All tests have been passed (internal tests and independent external ones). As in the case of signals component, increases RTLinux POSIX compatibility and reduces the cost of porting applications to Rtlinux. Allows to implement watchdog timers. The timers overhead is negligible when no timer is armed. When several timers are armed, the overhead introduced is O(n) where n is the number of armed timers. Due to the flexibility and changing scenarios (priority inheritance, scheduler operational modes, different scheduling policies, etc.) it is not possible to use advanced data structures to achieve better worst case overhead. It is possible to use some heuristics to improve the response time in some cases, but the worst case remains the same.

This test measures timer accuracy for both relative and absolute timer specifications. To do it, follows next procedure: Create a thread and program a periodic timer with some period (relative spec) or a one-shot timer for absolute specification. Then let expire the timer n times. If it is absolute, reprogram each time the timer by adding the period to the absolute time specification. After n expirations, calculate the teoric time transcurred (n*period) and the real (end_time -start_time). Finally, print the error as difference between the teoric time transcurred and the real one.

This test measures POSIX.1 Signals bandwidth, following next procedure: Create two threads, a parent and a child. During an interval of time send signals between them. Measure signals send/received per milisecond.

Simple program to test timers API, with the following procedure: Create a user-defined number of tasks. Make periodic them, with a period of 2 minutes. Arm timers for each task. The firs tasks arms a one-shot timer and the others repeating timers with an interval of 1 second. Install a handler for each timer that wakes up each task every timer expiration. Check that task period changes (for all tasks but the first) from 2 minutes to 1 second due to timers expirations and handlers executions.

This program test RTLinux POSIX.4 timers emulation of multitasking. Provides support for testing both CLOCK_REALTIME & CLOCK_MONOTONIC. Also for system clock on mode ONESHOT or PERIODIC deppending on the defines. Test follows next procedure: Create a user-defined number of tasks. Set the system clock on mode ONESHOT or PERIODIC. Schedule them, using RTLinux API or timers & signals. Analyse test chronograms. NOTE: You will observe that the scheduler result using the RTLinux API and timers + signals, is basically the same. Also you will observe that test chronogram for timers based on CLOCK_MONOTONIC and system clock on mode periodic is not synchronous. This is OK, since in RTLinux CLOCK_MONOTONIC with system clock on mode periodic is different from CLOCK_REALTIME (the one used by the scheduler and test chronogram). The monitor directory comes with a patched version of the scheduler that informs about tasks activations and executions times. Also provides a program (reader) to get kernel information. You need to place the program crono in that directory in order to see the chronograms (available from http://bernia.disca.upv.es/rtportal).

Check that a timer can be programed by different threads. Test follows next procedure: Create two tasks. The first time both arm a timer. Only the last is the owner and therefore the one that will receive notification of timer expiraition. The handler for that timer wakes up the other task, allowing it to program an action for the signal of the timer and set the timer. The proces is repeated printing the time passed since last timer expiration. Each time the timer is being programmed by a different thread.

The POSIX Test Suite is an open source test suite with the goal of performing conformance, functional, and stress testing of the IEEE 1003.1-2001 System Interfaces specification in a manner that is agnostic to any given implementation. Among other POSIX functionalities, these suite supports timers testing. We have used these tests slightly modified to run on RTLinux. Timers tests are divided into four directories. Each one corresponding with the functionality to test (timer_create(),timer_delete(), timer_settime(), timer_gettime()). Every test is well documented and ends with a report of assertions passed and failed.

This is the timers test suite provided by high resolution timers Linux implementation. The tests consists in two programs that test in a hard way timers functionality and implementation stability. More than 40 assertions are make against timers implementation.

We try to do our best on achieving good timers accuracy and emmulation of multitasking. One of the previous commented test timers resolution measures timers accuracy for both absolute and relative specifications. Test results vary depending on available hardware. In a PIII 500 MHZ with APIC, the resolution available is 10 microseconds for absolutes timers and 20 microseconds for relative timers. On a K6 II 3D NOW 300 MHZ without APIC the error is doubled (22 us absolute timers & 39 us relative timers). This results have been taken with CLOCK_REALTIME and system clock on mode ONE-SHOT (default mode). Using timers for multitasking emmulation was checked in one of the previous tests. From the test results, showed in next two chronograms it can observed that there is no difference between using RTLinux API (pthread_make_periodic_np, pthread_wait_np) and usign timers and signals to run periodic tasks.

In order to run any example, t he user must type make test in the example directory.

In the examples directory, two simple programs showing basic timers functionality are provided. The first one, implements periodic threads using signals and timers, while the second uses a timers to avoid machine hang up due to huge quantity of recursive calculations.

In order to install POSIX timers in RTLinux, please follow next steps: Install POSIX signals component. Install POSIX timers component. To do this, edit Makefile, set RTLINUX variable to your RTLinux copy path and type make install. Change to the RTLinux directory and type make xconfig. Next enable both posix signals and timers and type make clean ; make. Note: You can't select POSIX timers, if POSIX signals isn't selected. This is OK, since POSIX timers depends on POSIX signals implementation.