samples: timerfd: add sample and readme

Add the timerfd sample and README file.

The timerfd follows a similar behavior as specified in other
POSIX OS.

Signed-off-by: Marco Casaroli <marco.casaroli@gmail.com>

Author: casaroli

samples/posix/timerfd/CMakeLists.txt

@@ -0,0 +1,8 @@
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.20.0)
+
+find_package(Zephyr REQUIRED HINTS $ENV{ZEPHYR_BASE})
+project(timerfd)
+
+target_sources(app PRIVATE src/main.c)

samples/posix/timerfd/Makefile.host

@@ -0,0 +1,5 @@
+# This makefile builds the sample for a POSIX system, like Linux
+
+timerfd: src/main.c
+	mkdir -p build
+	$(CC) $^ -o build/$@

samples/posix/timerfd/README.rst

@@ -0,0 +1,41 @@
+.. zephyr:code-sample:: posix-timerfd
+   :name: timerfd_create()
+
+   Use ``timerfd_create()`` to create a file descriptor for timer notification.
+
+Overview
+********
+
+This sample application demonstrates using the POSIX timerfd_create() functions to create a file
+descriptor, which can be used as a timer. The returned file descriptor is used with read calls
+and the timeout count are printed to the console.
+
+Building and Running
+********************
+
+This project outputs to the console. It can be built and executed on QEMU as follows:
+
+.. zephyr-app-commands::
+   :zephyr-app: samples/posix/timerfd
+   :host-os: unix
+   :board: qemu_x86
+   :goals: run
+   :compact:
+
+For comparison, to build directly for your host OS if it is POSIX compliant (for ex. Linux):
+
+.. code-block:: console
+
+   cd samples/posix/timerfd
+   make -f Makefile.host
+
+The make output file will be located in samples/posix/timerfd/build.
+
+Sample Output
+=============
+
+.. code-block:: console
+
+    Timer expired 1 times
+    Timer expired 3 times
+    Timer closed

samples/posix/timerfd/prj.conf

@@ -0,0 +1,4 @@
+# General config
+CONFIG_REQUIRES_FULL_LIBC=y
+CONFIG_POSIX_API=y
+CONFIG_TIMERFD=y

samples/posix/timerfd/sample.yaml

@@ -0,0 +1,21 @@
+sample:
+  description: Extended POSIX (Linux) API timerfd() example
+  name: timerfd
+common:
+  filter: CONFIG_FULL_LIBC_SUPPORTED and not CONFIG_NATIVE_LIBC
+  tags: posix
+  platform_exclude: m2gl025_miv
+  integration_platforms:
+    - mps2/an385
+tests:
+  sample.posix.timerfd:
+    min_ram: 32
+    tags: posix
+    harness: console
+    harness_config:
+      type: multi_line
+      ordered: true
+      regex:
+        - "Timer expired 1 times"
+        - "Timer expired 3 times"
+        - "Timer closed"

samples/posix/timerfd/src/main.c

@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) 2025 Atym, Inc.
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ *
+ * This sample application is roughly based on the sample code in Linux
+ * manpage for timerfd().
+ */
+#include <sys/timerfd.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <stdint.h>
+#include <inttypes.h>
+
+#define fatal(msg) \
+	do { perror(msg); exit(EXIT_FAILURE); } while (0)
+
+void read_now(int fd)
+{
+    uint64_t count;
+
+    /* read the number of times the timer has expired */
+	int bytes_read = read(fd, &count, sizeof(count));
+	if (bytes_read == -1) {
+		fatal("read");
+	}
+	printf("Timer expired %" PRIu64 " times\n", count);
+}
+
+int main(void)
+{
+    /* create the timer file descriptor */
+	int tfd = timerfd_create(0, 0);
+	if (tfd == -1) {
+		fatal("timerfd_create");
+	}
+
+	/* arm a recurring timer for 1 second */
+	struct itimerspec timer_spec = {
+        .it_interval = { .tv_sec = 1, .tv_nsec = 0 },
+        .it_value = { .tv_sec = 1, .tv_nsec = 0 }
+    };
+
+    int rc = timerfd_settime(tfd, 0, &timer_spec, NULL);
+
+	if (rc == -1) {
+		fatal("timerfd_settime");
+	}
+
+	/* read the number of times the timer has expired */
+	/* will block until the timer expires */
+	read_now(tfd);
+
+	/* if we wait long enough, the timer will expire more than once */
+	sleep(3);
+
+	/* the function will not block as the timer already expired */
+	read_now(tfd);
+
+	close(tfd);
+
+	printf("Timer closed\n");
+
+	return 0;
+}