Updated docs

2025-04-15 11:22:50 +02:00
parent 30445e9d25
commit 0c2bba8c33
14 changed files with 57 additions and 207 deletions
@@ -1,17 +0,0 @@
 Bootloader
 ============
 Kern uses a two stage bootloader. The first stage is the 512 byte bootsector. 
 This code loads the 2nd stage, which is in the next seven sectors.
 Together this whole bootloader takes up the first filesystem block (4kiB).
 Bootframe
 ---------
 When the bootloader runs the kernel, it pushes a 32-bit address that points 
 to the bootframe It follows the following structure:
 * Memory map
 * Video memory
 * ...todo
 It is defined in the libk header 'boot.h'
@@ -1,25 +0,0 @@
 Building & Running
 ==================
 _If you want to try kern for some reason, you can._
 Tools
 -----
 * [NASM](https://www.nasm.us/)
 * [QEMU](https://www.qemu.org/) (for emulation)
 Unix-Like Systems
 *****************
 * [GCC](https://gcc.gnu.org/)
 On MacOS
 ********
 * A cross compiler: `$ brew tap nativeos/i386-elf-toolchain && brew install i386-elf-binutils i386-elf-gcc`
 Commands
 --------
 ```sh
 $ make # Or 'make os'
 $ make run # Run QEMU
 ```
 _I personally wouldn't recommend running this on real hardware, because it's untested and will just probably break you pc, but if you really want to, you can try it, but don't blame me if something goes wrong._
@@ -1,46 +1,51 @@
--- Terminal Escape Sequences ---
+Terminal Escape Sequences
 =========================
-Escape character:
+Escape character
-    char:   '\e'
+----------------
-    hex:    0x1b
+* hex: 0x1b
-    oct:    0o33
+* oct: 0o33
-    dec:    27
+* dec: 27
 Note: the escape character will be denoted by ESC here
-Syntax:
+Syntax
-    All escape sequenced start with the escape character followed by an opening square bracket '['
+------
-    The sequence can take any number of arguments in a semicolon separated list
+All escape sequenced start with the escape character followed by an opening
-    If a argument is skipped, it will be implicitly set to 0 unless stated otherwise 
+square bracket '['. The sequence can take any number of arguments in a semicolon
-    The escape sequence must end with a uppercase or lowercase letter
+separated list. If a argument is skipped, it will be implicitly set to 0 unless
 stated otherwise. The escape sequence must end with a uppercase or lowercase
 letter.
-Available escape sequences:
+Available escape sequences
-    - Cursor Controls -
+--------------------------
-    `ESC[#A` - Moves cursor # rows up (default: 1)
+Cursor Controls
-    `ESC[#B` - Moves cursor # rows down (default: 1)
+* `ESC[#A` - Moves cursor # rows up (default: 1)
-    `ESC[#C` - Moves cursor # columns left (default: 1)
+* `ESC[#B` - Moves cursor # rows down (default: 1)
-    `ESC[#D` - Moves cursor # columns right (default: 1)
+* `ESC[#C` - Moves cursor # columns left (default: 1)
-    `ESC[#E` - Moves cursor to #th row
+* `ESC[#D` - Moves cursor # columns right (default: 1)
-    `ESC[#F` - Moves cursor to #th column
+* `ESC[#E` - Moves cursor to #th row
-    `ESC[#G` - Show (# = 1) or hide (# = 0) cursor
+* `ESC[#F` - Moves cursor to #th column
-    `ESC[{row};{col}H`  - Moves cursor to specified position (if not arguments given, moves to [0,0])
+* `ESC[#G` - Show (# = 1) or hide (# = 0) cursor
-    - Erase functions -
+* `ESC[{row};{col}H`  - Moves cursor to specified position (if not arguments given, moves to [0,0])
-    `ESC[I`  - Reserved (Falls though to erase screen)
+Erase functions
-    `ESC[J`  - Erase screen
+* `ESC[I`  - Reserved (Falls though to erase screen)
-    `ESC[K`  - Erase line (not implemented)
+* `ESC[J`  - Erase screen
-    `ESC[L`  - Erase column (not implemented)
+* `ESC[K`  - Erase line (not implemented)
-    - Text Style -
+* `ESC[L`  - Erase column (not implemented)
-    `ESC[#M` - Sets foreground color to # (default 8)
+Text Style
-    `ESC[#N` - Sets backgorund color to # (default 8)
+* `ESC[#M` - Sets foreground color to # (default 8)
 * `ESC[#N` - Sets backgorund color to # (default 8)
-Color codes:
+Color codes
-    0 - Black   
+-----------
-    1 - Red     
+* 0 - Black   (000)
-    2 - Green   
+* 1 - Red     (100)
-    3 - Yellow  
+* 2 - Green   (010)
-    4 - Blue    
+* 3 - Yellow  (110)
-    5 - Magenta 
+* 4 - Blue    (001)
-    6 - Cyan    
+* 5 - Magenta (101)
-    7 - White   
+* 6 - Cyan    (011)
-    8 - Default
+* 7 - White   (111)
 * 8 - Default
@@ -1,16 +0,0 @@
 === Project Structure ===
 Root contains the Makefile that is used to build kern and some documents.
 It also contains these directories:
    src/    - Kernel source code
    boot/   - Bootloader code
    libc/   - C Standard library
    libk/   - Kernel library
    docs/   - Some documentation (mainly for me)
    other/  - Things like screenshot, etc.
    usr/    - Userspace files like fonts and programs
    bin/    - Intermediary binaries
 After running the Makefile and succesfully building the OS 
 a 'kern.iso' file will be created in the root directory
@@ -1,57 +0,0 @@
 Filesystem
 ============
 Sector = 512 Bytes
 Block  = 4096 Bytes
 Reserved sectors
 ----------------
 * Sector 0..7 - Bootblock, constains bootloader code that gets ran by the BIOS   (4KiB)
 * Sector 8..F - Superblock, contains metadata about the filesystem itself        (4KiB)
 Superblock structure (4096B)
 --------------------
 * Device ID
 * Max File Size
 * INode Count
 * INode Bitmap Block
 * INodes Start
 * INode Block Count
 * INodes per sector
 * Data Bitmap Block
 * Data Start
 * Data Block Count
 * Root INode Pointer
 * First Unreserved INode
 INode structure (64B)
 ---------------
 * Type
 * Size (bytes)
 * Sector Count (size in sectors)
 * Mode
 * Extent[4]
 * Single Indirect
 * Double Indirect?
 Extent (8B)
 ------
 * Block
 * Length
 Directory Entry (64B)
 ---------------
 * INode Number
 * Name (max length 60 Bytes)
 Filetypes
 ---------
 * File
 * Directory
 # TODO
 * Link
 * Device
 * Stream?
 These structs are defined in the libk header 'fs/fs.h'
@@ -1,8 +0,0 @@
 Magic addresses
 ===============
 This is a list of magic addreses that are used in kern.
 The goal is to minimize the number of these addreses.
 0x1000 - Memory map location, bootloader.memmap is a pointer to here
@@ -1,38 +0,0 @@
 Kern Dev Struct
 ===============
 Independant Modules
 -------------------
 * Each MUST have their own directory (eg. 'kernel/', 'boot/')
 * Each MAY have their own internal independant submodules (eg. userspace programs in 'usr/')
 * A module MAY be dependant on it's own submodules, but it's submodules MUST be independant of each other
 * Each MUST have a makefile in their directory (eg. 'libc/makefile')
 * Each module makefile MUST implement the 'all' and 'clean' targets
 * Each module MUST be listed in the 'make.defaults' directory
 * Each module MUST be self-contained and independentally compilable
 * A module SHOULD output binaries into the 'bin/' directory
 kern (Root "module", is dependant on all of it's submodules)
 |- boot
 |   |- bootsect (stage1)
 |   '- bootload (stage2)
 |- kernel
 |   '- libk
 |- libc (C Standard Library)
 '- user !EXCEPTION: Userspace programs are dependant upon libc!
     |- coreutils
     |- fdisk
     |- init
     |- mkfs
     |- sh
     ..
 TODO
 ====
 [ ] boot
 [ ] kernel
 [x] libc
 [ ] user
 [ ] makefile
 [ ] make.defaults
@@ -1,5 +1,5 @@
-Filesystem
+OS Filesystem
-==========
+=============
 Here's how the filesystem is layed out:
 	/
@@ -1,11 +1,17 @@
-=== System Calls === 
+System Calls 
 ============
-Syscall handlers are prefixed by 'sys_'
+Syscall handlers are prefixed by 'sys_'. Syscalls can be called using int 0x80.
-Syscalls can be called using interrupt 0x80
+Arguments are passed in registers like this:
-The EAX register should countain a syscall number on calling and it will contain a return value (if applicable) after calling
+* EAX - Syscall number
 * EBX - Argument 0
 * ECX - Argument 1
 * EDX - Argument 2
--- Syscall Table ---
+If the syscall returns, the return value will be in EAX.
 Syscall Table (TODO: Update this)
 -------------
 | NR | SYSC NAME | RETURN (EAX) | ARG0 (EBX) | ARG1 (ECX) | ARG2 (EDX) |
 | 00 | reserved  |       -      |      -     |      -     |      -     |
 | 01 | sleep     |       -      | uint ms    |      -     |      -     |