Davide, Andrew,

I applied Davide's v3 patchset (sent into LKML on 25 Nov) against
2.4.24-rc3, and did various tests (all on x86).  Several tests
were done using the program at the foot of this mail.  Various others
were done by cobbling together bits of code that I haven't included
here.

In covering the tests I ran, and as a kind of proof of concept,
I'll treat the draft man page as the test spec.

I think I've found two bugs (look for the string "BUG" below), one
of which is a significant deviation from expected behavior.  See
the comments below.

Cheers,

Michael


quoted text
> SYNOPSIS
>     #include <sys/timerfd.h>
>
>     int timerfd_create(int clockid, int flags);
>
>     int timerfd_settime(int fd, int flags,
>                         const struct itimerspec *new_value,
>                         struct itimerspec *curr_value);
>
>     int timerfd_gettime(int fd,
>                          struct itimerspec *curr_value);
>
> DESCRIPTION
>     These system calls create and operate on  a  timer  that
>     delivers  timer  expiration  notifications  via  a  file
>     descriptor.  They provide an alternative to the  use  of
>     setitimer(2) or timer_create(3), with the advantage that
>     the file  descriptor  may  be  monitored  by  select(2),
>     poll(2), and epoll(7).
>
>     The  use of these three system calls is analogous to the
>     use of timer_create(3), timer_settime(3), and timer_get-
>     time(3).   (There  is no analog of timer_gettoverrun(3),
>     since that functionality  is  provided  by  read(2),  as
>     described below.)
>
>   timerfd_create()
>     timerfd_create() creates a new timer object, and returns
>     a file  descriptor  that  refers  to  that  timer.   The
>     clockid  argument  specifies  the  clock that is used to
>     mark the progress of  the  timer,  and  must  be  either
>     CLOCK_REALTIME  or CLOCK_MONOTONIC.

Verified.  I've tried creating various combinations of
CLOCK_REALTIME and CLOCK_MONOTONIC timers, both one shot
(it_interval is zero) and repeating (it_interval is non-zero),
and everything works as I would expect.

quoted text
>     CLOCK_REALTIME is a
>     settable system-wide clock.  CLOCK_MONOTONIC is  a  non-
>     settable  clock  that  is  not affected by discontinuous
>     changes in the system clock  (e.g.,  manual  changes  to
>     system time).  The current value of each of these clocks
>     can be retrieved using clock_gettime(3).
>
>     The flags argument is reserved for future  use.   As  at
>     Linux 2.6.25, this argument must be specified as zero.

(Verified: see the ERRORS section of the man page, below.)

quoted text
>   timerfd_settime()
>     timerfd_settime()  arms  (starts) or disarms (stops) the
>     timer referred to by the file descriptor fd.

Disarming a timer works fine in my tests.

quoted text
>     The new_value argument specifies the initial  expiration
>     and  interval  for the timer.  The itimer structure used
>     for this argument contains two fields, each of which  is
>     in turn a structure of type timespec:
>
>       struct timespec {
>           time_t tv_sec;                /* Seconds */
>           long   tv_nsec;               /* Nanoseconds */
>       };
>
>       struct itimerspec {
>           struct timespec it_interval;  /* Interval for
>                                            periodic timer */
>           struct timespec it_value;     /* Initial
>                                            expiration */
>       };
>
>     new_value.it_value  specifies  the initial expiration of
>     the timer, in seconds and nanoseconds.   Setting  either
>     field of new_value.it_value to a non-zero value arms the
>     timer.  Setting both  fields  of  new_value.it_value  to
>     zero disarms the timer.

Verified: setting both  fields  of  new_value.it_value  to
zero disarms the timer.

quoted text
>     Setting  one  or both fields of new_value.it_interval to
>     non-zero values specifies the  period,  in  seconds  and
>     nanoseconds,  for  repeated  timer expirations after the
>     initial    expiration.

I've tested intervals down to 1 nanosec, which seem to seems to
work as I would expect.  (But see the BUG reported below.)

quoted text
>     If     both     fields     of
>     new_value.it_interval  are  zero, the timer expires just
>     once, at the time specified by new_value.it_value.

Verified.

quoted text
>     The flags argument is either  0,  to  start  a  relative
>     timer  (new_value.it_interval  specifies a time relative
>     to the current value of the clock specified by clockid),
>     or   TFD_TIMER_ABSTIME,   to  start  an  absolute  timer
>     (new_value.it_interval specifies an  absolute  time  for
>     the  clock specified by clockid; that is, the timer will
>     expire when the value of that clock  reaches  the  value
>     specified in new_value.it_interval).

Tested: after setting a CLOCK_REALTIME timer with the
TFD_TIMER_ABSTIME flag to expire at some time in the past with
a non-zero interval (e.g., setting 100 seconds in the past, with
a 5 second interval), read() from the file descriptor returns
the correct number of expirations (e.g., 20).

This seems a reasonable thing to do, I suppose.  However, while
playing around to test this, I found what looks like a bug (see
below).

BUG 1:
However, this test exposed what looks like a bug: if I set a
CLOCK_REALTIME clock to expire in the past, with a very small
interval, then the maximum number of expirations that can be
returned via read seems to be limited to 32 bits, even though
we have a 64-bit value for returning this information.
I haven't checked the kernel source to determine where this
bug is.

To demonstrate the bug use the program appended to this mail,
as follows:

# The following starts a CLOCK_REALTIME repeating timer with
# an interval of 1 microsecs (1000 nanosecs), with an initial
# expiration of just under 2^32 nanoseconds in the past.
# The '-a' flags says use TFD_TIMER_ABSTIME for timer_settime() calls.
# The 'r' command reads from the timerfd file descriptor.

$ ./timerfd_test -a -- -4290 0 0 1000
Initial setting for settime:   value=1197543860.000, interval=0.000
./timerfd_test> r           <-- type this immediately
Read: 4292190752            <-- nearly 2^32 expirations, as expected

$ ./timerfd_test -a -- -4290 0 0 1000
Initial setting for settime:   value=1197543900.000, interval=0.000
./timerfd_test> r           <-- type this after 5 secs
Read: 2992244               <-- Looks like the counter rolled over


quoted text
>     The  curr_value  argument returns a structure containing
>     the setting of the timer that was current at the time of
>     the  call; see the description of timerfd_gettime() fol-
>     lowing.

See the bug described under timerfd_gettime().

quoted text
>   timerfd_gettime()
>     timerfd_gettime() returns, in curr_value, an  itimerspec
>     that  contains the current setting of the timer referred
>     to by the file descriptor fd.
>
>     The it_value field returns the amount of time until  the
>     timer  will  next expire.  If both fields of this struc-
>     ture are zero, then the  timer  is  currently  disarmed.
>     This  field always contains a relative value, regardless
>     of whether the TFD_TIMER_ABSTIME flag was specified when
>     setting the timer.

BUG 2:
The last sentence does not match the implementation.
(Nor is it consistent with the behavior of POSIX timers.
And I *think* things did work correctly in the original
timerfd() implementation, but I have not gone back to check.)

Suppose that we set an absolute timer to expire 100 seconds
in the future.  Then according to this sentence of the man
page then each subsequent call to timerfd_gettime() should
retrun an itimerspec structure whose it_value steadily
decreases from 100 to 0 (when the timer expires).  (This
is the behavior in the analogous situation with POSIX timers
and with setitimer()/getitimer().)

However, the implementation of timerfd_gettime() always
returns the "time when the timer would next expire", and
this value depends on whether TFD_TIMER_ABSTIME was specified
when setting the timer.

Examples:
$ ./timerfd_test -a -- 100       # -a means TFD_TIMER_ABSTIME
Initial setting for settime:   value=1197550329.140, interval=0.000
./timerfd_test> g                <-- Calls timerfd_gettime()
(elapsed time=  1)
Current value:                 value=1197550329.140, interval=0.000

$ ./timerfd_test -- 100
Initial setting for settime:   value=100.295, interval=0.000
./timerfd_test> g
(elapsed time=  2)
Current value:                 value=18208.440, interval=0.000

In both of the above examples, the "value" retrieved by timer_gettime()
should be a number <= 100.


BUG 2a:
The bug described for timerfd_gettime() also applies for the
'curr_value' returned by a call to timerfd_settime().


quoted text
>     The it_interval field returns the interval of the timer.

Verified: the above was true in all my tests.

quoted text
>     If both fields of this  structure  are  zero,  then  the
>     timer  is set to expire just once, at the time specified
>     by curr_value.it_value.

Verified.

quoted text
>   Operating on a timer file descriptor
>     The file descriptor returned  by  timerfd_create()  sup-
>     ports the following operations:
>
>     read(2)
>            If  the  timer  has  already  expired one or more
>            times since its settings were last modified using
>            timerfd_settime(),  or  since the last successful
>            read(2), then the buffer given to read(2) returns
>            an  unsigned 8-byte integer (uint64_t) containing
>            the number of  expirations  that  have  occurred.

Verified: each call to timerfd_settime() resets the "expiration
count" to 0, even if a previous setting of the timer had already
expired.

quoted text
>            (The  returned value is in host byte order, i.e.,
>            the native byte order for integers  on  the  host
>            machine.)
>
>            If no timer expirations have occurred at the time
>            of the read(2), then the call either blocks until
>            the  next  timer  expiration,

Verified.

quoted text
>            or  fails with the
>            error EAGAIN if the file descriptor has been made
>            non-blocking (via the use of the fcntl(2) F_SETFL
>            operation to set the O_NONBLOCK flag).

Verified.

quoted text
>            A read(2) will fail with the error EINVAL if  the
>            size of the supplied buffer is less than 8 bytes.

Verified.

quoted text
>     poll(2), select(2) (and similar)
>            The file descriptor is  readable  (the  select(2)
>            readfds argument; the poll(2) POLLIN flag) if one
>            or more timer expirations have occurred.

Verified for both poll() and select().

quoted text
>            The file descriptor also supports the other file-
>            descriptor    multiplexing    APIs:   pselect(2),
>            ppoll(2), and epoll(7).
>
>     close(2)
>            When the file descriptor is no longer required it
>            should  be  closed.   When  all  file descriptors
>            associated with the same timer object  have  been
>            closed,  the  timer is disarmed and its resources
>            are freed by the kernel.

Not verified.  (No easy way to do that from userspace.)

quoted text
>   fork(2) semantics
>     After a fork(2), the child inherits a copy of  the  file
>     descriptor   created   by  timerfd_create().   The  file
>     descriptor refers to the same underlying timer object as
>     the  corresponding  file  descriptor  in the parent, and
>     read(2)s in the  child  will  return  information  about
>     expirations of the timer.

Verified.  Reads from a dup(2)ed file descriptor, or a file
descriptor duplicated via a fork(2) can be used to read
expiration information.

quoted text
>   execve(2) semantics
>     A  file  descriptor  created by timerfd_create() is pre-
>     served across execve(2), and continues to generate timer
>     expirations if the timer was armed.

Verified.  A timerfd file descriptor is preserved across an
exceve(), and continues to generate timer expirations that
can be read(2).

quoted text
> RETURN VALUE
>     On success, timerfd_create() returns a new file descrip-
>     tor.  On error, -1 is returned and errno is set to indi-
>     cate the error.

Verified.  (And obvious.)

quoted text
>     timerfd_settime() and timerfd_gettime() return 0 on suc-
>     cess; on error they return -1, and set errno to indicate
>     the error.

Verified.  (And obvious.)

quoted text
> ERRORS
>     timerfd_create() can fail with the following errors:
>
>     EINVAL The  clockid  argument is neither CLOCK_MONOTONIC
>            nor CLOCK_REALTIME;

(CLOCK_MONOTONIC is 1, CLOCK_REALTIME is 0)
Tested: clockid == 2, clockid == -1;
        timerfd_create() fails with EINVAL, as expected.

quoted text
>            or flags is invalid.

Currently, 'flags' must be zero.
Tested: flags == 1;
        timerfd_create() fails with EINVAL, as expected.

quoted text
>     EMFILE The per-process limit of  open  file  descriptors
>            has been reached.

Not tested.

quoted text
>     ENFILE The system-wide limit on the total number of open
>            files has been reached.

Not tested.

quoted text
>     ENODEV Could  not  mount  (internal)  anonymous   i-node
>            device.

Not tested.

quoted text
>     ENOMEM There  was  insufficient  kernel memory to create
>            the timer.

Not tested.

quoted text
>     timerfd_settime() and timerfd_gettime()  can  fail  with
>     the following errors:
>
>     EBADF  fd is not a valid file descriptor.

Tested for timerfd_gettime() and timerfd_settime().
      An invalid file descriptor (i.e., a file descriptor that
      is not open) yields the error EBADF, as expected.

quoted text
>     EINVAL fd  is  not  a  valid  timerfd  file  descriptor.

Tested for timerfd_gettime() and timerfd_settime().
      Passing a file descriptor that refers to an object other
      than a timerfd fails with the error EINVAL, as expected.

quoted text
>            new_value is not properly initialized (one of the
>            tv_nsec   falls   outside   the   range  zero  to
>            999,999,999).

Tested for timerfd_settime().
     Specifying it_value.tv_nsec == 1000000000 or
     it_interval.tv_nsec == 1000000000 yields the error EINVAL,
     as expected.

--- END MAN PAGE TEXT ---

/* timerfd_test.c */

/* Link with -lrt */

#define _GNU_SOURCE
#include <sys/syscall.h>
#include <unistd.h>
#include <time.h>
#if defined(__i386__)
#define __NR_timerfd_create 322
#define __NR_timerfd_settime 325
#define __NR_timerfd_gettime 326
#endif

static int
timerfd_create(int clockid, int flags)
{
    return syscall(__NR_timerfd_create, clockid, flags);
}

static int
timerfd_settime(int fd, int flags, struct itimerspec *new_value,
        struct itimerspec *curr_value)
{
    return syscall(__NR_timerfd_settime, fd, flags,
            new_value, curr_value);
}

static int
timerfd_gettime(int fd, struct itimerspec *curr_value)
{
    return syscall(__NR_timerfd_gettime, fd, curr_value);
}

#define TFD_TIMER_ABSTIME (1 << 0)


#define handle_error(msg) \
        do { perror(msg); exit(EXIT_FAILURE); } while (0)

// #include <sys/timerfd.h>
#include <time.h>
#include <sys/times.h>
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <stdint.h>     /* Definition of uint64_t */

static void
usage(const char *pname, const char *msg)
{
    if (msg != NULL)
        printf("%s", msg);
    fprintf(stderr, "Usage: %s [options] value-sec [value-nsec "
            "[intvl-sec [intvl-nsec]]]\n", pname);
    fprintf(stderr, "Options are:\n");
    fprintf(stderr, "\t-a    Use absolute timer\n");
    fprintf(stderr, "\t-m    Use CLOCK_MONOTONIC "
            "(instead of CLOCK_REALTIME)\n");

    exit(EXIT_FAILURE);
} /* usage  */

static void
display_help(void)
{
    printf("n val-sec val-nsec intvl-sec intvl-nsec\n"
           "                  Reset timer value & interval\n");
    printf("g                 Get timer value\n");
    printf("r                 Read from file descriptor\n");
    printf("t                 Print elapsed time\n");
} /* display_help */


#define MAX_LINE 1024

static void
print_itimerspec(struct itimerspec *its)
{
    printf("value=%ld.%03ld, interval=%ld.%03ld",
            (long) its->it_value.tv_sec,
            (long) its->it_value.tv_nsec / 1000000,
            (long) its->it_interval.tv_sec,
            (long) its->it_interval.tv_nsec / 1000000);
} /* print_itimerspec */


int
main(int argc, char *argv[])
{
    struct itimerspec new_value, curr_value;
    int fd, flags;
    struct timespec now;
    int s, opt, use_abs_timer, use_monotonic;
    long arg1, arg2, arg3, arg4;
    uint64_t exp;
    time_t start;
    char line[MAX_LINE];
    int num_read, clockid;
    char cmd;

    use_abs_timer = 0;
    use_monotonic = 0;

    while ((opt = getopt(argc, argv, "am")) != -1) {
        switch (opt) {
        case 'a':
            use_abs_timer = 1;
            break;

        case 'm':
            use_monotonic = 1;
            break;

        default:
            usage(argv[1], NULL);
            break;
        } /* switch */
    } /* while */

    clockid = (use_monotonic ? CLOCK_MONOTONIC : CLOCK_REALTIME);

    if (optind + 1 > argc)
        usage(argv[0], NULL);

    if (clock_gettime(clockid, &now) == -1)
        handle_error("clock_gettime");

    flags = use_abs_timer ? TFD_TIMER_ABSTIME : 0;

    /* Create a timer with initial expiration and interval
       as specified in command line */

    if (use_abs_timer) {
        new_value.it_value.tv_sec = now.tv_sec + atoi(argv[optind]);
        new_value.it_value.tv_nsec = (argc > optind + 1) ?
                        atol(argv[optind + 1]) : now.tv_nsec;
    } else {
        new_value.it_value.tv_sec = atoi(argv[optind]);
        new_value.it_value.tv_nsec = (argc > optind + 1) ?
                       atol(argv[optind + 1]) : now.tv_nsec;
    }

    new_value.it_interval.tv_sec = (argc > optind + 2) ?
                        atol(argv[optind + 2]) : 0;
    new_value.it_interval.tv_nsec = (argc > optind + 3) ?
                        atol(argv[optind + 3]) : 0;

    fd = timerfd_create(clockid, 0);
    if (fd == -1)
        handle_error("timerfd_create");

    printf("Initial setting for settime:   ");
    print_itimerspec(&new_value);
    printf("\n");

    s = timerfd_settime(fd, flags, &new_value, &curr_value);
    if (s == -1)
        handle_error("timerfd_settime");

    start = time(NULL);

    for ( ; ; ) {
        printf("%s> ", argv[0]);
        fflush(stdout);

        if (fgets(line, MAX_LINE, stdin) == NULL)       /* EOF */
            exit(EXIT_SUCCESS);
        line[strlen(line) - 1] = '\0';      /* Remove trailing '\n' */

        if (*line == '\0')
            continue;                       /* Skip blank lines */

        if (line[0] == '?')
            display_help();

        num_read = sscanf(line, " %c %ld %ld %ld %ld",
                          &cmd, &arg1, &arg2, &arg3, &arg4);

        switch (cmd) {
        case 'n':
            if (num_read != 5) {
                printf("Wrong number of arguments\n");
                continue;
            }

            if (use_abs_timer) {
                printf("This is an absolute timer\n");
                if (clock_gettime(clockid, &now) == -1)
                    handle_error("clock_gettime");
                printf("Now:                           ");
                printf("value=%ld.%03ld", (long) now.tv_sec,
                        (long) now.tv_nsec / 1000000);
                printf("\n");

                new_value.it_value.tv_sec = now.tv_sec + arg1;
                new_value.it_value.tv_nsec = now.tv_nsec + arg2;

            } else {
                printf("This is a relative timer\n");
                new_value.it_value.tv_sec = arg1;
                new_value.it_value.tv_nsec = arg2;
            }

            new_value.it_interval.tv_sec = arg3;
            new_value.it_interval.tv_nsec = arg4;

            printf("New setting for settime:       ");
            print_itimerspec(&new_value);
            printf("\n");

            s = timerfd_settime(fd, flags, &new_value, &curr_value);
            if (s == -1) {
                perror("timerfd_settime");
                break;
            }
            printf("Previous setting from settime: ");
            print_itimerspec(&curr_value);
            printf("\n");

            break;

        case 't':
            printf("%ld\n", (long) (time(NULL) - start));
            break;

        case 'g':
            s = timerfd_gettime(fd, &curr_value);
            if (s == -1)
                handle_error("timerfd_gettime");
            printf("(elapsed time=%3ld)\n", (long) (time(NULL) - start));
            printf("Current value:                 ");
            print_itimerspec(&curr_value);
            printf("\n");
            break;

        case 'r':
            s = read(fd, &exp, sizeof(uint64_t));
            if (s != sizeof(uint64_t))
                handle_error("read");
            printf("Read: %lld\n", exp);
            break;
        } /* switch */
    } /* for */

    exit(EXIT_SUCCESS);
}


--
unsubscribe notice
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/