zvfs: improve libc FILE to integer fd abstraction

Previously, there was an implicit assumption that Zephyr's
internal struct fd_entry * was synonymous with FILE * from
the C library.

This is generally not the case and aliasing these two
distinct types was preventing a fair bit of functionality
from Just Working - namely stdio function calls like
fgets() and fopen(). The problem count be seen directly
when trying to use a function like zvfs_fdopen().

Instead of aliasing the two types, require that all Zephyr
C libraries provide

1. FILE *z_libc_file_alloc(int fd, const char *mode)
   Allocate and populate the required fields of a FILE object

2. int z_libc_file_get_fd(FILE *fp)
   Convert a FILE* object to an integer file descriptor.

For Picolibc and Newlib-based C libraries, these functions
set and get the integer file descriptor from a field of the
internal FILE object representation.

For the minimal C library, these functions convert between
array index and struct fd_entry pointers.

Includes changes necessary for tests to still pass.

Signed-off-by: Chris Friedt <[email protected]>
Co-authored-by: Jakub Klimczak <[email protected]>
Signed-off-by: Jakub Klimczak <[email protected]>

Author: cfriedt

include/zephyr/posix/unistd.h

@@ -25,7 +25,9 @@ extern "C" {
 /* File related operations */
 int close(int file);
 ssize_t write(int file, const void *buffer, size_t count);
+ssize_t pwrite(int file, const void *buffer, size_t count, off_t offset);
 ssize_t read(int file, void *buffer, size_t count);
+ssize_t pread(int fd, void *buf, size_t count, off_t offset);
 off_t lseek(int file, off_t offset, int whence);
 int fsync(int fd);
 int ftruncate(int fd, off_t length);

include/zephyr/sys/fdtable.h

@@ -14,6 +14,20 @@
 #include <zephyr/kernel.h>
 #include <zephyr/sys/util.h>
 
+/* FIXME: use k_off_t and k_ssize_t to avoid the POSIX->Zephyr->POSIX dependency cycle */
+#ifdef CONFIG_NEWLIB_LIBC
+#ifndef _OFF_T_DECLARED
+typedef _off_t off_t;
+#define _OFF_T_DECLARED
+#endif
+#ifndef _SSIZE_T_DECLARED
+typedef _ssize_t ssize_t;
+#define _SSIZE_T_DECLARED
+#endif
+#endif
+
+#include <stdio.h>
+
 #ifdef CONFIG_PICOLIBC
 #define ZVFS_O_APPEND 0x0400
 #define ZVFS_O_CREAT  0x0040
@@ -60,18 +74,6 @@
 extern "C" {
 #endif
 
-/* FIXME: use k_off_t and k_ssize_t to avoid the POSIX->Zephyr->POSIX dependency cycle */
-#ifdef CONFIG_NEWLIB_LIBC
-#ifndef _OFF_T_DECLARED
-typedef __off_t off_t;
-#define _OFF_T_DECLARED
-#endif
-#ifndef _SSIZE_T_DECLARED
-typedef _ssize_t ssize_t;
-#define _SSIZE_T_DECLARED
-#endif
-#endif
-
 /**
  * File descriptor virtual method table.
  * Currently all operations beyond read/write/close go thru ioctl method.
@@ -261,6 +263,12 @@ __syscall int zvfs_select(int nfds, struct zvfs_fd_set *ZRESTRICT readfds,
 			  struct zvfs_fd_set *ZRESTRICT errorfds,
 			  const struct timespec *ZRESTRICT timeout, const void *ZRESTRICT sigmask);
 
+void zvfs_libc_file_alloc_cb(int fd, const char *mode, FILE *fp);
+int zvfs_libc_file_alloc(int fd, const char *mode, FILE **fp, k_timeout_t timeout);
+void zvfs_libc_file_free(FILE *fp);
+int zvfs_libc_file_get_fd(FILE *fp);
+FILE *zvfs_libc_file_from_fd(int fd);
+
 /**
  * Request codes for fd_op_vtable.ioctl().
  *

lib/libc/common/CMakeLists.txt

@@ -20,6 +20,7 @@ zephyr_library_sources_ifdef(CONFIG_COMMON_LIBC_THRD
     source/thrd/tss.c
     )
 zephyr_library_sources_ifdef(CONFIG_COMMON_LIBC_REMOVE source/stdio/remove.c)
+zephyr_library_sources_ifdef(CONFIG_COMMON_LIBC_FCLOSE source/stdio/fclose.c)
 
 # Prevent compiler from optimizing calloc into an infinite recursive call
 zephyr_library_compile_options($<TARGET_PROPERTY:compiler,no_builtin_malloc>)

lib/libc/common/Kconfig

@@ -109,7 +109,7 @@ config COMMON_LIBC_THRD
 	depends on DYNAMIC_THREAD
 	# Note: the POSIX_API dependency is only necessary until common elements
 	# of C11 threads and POSIX API can be abstracted out to a common library.
-	depends on POSIX_API
+	depends on POSIX_THREADS
 	default y
 	help
 	  Common implementation of C11 <threads.h> API.
@@ -120,3 +120,9 @@ config COMMON_LIBC_REMOVE
 	default y if FILE_SYSTEM
 	help
 	  Common implementation of remove().
+
+config COMMON_LIBC_FCLOSE
+	bool "Common C library fclose"
+	default y if ZVFS && !MINIMAL_LIBC
+	help
+	  Enable the common C library implementation of fclose()

lib/libc/common/source/stdio/fclose.c

@@ -0,0 +1,25 @@
+/*
+ * Copyright (c) 2025 Antmicro <www.antmicro.com>
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/sys/fdtable.h>
+#include <unistd.h>
+
+int fclose(FILE *stream)
+{
+	int fd;
+
+	fflush(stream);
+	fd = zvfs_libc_file_get_fd(stream);
+
+	if (!fd) {
+		return EOF;
+	}
+	if (close(fd)) {
+		return EOF;
+	}
+
+	return 0;
+}

lib/libc/newlib/CMakeLists.txt

@@ -3,6 +3,8 @@
 zephyr_library()
 zephyr_library_sources(libc-hooks.c)
 
+zephyr_library_sources_ifdef(CONFIG_ZVFS zvfs_libc.c)
+
 # Do not allow LTO when compiling libc-hooks.c file
 set_source_files_properties(libc-hooks.c PROPERTIES COMPILE_OPTIONS $<TARGET_PROPERTY:compiler,prohibit_lto>)
 

lib/libc/newlib/Kconfig

@@ -80,4 +80,12 @@ config NEWLIB_LIBC_USE_POSIX_LIMITS_H
 	  Disable this option if your toolchain's newlib already includes all mandatory POSIX
 	  limits.
 
+if ZVFS
+
+config ZVFS_LIBC_FILE_SIZE
+	default 184 if 64BIT
+	default 104
+
+endif # ZVFS
+
 endif # NEWLIB_LIBC

lib/libc/newlib/libc-hooks.c

@@ -169,6 +169,9 @@ static int (*_stdout_hook)(int) = _stdout_hook_default;
 void __stdout_hook_install(int (*hook)(int))
 {
 	_stdout_hook = hook;
+#ifdef CONFIG_ZVFS
+	stdout->_file = 1; /* STDOUT_FILENO */
+#endif
 }
 
 static unsigned char _stdin_hook_default(void)
@@ -181,6 +184,9 @@ static unsigned char (*_stdin_hook)(void) = _stdin_hook_default;
 void __stdin_hook_install(unsigned char (*hook)(void))
 {
 	_stdin_hook = hook;
+#ifdef CONFIG_ZVFS
+	stdin->_file = 0; /* STDIN_FILENO */
+#endif
 }
 
 int z_impl_zephyr_read_stdin(char *buf, int nbytes)

lib/libc/newlib/zvfs_libc.c

@@ -0,0 +1,82 @@
+/*
+ * Copyright (c) 2024 Tenstorrent AI ULC
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+
+#include <zephyr/sys/fdtable.h>
+#include <zephyr/toolchain.h>
+
+BUILD_ASSERT(CONFIG_ZVFS_LIBC_FILE_SIZE >= sizeof(__FILE),
+	     "CONFIG_ZVFS_LIBC_FILE_SIZE must at least match size of FILE object");
+BUILD_ASSERT(CONFIG_ZVFS_LIBC_FILE_ALIGN == __alignof(__FILE),
+	     "CONFIG_ZVFS_LIBC_FILE_SIZE must match alignment of FILE object");
+
+static int z_libc_sflags(const char *mode)
+{
+	int ret = 0;
+
+	switch (mode[0]) {
+	case 'r':
+		ret = ZVFS_O_RDONLY;
+		break;
+
+	case 'w':
+		ret = ZVFS_O_WRONLY | ZVFS_O_CREAT | ZVFS_O_TRUNC;
+		break;
+
+	case 'a':
+		ret = ZVFS_O_WRONLY | ZVFS_O_CREAT | ZVFS_O_APPEND;
+		break;
+	default:
+		return 0;
+	}
+
+	while (*++mode) {
+		switch (*mode) {
+		case '+':
+			ret |= ZVFS_O_RDWR;
+			break;
+		case 'x':
+			ret |= ZVFS_O_EXCL;
+			break;
+		default:
+			break;
+		}
+	}
+
+	return ret;
+}
+
+void zvfs_libc_file_alloc_cb(int fd, const char *mode, FILE *fp)
+{
+	/*
+	 * These symbols have conflicting declarations in upstream headers.
+	 * Use uintptr_t and a cast to assign cleanly.
+	 */
+	extern uintptr_t _close_r;
+	extern uintptr_t _lseek_r;
+	extern uintptr_t _read_r;
+	extern uintptr_t _write_r;
+
+	__ASSERT_NO_MSG(mode != NULL);
+	__ASSERT_NO_MSG(fp != NULL);
+
+	fp->_flags = z_libc_sflags(mode);
+	fp->_file = fd;
+	fp->_cookie = (void *)fp;
+
+	*(uintptr_t *)&fp->_read = (uintptr_t)&_read_r;
+	*(uintptr_t *)&fp->_write = (uintptr_t)&_write_r;
+	*(uintptr_t *)&fp->_seek = (uintptr_t)&_lseek_r;
+	*(uintptr_t *)&fp->_close = (uintptr_t)&_close_r;
+}
+
+int zvfs_libc_file_get_fd(FILE *fp)
+{
+	return fp->_file;
+}

lib/libc/picolibc/CMakeLists.txt

@@ -11,6 +11,8 @@ zephyr_library_sources(
   stdio.c
   )
 
+zephyr_library_sources_ifdef(CONFIG_ZVFS zvfs_libc.c)
+
 zephyr_library_compile_options($<TARGET_PROPERTY:compiler,prohibit_lto>)
 
 # define __LINUX_ERRNO_EXTENSIONS__ so we get errno defines like -ESHUTDOWN