feat: extend PPME_SYSCALL_TIMERFD_CREATE_X with enter parameters

ekoops · poiana · commit 04ca7f18139e · 2025-06-27T12:05:59.000+02:00
Add `PPME_SYSCALL_TIMERFD_CREATE_E` parameters to
`PPME_SYSCALL_TIMERFD_CREATE_X` event definition and align all 3
kernel drivers to it.

Add new rules to scap file converter table to convert events in old
scap files to the new layout.

Add/update timerfd_create-related drivers, scap converter and sinsp
parser tests to account the new layout.

Signed-off-by: Leonardo Di Giovanna &lt;leonardodigiovanna1@gmail.com&gt;
diff --git a/driver/SCHEMA_VERSION b/driver/SCHEMA_VERSION
@@ -1 +1 @@
-3.56.0
+3.57.0
diff --git a/driver/bpf/fillers.h b/driver/bpf/fillers.h
@@ -3987,6 +3987,22 @@ FILLER(sys_io_uring_register_x, true) {
 	return bpf_push_u32_to_ring(data, nr_args);
 }
 
+FILLER(sys_timerfd_create_x, true) {
+	/* Parameter 1: res (type: PT_FD) */
+	int64_t retval = (int64_t)(int32_t)bpf_syscall_get_retval(data->ctx);
+	int res = bpf_push_s64_to_ring(data, retval);
+	CHECK_RES(res);
+
+	/* Parameter 2: clockid (type: PT_UINT8) */
+	/* Send `0`. */
+	res = bpf_push_u8_to_ring(data, 0);
+	CHECK_RES(res);
+
+	/* Parameter 3: flags (type: PT_UINT8) */
+	/* Send `0`. */
+	return bpf_push_u8_to_ring(data, 0);
+}
+
 FILLER(sys_inotify_init_e, true) {
 	/* Parameter 1: flags (type: PT_UINT8) */
 	/* We have nothing to extract from the kernel here so we send `0`.
diff --git a/driver/event_table.c b/driver/event_table.c
@@ -801,15 +801,19 @@ const struct ppm_event_info g_event_info[] = {
                                        {"interval", PT_RELTIME, PF_DEC}}},
         [PPME_SYSCALL_TIMERFD_CREATE_E] = {"timerfd_create",
                                            EC_TIME | EC_SYSCALL,
-                                           EF_CREATES_FD | EF_MODIFIES_STATE,
+                                           EF_CREATES_FD | EF_MODIFIES_STATE |
+                                                   EF_TMP_CONVERTER_MANAGED,
                                            2,
                                            {{"clockid", PT_UINT8, PF_DEC},
                                             {"flags", PT_UINT8, PF_HEX}}},
         [PPME_SYSCALL_TIMERFD_CREATE_X] = {"timerfd_create",
                                            EC_TIME | EC_SYSCALL,
-                                           EF_CREATES_FD | EF_MODIFIES_STATE,
-                                           1,
-                                           {{"res", PT_FD, PF_DEC}}},
+                                           EF_CREATES_FD | EF_MODIFIES_STATE |
+                                                   EF_TMP_CONVERTER_MANAGED,
+                                           3,
+                                           {{"res", PT_FD, PF_DEC},
+                                            {"clockid", PT_UINT8, PF_DEC},
+                                            {"flags", PT_UINT8, PF_HEX}}},
         [PPME_SYSCALL_INOTIFY_INIT_E] = {"inotify_init",
                                          EC_IPC | EC_SYSCALL,
                                          EF_CREATES_FD | EF_MODIFIES_STATE,
diff --git a/driver/fillers_table.c b/driver/fillers_table.c
@@ -144,7 +144,7 @@ const struct ppm_event_entry g_ppm_events[PPM_EVENT_MAX] = {
                                            2,
                                            APT_REG,
                                            {{AF_ID_USEDEFAULT, 0}, {AF_ID_USEDEFAULT, 0}}},
-        [PPME_SYSCALL_TIMERFD_CREATE_X] = {FILLER_REF(sys_single_x)},
+        [PPME_SYSCALL_TIMERFD_CREATE_X] = {FILLER_REF(sys_timerfd_create_x)},
         [PPME_SYSCALL_INOTIFY_INIT_E] = {FILLER_REF(sys_inotify_init_e)},
         [PPME_SYSCALL_INOTIFY_INIT_X] = {FILLER_REF(sys_single_x)},
         [PPME_SYSCALL_GETRLIMIT_E] = {FILLER_REF(sys_getrlimit_setrlimit_e)},
diff --git a/driver/modern_bpf/definitions/events_dimensions.h b/driver/modern_bpf/definitions/events_dimensions.h
@@ -91,7 +91,7 @@
 #define NANOSLEEP_E_SIZE HEADER_LEN + sizeof(uint64_t) + PARAM_LEN
 #define NANOSLEEP_X_SIZE HEADER_LEN + sizeof(int64_t) + sizeof(uint64_t) + PARAM_LEN * 2
 #define TIMERFD_CREATE_E_SIZE HEADER_LEN + sizeof(uint8_t) * 2 + PARAM_LEN * 2
-#define TIMERFD_CREATE_X_SIZE HEADER_LEN + sizeof(int64_t) + PARAM_LEN
+#define TIMERFD_CREATE_X_SIZE HEADER_LEN + sizeof(int64_t) + sizeof(uint8_t) * 2 + PARAM_LEN * 3
 #define INOTIFY_INIT_E_SIZE HEADER_LEN + sizeof(uint8_t) + PARAM_LEN
 #define INOTIFY_INIT_X_SIZE HEADER_LEN + sizeof(int64_t) + PARAM_LEN
 #define GETRLIMIT_E_SIZE HEADER_LEN + sizeof(uint8_t) + PARAM_LEN
diff --git a/driver/modern_bpf/programs/tail_called/events/syscall_dispatched_events/timerfd_create.bpf.c b/driver/modern_bpf/programs/tail_called/events/syscall_dispatched_events/timerfd_create.bpf.c
@@ -51,9 +51,17 @@ int BPF_PROG(timerfd_create_x, struct pt_regs *regs, long ret) {
 
 	/*=============================== COLLECT PARAMETERS  ===========================*/
 
-	/* Parameter 1: res (type: PT_FD)*/
+	/* Parameter 1: res (type: PT_FD) */
 	ringbuf__store_s64(&ringbuf, ret);
 
+	/* Parameter 2: clockid (type: PT_UINT8) */
+	/* Like in the old probe we send `0` */
+	ringbuf__store_u8(&ringbuf, 0);
+
+	/* Parameter 3: flags (type: PT_UINT8) */
+	/* Like in the old probe we send `0` */
+	ringbuf__store_u8(&ringbuf, 0);
+
 	/*=============================== COLLECT PARAMETERS  ===========================*/
 
 	ringbuf__submit_event(&ringbuf);
diff --git a/driver/ppm_fillers.c b/driver/ppm_fillers.c
@@ -6524,6 +6524,28 @@ int f_sys_io_uring_register_x(struct event_filler_arguments *args) {
 	return add_sentinel(args);
 }
 
+int f_sys_timerfd_create_x(struct event_filler_arguments *args) {
+	int64_t retval;
+	int res;
+
+	/* Parameter 1: res (type: PT_FD) */
+	retval = (int64_t)(int32_t)syscall_get_return_value(current, args->regs);
+	res = val_to_ring(args, retval, 0, false, 0);
+	CHECK_RES(res);
+
+	/* Parameter 2: clockid (type: PT_UINT8) */
+	/* Send `0`. */
+	res = val_to_ring(args, 0, 0, false, 0);
+	CHECK_RES(res);
+
+	/* Parameter 3: flags (type: PT_UINT8) */
+	/* Send `0`. */
+	res = val_to_ring(args, 0, 0, false, 0);
+	CHECK_RES(res);
+
+	return add_sentinel(args);
+}
+
 int f_sys_inotify_init_e(struct event_filler_arguments *args) {
 	/* Parameter 1: flags (type: PT_UINT8) */
 	/* We have nothing to extract from the kernel here so we send `0`.
diff --git a/driver/ppm_fillers.h b/driver/ppm_fillers.h
@@ -208,6 +208,7 @@ or GPL2.txt for full copies of the license.
 	FN(sys_umount2_e)                    \
 	FN(sys_umount2_x)                    \
 	FN(sys_pipe2_x)                      \
+	FN(sys_timerfd_create_x)             \
 	FN(sys_inotify_init_e)               \
 	FN(sys_inotify_init1_x)              \
 	FN(sys_eventfd2_e)                   \
diff --git a/test/drivers/test_suites/syscall_exit_suite/timerfd_create_x.cpp b/test/drivers/test_suites/syscall_exit_suite/timerfd_create_x.cpp
@@ -35,8 +35,16 @@ TEST(SyscallExit, timerfd_createX) {
 	/* Parameter 1: res (type: PT_FD) */
 	evt_test->assert_numeric_param(1, (int64_t)errno_value);
 
+	/* Parameter 2: clockid (type: PT_UINT8) */
+	// We always send 0 from drivers.
+	evt_test->assert_numeric_param(2, (uint8_t)0);
+
+	/* Parameter 3: flags (type: PT_FLAGS8) */
+	// We always send 0 from drivers.
+	evt_test->assert_numeric_param(3, (uint8_t)0);
+
 	/*=============================== ASSERT PARAMETERS  ===========================*/
 
-	evt_test->assert_num_params_pushed(1);
+	evt_test->assert_num_params_pushed(3);
 }
 #endif
diff --git a/test/libscap/test_suites/engines/savefile/converter.cpp b/test/libscap/test_suites/engines/savefile/converter.cpp
@@ -493,6 +493,71 @@ TEST_F(convert_event_test, PPME_SYSCALL_NANOSLEEP_X_1_to_2_params_with_enter) {
 	        create_safe_scap_event(ts, tid, PPME_SYSCALL_NANOSLEEP_X, 2, res, interval));
 }
 
+////////////////////////////
+// TIMERFD_CREATE
+////////////////////////////
+
+TEST_F(convert_event_test, PPME_SYSCALL_TIMERFD_CREATE_E_store) {
+	constexpr uint64_t ts = 12;
+	constexpr int64_t tid = 25;
+
+	constexpr uint8_t clock_id = 10;
+	constexpr uint8_t flags = 20;
+
+	const auto evt =
+	        create_safe_scap_event(ts, tid, PPME_SYSCALL_TIMERFD_CREATE_E, 2, clock_id, flags);
+	assert_single_conversion_skip(evt);
+	assert_event_storage_presence(evt);
+}
+
+TEST_F(convert_event_test, PPME_SYSCALL_TIMERFD_CREATE_X_1_to_3_params_no_enter) {
+	constexpr uint64_t ts = 12;
+	constexpr int64_t tid = 25;
+
+	constexpr int64_t res = 89;
+
+	// Defaulted to 0
+	constexpr uint8_t clock_id = 0;
+	constexpr uint8_t flags = 0;
+
+	assert_single_conversion_success(
+	        conversion_result::CONVERSION_COMPLETED,
+	        create_safe_scap_event(ts, tid, PPME_SYSCALL_TIMERFD_CREATE_X, 1, res),
+	        create_safe_scap_event(ts,
+	                               tid,
+	                               PPME_SYSCALL_TIMERFD_CREATE_X,
+	                               3,
+	                               res,
+	                               clock_id,
+	                               flags));
+}
+
+TEST_F(convert_event_test, PPME_SYSCALL_TIMERFD_CREATE_X_1_to_3_params_with_enter) {
+	constexpr uint64_t ts = 12;
+	constexpr int64_t tid = 25;
+
+	constexpr uint8_t clock_id = 10;
+	constexpr uint8_t flags = 20;
+	constexpr int64_t res = 89;
+
+	// After the first conversion we should have the storage
+	const auto evt =
+	        create_safe_scap_event(ts, tid, PPME_SYSCALL_TIMERFD_CREATE_E, 2, clock_id, flags);
+	assert_single_conversion_skip(evt);
+	assert_event_storage_presence(evt);
+
+	assert_single_conversion_success(
+	        conversion_result::CONVERSION_COMPLETED,
+	        create_safe_scap_event(ts, tid, PPME_SYSCALL_TIMERFD_CREATE_X, 1, res),
+	        create_safe_scap_event(ts,
+	                               tid,
+	                               PPME_SYSCALL_TIMERFD_CREATE_X,
+	                               3,
+	                               res,
+	                               clock_id,
+	                               flags));
+}
+
 ////////////////////////////
 // GETRLIMIT
 ////////////////////////////
diff --git a/test/libsinsp_e2e/sys_call_test.cpp b/test/libsinsp_e2e/sys_call_test.cpp
@@ -491,6 +491,8 @@ TEST_F(sys_call_test, timerfd) {
 			callnum++;
 		} else if(type == PPME_SYSCALL_TIMERFD_CREATE_X) {
 			EXPECT_EQ(fd, std::stoll(e->get_param_value_str("res", false)));
+			EXPECT_EQ(0, std::stoll(e->get_param_value_str("clockid")));
+			EXPECT_EQ(0, std::stoll(e->get_param_value_str("flags")));
 			callnum++;
 		} else if(type == PPME_SYSCALL_READ_E) {
 			if(callnum == 2) {
diff --git a/userspace/libscap/engine/gvisor/fillers.cpp b/userspace/libscap/engine/gvisor/fillers.cpp
@@ -1362,13 +1362,17 @@ int32_t fill_event_timerfd_create_e(scap_sized_buffer scap_buf,
 int32_t fill_event_timerfd_create_x(scap_sized_buffer scap_buf,
                                     size_t* event_size,
                                     char* scap_err,
-                                    int64_t res) {
+                                    int64_t res,
+                                    uint8_t clockid,
+                                    uint8_t flags) {
 	return scap_event_encode_params(scap_buf,
 	                                event_size,
 	                                scap_err,
 	                                PPME_SYSCALL_TIMERFD_CREATE_X,
-	                                1,
-	                                res);
+	                                3,
+	                                res,
+	                                clockid,
+	                                flags);
 }
 
 // PPME_SYSCALL_INOTIFY_INIT_E
diff --git a/userspace/libscap/engine/gvisor/fillers.h b/userspace/libscap/engine/gvisor/fillers.h
@@ -489,7 +489,9 @@ int32_t fill_event_timerfd_create_e(scap_sized_buffer scap_buf,
 int32_t fill_event_timerfd_create_x(scap_sized_buffer scap_buf,
                                     size_t* event_size,
                                     char* scap_err,
-                                    int64_t res);
+                                    int64_t res,
+                                    uint8_t clockid,
+                                    uint8_t flags);
 
 int32_t fill_event_inotify_init_e(scap_sized_buffer scap_buf,
                                   size_t* event_size,
diff --git a/userspace/libscap/engine/gvisor/parsers.cpp b/userspace/libscap/engine/gvisor/parsers.cpp
@@ -1769,7 +1769,9 @@ static parse_result parse_timerfd_create(uint32_t id,
 		ret.status = scap_gvisor::fillers::fill_event_timerfd_create_x(scap_buf,
 		                                                               &ret.size,
 		                                                               scap_err,
-		                                                               gvisor_evt.exit().result());
+		                                                               gvisor_evt.exit().result(),
+		                                                               gvisor_evt.clock_id(),
+		                                                               gvisor_evt.flags());
 	} else {
 		ret.status = scap_gvisor::fillers::fill_event_timerfd_create_e(scap_buf,
 		                                                               &ret.size,
diff --git a/userspace/libscap/engine/savefile/converter/table.cpp b/userspace/libscap/engine/savefile/converter/table.cpp
@@ -72,6 +72,13 @@ const std::unordered_map<conversion_key, conversion_info> g_conversion_table = {
         {conversion_key{PPME_SYSCALL_NANOSLEEP_E, 1}, conversion_info().action(C_ACTION_STORE)},
         {conversion_key{PPME_SYSCALL_NANOSLEEP_X, 1},
          conversion_info().action(C_ACTION_ADD_PARAMS).instrs({{C_INSTR_FROM_ENTER, 0}})},
+        /*====================== TIMERFD_CREATE ======================*/
+        {conversion_key{PPME_SYSCALL_TIMERFD_CREATE_E, 2},
+         conversion_info().action(C_ACTION_STORE)},
+        {conversion_key{PPME_SYSCALL_TIMERFD_CREATE_X, 1},
+         conversion_info()
+                 .action(C_ACTION_ADD_PARAMS)
+                 .instrs({{C_INSTR_FROM_ENTER, 0}, {C_INSTR_FROM_ENTER, 1}})},
         /*====================== GETRLIMIT ======================*/
         {conversion_key{PPME_SYSCALL_GETRLIMIT_E, 1}, conversion_info().action(C_ACTION_STORE)},
         {conversion_key{PPME_SYSCALL_GETRLIMIT_X, 3},
diff --git a/userspace/libscap/scap.h b/userspace/libscap/scap.h
@@ -102,7 +102,7 @@ struct scap_vtable;
 // and handle the result
 //
 #define SCAP_MINIMUM_DRIVER_API_VERSION PPM_API_VERSION(8, 0, 0)
-#define SCAP_MINIMUM_DRIVER_SCHEMA_VERSION PPM_API_VERSION(3, 56, 0)
+#define SCAP_MINIMUM_DRIVER_SCHEMA_VERSION PPM_API_VERSION(3, 57, 0)
 
 //
 // This is the dimension we used before introducing the variable buffer size.
diff --git a/userspace/libsinsp/test/events_file.ut.cpp b/userspace/libsinsp/test/events_file.ut.cpp
@@ -273,7 +273,13 @@ TEST_F(sinsp_with_test_input, creates_fd_generic) {
 	                     2,
 	                     (uint8_t)0,
 	                     (uint8_t)0);
-	evt = add_event_advance_ts(increasing_ts(), 1, PPME_SYSCALL_TIMERFD_CREATE_X, 1, fd);
+	evt = add_event_advance_ts(increasing_ts(),
+	                           1,
+	                           PPME_SYSCALL_TIMERFD_CREATE_X,
+	                           3,
+	                           fd,
+	                           (uint8_t)0,
+	                           (uint8_t)0);
 	ASSERT_EQ(get_field_as_string(evt, "fd.type"), "timerfd");
 	ASSERT_EQ(get_field_as_string(evt, "fd.typechar"), "t");
 	ASSERT_EQ(get_field_as_string(evt, "fd.num"), "6");
diff --git a/userspace/libsinsp/test/parsers/parse_timerfd_create.cpp b/userspace/libsinsp/test/parsers/parse_timerfd_create.cpp
@@ -0,0 +1,50 @@
+
+// SPDX-License-Identifier: Apache-2.0
+/*
+Copyright (C) 2025 The Falco Authors.
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+    http://www.apache.org/licenses/LICENSE-2.0
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+
+#include <sinsp_with_test_input.h>
+
+TEST_F(sinsp_with_test_input, TIMERFD_CREATE_success) {
+	add_default_init_thread();
+	open_inspector();
+
+	constexpr int64_t return_value = 60;
+	constexpr uint8_t clock_id = 0;
+	constexpr uint8_t flags = 0;
+
+	const auto evt = add_event_advance_ts(increasing_ts(),
+	                                      INIT_TID,
+	                                      PPME_SYSCALL_TIMERFD_CREATE_X,
+	                                      3,
+	                                      return_value,
+	                                      clock_id,
+	                                      flags);
+
+	// Check that the returned value is as expected.
+	ASSERT_EQ(evt->get_param_by_name("res")->as<int64_t>(), return_value);
+	// Check that the clockid value is as expected.
+	ASSERT_EQ(evt->get_param_by_name("clockid")->as<uint8_t>(), clock_id);
+	// Check that the flags value is as expected.
+	ASSERT_EQ(evt->get_param_by_name("flags")->as<uint8_t>(), flags);
+
+	// Check that fd info associated with the event are as expected.
+	auto fdinfo = evt->get_fd_info();
+	ASSERT_TRUE(fdinfo);
+
+	// Check that fd info associated with the thread are as expected.
+	const auto init_tinfo = m_inspector.m_thread_manager->get_thread_ref(INIT_TID, false).get();
+	ASSERT_TRUE(init_tinfo);
+	fdinfo = init_tinfo->get_fd(return_value);
+	ASSERT_TRUE(fdinfo);
+}
diff --git a/userspace/libsinsp/test/scap_files/converter_tests.cpp b/userspace/libsinsp/test/scap_files/converter_tests.cpp
@@ -327,6 +327,12 @@ TEST_F(scap_file_test, nanosleep_x_check_final_converted_event) {
 	        create_safe_scap_event(ts, tid, PPME_SYSCALL_NANOSLEEP_X, 2, res, interval));
 }
 
+////////////////////////////
+// TIMERFD_CREATE
+////////////////////////////
+
+// We don't have scap-files with TIMERFD_CREATE events. Add it if we face a failure.
+
 ////////////////////////////
 // GETRLIMIT
 ////////////////////////////
