Comment boot assembly, Add Setup, Dependencies and Resources to READM…

…E.md

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)

link.ld

@@ -1,7 +1,6 @@
 ENTRY(start)
 SECTIONS
 {
-
     .mbheader 0x100000 :
     {
         *(.mbheader)

src/boot.asm

@@ -1,39 +1,42 @@
+; 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
     dd  start
 
 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