Author: Virgil Dupras <email@example.com>
Date: Sun, 6 Nov 2022 16:02:12 -0500
doc: add detailed install instructions
|A||fs/doc/install.txt|| | ||74||++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++|
1 file changed, 74 insertions(+), 0 deletions(-)
diff --git a/fs/doc/install.txt b/fs/doc/install.txt
@@ -0,0 +1,74 @@
+# 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
+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
+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
+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.