SchOS/docs/architecture/filesystem.md

# The VFS

The layer between `open(2)` and a filesystem. SchFS is described separately in
[schfs.md](schfs.md); this is the machinery it plugs into, plus the buffer cache,
mounts, and procfs.

---

## `struct fs_ops`

A filesystem is a vtable, chosen by `iget()` from the device number and never
null once an inode is held.

```c
struct fs_ops {
  const char *name;

  void (*iload)   (struct inode *);          // fill type/size/nlink from disk
  void (*istore)  (struct inode *);          // write them back
  void (*ifree)   (struct inode *);          // last link gone, release it

  int  (*read)    (struct inode *, int user_dst, uint64 dst, uint64 off, uint n);
  int  (*write)   (struct inode *, int user_src, uint64 src, uint64 off, uint n);
  void (*truncate)(struct inode *, uint64 newsize);

  struct inode *(*dirlookup)(struct inode *dp, char *name, uint *poff);
  int  (*dirlink)  (struct inode *dp, char *name, uint64 inum);
  int  (*dirunlink)(struct inode *dp, char *name, uint off);
  int  (*dirempty) (struct inode *dp);

  struct inode *(*ialloc)(uint dev, short type);
  int  (*getdents)(struct inode *dp, char *out, int cap, uint64 *off);
};
```

Two implementations exist: `schfs_ops` (`kernel/fs/schfs/vfs.c`) and `procfs_ops`
(`kernel/fs/procfs.c`).

`poff` is deliberately **an opaque cookie** rather than a byte offset —
meaningful only to the same filesystem's `dirunlink`. A directory does not have
to be an array of fixed-size records for this interface to work.

`ialloc` creates an object **with no name**. The caller sets `nlink` and calls
`dirlink`; until it does, nothing can reach the object. If the caller dies in
between, the result is an unreferenced record that is harmless and, in SchFS,
never reaches the disk anyway — nothing is durable until the transaction commits.

### The one place the models disagree

The VFS inherited xv6's shape: allocate an inode, fill it in, link a name to it.
SchFS has no free-standing inode — an object exists because a record with its id
exists.

`nlink` is the sharper disagreement. **The VFS adjusts it itself** and then calls
`iupdate`, so SchFS's own link accounting is deliberately bypassed in the VFS
path: `schfs_dir_add`/`schfs_dir_del` are used rather than `schfs_link`/
`schfs_unlink`, and `iput`'s `ifree` hook releases the object once the VFS has
decided there are no names left.

> Two pieces of code counting links independently is precisely how a filesystem
> loses a file that is still referenced.

`nlink` is an `int`, not a `short`. SchFS stores a `uint32` and the narrower type
truncated it, so a file past 32767 names came back with a *negative* count — and
`iput` frees an object whose count reaches zero. Signed on purpose: `nlink--` on
a count that is somehow already zero should land somewhere a check can see it,
not wrap to four billion.

## Path resolution

`namex()` walks a path one component at a time. It was refactored into
`namex_from(struct inode *start, ...)`, parameterising what used to be a
hardcoded `idup(proc->cwd)`.

That refactor is what made the `*at()` family work. Every one of them — `openat`,
`fstatat`, `unlinkat`, `renameat`, `linkat`, `symlinkat`, `mkdirat`, `mknodat`,
`readlinkat`, `faccessat` — previously handled only two cases: `AT_FDCWD`, or an
absolute path with `dirfd` ignored. A **real** dirfd with a **relative** path is
the standard, efficient way any directory-tree walker avoids rebuilding full
path strings, and it was either rejected outright or — worse, in `openat` —
silently resolved against `proc->cwd`, which can open the wrong file entirely.

`sys_fs.c` now has `at_dir(dirfd)`, `at_namei()` and `at_nameiparent()`, and
every `*at()` call uses them.

## The buffer cache

`kernel/dev/bio.c`, xv6's design unchanged: a fixed pool of buffers, an LRU
list, one sleeplock per buffer. `bread()` returns a locked buffer; `bwrite()`
flushes it; `brelse()` releases.

**Sleeping is the point.** A buffer lock is held across a disk read, which is
why every path that touches a filesystem must be able to sleep — and why the
root mount happens in `forkret()` rather than in `main()`.

## Mounts

`mount()` and `umount2()` at their Linux numbers, with a mount table consulted
during path resolution. `/proc` is mounted by init:

```c
mount("proc", "/proc", "proc", 0, 0);
```

## procfs

`kernel/fs/procfs.c`. A real filesystem behind the same vtable, not a set of
character devices.

**The reason it had to become one is `ps`.** /proc used to be `mknod`'d nodes —
init ran `mknod("/proc/uptime", 6, 2)` and friends, so every file was a real
inode on the root filesystem with a major/minor behind it. That is fine for a
fixed list and cannot work at all for the thing /proc is mostly for: **one
directory per process**. You cannot `mknod` a directory for a process that does
not exist yet and will be gone in a minute. `ps` listed `/proc`, got no numbers,
and reported nothing. It was never a `ps` problem.

Nothing is stored. Directory listings are generated from the process table when
asked; file contents when read.

Three things worth knowing:

- **The split is deliberate.** `kernel/fs/procfs.c` owns the *namespace* — what
  exists. `kernel/dev/procfs.c` keeps the *generators* — what the global files
  say. They change for different reasons, and `proc_gen_global()` is the only
  thing that crosses between them.
- **procfs never walks the process table.** `proc_snapshot()` copies what is
  needed out from under `ptable.lock`, so a process that exits between the
  readdir that listed it and the open that reads it produces a stale line rather
  than a use-after-free.
- **Sizes are reported as zero**, exactly as Linux does. A synthetic file has no
  length until it is generated, and generating every one on every `stat()` to
  fill in a number almost nothing reads would be absurd.

### What is there

Per-process directories, plus the global files: `meminfo`, `uptime`, `cpuinfo`,
`version`, `stat`, `loadavg`, `mounts`, `filesystems`, `schfs`, `pci`,
`interrupts`, `devices`, `netif`, and `sysrq`.

**/proc is read-only except `sysrq`**, which is the one deliberate write target,
and the code says so in one place. Marking every procfs inode read-only once
broke `echo s > /proc/sysrq` and took out three USB checks within a minute —
they drive the disk through sysrq.

`sysrq` keys: `c` crash on purpose, `u` / `s` storage checks, `d` display
selftest, `t` text specimen, `n` the netdev ARP selftest.

---

## What it does not do

- **No page cache.** `mmap` of a file reads the whole thing in at map time, and
  writable `MAP_SHARED` of a file is refused rather than faked. This is the
  single largest gap in the layer.
- **No symlinks in procfs**, which is why `/proc/<pid>/exe` is a regular file
  and `ps -o comm` prints `[init]`.
- **No `AF_UNIX` socket inodes.** Socket names live in a table in
  `kernel/net/unix.c`, so `bind()` creates nothing that can be `stat()`ed or
  `unlink()`ed.
- **No unified inode cache across filesystems** beyond the single `itable`.
- **A known, un-root-caused hang:** heavy `ls -lR` use across many commands in
  one long shell session can eventually make a *later*, unrelated directory
  hang; the identical command succeeds on a fresh boot. It is not inode or file
  table exhaustion — both fail cleanly and neither fired. It smells like a lock
  or refcount leak in the `*at()` paths or in toybox's own fd handling. The next
  step is instrumenting `itable`/`ftable` occupancy across a long session to see
  what is climbing.
- **`sys_delete`/`sys_show`/`sys_showstat`** are orphaned entries from the old
  v1 filesystem's recycle bin. Nothing reaches them and they die with `fs.c`.