SchOS/docs/architecture/filesystem.md

The VFS

The layer between open(2) and a filesystem. SchFS is described separately in 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.

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);

  uint max_write;          // largest write in one call; 0 for no limit
  uint refuse_types;       // 1 << T_* the filesystem cannot store: EPERM
  int  no_hardlinks;       // link() fails with EPERM
};

The implementations: schfs_ops (kernel/fs/schfs/vfs.c), fat_ops (kernel/fs/fat/fat.c, see fat.md), procfs_ops (kernel/fs/procfs.c) and devfs_ops (kernel/fs/devfs.c).

Creation can fail, and is undone when it does. ialloc and dirlink used to panic on failure, because on v1 and SchFS they cannot fail for a reason the caller could have avoided. FAT can: the volume fills, the fixed root directory of FAT16 holds 512 names, a name holds a character FAT does not allow. So createat_x() gives the object back and reports ENOSPC, EINVAL, EPERM or EROFS, and open, mkdir, mknod and symlink return that errno instead of ENOENT.

A short write is a full disk. filewrite() panicked on one, which held as long as no filesystem ever wrote short. Now write(2) returns what went in, and the next call gets the error.

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:

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

The filesystem types are proc, devtmpfs, schfs and vfat (also accepted as msdos and fat). Unmounting a FAT volume while anything on it is open, or is some process's working directory, fails with EBUSY.

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.

devtmpfs

/dev is generated, not stored. kernel/fs/devfs.c, behind the same fs_ops vtable, mounted by init with mount("dev", "/dev", "devtmpfs", 0, 0).

It used to be twenty mknod() calls in cmd/schinit, which was wrong twice over:

The cost. Every node was a real inode on the root filesystem, and SchFS commits each mutation as its own transaction group — a copy-on-write rewrite of the path to the root, then an uberblock behind a cache flush. Measured at 2600 ms of a first boot, spent before init printed its first line. On later boots the nodes already existed and the same code took 0 ms, so the cost was invisible to anyone not building fresh images — which is to say, invisible to everyone except whoever works on the system.

The duplication, which matters more. Major and minor numbers are the kernel's: they are what devsw[] in kernel/dev/cdev.c dispatches on. init held a second copy of that mapping and nothing checked the two agreed. Adding a character device meant editing a userspace program, and a wrong minor there produced a node that opened successfully and did nothing.

The table now sits next to the thing it describes. The namespace is all devfs provides — reads and writes never reach it, because fileread/filewrite see T_DEV and dispatch through devsw themselves.

It is read-only: dirlink and ialloc answer EROFS rather than pretending. A node exists because the kernel has the device, or it does not exist.

What is there

console, null, keyboard, zero, full, random, urandom, tty, stdin, stdout, stderr, fb0, mouse, hda, hdb, and input/event0 and input/event1 in one subdirectory.

Every disk and partition the block layer registered is there too, under the name it was given (sata0, sata0p2, nvme0p1, usb0p1): major 8, minor its block device number, listed only while it is present. Reads and writes go through blkdev_xfer in whole sectors, end at the end of the device, and do not pass through the buffer cache. A partition need not be a whole number of 4 KB blocks, and the buffer cache's last block of one would run into the next. Minors under major 1 follow Linux's mem-major layout where it costs nothing.

The raw disks are created whether or not a drive is present: opening one with nothing behind it fails with ENXIO, which is a better answer than a missing path — and with no node at all, echo x > /dev/hdb silently creates an ordinary file of that name and appears to work.

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.

---

Errno, and why return -1 is a bug

A syscall that fails returns a negative errno. -1 is therefore -EPERM, "operation not permitted" — and about ninety error paths in kernel/sys/sys_fs.c still say return -1 because that is what xv6 did, where the convention was just "negative means no".

It is not a cosmetic difference. Callers branch on errno, and the standard shape for removing a file you are not sure about is:

if (unlink(p) < 0 && errno != ENOENT)
    complain();

Against -1 every such test takes the complaining branch. That is how it was found — zsh, saving its history, reported failures for things that had succeeded:

zsh: locking failed for /root/.zsh_history: operation not permitted
zsh: failed to write history file /root/.zsh_history.new: operation not permitted

link, unlink, rename and renameat return real values now — ENOENT, EEXIST, EXDEV, EISDIR, ENOTEMPTY, EFAULT. The rest of the file does not, and that is the honest state: these four were corrected because these four were the ones a program tripped over.

symlink() joined them later, and for the same reason: symlink() is the classic atomic lock — create the link, and if it exists someone else holds it — so zsh distinguishes EEXIST ("contended, retry") from anything else ("this cannot work, give up"). A bare -1 is -EPERM, which put every shell on the machine in the second bucket on a filesystem that supports symlinks perfectly well, and printed the first line above on every boot.

rename() replaces its target, and why it did not

rename() used to refuse an existing destination, which broke write-to-a-temporary-then-rename — how every careful program saves a file, and how zsh saves history. The second save of anything failed with EEXIST and left a .zsh_history.new behind for ever.

The first attempt to fix it was reverted after it lost both files, and the note left behind blamed HTree slot reuse. That was the wrong suspect. sys_rename was removing the old name by hand — memset a struct dirent to zero and writei() it into the parent directory at the offset dirlookup returned. That is the v1 filesystem's on-disk layout, written directly, bypassing dp->ops. On SchFS a directory is a B-tree with an index over it: "the record at that offset" is not a thing, and writing zeroes there corrupted the directory while leaving the name in the index. Adding a second removal on top of that is what lost both files.

Every other caller in the file already used dirunlink(). This one had been open-coding a filesystem it no longer ran on, and the bug was invisible while nothing asked it to remove two names instead of one.

The lock discipline is the delicate part and is inherited rather than invented: dp_old and dp_new are frequently the same directory reached through two nameiparent() calls, which is two references to one inode. No two directory locks are ever held at once, and the source inode stays unlocked throughout, held alive by an nlink bump.

Renaming a directory is still refused with EISDIR, and so is replacing one: both need the .. fixup and the ancestor-loop check that are not written.

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].
• Symlinks resolve on the final path component only. open(), stat() and friends follow a link they are pointed at; a link in the middle of a path — /a/link/b — is not resolved. That belongs in namex(), which would have to re-enter path lookup while holding a directory lock, and getting that wrong is a deadlock rather than a wrong answer.
• rename() does not move directories, and will not replace one. EISDIR either way.
• No named pipes. mkfifo() does not fail — it succeeds and produces a character device, because mknod() turns S_IFIFO into a T_DEV and keeps the major/minor. ls -l shows crw-rw-rw- 438, 0 where a p belongs, and nothing written to it comes back out. Succeeding wrongly is worse than refusing: the zsh port was configured with zsh_cv_sys_fifo=yes on the strength of it, and process substitution failed at the point of use rather than being reported as unavailable.
• No /dev/fd, and no /proc/self. A process cannot reach its own open descriptors by path. <(cmd) needs one or the other — zsh now knows it has neither and says so.
• 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.