doc: Documentation + anglicisation

bootloader/bootSector/bootloader.asm

@@ -1,27 +1,29 @@
-; Load tout le programme en 0x7c00 = définit un offset
+; Bootloader, first bytecode loaded, 16 bits only
+
+; Load all the program to the offset 0x7c00
 [org 0x7c00]
 
-; Numéro du disque
+; Disk number
 mov [BOOT_DISK], dl
 
-; Création du stack, début à 0x7c00
+; Stack creation at 0x7c00
 mov bp, 0x7c00
-; Stack pointer, current mem address
+; Stack pointer == current memory address
 mov sp, bp
 
 call readDisk
 
-; Jump aux secteurs suivants
+; Jump to next sectors
 jmp PROGRAM_SPACE
 
 %include "printString.asm"
 %include "diskRead.asm"
 
-; Écriture du boot sector (512 premiers bytes du disque terminés par 0x55 0xaa) pour booter l'OS
-; Répète "db 0" (écrit 0) jusqu'à 2 bytes avant la fin du boot sector
-; $$ : début de la section courante, adresse de la 1ère ligne
-; Par déduction, ($ - $$) = taille du code précédent
+; Write the end of the boot sector (first 512 bytes of the disk, ended by 0x55 0xaa) to boot the OS
+; Writes 0 until 2 bytes before the end of the boot sector
+; $$ : current section section, 1st line address
+; Thus ($ - $$) == precedent code size
 times 510-($-$$) db 0
 
-; Écriture des 2 derniers bytes du boot sector
+; 2 last boot sector bytes
 db 0x55, 0xaa

bootloader/bootSector/diskRead.asm

@@ -1,60 +1,65 @@
-; 512 bytes apres 0x7c00
+; Disk utilities and stuff
+; 16 bits only
+
+; 512 bytes after 0x7c00
 PROGRAM_SPACE equ 0x8000
 
+; Reads the disk
 readDisk:
-    ; Configure le BIOS pour lire le disque
+    ; Configure BIOS to read the disk
     mov ah, 0x02
 
-    ; Pour que le BIOS sache où mettre la data en mémoire
+    ; So the BIOS know where to load data in mémoire
     mov bx, PROGRAM_SPACE
 
-    ; Nombre de secteurs de 512 bytes du disque
-    ; %include "diskReadSegments.asm"
+    ; Number of 512 bytes sectors on the disk
+    ; TODO: %include "diskReadSegments.asm"
     mov al, 127
 
-    ; Quel disque choisir
+    ; Which disk to choose
     mov dl, [BOOT_DISK]
 
-    ; Cylindre num 0 (hard drive)
+    ; Cylinder number 0 (hard drive)
     mov ch, 0x00
 
-    ; Head num 0 (hard drive)
+    ; Head number 0 (hard drive)
     mov dh, 0x00
 
-    ; Lecture à partir du 2e secteur, le 1er étant le boot sector
+    ; Starts reading at the 2nd secteur (the 1st one being the boot sector)
     mov cl, 0x02
 
+    ; Main reading loop
     diskReadLoop:
+        ; FIXME: Shouldn't we push and pop ?
         ; push ax
         ; push bx
         ; push cx
         ; push dx
 
-        ; Interruption BIOS pour lire
+        ; BIOS interrupt to read
         int 0x13
 
         ; pop dx
         ; pop cx
         ; pop bx
         ; pop ax
 
-        ; Bon, l'avenir nous dira si ce code était une erreur ou non...
-        ; Jmp if carry set (= erreur disque)
+        ; Jump if carry set, if there's an error on the disk
         jc diskReadExit
-        ; Autre possibilité:
-        ; jc diskReadError
+        ; FIXME: why not `jc diskReadError` ?
 
-        ; Écriture des 512 bytes suivants
+        ; Writes the next 512 bytes
         add bx, 512
-        ; Lecture secteur suivant
+        ; Reads the next sector
         inc cx
 
-         ; limite de 255 secteurs
+        ; Hard limit of 255 sectors
         cmp cl, 255
         je diskReadExit
 
         jmp diskReadLoop
 
+    ; Exit loop
     diskReadExit:
         ; pop dx
         ; pop cx
@@ -69,7 +74,7 @@ diskReadErrorString:
 diskReadError:
     mov bx, diskReadErrorString
     call printStringBIOS
-    ; Boucle infinie parce que erreur de toute façon
+    ; Infinite loop but we don't really care here, the failure is unrecoverable
     jmp $
 
 BOOT_DISK:

bootloader/bootSector/diskReadSegments.asm

@@ -1,3 +1,3 @@
-; Fichier généré automatiquement.
-; La valeur est calculée selon l'espace occupé par le fichier binaire final.
+; AUTO-GENERATED FILE
+; This value is calculated using the final binary file size.
 mov al, 42

bootloader/bootSector/printString.asm

@@ -1,23 +1,26 @@
-; Affiche une chaine de caractères terminée par '\0'
+; Prints the string
+; 16 bits-only I think ? Because BIOS only
+
+; Outputs a string ending with '\0'
 printStringBIOS:
     push ax
     push bx
 
-    ; BIOS set en mode TTY
+    ; BIOS set to TTY mode
     mov ah, 0x0e
 
     .loopPrintString:
 
-    ; Comparaison de bx et de \0
+    ; Compare bx and `\0`
     cmp [bx], byte 0
 
-    ; Check le flag d'égalité, si == alors jmp exitPrintString
+    ; Checks equality flag, and jump to exitPrintString if equals
     je .exitPrintString
-        ; Registre d'écriture
+        ; Write registry
         mov al, [bx]
-        ; Interruption BIOS pour écrire le contenu de al
+        ; BIOS interrupt to write the content of al
         int 0x10
-        ; Incrémente bx pour passer au caractère suivant
+        ; Increments bx to compare next character
         inc bx
         jmp .loopPrintString
     .exitPrintString:

bootloader/secondSector/CPUID.asm

@@ -1,41 +1,43 @@
-; Flip un bit, s'il reste identique alors CPUID est supporté
+; CPUID detection
+
+; Flips a bit, if the bit isn't changed then CPUID is supported
 detectCPUID:
-    ; Push flags dans le stack
+    ; Push flags to stack as a backup
     pushfd
     pop eax
 
     ; Backup eax
     mov ecx, eax
 
-    ; Flip un bit
+    ; Flip the bit
     xor eax, 1 << 21
 
-    ; Pop eax dans flags
+    ; Pop eax to the flags
     push eax
     popfd
 
     pushfd
     pop eax
 
-    ; Restore flags à ancienne version
+    ; Restore the flags to the old version
     push ecx
     popfd
 
-    ; Check différence
+    ; Check the difference
     xor eax, ecx
 
-    ; jmp if zero
+    ; Jump if zero
     jz noCPUID
 
     ret
 
-; No CPUID support
+; No CPUID support, can't continue
 noCPUID:
     hlt
 
-; Détection du long-mode pour 64-bits mode
+; Long-mode for 64-bits detection
 detectLongMode:
-    ; Gros nombre
+    ; Big number just to check
     mov eax, 0x80000001
     cpuid
     test edx, 1 << 29

bootloader/secondSector/GDT.asm

@@ -1,10 +1,12 @@
-; GDT: structure définissant l'accès à la RAM, la taille de la RAM et les privilèges système
+; GDT: structure defining the RAM (access, size, system privileges...)
+; x86
 
-; Null Descriptor du GDT
+; GDT Null Descriptor
 gdt_nullDesc:
     dd 0
     dd 0
 
+; Code segment descriptor, executable
 ; Structure:
 ; [ 0, 15]: Limit 0:15
 ; [16, 31]: Base 0:15
@@ -14,39 +16,40 @@ gdt_nullDesc:
 ; [52, 55]: Flags
 ; [56, 63]: Base 24:31
 gdt_codeSegmentDesc:
-    ; Limit, on couvre l'intégralité de la RAM
+    ; Limit, entierly covers the RAM
     dw 0xffff
     ; Base (low)
     dw 0x0000
     ; Base (med)
     db 0x00
 
     ; Access byte (flags)
-    ; 1, Pr         : Secteur valide ("present") ou non ("not present" => marqué comme ignoré)
-    ; 00, Privil    : Privilège de 0 à 3, ici kernel donc 0
-    ; 1, S          : Descriptor top, 1 pour code et data segment, 0 pour system segment
-    ; 1, Ex         : Exécutable ou non
-    ; 0, DC         : Direction, si peut être exécuté avec moins de privilège ou si doit avoir forcément Pr
-    ; 1, RW         : Readable ou non
-    ; 0, Ac         : Set par le CPU lorsque le segment est accédé
+    ; 1, Pr         : Valid sectors, "present" or "not present" => marked as ignored
+    ; 00, Privil    : Privilege, 0 to 3, kernel level here so 0
+    ; 1, S          : Descriptor top, 1 for code and data segments, 0 for system segment
+    ; 1, Ex         : Executable or not
+    ; 0, DC         : Direction, if it can be executed with less privileges or if it requires Pr
+    ; 1, RW         : Readable or not
+    ; 0, Ac         : Sets by the CPU when the segmen is accessed
     db 10011010b
 
     ; Flags + upper limit
-    ; 1, Gr         : Granularité, limite en blocs (4 ko) ou en bytes
-    ; 1, Sz         : Size, 32-bits protected ou 16-bits protected
-    ; 00            : Non utilisé
+    ; 1, Gr         : Granularity, limit in 4 kB blocs or in bytes
+    ; 1, Sz         : Size, 32-bits protected or 16-bits protected
+    ; 00            : Not used here
     ; 1111          : Limit
     db 11001111b
 
     ; Base (high)
     db 0x00
 
-; Quasiment identique à codeSegmentDesc
+; Data segment descriptor, not executable
+; Almost identical to codeSegmentDesc
 gdt_dataSegmentDesc:
     dw 0xffff
     dw 0x0000
     db 0x00
-    ; Non exécutable
+    ; Not executable
     db 10010010b
     db 11001111b
     db 0x00
@@ -62,10 +65,11 @@ codeSegment equ gdt_codeSegmentDesc - gdt_nullDesc
 dataSegment equ gdt_dataSegmentDesc - gdt_nullDesc
 
 [bits 32]
-; Passe le GDT en 64 bits
+; GDT goes to x64
 editGDT:
     mov [gdt_codeSegmentDesc + 6], byte 10101111b
     mov [gdt_dataSegmentDesc + 6], byte 10101111b
     ret
 
 [bits 16]
+; FIXME: Shouldn't it be in extendedProgram ?

bootloader/secondSector/IDT.asm

@@ -1,12 +1,14 @@
+; Interrupt Descriptor Table, x64 only
+
 [extern _idt]
 IDTDescriptor:
     ; 256 entries * 16 bytes
     dw 4095
 
-    ; IDT utilisé par le linker
+    ; IDT used by the linker
     dq _idt
 
-; Garde l'état des registres
+; Backup the registry state
 %macro PUSHALL 0
     push rax
     push rcx
@@ -17,7 +19,7 @@ IDTDescriptor:
     push r11
 %endmacro
 
-; Récupère l'état des registres
+; Load the regirstry state
 %macro POPALL 0
     pop r11
     pop r10
@@ -28,23 +30,24 @@ IDTDescriptor:
     pop rax
 %endmacro
 
+; Will be defined in the kernel
 [extern isr1Handler]
 
-; Rend isr1 global et donc utilisable par le kernel C++
+; isr1 is usable by the C++ kernel
 GLOBAL _isr1
-; Interrupt service routine 1, = keyboard
+; Interrupt service routine 1, == keyboard
 _isr1:
-    ; Pour maintenir l'état des registres
+    ; So we can keep the registry state
     PUSHALL
     call isr1Handler
     POPALL
-    ; Interrupt return quad (car 64 bits)
+    ; 64 bits so quad
     iretq
 
 GLOBAL _loadIDT
-; Charge les interruptions IDT
+; Loads the IDT interrupts
 _loadIDT:
     lidt [IDTDescriptor]
-    ; Active les interruptions IDT
+    ; Enable the IDT interrupts
     sti
     ret

bootloader/secondSector/binaries.asm

@@ -1,4 +1,4 @@
-; Inclure les binaires
+; Includes binaries
 %macro incBin 2
     SECTION .rodata
     GLOBAL %1