From 13b26134b330cc11cd1bab5a68e8ad44e06bf2e8 Mon Sep 17 00:00:00 2001
From: jonpas <jonpas33@gmail.com>
Date: Thu, 18 Jan 2018 00:12:28 +0100
Subject: [PATCH] Comment boot assembly, Add Setup, Dependencies and Resources
 to README.md

---
 README.md    | 27 ++++++++++++++++++++++++++-
 link.ld      |  1 -
 src/boot.asm | 39 +++++++++++++++++++++------------------
 3 files changed, 47 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index e56a696..fa42f8e 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,30 @@
 # FERI-TyrOS
 
-Operating System project for seminar paper at Operating Systems
+Operating System project for seminar paper at Operating Systems (slo. Operacijski Sistemi)
 
 Týr - Germanic god associated with law and heroic glory in Norse mythology, portrayed as **one-handed**.
+
+### Setup
+
+```
+$ make          # Build
+$ make bosch    # Build and run using bosch
+$ make qemu     # Build and run using qemu
+$ make debug    # Build and run using qemu in gdb
+$ make clean    # Clean build files
+```
+
+**Dependencies:**
+- GCC
+- NASM
+- GRUB
+- xorriso
+- bochs (with `--with-sdl` - `bochs-sdl` on Ubuntu, `PKGBUILD` edit on Arch Linux)
+- QEMU (instead of bochs and debugging)
+
+### Resources
+
+- [OSDev.org](http://wiki.osdev.org)
+- [James Molloy's Kernel Development Tutorials](http://www.jamesmolloy.co.uk/tutorial_html/index.html)
+- [James Molloy's Kernel Development Tutorials (Improved Source)](https://github.com/cirosantilli/jamesmolloy-kernel-development-tutorials)
+- [James Molloy's Tutorial Known Bugs](http://wiki.osdev.org/James_Molloy%27s_Tutorial_Known_Bugs)
diff --git a/link.ld b/link.ld
index d6fe316..a81ff43 100644
--- a/link.ld
+++ b/link.ld
@@ -1,7 +1,6 @@
 ENTRY(start)
 SECTIONS
 {
-
     .mbheader 0x100000 :
     {
         *(.mbheader)
diff --git a/src/boot.asm b/src/boot.asm
index ab04570..6f43fe2 100644
--- a/src/boot.asm
+++ b/src/boot.asm
@@ -1,26 +1,29 @@
+; Sets up multiboot configuration for GRUB
+
 MBOOT_PAGE_ALIGN    equ 1<<0        ; Load kernel and modules on a page boundary
-MBOOT_MEM_INFO      equ 1<<1        ; Provide your kernel with memory info
-MBOOT_HEADER_MAGIC  equ 0x1BADB002  ; Multiboot Magic value
-; NOTE: We do not use MBOOT_AOUT_KLUDGE. It means that GRUB does not
-; pass us a symbol table.
+MBOOT_MEM_INFO      equ 1<<1        ; Provide kernel with memory info
+MBOOT_HEADER_MAGIC  equ 0x1BADB002  ; Multiboot magic value (identify kernel as multiboot-compatible)
+; We do not use MBOOT_AOUT_KLUDGE, meaning GRUB does not pass us a symbol table
 MBOOT_HEADER_FLAGS  equ MBOOT_PAGE_ALIGN | MBOOT_MEM_INFO
-MBOOT_CHECKSUM      equ -(MBOOT_HEADER_MAGIC + MBOOT_HEADER_FLAGS)
+MBOOT_CHECKSUM      equ -(MBOOT_HEADER_MAGIC + MBOOT_HEADER_FLAGS) ; Error checking (must be 0)
 
 
-[BITS 32]
+[BITS 32]                   ; All instructions 32-bit
 
-[GLOBAL mboot]
-[EXTERN code]
-[EXTERN bss]
-[EXTERN end]
+[GLOBAL mboot]              ; Make 'mboot' accessible from C
+[EXTERN code]               ; Start of the '.text' section
+[EXTERN bss]                ; Start of the '.bss' section
+[EXTERN end]                ; End of last loadable section
 
 section .mbheader
 
+; Embed constants into kernel
 mboot:
     dd  MBOOT_HEADER_MAGIC
     dd  MBOOT_HEADER_FLAGS
     dd  MBOOT_CHECKSUM
-    dd  mboot
+    dd  mboot               ; Address of structure we are currently writing (for relocations)
+    ; Linker defined, defines sections where kernel can be located
     dd  code
     dd  bss
     dd  end
@@ -28,12 +31,12 @@ mboot:
 
 section .text
 
-[GLOBAL start]
-[EXTERN main]
+[GLOBAL start]              ; Kernel entry point
+[EXTERN main]               ; C code entry point
 
 start:
-    ; Load multiboot information:
-    push    ebx
-    cli
-    call main
-    jmp $
+    ; Load multiboot information
+    push    ebx             ; Save mboot information structure
+    cli                     ; Disable interrupts
+    call    main            ; Call 'main()' C function
+    jmp     $               ; Continue loop