From c00a137578208668ea469445ecf480070d735aa4 Mon Sep 17 00:00:00 2001
From: Vincent Ollivier <v@vinc.cc>
Date: Fri, 1 Nov 2024 19:07:36 +0100
Subject: [PATCH] Add more content to the device doc

---
 doc/devices.md    | 62 +++++++++++++++++++++++++++++++++++++++++------
 doc/filesystem.md |  7 ++++--
 doc/shell.md      |  2 +-
 3 files changed, 60 insertions(+), 11 deletions(-)

diff --git a/doc/devices.md b/doc/devices.md
index e6de869c3..de5f5436f 100644
--- a/doc/devices.md
+++ b/doc/devices.md
@@ -29,7 +29,7 @@ write /dev/vga/mode -d vga-mode
 write /dev/vga/palette -d vga-palette
 ```
 
-## Clocks
+## Clock Devices
 
 Reading the number of seconds since boot:
 
@@ -59,7 +59,7 @@ Changing the system time:
 [580.327629] RTC 2025-01-01 00:00:00 +0000
 ```
 
-## Network
+## Network Devices
 
 Opening `/dev/net/tcp` or `/dev/net/udp` with the `OPEN` syscall and the device
 flag will return a file handle for a TCP or UDP socket supporting the standard
@@ -92,7 +92,7 @@ Reading a socket with a 1 byte buffer will return the status of the socket:
 +-----+--------------+
 ```
 
-## Speaker
+## Speaker Device
 
 Playing a 440 Hz sound on the PC speaker:
 
@@ -106,9 +106,38 @@ Stopping the sound:
 > print 0 => /dev/speaker
 ```
 
-## VGA
+## Null Device
 
-### Font
+Writing to `/dev/null` will discard any data sent to it:
+
+```
+> print hello
+hello
+
+> print hello => /dev/null
+```
+
+It can be used to suppress errors:
+
+```
+> copy none.txt some.txt
+Error: Could not read file 'none.txt'
+
+> copy none.txt some.txt [2]=> /dev/null
+```
+
+## Random Device
+
+Reading from `/dev/random` will return bytes from a cryptographically secure
+random number generator that uses the [HC-128][1] algorithm seeded from the
+[RDRAND][2] instruction when available.
+
+[1]: https://en.wikipedia.org/wiki/HC-256
+[2]: https://en.wikipedia.org/wiki/RDRAND
+
+## VGA Devices
+
+### VGA Font Device
 
 Changing the VGA font:
 
@@ -116,7 +145,7 @@ Changing the VGA font:
 > copy /ini/fonts/zap-light-8x16.psf /dev/vga/font
 ```
 
-### Mode
+### VGA Mode Device
 
 Changing the VGA mode:
 
@@ -124,6 +153,23 @@ Changing the VGA mode:
 > print 320x200 => /dev/vga/mode
 ```
 
-### Palette
+The accepted modes are:
+
+- `80x25` for the primary text mode with 16 colors
+- `320x200` for the primary graphics mode with 256 colors
+- `640x480` for the secondary graphics mode with 16 colors
+
+It is possible to read the current mode from this device file.
+
+### VGA Palette Device
+
+Changing the VGA palette is done by writting a 768 bytes buffer to
+`/dev/vga/palette` containing the RGB values of 256 colors.
+
+It is possible to read the current palette from this device file.
+
+### VGA Buffer Device
 
-### Buffer
+Changing the VGA framebuffer is done by writting a 64 KB bytes buffer to
+`/dev/vga/buffer` containing the index of the color of each pixel on the
+screen while in `320x200` mode.
diff --git a/doc/filesystem.md b/doc/filesystem.md
index a94e627f5..bbcf333d6 100644
--- a/doc/filesystem.md
+++ b/doc/filesystem.md
@@ -57,6 +57,9 @@ The next step during setup is to create the directory structure:
     > write /usr/           # User directories
     > write /var/           # Variable files
 
+See the [devices](devices.md) documentation to create the device files in the
+`/dev` directory.
+
 Then the following should be added to the boot script with the
 command `edit /ini/boot.sh` to allow MOROS to finish booting:
 
@@ -157,7 +160,7 @@ Structure:
 A directory entry represents a file or a directory contained inside a
 directory. Each entry use a variable number of bytes that must fit inside the
 data of one block. Those bytes represent the kind of entry (file or dir), the
-address of the first block, the filesize (max 4GB), the last modified time in
+address of the first block, the filesize (max 4 GB), the last modified time in
 seconds since Unix Epoch, the length of the filename, and the filename (max
 255 chars) of the entry.
 
@@ -176,7 +179,7 @@ Structure:
 
 ### FileInfo
 
-The `info` syscall on a file or directory and the `read` syscall on a directory
+The `INFO` syscall on a file or directory and the `READ` syscall on a directory
 return a subset of a directory entry for userspace programs.
 
 Structure:
diff --git a/doc/shell.md b/doc/shell.md
index 19636e885..f73abb2f8 100644
--- a/doc/shell.md
+++ b/doc/shell.md
@@ -82,7 +82,7 @@ When executed without arguments, this command will print the current directory.
     > read foo.txt or read bar.txt
 
 
-## Pipes and redirections (WIP)
+## Pipes and Redirections (WIP)
 
 A thin arrow `->` can be used for piping the output from one command to the
 input of another command (TODO):