commit 833d27e6cbd20bace681edfc95fdc948e02c12b6
parent 93700bff552626c93237c2f258576ee83b9ec88d
Author: Virgil Dupras <hsoft@hardcoded.net>
Date: Wed, 18 Jan 2023 20:48:00 -0500
Improve docs
(documentation changes aren't made from within Dusk. my PC image doesn't have it
yet)
Diffstat:
4 files changed, 45 insertions(+), 6 deletions(-)
diff --git a/README.md b/README.md
@@ -161,6 +161,9 @@ higher cognitive space to fit BSD/Linux wider abstractions in your mind.
* Did I mention that the *whole* code for Dusk OS and its ported applications
(excluding docs and test code) is less than 13K lines of code and that DuskCC
is less than 1400 lines of code?
+* Since `text/ed` has reached a usable status, the main author of Dusk has been
+ developing it from within itself on an old Pentium 75 Mhz with 16mb of RAM and
+ he's having a blast.
List of ported codebases:
@@ -169,6 +172,11 @@ List of ported codebases:
* The `puff()` algorithm from [zlib][zlib]
* The [left][left] text editor. (Still a bit glitchy...)
+List of homegrown applications:
+
+* C Compiler (see `doc/cc`)
+* Text editor (see `doc/text/ed`)
+
What's next? See the [roadmap][roadmap]!
Development happens on [sourcehut][shproj].
@@ -204,7 +212,7 @@ that. To avoid that, you can invoke it like this:
`make run` does this for you.
-### Building bare metal binaries
+## Deploying to a real machine
`make run` builds and runs a binary designed to work on a POSIX platform, but
if you want to build binaries designed to run on bare metal, it's another
@@ -214,11 +222,10 @@ For now, only the x86 PC platform is supported and can be built with
`make pc.img`. If you have QEMU installed, you can run it right away with
`make pcrun`.
-To run Dusk on an actual machine, what you can do is to write it directly to a
-USB key (`dd if=pc.img of=/dev/sdX`) and then boot from that key in "Legacy
-BIOS" mode.
+To deploy that image on a real machine, it's a bit more involving and you should
+read `doc/deploy.txt`.
-### See what it can do
+## See what it can do
Dusk OS on the PC has graphical capabilities as well as [varvara][varvara]
bindings for it. If you have QEMU installed, you can try a few little things on
diff --git a/fs/doc/deploy.txt b/fs/doc/deploy.txt
@@ -106,7 +106,7 @@ have those drivers create structures that extend 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
+Once you have those drivers, you instantiate them in your init.fs and plug them
to the Console and StdIO.
That's all you need driver-wise. You're now ready to write the "user" part of
diff --git a/fs/doc/hw/i386/pc/deploy.txt b/fs/doc/hw/i386/pc/deploy.txt
@@ -20,6 +20,12 @@ 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.
+What you'll probably want to do if you want to have a "nice" Dusk running from
+your not-so-vintage PC is that you boot from USB using the BIOS disk driver,
+and then copy the contents of the USB key sector-by-sector to your internal disk
+which is likely to be ran by an AHCI controller. Then, you boot from your
+internal disk and enable the AHCI driver.
+
## Creating a boot media for the PC
Whatever the BIOS can read through INT13h, Dusk can boot from it. Dusk is
diff --git a/fs/doc/sys/rdln.txt b/fs/doc/sys/rdln.txt
@@ -0,0 +1,26 @@
+# Readline subsystem
+
+Dusk's main loop endlessly consumes text coming from "console". If you plug your
+input (for example the keyboard device) directly on it, words will be executed
+as soon as you type a whitespace. This behavior is generally uncomfortable
+because we expect the system to consume what we type in a line-by-line manner.
+We also want to have the opportunity to correct mistakes on that line before we
+send it for interpretation. We also usually want to have some kind of prompt
+(the "ok" prompt). That's what sys/rdln does.
+
+It defines a read-only RdlnIn IO structure as well as a re-implementation of the
+"main" routine (the routine that endlessly consumes words).
+
+To install it, you only have to call "rdln$", which installs itself at the
+appropriate places:
+
+1. Set the "abort" alias to its regular "(abort)" target (rdln is usually
+ installed during boot, at which time "abort" points to a word that spits
+ "boot failure" and halts the machine)
+2. Change "main" to its own implementation, which resets the rdln buffer before
+ starting the endless loop. This way, when we run "quit", the rest of the rdln
+ buffer will not be ran.
+3. Set "console readio" the RdlnIn.
+
+After the "rdln$" call, the readline subsystem is active and you'll be prompted
+for the first time.
