Add more content to the device doc

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,24 +106,70 @@ 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:
 
 ```
 > copy /ini/fonts/zap-light-8x16.psf /dev/vga/font
 ```
 
-### Mode
+### VGA Mode Device
 
 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.

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:

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):