commit a5673fcc973d3546dd4335bb0508a29aaaa0900b
parent deab8801ab1375fa81d308460c69018a76161166
Author: Virgil Dupras <hsoft@hardcoded.net>
Date: Wed, 20 Jul 2022 10:32:56 -0400
Refresh doc/arch
Diffstat:
| M | fs/doc/arch.txt | | | 65 | ++++++++++++++++++++++++++++++++++++++++++++++++----------------- |
1 file changed, 48 insertions(+), 17 deletions(-)
diff --git a/fs/doc/arch.txt b/fs/doc/arch.txt
@@ -18,8 +18,8 @@ Xb name
1b name length + immediate
--> this is where we link
-When we refer to word in Dusk OS, we always refer to its first executable byte,
-right after the name length field. This way, we can call it directly.
+When we refer to a word in Dusk OS, we always refer to its first executable
+byte, right after the name length field. This way, we can call it directly.
"previous entry" field in an entry refers to this same place.
@@ -37,7 +37,7 @@ A running Dusk OS instance has a few layers upon which the prompt is laid out.
We try to keep a consistent terminology for each of those layers, this
terminology is defined below.
-# Native Kernel (kernel)
+## Native Kernel (kernel)
This is the very core of the system, written in assembler and cross-compiled.
Its role is to implement "mainloop" and ":" as well as all the words that those
@@ -52,29 +52,60 @@ words in the kernel are strictly needed.
In x86, the source for the kernel is /dusk.asm.
-# Boot layer (boot)
+## Boot layer (boot)
At this point, we're done with cross-compiled binaries and we're now entirely
on our own. Let's pick ourselves up by the bootstraps!
-The contents of /boot.fs has been embedded to the Dusk OS binary and is being
-read from memory (by "boot<"), in its source form. The role of the boot layer
-is to:
+The boot layer is Forth code that has been embedded in the binary and is
+directly available to Dusk's memory. Its contents depends on the target system
+and is assembled at build time. It has this structure:
-1. Implement a minimally convenient set of words, such as comments, conditions
- and loops, create/value/alias.
-2. Give access to the root filesystem (f<<).
-3. Load /init.fs and run it.
+1. bootlo
+2. boot storage driver
+3. glue1
+4. filesystem
+5. glue2
+6. boothi
-# Initialization layer (init)
+The "bootlo" part bootstraps from where the kernel left off, implementing what
+is considered the "core" set of words of Dusk. At build time, it is sourced from
+/xcomp/bootlo.fs.
+
+The boot storage driver depends on the target machine and has the responsibility
+of providing a way to read sectors from mass storage. In the Linux target
+machine, it is sourced from /drv/ramdrive.fs
+
+The first glue file plugs words from the sotage driver to aliases that the file
+system code will understand, namely (drv@) and drvblksz. In the Linux target,
+this is sourced from /xcomp/glue1.fs.
+
+The filesystem layer depends on the target machine and has the responsibility
+to implement fopen, fclose, fchild and freadbuf. In the Linux target, this is
+sourced from /fs/fatlo.fs.
+
+The second glue file plugs words from the previous layer in fopen and fchild
+aliases (fclose and freadbuf are in handle preludes). It also has the
+responsibility of adding references of included files in "floaded" so that they
+aren't loaded twice in memory. In the Linux target, this is sourced from
+/xcomp/glue2.fs
+
+The "boothi" part takes all of this and implements "fload", and then loads
+/init.fs. This is sourced from /xcomp/boothi.fs
+
+## Initialization layer (init)
The 2 first layers are machine-dependent and will not change unless something
fundamental changes with your machine. The "init" layer, however, is
-user-dependent. It does whatever you need it to do.
+where you shape the system you want as a user.
+
+It lives in /init.fs and is loaded at the end of the "boot" layer. When it
+starts, it's quite limited in the tooling it has to load further files: it
+doesn't have f<<, only fchild and fload. The first thing you'll typically want
+to do is to load /sys/file, which gives you f<<.
-It will typically load subsystems from /sys/ and then present a prompt. The boot
-layer didn't leave your machine with a way for the user to interact with the
-machine, so before you prompt, you'll have to load a subsystem for user
-interaction, for example /sys/rdln.fs.
+Then, you load the subsystems you want to use, and end up with your main loop.
+A typical system will spit a prompt and pass the control to /sys/rdln, which
+reads input line by line and interprets them.
The system is yours.
