# simplefs: a Linux filesystem module built to be read

> simplefs is a small C filesystem for the Linux kernel that exists to teach how filesystems work, with a superblock, an inode store and single block files. The author states plainly that it is a work in progress and should not be used yet, and the code is deliberately simple rather than correct at scale.

**psankar/simplefs** — A simple, kernel-space, on-disk filesystem from the scratch

- Repository: https://github.com/psankar/simplefs
- Stars: 981 · Forks: 222
- Language: C
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/psankar-simplefs

## A filesystem whose purpose is to be understood

simplefs is a Linux kernel filesystem module written from scratch in C, and the README is unambiguous about why. It says it is a simple filesystem to understand things, and that if you are planning to learn filesystems you should start from the scratch and follow the repository from the first commit upwards. The author also names the design rule: the filesystem is kept simple and minimal so it can serve as good course notes for others.

That rule has teeth. The README states that the project is not planned for use on a production machine, and that some design choices are driven by learning and teaching simplicity over performance and scalability, and that this is intentional, with a request not to fix those things. That is the single most useful sentence in the documentation for anyone deciding what they are getting into.

The project is also honest about its own status, saying this is a work in progress and that it should not be used yet. Its topics are c, filesystem and kernel, the code is a handful of C files at the repository root (simple.c, simple.h, super.h, mkfs-simplefs.c) plus a Makefile and simple-test.sh, and there are no GitHub releases at all, so the only artifact is the source tree.

The intended reader is a kernel developer or a systems programmer who wants to read a complete filesystem implementation end to end, rather than a sysadmin looking for a new filesystem to mount on Monday.

## Block zero is the superblock, block one holds every inode

The on-disk layout is short enough to hold in your head, which is the point. The architecture notes describe three blocks up front. Block zero is the super block, block one is the inode store, and block two is occupied by the initial file that is created as part of the mkfs step.

So the inode store is a single block, which means the total number of filesystem objects is limited, and the README says exactly that: only a limited number of filesystem objects are supported. That limit falls out of the layout rather than being enforced by policy, and it is the first thing to understand about how the filesystem behaves.

Directories store the children inode number and name in their data blocks, so a directory is a list of name to inode pairs rather than a special structure. The mount transcript in the README shows the mkfs tool writing each of these pieces separately: the super block, the root directory inode, the welcome file inode, inode store padding after the two inodes, the root directory data blocks holding the name and inode number pair for the welcome file, padding after the root directory children, and the welcome file body.

Files and directories can both be created, with support for .create and .mkdir implemented, and nested directories work. The mount log lines show the filesystem detecting its own magic number in the disk, reporting version [1] and a block size of [4096], and confirming that it is mounted on the loop device.

## One block per file, and writes that only work from offset zero

The limitations here are specific enough to be useful as a teaching catalogue, because each one maps to a real filesystem problem.

A file cannot grow beyond one block, and ENOSPC is returned as an error if you attempt it. This is the direct consequence of the inode store and data block model, and it is a clean illustration of how a fixed structure limit turns into a user visible error code.

Read support is implemented. Basic write support is implemented as well, but with a caveat that is easy to miss and expensive to debug: writes may not succeed if done in an offset, and the write works when you overwrite the entire block. So a file is effectively a single buffer. Writing "Hello World" over the whole file works, and the README transcript shows exactly that with an echo redirect followed by a cat.

The locking scheme is the other flagged area. The README says locks are not well thought out, that the current scheme works but needs more analysis and code reviews, and it adds that memory leaks may, or will, exist. That combination tells you this is a codebase to read rather than one to depend on.

The README transcript also ends on an unfinished kernel log line beginning No inode foun, which is the sort of thing you should expect to find in a work in progress and should read as a warning rather than a transcription artefact.

## Build a module and a mkfs tool, then mount a loop image

Compiling is documented in two sentences: install Linux kernel sources and run make from the checked out directory. The Makefile shows what that produces. The module is a single object built from simple.o, and the debug flag is compiled in through ccflags-y:

```make
obj-m := simplefs.o
simplefs-objs := simple.o
ccflags-y := -DSIMPLEFS_DEBUG
```

The default target builds both the kernel module and the userspace formatting tool:

```make
all: ko mkfs-simplefs
```

The ko target runs the kernel build system against the running kernel's module directory, which is why matching kernel sources matter. A separate environment for building is referenced at github.com/azat/simplefs-bld.

The README then walks through the whole lifecycle, starting with an image file, the formatter, and the module load with a loop mount:

```bash
make
dd bs=4096 count=100 if=/dev/zero of=image
./mkfs-simplefs image
```

Mounting needs root, and the transcript loads the module, mounts the image on a loop device and reads the kernel log:

```bash
insmod simplefs.ko ; mount -o loop -t simplefs image /home/psankar/src/simplefs/mount/ ; dmesg
```

Unmounting and unloading is the reverse pair, umount and rmmod, and the README repeats it after the filesystem has been written to, which is how it shows that the tree survives a remount.

## The roadmap stops at extents and journalling, on purpose

The forward plan in the README is short and it explains the shape of the project better than any feature list could. After the 1.0 release the plan is support for extents, which on completion will be 2.0. After the 2.0 release the plan is journalling support, which on completion will be 3.0.

Both entries are the classic two milestones of a teaching filesystem, and neither has started, which is consistent with the work in progress label. Version numbers here are not marketing, they are curriculum stages.

The rest of the repository supports that reading. The root holds a Makefile, the simple.c, simple.h and super.h sources, the mkfs-simplefs.c formatter, a simple-test.sh script, and a LICENSE file. The README records that the initial source was written by psankar with patches contributed by other GitHub members, azat being the first contributor, and thanks the kernelnewbies mailing list for help with the nitty gritty of the Linux kernel. The project also asks contributors to publish changes under the same licence.

The credits are worth mentioning for a second reason: they explain why the repository is a course rather than a product. The author credits talks on filesystems by VijaiBabu M and Santosh Venugopal as the motivation for writing one from the scratch, which is the clearest statement of intent in the whole repository.

## CC0 for the sources, no releases, and a last push on 2026-07-01

The licence situation is unusually simple for a kernel project. The README states that the source files are licensed under the Creative Commons Zero licence, with links to the licence text and legal code, and that a merge request should only be sent if the contributor is ready to publish their changes under that same licence. GitHub cannot categorise the licence as a standard one, so the LICENSE file is the place to check the exact terms rather than a badge on the README.

CC0 is a public domain dedication rather than a copyleft licence, which is the right choice for teaching code that other people are meant to copy, study and modify. That is a description of the licence, not advice about your own use of it.

On maintenance, the last push was on 2026-07-01, and the repository has no GitHub releases, so there is no tagged version to install or to pin a dependency to. There is also no upstream kernel tree integration described anywhere in the README, no documentation of how the module would be packaged for distribution, and no changelog. The one command that builds it is make, against kernel sources you already have.

That combination, a permissive licence, a documented teaching goal, and a repository that has not been touched since the start of July 2026, tells you exactly what kind of dependency this is: something to read, fork and learn from, not something to mount on a machine that matters.

## Conclusion

simplefs fits a reader who wants to understand filesystem internals by following one small implementation from the first commit upwards, and it does not fit anyone with real data to store, since the README states it is a work in progress that should not be used yet. Verify first that you have kernel sources matching your running kernel, that the module builds with the SIMPLEFS_DEBUG flag, and that you understand the one block per file limit, because the ENOSPC path is the filesystem's main way of saying no.

## FAQ

### How do I build simplefs?

Install Linux kernel sources and run make from the checked out directory. The Makefile builds the simplefs.ko kernel module from simple.o with the SIMPLEFS_DEBUG flag and the mkfs-simplefs formatting tool, and a separate build environment is available at github.com/azat/simplefs-bld.

### How do I create and mount a simplefs image?

Create the image with dd bs=4096 count=100 if=/dev/zero of=image, format it with ./mkfs-simplefs image, then as root load the module and mount it with insmod simplefs.ko and mount -o loop -t simplefs image pointing at a mount directory. Unmount and unload with umount and rmmod.

### Can a file in simplefs grow larger than one block?

No. A file cannot grow beyond one block and ENOSPC is returned as an error on attempting it. Read support is implemented and basic write support works when you overwrite the entire block, but writes may not succeed if done in an offset.

### What licence is simplefs released under?

The README states that the source files are licensed under the Creative Commons Zero licence, and asks that patches be published under the same licence so the project stays usable as a teaching resource. GitHub cannot classify the licence as a standard one, so the LICENSE file holds the exact terms.

## Sources

- [Issues](https://github.com/psankar/simplefs/issues)
- [psankar/simplefs on GitHub](https://github.com/psankar/simplefs)
- [README](https://github.com/psankar/simplefs/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/psankar-simplefs