From 701b0fbf1f95c3d0d8643e156a7bfe3264ad2003 Mon Sep 17 00:00:00 2001
From: Matthias Kruk <m@m10k.eu>
Date: Fri, 28 Aug 2020 12:17:08 +0900
Subject: [PATCH] doc/man: Add manpage for the initial filesystem

---
 doc/man/initfs.10 | 124 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 124 insertions(+)
 create mode 100644 doc/man/initfs.10

diff --git a/doc/man/initfs.10 b/doc/man/initfs.10
new file mode 100644
index 0000000..2244283
--- /dev/null
+++ b/doc/man/initfs.10
@@ -0,0 +1,124 @@
+.TH INITFS 9 2020-08-27 "0.1" "Corax Kernel Documentation"
+
+.SH INTRODUCTION
+At the heart of the Corax operating system is a microkernel. One of the key characteristics of a
+microkernel is that device drivers are not part of the kernel itself. However, this causes a
+chicken-and-egg kind of problem during operating system initialization as the kernel needs drivers
+for the storage device that the drivers are stored on. To address this problem, every Corax kernel
+image contains an initial file system, or
+.BR initfs .
+
+.SH LOGICAL STRUCTURE
+
+The term "file system" is actually a bit of a misnomer, since the initfs is nothing like a common
+file system such as ext2. More accurately, it is a table of structures of type
+.B struct initfs_entry
+which contain the name, address, and size of ELF binaries that are linked into the kernel image.
+The following structures are defined in
+.IR include/corax/initfs.h .
+
+.in +4
+.nf
+
+struct initfs_entry {
+        const char * const  ife_name;
+        const void * const  ife_base;
+        const unsigned long ife_limit;
+};
+
+struct initfs {
+        struct initfs_entry *ifs_entries;
+        unsigned int ifs_num_entries;
+};
+.fi
+.in
+
+The definition of the initial filesystem is located in
+.IR sys/initfs.c .
+The following code is the definition of the file system's
+.B struct initfs
+at the time of writing (and probably way beyond, since it does not need to be modified due to its
+simplicity).
+
+.in +4
+.nf
+struct initfs initfs = {
+        .ifs_entries = _ifs_entries,
+        .ifs_num_entries = sizeof(_ifs_entries) / sizeof(_ifs_entries[0])
+};
+.fi
+.in
+
+The
+.IR _ifs_entries
+referenced by the initialization of
+.IR initfs
+typically looks like the following code.
+
+.in +4
+.nf
+extern const char _binary_io_end[];
+extern const char _binary_io_start[];
+extern const unsigned long _binary_io_size;
+
+static struct initfs_entry _ifs_entries[] = {
+        {
+                .ife_name = "io",
+                .ife_base = &_binary_io_start,
+                .ife_limit = (unsigned long)&_binary_io_size
+        }
+};
+.fi
+.in
+
+The symbols
+.IR _binary_io_start ,
+.IR _binary_io_end ,
+and
+.IR _binary_io_size
+that are referenced within are defined by the linker when the io process's ELF binary is linked.
+
+
+.SH KERNEL OBJECTS
+
+A kernel object (a .ko file) is an .o file that contains an ELF-binary compiled for the Corax
+operating system. A .ko file is generated from an ELF file using ld:
+
+.in +4
+.nf
+ld -r --oformat=elf32-i386 -m elf_i386 -b binary -o hoge.ko hoge
+.fi
+.in
+
+In the above example,
+.IR hoge
+is an ELF binary and
+.IR hoge.ko
+is the resulting kernel object. The command essentially encodes an input file (it doesn't have to
+be an ELF file) into an object file, allowing it to be embedded into a binary. Corax uses this
+technique to embed system processes and device drivers into the kernel image, from where the
+kernel starts them once it has completed initialization.
+
+
+.SH INITFS GENERATION
+
+The initial file system is generated in three steps. First, the kernel objects to be included in
+the filesystem image are compiled and placed in the
+.IR sys
+directory. In the second step, the filesystem structures that are used by the kernel to determine
+the location and size of the filesystem contents are compiled into the
+.IR sys/initfs.o
+file. Finally, all kernel objects and the initfs.o file are combined into the static library
+.IR sys/initfs.a .
+At the end of the kernel compilation, the kernel will be statically linked against this library,
+creating a kernel image with an embedded initial file system.
+
+
+.SH SEE ALSO
+.ad l
+.nh
+.BR kernel (10)
+.BR startup (10)
+
+.SH AUTHOR
+Matthias Kruk
-- 
2.47.3