doc: add moar docs

This commit is contained in:
d0p1 🏳️‍⚧️ 2024-07-20 08:59:37 +02:00
parent 9078742c29
commit f20f1cc398
12 changed files with 226 additions and 43 deletions

View file

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

View file

@ -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
;; .nlink - TODO
;; .uid - TODO
;; .gid - TODO
;; .flags - TODO
;; .size - Date size in byte
;; .zone - TODO
;; .actime - TODO
;; .modtime - TODO
;; .mode - File mode
;; .nlink - Links count
;; .uid - Owner Uid
;; .gid - Group Id
;; .flags - File flags, see <StupidFS i-node flags>
;; .size - Data size in byte
;; .zone - See bellow
;; .actime - Access time (64-bit UNIX timestamp)
;; .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┌────────┌────────┐ ────────┐
;; > │zone 9 └──────────────►│ ├───►│ ├───►│
;; > └──┬───┘ Data
;; >
;; > └────────└────────┘ ────────┘
;; > ├──────┤ │Double indirect┌────────┌────────┐ ────────┐
;; > │zone 9 └──────────────►│ ├───►│ ├───►│
;; > └──┬───┘ Data
;; >
;; > └────────└────────┘ ────────┘
;; > Triple indirect ┌────────┐
;; > └────────────────►│ ┌──────────────────┐ ──────────┐
;; > ├───►│
;; > ├─────►│ ├─────►│ Data
;; > └────────┘
;; > └──────────────────┘ ──────────┘
;; > └────────────────►│ ┌────────────────┐ ────────┐
;; > ├───►│
;; > ├─────►│ ├─────►│ 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

View file

@ -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(?)

View file

@ -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

View file

@ -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

View file

@ -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

View file

@ -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 */

View file

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

View file

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

View file

@ -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