doc: add moar docs

docs/config/Menu.txt

@@ -20,7 +20,7 @@ Timestamp: Updated yyyy/mm/dd
 # These are indexes you deleted, so Natural Docs will not add them again
 # unless you remove them from this line.
 
-Don't Index: Classes, Macros, Variables
+Don't Index: Classes, Variables, Macros
 
 
 # --------------------------------------------------------------------------
@@ -47,8 +47,8 @@ File: Introduction  (docs/intro.txt)
 Link: Source Code  (https://git.cute.engineering/d0p1/StupidOS)
 File: Coding Style  (docs/coding-style.txt)
 File: FAQ  (docs/faq.txt)
-Link: StupidFS  (https://stupidfs.d0p1.eu/)
 File: Common Object File Format &lparen;COFF&rparen;  (docs/COFF.txt)
+Link: StupidFS  (https://stupidfs.d0p1.eu/)
 
 Group: BootLoader  {
 
@@ -153,11 +153,6 @@ Group: Lib  {
 
       File: rc4.asm  (no auto-title, lib/crypto/rc4/rc4.asm)
 
-      Group: chacha20  {
-
-         File: chacha20.asm  (lib/crypto/chacha20/chacha20.asm)
-         }  # Group: chacha20
-
       Group: Dilithium  {
 
          File: ntt.asm  (lib/crypto/dilithium/ntt.asm)
@@ -168,6 +163,9 @@ Group: Lib  {
          File: sha256.asm  (lib/crypto/sha2/sha256.asm)
          }  # Group: SHA2
 
+      File: xchacha.asm  (lib/crypto/xchacha/xchacha.asm)
+      File: chacha.asm  (lib/crypto/chacha/chacha.asm)
+      File: hchacha.asm  (lib/crypto/hchacha/hchacha.asm)
       }  # Group: Crypto
 
    File: ctype  (no auto-title, lib/c/ctype.asm)

kernel/fs/stpdfs.inc

@@ -1,4 +1,6 @@
 	;; File: stpdfs.inc
+	
+	;; Section: Stupid Filesystem
 	;;
 	;; > ┌──────────┬───────────┬──────┬───┬──────┬────┬───┬────┐
 	;; > │Boot block│Super block│Inodes│...│Inodes│Data│...│Data│
@@ -15,12 +17,16 @@ STPDFS_SB_REV   = 1
 STPDFS_BSIZE    = 512
 	;; Constant: STPDFS_BADINO
 	;; StupidFS bad inode
-STPDBOOT_BADINO = 0
+STPDFS_BADINO = 0
 	;; Constant: STPDFS_ROOTINO
-	;; StupidFS root inode
+	;; StupidFS root inode number
 STPDFS_ROOTINO  = 1
 	;; Constant: STPDFS_NDIRECT
+	;; Number of direct block (7)
 STPDFS_NDIRECT  = 7
+	;; Constant: STPDFS_INDIRECT_PER_BLOCK
+STPDFS_INDIRECT_PER_BLOCK = STPDFS_BSIZE / 4
+
 	;; Constant: STPDFS_NAME_MAX
 	;; Max file name length (28)
 STPDFS_NAME_MAX = 28
@@ -33,8 +39,28 @@ STPDFS_CLEANLY_UNMOUNTED = 0
 STPDFS_ERROR             = 1
 STPDFS_DIRTY             = 1
 
+	;; Enum: StupidFS i-node flags
+	;; STPDFS_INO_FLAG_ALOC - I-node is allocated
+	;; STPDFS_INO_FLAG_LZP  - I-node data is compressed using LZP algorithm (see <lzp.asm>)
+	;; STPDFS_INO_FLAG_ENC  - I-node data is encrypted with XChaCha12 (see <xchacha.asm>)
+STPDFS_INO_FLAG_ALOC = 0x8000
+STPDFS_INO_FLAG_LZP  = 0x0001
+STPDFS_INO_FLAG_ENC  = 0x0002
+
+	;; Constant: STPDFS_INODE_PER_BLOCK
+	;; I-node per block
+STPDFS_INODE_PER_BLOCK = sizeof.StpdFS_Inode / STPDFS_BSIZE
+
+	;; Constant: STPDFS_DIRENT_PER_BLOCK
+	;; Directory entry per block
+STPDFS_DIRENT_PER_BLOCK = sizeof.StpdFS_Dirent / STPDFS_BSIZE
+
+
 	;; Struc: StpdFS_FreeList
 	;;
+	;; .free  - List of free block (0-99), index 0 point to next freelist
+	;; .nfree - Index
+	;;
 	;; > ┌──────────┐                                                     
 	;; > │ block 99 │                              
 	;; > ├──────────┤                              
@@ -84,15 +110,15 @@ DEFN StpdFS_Sb
 	;; Struc: StpdFS_Inode
 	;; StupidFS on disk i-node
 	;;
-	;; .mode    - TODO
+	;; .mode    - File mode
-	;; .nlink   - TODO
+	;; .nlink   - Links count
-	;; .uid     - TODO
+	;; .uid     - Owner Uid
-	;; .gid     - TODO
+	;; .gid     - Group Id
-	;; .flags   - TODO
+	;; .flags   - File flags, see <StupidFS i-node flags>
-	;; .size    - Date size in byte
+	;; .size    - Data size in byte
-	;; .zone    - TODO
+	;; .zone    - See bellow
-	;; .actime  - TODO
+	;; .actime  - Access time (64-bit UNIX timestamp)
-	;; .modtime - TODO
+	;; .modtime - Modification time (64-bit UNIX timestamp)
 	;;
 	;;
 	;; Zone 0-6 are direct, zone 7 indirect, zone 8 double indirect, zone 9 triple indirect
@@ -110,17 +136,17 @@ DEFN StpdFS_Sb
 	;; > │zone 7├─────────►│        │      │        │                                      
 	;; > ├──────┤          └────────┘      └────────┘                                      
 	;; > │zone 8├───────┐                                                                  
-	;; > ├──────┤       │Double indirect┌─────────┐    ┌────────┐    ┌─────────┐           
+	;; > ├──────┤       │Double indirect┌────────┐    ┌────────┐    ┌────────┐           
 	;; > │zone 9│       └──────────────►│        ├───►│        ├───►│        │           
 	;; > └──┬───┘                       │        │    │        │    │ Data   │           
 	;; >    │                           │        │    │        │    │        │           
-	;; >    │                           └─────────┘    └────────┘    └─────────┘           
+	;; >    │                           └────────┘    └────────┘    └────────┘           
 	;; >    │ Triple indirect ┌────────┐                                                   
-	;; >    └────────────────►│        │    ┌──────────┐      ┌─────────┐      ┌──────────┐
+	;; >    └────────────────►│        │    ┌────────┐      ┌────────┐      ┌────────┐
 	;; >                      │        ├───►│        │      │        │      │        │
 	;; >                      │        │    │        ├─────►│        ├─────►│ Data   │
 	;; >                      └────────┘    │        │      │        │      │        │
-	;; >                                    └──────────┘      └─────────┘      └──────────┘
+	;; >                                    └────────┘      └────────┘      └────────┘
 struc StpdFS_Inode {
 	.mode    dw ?
 	.nlink   dw ?
@@ -134,8 +160,9 @@ struc StpdFS_Inode {
 }
 DEFN StpdFS_Inode
 
+
 	;; Struc: StpdFS_Dirent
-	;; StupidFS dir entry
+	;; StupidFS directory entry
 	;;
 	;; .inode - address of i-node
 	;; .name  - null terminated file name (see <STPDFS_NAME_MAX>)
@@ -145,8 +172,6 @@ struc StpdFS_Dirent {
 }
 DEFN StpdFS_Dirent
 
-STPDFS_DIRENT_PER_BLOCK = sizeof.StpdFS_Dirent / STPDFS_BSIZE
-
 	; ------------------------------------------------------------------------
 
 	;; Section: Implementation

kernel/fs/xv6fs.inc

@@ -1,18 +1,27 @@
 	;; File: xv6fs.inc
 	;;
+	;; Usefull links:
+	;; - <https://github.com/mit-pdos/xv6-riscv/blob/riscv/kernel/fs.h>
+	;; - <xv6 book at https://pdos.csail.mit.edu/6.1810/2023/xv6/book-riscv-rev3.pdf>
+	;;
+	;; Section: xv6 Filesystem
+	;;
 	;; > ┌──────────┬───────────┬───┬───┬───┬──────┬───┬──────┬──────┬───┬──────┬────┬───┬────┐
 	;; > │Boot block│Super block│Log│...│Log│Inodes│...│Inodes│Bitmap│...│Bitmap│Data│...│Data│
 	;; > └──────────┴───────────┴───┴───┴───┴──────┴───┴──────┴──────┴───┴──────┴────┴───┴────┘
 	;;
-	;; Usefull links:
-	;; - <https://github.com/mit-pdos/xv6-riscv/blob/riscv/kernel/fs.h>
-	;; - <xv6 book at https://pdos.csail.mit.edu/6.1810/2023/xv6/book-riscv-rev3.pdf>
 
 	;; Constant: XV6FS_BSIZE
 	;; xv6 Filesystem block size (1024)
 XV6FS_BSIZE     = 1024
+	;; Constant: XV6FS_ROOTINO
+	;; root inode number
 XV6FS_ROOTINO   = 1
+	;; Constant: XV6FS_MAGIC
+	;; Superblock magic number, MUST BE `0x10203040`
 XV6FS_MAGIC     = 0x10203040
+	;; Constant: XV6FS_NDIRECT
+	;; Number of direct block (12)
 XV6FS_NDIRECT   = 12
 XV6FS_NINDIRECT = (XV6FS_BSIZE / 4)
 XV6FS_MAXFILE   = (XV6FS_NDIRECT + XV6FS_NINDIRECT)
@@ -20,6 +29,16 @@ XV6FS_IPB       = (XV6FS_BSIZE / 64)
 XV6FS_DIRSIZE   = 14 
 
 	;; Struc: Xv6FS_Sb
+	;; xv6FS superblock
+	;;
+	;; .magic      - See <XV6FS_MAGIC>
+	;; .size       - TODO
+	;; .nblock     - TODO
+	;; .ninodes    - TODO
+	;; .nlog       - TODO
+	;; .nlogstart  - TODO
+	;; .inodestart - TODO
+	;; .bmapstart  - TODO
 struc Xv6FS_Sb {
 	.magic      dd ?
 	.size       dd ?
@@ -33,6 +52,14 @@ struc Xv6FS_Sb {
 DEFN Xv6FS_Sb
 
 	;; Struc: Xv6FS_Inode
+	;; xv6FS on disk i-node
+	;;
+	;; .type  - TODO
+	;; .major - TODO
+	;; .minor - TODO
+	;; .nlink - TODO
+	;; .size  - TODO
+	;; .addrs - TODO
 struc Xv6FS_Inode {
 	.type  dw ?
 	.major dw ?
@@ -44,6 +71,7 @@ struc Xv6FS_Inode {
 DEFN Xv6FS_Inode
 
 	;; Struc: Xv6FS_Dirent
+	;; xv6FS directory entry
 struc Xv6FS_Dirent {
 	.inum dw ?
 	.name db XV6FS_DIRSIZE dup(?)

lib/crypto/Makefile

@@ -1,13 +1,16 @@
 TARGET	= libcrypto.a
 OBJS	= sha2/sha256.o sha2/sha512.o \
-			chacha20/chacha20.o
+			chacha/chacha.o \
+			hchacha/hchacha.o
 INCS	= sha2/sha2.h \
-			chacha20/chacha20.h \
+			chacha/chacha.h \
+			hchacha/hchacha.h \
 			dilithium/dilithium.h \
 			falcon/falcon.h \
 			keccak/keccak.h
 ASMS	= sha2/sha2.inc \
-			chacha20/chacha20.inc
+			chacha/chacha.inc \
+			hchacha/hchacha.inc
 
 INCCRYPOTDIR = $(INCDIR)/crypto
 ASMCRYPTODIR = $(ASMDIR)/crypto

lib/crypto/chacha/chacha.asm

@@ -1,4 +1,4 @@
-	;; File: chacha20.asm
+	;; File: chacha.asm
 	
 	; https://en.wikipedia.org/wiki/Salsa20#ChaCha_variant
 	; https://datatracker.ietf.org/doc/html/rfc7539
@@ -6,7 +6,7 @@
 	format COFF
 	use32
 
-	include 'chacha20.inc'
+	include 'chacha.inc'
 	virtual at 0
 		ctx ChaCha20Ctx
 	end virtual

lib/crypto/hchacha/hchacha.asm

@@ -0,0 +1,96 @@
+	;; File: hchacha.asm
+
+CHACHA_CONST1 = 0x61707865
+CHACHA_CONST2 = 0x3320646e
+CHACHA_CONST3 = 0x3320646e
+CHACHA_CONST4 = 0x6b206574
+
+macro TO_LE32 {
+	movzx ecx, byte [eax+1]
+	sal ecx, 8
+	movzx edx, byte [eax+2]
+	sal edx, 16
+	or edx, ecx
+	movzx ecx, byte [eax]
+	or edx, ecx
+	movzx ecx, byte [eax+3]
+	sal ecx, 24
+	or ecx, edx
+}
+
+hchacha:
+	push ebp
+	mov ebp, esp
+	sub esp, 4*4*4
+
+	mov [ebp-64], dword CHACHA_CONST1
+	mov [ebp-60], dword CHACHA_CONST2
+	mov [ebp-56], dword CHACHA_CONST3
+	mov [ebp-52], dword CHACHA_CONST4
+
+	mov eax, [ebp+12]
+
+	; key
+	TO_LE32
+	mov [ebp-48], ecx
+
+	; key + 4
+	add eax, 4
+	TO_LE32
+	mov [ebp-44], ecx
+
+	; key + 4 * 2
+	add eax, 4
+	TO_LE32
+	mov [ebp-40], ecx
+
+	; key + 4 * 3
+	add eax, 4
+	TO_LE32
+	mov [ebp-36], ecx
+
+	; key + 16
+	add eax, 4
+	TO_LE32
+	mov [ebp-32], ecx
+
+	; key + 16 + 4
+	add eax, 4
+	TO_LE32
+	mov [ebp-28], ecx
+
+	; key + 16 + 4 * 2
+	add eax, 4
+	TO_LE32
+	mov [ebp-24], ecx
+
+	; key + 16 + 4 * 3
+	add eax, 4
+	TO_LE32
+	mov [ebp-20], ecx
+
+	; nonce
+	mov eax, [ebp+16] 
+	TO_LE32
+	mov [ebp-16], ecx
+
+	; nonce + 4
+	add eax, 4
+	TO_LE32
+	mov [ebp-12], ecx
+
+	; nonce + 8
+	add eax, 4
+	TO_LE32
+	mov [ebp-8], ecx
+
+	add eax, 4
+	TO_LE32
+	mov [ebp-4], ecx
+
+	;; round
+
+	;; out
+
+	leave
+	ret

lib/crypto/hchacha/hchacha.h

@@ -0,0 +1,22 @@
+#ifndef CRYPTO_HCHACHA_H
+# define CRYPTO_HCHACHA_H 1
+
+# include <stdint.h>
+
+# define HCHACHA_OUT_BYTES   32
+# define HCHACHA_KEY_BYTES   32
+# define HCHACHA_NONCE_BYTES 16
+
+void hchacha(uint8_t out[HCHACHA_OUT_BYTES],
+			const uint8_t key[HCHACHA_KEY_BYTES],
+			const uint8_t nonce[HCHACHA_NONCE_BYTES], int round);
+
+void hchacha12(uint8_t out[HCHACHA_OUT_BYTES],
+			const uint8_t key[HCHACHA_KEY_BYTES],
+			const uint8_t nonce[HCHACHA_NONCE_BYTES]);
+
+void hchacha20(uint8_t out[HCHACHA_OUT_BYTES],
+			const uint8_t key[HCHACHA_KEY_BYTES],
+			const uint8_t nonce[HCHACHA_NONCE_BYTES]);
+
+#endif /* !CRYPTO_HCHACHA_H */

lib/crypto/hchacha/hchacha.inc

@@ -0,0 +1,7 @@
+HCHACHA_OUT_BYTES   = 32
+HCHACHA_KEY_BYTES   = 32
+HCHACHA_NONCE_BYTES = 16
+
+	public hchacha
+	public hchacha12
+	public hchacha20

lib/crypto/xchacha/xchacha.asm

@@ -0,0 +1,3 @@
+	;; File: xchacha.asm
+	;; eXtended-nonce ChaCha cipher
+	;;

lib/lzp/lzp.asm

@@ -1,8 +1,9 @@
 	;; File: lzp.asm
+	;; *Lempel-Ziv + Prediction* (a fast, efficient, and memory-use
+	;; conservative compression algorithm)
+	;;
+	;; (paper: https://ieeexplore.ieee.org/document/488353)
 
-	; Lempel-Ziv + Prediction (a fast, efficient, and memory-use
-	; conservative compression algorithm)
-	; (paper: https://ieeexplore.ieee.org/document/488353)
 	format COFF
 	use32