commit 5032416fd67e854f98a6dabe7ad4d80487aab769
parent c791a72f8738a107de38c902fbb60f39c747de7d
Author: Virgil Dupras <hsoft@hardcoded.net>
Date: Tue, 27 Dec 2022 09:51:50 -0500
Improve deploy documentation
Diffstat:
4 files changed, 186 insertions(+), 75 deletions(-)
diff --git a/fs/doc/deploy.txt b/fs/doc/deploy.txt
@@ -0,0 +1,117 @@
+# Deploying Dusk OS
+
+To deploy Dusk OS on your hardware, you need to craft a bootable media for it.
+If you're deploying to an already supported platform, then it's only a matter of
+using the existing build scripts, maybe tweak the init.fs a bit.
+
+If you're deploying hardware that isn't supported yet, then you'll need to craft
+those build scripts yourself.
+
+To understand thise document, you should have read doc/usage and doc/arch.
+
+## The general steps
+
+The steps to create a build media are the same everywhere:
+
+1. Prepare a media with FAT on it.
+2. Devise a way to make this media bootable so that it loads the kernel and boot
+ layer in memory, and execute it.
+3. Compile the kernel, install it on the media.
+4. Create the boot "stream" (boot source files lined up next to each other) and
+ place it on the media.
+5. Copy all Dusk files in the target FAT volume.
+6. Create a init.fs file and place it in the target FAT volume.
+
+## Supported platforms
+
+To deploy to a supported platform, it's generally only a matter of tweaking the
+init.fs file and run the build script. You should follow hardware-dependent
+deploy documentation:
+
+* PC: doc/hw/i386/pc/deploy
+
+## New platforms
+
+Deploying Dusk to a new platform is quite a challenge which involves a lot of
+trial and errors. Maybe these little guidelines can help you.
+
+### Bootloader
+
+The first thing you have to do is to write your bootloader. I don't know your
+platform, so I can't tell you how, but what I can tell you is that it has to
+load both the kernel and the boot "stream" in memory. By "stream", I mean that
+the source of all the source files that compose the boot sequence (see doc/arch)
+are lined up one after the other so that the Forth interpreter can just consume
+it all from memory.
+
+You have to place your boot stream so that the "boot<" word reads from it. It's
+generally going to be right after the kernel in memory, but it doesn't have to.
+
+### Writing the kernel
+
+Writing the kernel is pretty hard. You will probably want to do this in an
+emulator. My advice is to try to find a way to test each word as you write it,
+however hacked up that way is. For the PC, my trick was to write stuff to memory
+at $b8000 (the vga text mode buffer) because I didn't have a function "emit"
+yet. If you're in an emulator, you have access to machine state, so you can
+debug through that too.
+
+### Testing boolo
+
+Compiling and testing the "bootlo" layer is the best way to iron kinks out of
+the kernel. Even though all your words were tested in isolation as you built the
+kernel, it's likely that subtle bugs are still lurking in there, but if your
+kernel can compile bootlo and, say, instantiate a dummy struct, then you can be
+confident that your kernel is solid.
+
+Again, you don't have "emit" yet, so you need some tricks to visualize the
+results of your tests. A blinking LED maybe?
+
+So, what you do is that you begin with a dummy test right at "boot<". Something
+like "blink my LED and loop forever". We're good? alright. Now copy the first
+few lines of bootlo (those that handle ":" and ";") and copy that into your
+bootloader stream. Then, create word definition that blinks your LED. Still
+good? The hard part's over! Now let's get those other lines of code wiggling!
+
+So, you have instantiated that dummy struct? It's working? Seriously, the hard
+part is really over. Congratulations!
+
+### Storage
+
+Magic is about to trickle in. You'll want to get to your first "fload". You need
+to begin writing your storage driver. I can't tell you how, but as always, you
+should proceed in incremental steps. Read a sector, test it. Does it work for
+other sectors too? Well, that sounds good, it looks like you can plug fatlo in.
+
+For this, I recommend looking at how the PC platform does it. It should look the
+same for all targets: we stream bootlo in, then the storage driver, then fatlo,
+then the "glue" file, which create an instance of Filesystem and place it in the
+"bootfs" value.
+
+If you look at PC's glue.fs, you'll also see something about "floaded," the goal
+of that is to "register" files in the boot stream as "loaded" so that "?f<<"
+doesn't load them twice.
+
+### init.fs
+
+You're almost done! Your next step is to load "boothi", and then create a dummy
+init.fs, again blinking your LED. Working? good!
+
+Did you try a f<< call? Working too? You're on a roll!
+
+You have a working Dusk system. The rest is up to you. You probably want a
+prompt right? To have that, you need to set ConsoleIn and ConsoleOut. So, write
+your drivers for input and output (a serial console is usually the quickest way
+to this) and have those drivers conform create structure that extends IO (see
+doc/sys/io). You'll want your input driver to implement :readbuf and your output
+driver to implement :writebuf. I recommend looking at PC drivers for
+inspiration.
+
+Once you have those drivers, you instanciate them in your init.fs and plug them
+to ConsoleOut/StdOut and ConsoleIn/StdIn.
+
+That's all you need driver-wise. You're now ready to write the "user" part of
+your init.fs, the one that will load the sys/rdln subsystem and define the
+"init" word. You can copy it from xcomp/init.fs or write your own.
+
+You're done, Congratulations!
diff --git a/fs/doc/hw/i386/pc/deploy.txt b/fs/doc/hw/i386/pc/deploy.txt
@@ -0,0 +1,68 @@
+# Deploying Dusk to a PC
+
+As long as the PC has a 80386 CPU, it should be good enough to run Dusk, which
+has very small memory and disk requirements.
+
+So far, the most underpowered computer Dusk has been known to run on is an old
+Pentium 75Mhz laptop from Zenith Data Systems with 16MB of RAM. It boots in
+about 5 seconds and can load DuskCC from its ATA disk in about another 5
+seconds.
+
+Dusk can boot from whatever media the BIOS can read. However, early in its boot
+process, Dusk loads one of its own storage drivers so that it doesn't have to
+rely on the BIOS, which comes with heavy constraints and limitations.
+
+At this time, Dusk has storage drivers for floppy, ATA and AHCI storage
+controllers. USB storage isn't implemented yet.
+
+If you want to boot Dusk from a media for which Dusk doesn't have a driver, you
+can, but you'll have to tweak your /init.fs file to not load any storage driver.
+You'll get to Dusk prompt, but you'll have a severly limited environment, and
+probably buggy too. But it might be very useful to explore and debug a computer.
+
+## Creating a boot media for the PC
+
+Whatever the BIOS can read through INT13h, Dusk can boot from it. Dusk is
+installed as a FAT volume with a bootloader embedded in its first sector.
+Following that first sector are a few dozens "reserved" sectors which contain
+Dusk's kernel followed by its embedded boot code (see doc/arch).
+
+The task of the bootloader is to load those reserved sectors in memory, go in
+32-bit protected mode, then jump to the first address of these sectors we've
+just loaded. Then, bootstrapping takes placed normally.
+
+Then, what you need to do is to copy all files of the Dusk system into that new
+FAT volume, and craft a proper "/init.fs" file (see doc/arch).
+
+There is some helper code to craft such a volume in xcomp/i386/pc/build.fs.
+Upon loading this unit, a bootloader and kernel are compiled, and FAT creation
+helper words become available. The word you'll want to use among those is
+"buildPC ( drv clustercnt -- fat )". It takes a drive and cluster count as a
+parameter and does the following:
+
+1. Create a new FAT volume (FAT12 only for now) in the specified drive with the
+ specified cluster count.
+2. Copy all files present in the current boot filesystem into this new FAT
+ volume.
+3. Copy the bootloader in the first sector, embedded in FAT headers.
+4. Copy the kernel in the reserved sectors.
+5. After the kernel, still in the reserved sectors, copy all files that the
+ kernel needs for bootstrapping on the PC (for example, the int13h driver).
+
+After that's done, you're almost ready to boot. The only thing you have to do is
+to tweak the "/init.fs" file in that new FAT volume. The one from your current
+system was copied and that might not be what you need on your target machine.
+For example, you might want to change the storage driver parameters.
+
+That's it! you have a new bootable Dusk media.
+
+### Booting from a floppy
+
+Dusk's bootloader uses FAT headers to determine boot device geometry. Except for
+floppies, almost all boot media have the same geometry: 63 sectors per track and
+16 heads and drive number 128.
+
+That is what "buildPC" embeds in its FAT headers by default. If you let these
+default be written to a 1.44MB floppy, that floppy will not boot. To fix this
+problem, you can tweak xcomp/i386/pc/build.ps to change "secpertrk", "numheads"
+and "drvnum" FAT options to 18, 2 and 0. Then, your floppy will boot.
diff --git a/fs/doc/index.txt b/fs/doc/index.txt
@@ -19,7 +19,7 @@ about sys/io, you'll want to open doc/sys/io.
usage General usage guide
dict Dictionary of system word
-install Deploy Dusk to another machine
+deploy Deploy Dusk to another machine
terms Terminology
dirs Directory structure
arch Architecture details
diff --git a/fs/doc/install.txt b/fs/doc/install.txt
@@ -1,74 +0,0 @@
-# Installing Dusk OS
-
-To install Dusk OS on your hardware, you need to craft a bootable media for one
-of the supported platforms.
-
-## Supported platforms
-
-For now, only the PC platform is supported. As long as the PC has a 80386 CPU,
-it should be good enough to run Dusk, which has very small memory and disk
-requirements.
-
-So far, the most underpowered computer Dusk has been known to run on is an old
-Pentium 75Mhz laptop from Zenith Data Systems with 16MB of RAM. It boots in
-about 5 seconds and can load DuskCC from its ATA disk in about another 5
-seconds.
-
-Dusk can boot from whatever media the BIOS can read. However, early in its boot
-process, Dusk loads one of its own storage drivers so that it doesn't have to
-rely on the BIOS, which comes with heavy constraints and limitations.
-
-At this time, Dusk has storage drivers for floppy, ATA and AHCI storage
-controllers. USB storage isn't implemented yet.
-
-If you want to boot Dusk from a media for which Dusk doesn't have a driver, you
-can, but you'll have to tweak your /init.fs file to not load any storage driver.
-You'll get to Dusk prompt, but you'll have a severly limited environment, and
-probably buggy too. But it might be very useful to explore and debug a computer.
-
-## Creating a boot media for the PC
-
-Whatever the BIOS can read through INT13h, Dusk can boot from it. Dusk is
-installed as a FAT volume with a bootloader embedded in its first sector.
-Following that first sector are a few dozens "reserved" sectors which contain
-Dusk's kernel followed by its embedded boot code (see doc/arch).
-
-The task of the bootloader is to load those reserved sectors in memory, go in
-32-bit protected mode, then jump to the first address of these sectors we've
-just loaded. Then, bootstrapping takes placed normally.
-
-Then, what you need to do is to copy all files of the Dusk system into that new
-FAT volume, and craft a proper "/init.fs" file (see doc/arch).
-
-There is some helper code to craft such a volume in xcomp/i386/pc/build.fs.
-Upon loading this unit, a bootloader and kernel are compiled, and FAT creation
-helper words become available. The word you'll want to use among those is
-"buildPC ( drv clustercnt -- fat )". It takes a drive and cluster count as a
-parameter and does the following:
-
-1. Create a new FAT volume (FAT12 only for now) in the specified drive with the
- specified cluster count.
-2. Copy all files present in the current boot filesystem into this new FAT
- volume.
-3. Copy the bootloader in the first sector, embedded in FAT headers.
-4. Copy the kernel in the reserved sectors.
-5. After the kernel, still in the reserved sectors, copy all files that the
- kernel needs for bootstrapping on the PC (for example, the int13h driver).
-
-After that's done, you're almost ready to boot. The only thing you have to do is
-to tweak the "/init.fs" file in that new FAT volume. The one from your current
-system was copied and that might not be what you need on your target machine.
-For example, you might want to change the storage driver parameters.
-
-That's it! you have a new bootable Dusk media.
-
-### Booting from a floppy
-
-Dusk's bootloader uses FAT headers to determine boot device geometry. Except for
-floppies, almost all boot media have the same geometry: 63 sectors per track and
-16 heads and drive number 128.
-
-That is what "buildPC" embeds in its FAT headers by default. If you let these
-default be written to a 1.44MB floppy, that floppy will not boot. To fix this
-problem, you can tweak xcomp/i386/pc/build.ps to change "secpertrk", "numheads"
-and "drvnum" FAT options to 18, 2 and 0. Then, your floppy will boot.
