[WIP] [LibOS] Add support for timerfd system calls

This commit adds support for system calls that create and operate on a
timer that delivers timer expiration notifications via a file
descriptor, specifically: `timerfd_create()`, `timerfd_settime()` and
`timerfd_gettime()`. The timerfd object is associated with a dummy
eventfd created on the host to trigger notifications (e.g., in epoll).
The object is created inside Gramine, with all it operations resolved
entirely inside Gramine.

The emulation is currently implemented at the level of a single process.
However, it may sometimes work for multi-process applications, e.g.,
if the child process inherits the timerfd object but doesn't use it;  to
support these cases, we introduce the
`sys.experimental__allow_timerfd_fork` manifest option.

LibOS regression tests are also added.

Signed-off-by: Kailun Qin <[email protected]>

Author: kailun-qin

Documentation/devel/features.md

@@ -1036,7 +1036,7 @@ The below list is generated from the [syscall table of Linux
 - ☒ `signalfd()`
   <sup>[7](#signals-and-process-state-changes)</sup>
 
-- ☒ `timerfd_create()`
+- ▣ `timerfd_create()`
   <sup>[20](#sleeps-timers-and-alarms)</sup>
 
 - ▣ `eventfd()`
@@ -1045,10 +1045,10 @@ The below list is generated from the [syscall table of Linux
 - ▣ `fallocate()`
   <sup>[9a](#file-system-operations)</sup>
 
-- ☒ `timerfd_settime()`
+- ▣ `timerfd_settime()`
   <sup>[20](#sleeps-timers-and-alarms)</sup>
 
-- ☒ `timerfd_gettime()`
+- ▣ `timerfd_gettime()`
   <sup>[20](#sleeps-timers-and-alarms)</sup>
 
 - ☑ `accept4()`
@@ -2862,9 +2862,21 @@ Gramine implements getting and setting the interval timer: `getitimer()` and `se
 
 Gramine implements alarm clocks via `alarm()`.
 
+Gramine implements timers that notify via file descriptors: `timerfd_create()`, `timerfd_settime()`
+and `timerfd_gettime()`. The timerfd object is created inside Gramine, and all operations are
+resolved entirely inside Gramine. Each timerfd object is associated with a dummy eventfd created on
+the host. This is purely for triggering read/write notifications (e.g., in epoll); timerfd data is
+verified inside Gramine and is never exposed to the host. Since the host is used purely for
+notifications, a malicious host can only induce Denial of Service (DoS) attacks.
+
+The emulation is currently implemented at the level of a single process. The emulation may work for
+multi-process applications, e.g., if the child process inherits the timerfd object but doesn't use
+it. However, multi-process support is brittle and thus disabled by default (Gramine will issue a
+warning). To enable it still, set the [`sys.experimental__allow_timerfd_fork` manifest
+option](../manifest-syntax.html#allowing-timerfd-in-multi-process-applications).
+
 Gramine does *not* currently implement the POSIX per-process timer: `timer_create()`, etc. Gramine
-also does not currently implement timers that notify via file descriptors. Gramine could implement
-these timers in the future, if need arises.
+could implement it in the future, if need arises.
 
 <details><summary>Related system calls</summary>
 
@@ -2880,9 +2892,9 @@ these timers in the future, if need arises.
 - ☒ `timer_getoverrun()`: may be implemented in the future
 - ☒ `timer_delete()`: may be implemented in the future
 
-- ☒ `timerfd_create()`: may be implemented in the future
-- ☒ `timerfd_settime()`: may be implemented in the future
-- ☒ `timerfd_gettime()`: may be implemented in the future
+- ▣ `timerfd_create()`: see notes above
+- ▣ `timerfd_settime()`: see notes above
+- ▣ `timerfd_gettime()`: see notes above
 
 </details><br />
 

Documentation/manifest-syntax.rst

@@ -364,6 +364,22 @@ Python). Could be useful in SGX environments: child processes consume
    to achieve this, you need to run the whole Gramine inside a proper security
    sandbox.
 
+.. _timerfd-in-multi-process:
+
+Allowing timerfd in multi-process applications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+    sys.experimental__allow_timerfd_fork = [true|false]
+    (Default: false)
+
+Gramine implements timerfd in a secure way, but this implementation works only
+in single-process applications. If you have a multi-process application and you
+are sure that the parent process and its child processes do not have
+cross-process usage of timerfd, you can use
+``sys.experimental__allow_timerfd_fork`` manifest syntax.
+
 Root FS mount point
 ^^^^^^^^^^^^^^^^^^^
 

libos/include/libos_fs.h

@@ -182,6 +182,10 @@ struct libos_fs_ops {
     /* Poll a single handle. Must not block. */
     int (*poll)(struct libos_handle* hdl, int in_events, int* out_events);
 
+    /* Verify a single handle after poll. Must update `pal_ret_events` in-place with only allowed
+     * ones. Used in e.g. secure timerfd FS. */
+    void (*post_poll)(struct libos_handle* hdl, pal_wait_flags_t* pal_ret_events);
+
     /* checkpoint/migrate the file system */
     ssize_t (*checkpoint)(void** checkpoint, void* mount_data);
     int (*migrate)(void* checkpoint, void** mount_data);
@@ -930,6 +934,7 @@ extern struct libos_fs eventfd_builtin_fs;
 extern struct libos_fs synthetic_builtin_fs;
 extern struct libos_fs path_builtin_fs;
 extern struct libos_fs shm_builtin_fs;
+extern struct libos_fs timerfd_builtin_fs;
 
 struct libos_fs* find_fs(const char* name);
 

libos/include/libos_handle.h

@@ -46,6 +46,7 @@ enum libos_handle_type {
     /* Special handles: */
     TYPE_EPOLL,      /* epoll handles, see `libos_epoll.c` */
     TYPE_EVENTFD,    /* eventfd handles, used by `eventfd` filesystem */
+    TYPE_TIMERFD,    /* timerfd handles, used by `timerfd` filesystem */
 };
 
 struct libos_pipe_handle {
@@ -134,6 +135,16 @@ struct libos_epoll_handle {
     size_t last_returned_index;
 };
 
+struct libos_timerfd_handle {
+    spinlock_t expiration_lock; /* protecting below fields */
+    uint64_t num_expirations;
+    uint64_t dummy_host_val;
+
+    spinlock_t timer_lock;
+    uint64_t timeout;
+    uint64_t reset;
+};
+
 struct libos_handle {
     enum libos_handle_type type;
     bool is_dir;
@@ -204,6 +215,7 @@ struct libos_handle {
 
         struct libos_epoll_handle epoll;         /* TYPE_EPOLL */
         struct { bool is_semaphore; } eventfd;   /* TYPE_EVENTFD */
+        struct libos_timerfd_handle timerfd;     /* TYPE_TIMERFD */
     } info;
 
     struct libos_dir_handle dir_info;

libos/include/libos_internal.h

@@ -262,3 +262,7 @@ int init_stack(const char* const* argv, const char* const* envp, char*** out_arg
  * The implementation of this function depends on the used architecture.
  */
 noreturn void call_elf_entry(elf_addr_t entry, void* argp);
+
+extern bool g_timerfd_allow_fork;
+extern uint32_t g_timerfd_cnt;
+int init_timerfd(void);

libos/include/libos_table.h

@@ -206,3 +206,7 @@ long libos_syscall_getcpu(unsigned* cpu, unsigned* node, void* unused_cache);
 long libos_syscall_getrandom(char* buf, size_t count, unsigned int flags);
 long libos_syscall_mlock2(unsigned long start, size_t len, int flags);
 long libos_syscall_sysinfo(struct sysinfo* info);
+long libos_syscall_timerfd_create(int clockid, int flags);
+long libos_syscall_timerfd_settime(int fd, int flags, const struct __kernel_itimerspec* value,
+                                   struct __kernel_itimerspec* ovalue);
+long libos_syscall_timerfd_gettime(int fd, struct __kernel_itimerspec* value);

libos/include/libos_utils.h

@@ -53,7 +53,7 @@ int create_pipe(char* name, char* uri, size_t size, PAL_HANDLE* hdl, bool use_vm
 
 /* Asynchronous event support */
 int init_async_worker(void);
-int64_t install_async_event(PAL_HANDLE object, unsigned long time,
+int64_t install_async_event(PAL_HANDLE object, unsigned long time, bool absolute_time,
                             void (*callback)(IDTYPE caller, void* arg), void* arg);
 struct libos_thread* terminate_async_worker(void);
 

libos/include/linux_abi/timerfd.h

@@ -0,0 +1,17 @@
+/* SPDX-License-Identifier: LGPL-3.0-or-later */
+/* Copyright (C) 2024 Intel Corporation
+ *                    Kailun Qin <[email protected]>
+ */
+
+#pragma once
+
+/* Types and structures used by various Linux ABIs (e.g. syscalls). */
+/* These need to be binary-identical with the ones used by Linux. */
+
+#include <linux/timerfd.h>
+
+#define TFD_SHARED_FCNTL_FLAGS (TFD_CLOEXEC | TFD_NONBLOCK)
+/* Flags for timerfd_create. */
+#define TFD_CREATE_FLAGS TFD_SHARED_FCNTL_FLAGS
+/* Flags for timerfd_settime. */
+#define TFD_SETTIME_FLAGS (TFD_TIMER_ABSTIME | TFD_TIMER_CANCEL_ON_SET)

libos/src/arch/x86_64/libos_table.c

@@ -297,11 +297,11 @@ libos_syscall_t libos_syscall_table[LIBOS_SYSCALL_BOUND] = {
     [__NR_utimensat]               = (libos_syscall_t)0, // libos_syscall_utimensat
     [__NR_epoll_pwait]             = (libos_syscall_t)libos_syscall_epoll_pwait,
     [__NR_signalfd]                = (libos_syscall_t)0, // libos_syscall_signalfd
-    [__NR_timerfd_create]          = (libos_syscall_t)0, // libos_syscall_timerfd_create
+    [__NR_timerfd_create]          = (libos_syscall_t)libos_syscall_timerfd_create,
     [__NR_eventfd]                 = (libos_syscall_t)libos_syscall_eventfd,
     [__NR_fallocate]               = (libos_syscall_t)libos_syscall_fallocate,
-    [__NR_timerfd_settime]         = (libos_syscall_t)0, // libos_syscall_timerfd_settime
-    [__NR_timerfd_gettime]         = (libos_syscall_t)0, // libos_syscall_timerfd_gettime
+    [__NR_timerfd_settime]         = (libos_syscall_t)libos_syscall_timerfd_settime,
+    [__NR_timerfd_gettime]         = (libos_syscall_t)libos_syscall_timerfd_gettime,
     [__NR_accept4]                 = (libos_syscall_t)libos_syscall_accept4,
     [__NR_signalfd4]               = (libos_syscall_t)0, // libos_syscall_signalfd4
     [__NR_eventfd2]                = (libos_syscall_t)libos_syscall_eventfd2,

libos/src/fs/libos_fs.c

@@ -33,6 +33,7 @@ static struct libos_fs* g_builtin_fs[] = {
     &synthetic_builtin_fs,
     &path_builtin_fs,
     &shm_builtin_fs,
+    &timerfd_builtin_fs,
 };
 
 static struct libos_lock g_mount_mgr_lock;