vfs.h

Go to the documentation of this file.

// MIT License
//
// Copyright (c) 2026 Christian Spoo
//
// Permission is hereby granted, free of charge, to any person obtaining a copy
// of this software and associated documentation files (the "Software"), to deal
// in the Software without restriction, including without limitation the rights
// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
// copies of the Software, and to permit persons to whom the Software is
// furnished to do so, subject to the following conditions:
//
// The above copyright notice and this permission notice shall be included in all
// copies or substantial portions of the Software.
//
// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
// SOFTWARE.
 
#ifndef _MINIOS_FS_VFS_H_
#define _MINIOS_FS_VFS_H_
 
#include <miniOS/types.h> 
 
#include <miniOS/fs/ext2.h>
#include <miniOS/fs/pipe.h>
 
#define VFS_MAX_FDS     64    /* max open files per task */
#define VFS_PATH_MAX   256    /* max path length */
#define VFS_FD_STDIN    0
#define VFS_FD_STDOUT   1
#define VFS_FD_STDERR   2
#define VFS_FIRST_OPEN_FD 3
 
/* File type flags stored in vfs_file */
#define VFS_FILE_TYPE_REG     1
#define VFS_FILE_TYPE_DIR     2
#define VFS_FILE_TYPE_PIPE    3  /* anonymous pipe backed by ring buffer */
#define VFS_FILE_TYPE_SYMLINK 4  /* symbolic link; used by lstat to detect symlink targets */
#define VFS_FILE_TYPE_CHAR    5  /* character device node */
#define VFS_FILE_TYPE_BLK     6  /* block device node */
#define VFS_FILE_TYPE_SOCKET  7  /* BSD-style socket backed by lwIP PCB */
#define VFS_FILE_TYPE_UNIX_SOCKET 8   /* AF_UNIX socket backed by unix_sock_t */
 
#define VFS_DEVICE_NONE 0
#define VFS_DEVICE_TTY  1
#define VFS_DEVICE_NULL 2
 
typedef struct vfs_inode_info {
    uint32_t inode;
    uint8_t  file_type;
    uint8_t  device_type;
    uint32_t dev;         /* encoded (major<<8)|minor for CHR/BLK nodes; 0 otherwise */
    uint64_t size;
    uint16_t mode;        /* lower 9 bits: rwxrwxrwx permission bits; 0 = unknown */
} vfs_inode_info_t;
 
/* Filesystem statistics — filled by the statfs vfs_ops callback */
typedef struct vfs_statfs {
    uint64_t f_type;    /* filesystem magic (e.g. 0xEF53 for ext2) */
    uint64_t f_bsize;   /* block size in bytes */
    uint64_t f_blocks;  /* total data blocks */
    uint64_t f_bfree;   /* free blocks */
    uint64_t f_bavail;  /* free blocks available to unprivileged user */
    uint64_t f_files;   /* total inodes */
    uint64_t f_ffree;   /* free inodes */
    uint64_t f_namelen; /* max filename length */
    uint64_t f_fsid;    /* unique per-mount id (stamped by vfs_statfs) */
} vfs_statfs_t;
 
/* A VFS ops table — one per mounted filesystem */
typedef struct vfs_ops {
    /* Look up path metadata, return 0 on success or -1 on not found */
    int (*lookup)(const char *path, vfs_inode_info_t *out);
    /* Read bytes from inode; returns bytes read or -1 */
    int (*read)(uint32_t ino, uint64_t off, void *buf, uint32_t len);
    /* Iterate directory entries at inode; calls cb per entry */
    int (*readdir)(uint32_t ino, uint64_t *offset, vfs_dirent_cb_t cb, void *ud);
    /* Write bytes to inode; returns bytes written or -1 */
    int (*write)(uint32_t ino, uint64_t off, const void *buf, uint32_t len);
    /* Flush inode metadata to disk; returns 0 on success or -1 */
    int (*flush)(uint32_t ino);
    /* Filesystem-specific file/directory creation and deletion.
     * NULL if the filesystem is read-only or does not support this operation. */
    int (*create)(uint32_t parent_ino, const char *name, uint16_t mode, uint32_t *new_ino_out);
    int (*unlink)(uint32_t parent_ino, const char *name);  /* file only; use rmdir for dirs */
    int (*rename)(uint32_t old_parent_ino, const char *old_name,
                  uint32_t new_parent_ino, const char *new_name);
    int (*mkdir)(uint32_t parent_ino, const char *name, uint32_t *new_ino_out);  /* dir creation; NULL if unsupported */
    int (*rmdir)(uint32_t parent_ino, const char *name);   /* empty dir removal; NULL if unsupported */
    /* Set the active root inode before path resolution; NULL if unused (e.g. ext2) */
    void (*set_root)(uint32_t root_ino);
    /* Truncate a regular file to zero bytes; returns 0 on success, -1 on error.
     * NULL if the filesystem does not support truncation. */
    int (*truncate)(uint32_t ino, uint64_t new_size);
    /* Read the target of a symlink inode into buf (max len bytes, NOT null-terminated
     * per POSIX readlink(2)). Returns bytes written (>= 0) or -1 on error.
     * NULL if the filesystem does not support symlinks. */
    int (*readlink)(uint32_t ino, char *buf, uint32_t len);
    /* Create a symlink named `name` in directory `parent_ino` pointing to `target`.
     * Returns 0 on success, -1 on error.
     * NULL if the filesystem does not support symlink creation. */
    int (*symlink)(uint32_t parent_ino, const char *name, const char *target);
    /* Create a device special file (char or block) named `name` in `parent_ino`.
     * @mode: EXT2_S_IFCHR|perms or EXT2_S_IFBLK|perms.
     * @dev:  Encoded device number (major<<8)|minor.
     * Returns 0 on success, -1 on error.
     * NULL if the filesystem does not support device node creation. */
    int (*mknod)(uint32_t parent_ino, const char *name, uint16_t mode,
                 uint32_t dev, uint32_t *new_ino_out);
    /* Change permission bits of an inode; @mode contains only the low 12 bits
     * (permissions + setuid/setgid/sticky). Returns 0 on success, -1 on error.
     * NULL if the filesystem does not support chmod. */
    int (*chmod)(uint32_t ino, uint16_t mode);
    /* Fill filesystem statistics; returns 0 on success, -1 on error.
     * NULL if the filesystem does not expose usage statistics. */
    int (*statfs)(vfs_statfs_t *out);
    /* Release any single-instance global state held by this filesystem so it
     * can be mounted again. Called by vfs_unregister_mount(). NULL if the
     * filesystem has no such state to release (e.g. tmpfs, sysfs). */
    void (*unmount)(void);
} vfs_ops_t;
 
/* Filesystem type registry — maps fstype names to mount callbacks */
#define VFS_MAX_FS_TYPES 16
 
typedef struct filesystem_type {
    char name[16];  /* e.g. "ext2", "sysfs", "tmpfs" */
    /* mount() — called by vfs_mount_fstype() to attach the filesystem.
     * @source: device or source identifier (may be NULL for pseudo-filesystems)
     * @target: absolute mount point path (e.g. "/", "/sys")
     * @data:   filesystem-specific options struct (may be NULL); cast to the
     *          appropriate type inside the callback (e.g. ext2_mount_data_t *)
     * The callback is responsible for calling vfs_register_mount() internally.
     * Returns 0 on success, negative errno on failure. */
    int (*mount)(const char *source, const char *target, const void *data);
} filesystem_type_t;
 
int register_filesystem(const char *name,
                        int (*mount)(const char *source, const char *target,
                                     const void *data));
int vfs_mount_fstype(const char *fstype, const char *source,
                     const char *target, const void *data);
 
/* Mount table entry — maps a mount point path to a filesystem ops table */
#define VFS_MAX_MOUNTS 16
 
typedef struct vfs_mount {
    char       mount_point[VFS_PATH_MAX]; /* e.g. "/" or "/tmp" */
    vfs_ops_t *ops;                        /* filesystem operations */
    uint32_t   root_ino;                   /* per-mount root inode (0 = fs default) */
    char       fstype[16];                 /* e.g. "ext2", "tmpfs", "proc" */
    char       device[32];                 /* e.g. "/dev/sda1" or fstype name for pseudo-fs */
} vfs_mount_t;

int vfs_register_mount(const char *point, vfs_ops_t *ops, uint32_t root_ino);

int vfs_unregister_mount(const char *point);
 
int vfs_mount_count(void);
const vfs_mount_t *vfs_get_mount(int idx);
int vfs_path_devno(const char *path);  /* 1-based mount index, 0 if not found */
int vfs_fd_devno(int fd);              /* 1-based mount index for open fd */
 
/* Forward declarations for socket types — avoids circular includes */
struct net_sock;
struct unix_sock;
 
/* An open file handle */
typedef struct vfs_file {
    uint8_t     in_use;
    uint32_t    inode;
    uint64_t    offset;     /* current read/write position */
    uint64_t    size;
    uint8_t     ftype;      /* VFS_FILE_TYPE_REG, VFS_FILE_TYPE_DIR, VFS_FILE_TYPE_PIPE, VFS_FILE_TYPE_CHAR */
    uint8_t     device_type; /* VFS_DEVICE_* for character devices */
    uint32_t    dev;         /* encoded (major<<8)|minor for CHR/BLK nodes; 0 otherwise */
    int         flags;         /* O_RDONLY (0) or O_WRONLY (1); set by vfs_open */
    int         status_flags;  /* O_NONBLOCK (0x800), O_APPEND (0x400), O_ASYNC (0x2000); mutable via fcntl F_SETFL */
    vfs_ops_t  *ops;
    uint32_t    ref_count;  /* number of fd slots pointing at this file description */
    pipe_t     *pipe;       /* non-NULL iff ftype == VFS_FILE_TYPE_PIPE */
    /* sock and usock share a slot: an fd is either a lwIP socket or AF_UNIX socket,
     * never both. Using a union keeps sizeof(vfs_file_t) exactly the same as
     * the original two-pointer layout. */
    union {
        struct net_sock  *sock;  /* non-NULL iff ftype == VFS_FILE_TYPE_SOCKET */
        struct unix_sock *usock; /* non-NULL iff ftype == VFS_FILE_TYPE_UNIX_SOCKET */
    };
} vfs_file_t;

void vfs_mount(vfs_ops_t *ops);

int vfs_open(const char *path, int flags, int mode);

int vfs_read(int fd, void *buf, uint32_t len);

int vfs_readdir(int fd, vfs_dirent_cb_t cb, void *ud);

int vfs_write(int fd, const void *buf, uint32_t len);

int vfs_close(int fd);

int vfs_unlink(const char *path);

int vfs_rename(const char *oldpath, const char *newpath);

int vfs_rmdir(const char *path);

int vfs_mkdir(const char *path, int mode);

int vfs_stat(const char *path, vfs_inode_info_t *out);
int vfs_statfs(const char *path, vfs_statfs_t *out);
int vfs_fstatfs(int fd, vfs_statfs_t *out);

int vfs_fstat(int fd, vfs_inode_info_t *out);

int vfs_lstat(const char *path, vfs_inode_info_t *out);

int vfs_symlink(const char *path, const char *target);

int vfs_chmod(const char *path, uint16_t mode);

int vfs_mknod(const char *path, uint16_t mode, uint32_t dev);

int vfs_readlink(const char *path, char *buf, uint32_t bufsiz);
 
#endif /* _MINIOS_FS_VFS_H_ */