Split up getting started, create an about

README.md

@@ -1,7 +1,9 @@
 # x86 Bare Metal Examples
 
-Hello world programs that run without an operating system.
+Minimal operating systems to learn low level programming.
 
+1.  [Getting started](getting-started.md)
+1.  [About](about.md)
 1.  Examples
     1.  [printf](printf/)
     1.  [min](min.S)
@@ -64,59 +66,3 @@ Hello world programs that run without an operating system.
     1.  [Debug](debug.md)
     1.  [Bibliography](bibliography.md)
 1.  [TODO](TODO.md)
-
-## Getting started
-
-    sudo apt-get install bochs bochs-sdl build-essential gdb gnu-efi qemu nasm xorriso
-
-### Emulator
-
-Run the default program on QEMU:
-
-    make run
-
-Run a given program:
-
-    make run RUN=min
-    make run RUN=bios_one_char
-
-Use Bochs instead of QEMU:
-
-    make bochs RUN=min
-
-Tested on Ubuntu 14.04 AMD64.
-
-### Real hardware
-
-Insert an USB, determine its device (`/dev/sdX`) with:
-
-    sudo lsblk
-    sudo fdisk -l
-
-Pick the `.img` file that you wan to run and:
-
-    sudo dd if=bios_hello_world.img of=/dev/sdX
-
-Then:
-
-- insert the USB in a computer
-- during boot, hit some special hardware dependant key, usually F12, Esc
-- choose to boot from the USB
-
-When you are done, just hit the power button to shutdown.
-
-Tested on: ThinkPad T400.
-
-#### Big image
-
-Create a `big.img` that contains all examples that can be booted from GRUB:
-
-    make big-img
-
-Now if you do:
-
-    sudo dd if=big.img of=/dev/sdX
-
-you can test several examples with a single USB burn, which is much faster.
-
-You will also want to change the boot order to put the USB first from the F12 BIOS menu. This way you don't have to hit F12 like a madman every time.

TODO.md

@@ -85,12 +85,13 @@
 
 -   multithreading:
 
-    http://stackoverflow.com/questions/7308391/how-is-concurrency-done-in-intel-x86-assembly || http://stackoverflow.com/questions/980999/what-does-multicore-assembly-language-look-like || http://stackoverflow.com/questions/714905/threads-in-x86-assembler-using-the-gnu-assember-as || https://github.com/cirosantilli/oszur11-operating-system-examples/tree/1af6451852887fac3d7206d4d09714c181c81d1e/Chapter_07_Threads
+    - http://stackoverflow.com/questions/7308391/how-is-concurrency-done-in-intel-x86-assembly
+    - http://stackoverflow.com/questions/980999/what-does-multicore-assembly-language-look-like
+    - http://stackoverflow.com/questions/714905/threads-in-x86-assembler-using-the-gnu-assember-as
+    - https://github.com/cirosantilli/oszur11-operating-system-examples/tree/1af6451852887fac3d7206d4d09714c181c81d1e/Chapter_07_Threads
 
 -   play with hardware
 
-    -   keyboard through interrupt (high level BIOS int 16 that waits for input done)
-        - keyboard protected mode: http://stackoverflow.com/questions/219120/x86-assembly-protected-mode-keyboard-access
     -   set a pixel on screen in protected mode http://stackoverflow.com/questions/14419088/assembly-draw-a-pixel-on-the-screen-in-protected-mode
     -   USB
     -   networking
@@ -105,3 +106,12 @@
 -   https://en.wikipedia.org/wiki/Task_state_segment
 
     Not used by Linux: <http://stackoverflow.com/questions/2711044/why-doesnt-linux-use-the-hardware-context-switch-via-the-tss>
+
+-   keyboard through interrupt (high level BIOS int 16 that waits for input done)
+
+    - keyboard protected mode: http://stackoverflow.com/questions/219120/x86-assembly-protected-mode-keyboard-access
+    - oszur does it with the i8042: http://stackoverflow.com/questions/22744624/keyboard-interrupt-handler-for-own-kernel-c
+
+-   mouse
+
+

about.md

@@ -0,0 +1,13 @@
+# About
+
+There are a few tutorials that explain how to make an operating system and give examples of increasing complexity with more and more functionality added.
+
+This is not one of them.
+
+The goal of this repository is to use the minimal setup possible to be able to observe *a single* low-level programming concept for each minimal operating system we create.
+
+This is not meant provide a template from which you can write a real OS, but instead to illustrate how those low level concepts work, so that you can use that knowledge to implement operating systems or drivers.
+
+Minimal examples are useful because it is easier to observe the requirements for a given concept to be observable.
+
+Another advantage is that it is easier to DRY up minimal examples (here done simply through `#include` and macros), which is much harder on progressive OS template tutorials, which tend to repeat big chunks of code between the examples.

bibliography.md

@@ -65,7 +65,7 @@ The following did not work on my machine out of the box:
 
     Not tested yet.
 
-    GAS based, no GRUB needed.
+    GAS based, no multiboot used.
 
 ## Actually useful
 

getting-started.md

@@ -0,0 +1,55 @@
+# Getting started
+
+    sudo apt-get install bochs bochs-sdl build-essential gdb gnu-efi qemu nasm xorriso
+
+## Emulator
+
+Run the default program on QEMU:
+
+    make run
+
+Run a given program:
+
+    make run RUN=min
+    make run RUN=bios_one_char
+
+Use Bochs instead of QEMU:
+
+    make bochs RUN=min
+
+Tested on Ubuntu 14.04 AMD64.
+
+## Real hardware
+
+Insert an USB, determine its device (`/dev/sdX`) with:
+
+    sudo lsblk
+    sudo fdisk -l
+
+Pick the `.img` file that you wan to run and:
+
+    sudo dd if=bios_hello_world.img of=/dev/sdX
+
+Then:
+
+- insert the USB in a computer
+- during boot, hit some special hardware dependant key, usually F12, Esc
+- choose to boot from the USB
+
+When you are done, just hit the power button to shutdown.
+
+Tested on: ThinkPad T400.
+
+### Big image
+
+Create a `big.img` that contains all examples that can be booted from GRUB:
+
+    make big-img
+
+Now if you do:
+
+    sudo dd if=big.img of=/dev/sdX
+
+you can test several examples with a single USB burn, which is much faster.
+
+You will also want to change the boot order to put the USB first from the F12 BIOS menu. This way you don't have to hit F12 like a madman every time.

segment_base.S

@@ -1,5 +1,5 @@
 /*
-TODO get working.
+TODO get working. All tutorials I've seen so far just set it to 0 like real OSes :-(
 
 Example of the effect on a memory access of changing the segment base address .
 
@@ -60,7 +60,7 @@ BEGIN
     /*
     TODO this sanity check is not printing "ab",
     so we're not restoring the old state properly.
-    HOW??
+    Likely blows up because video memory going wrong.
     */
     VGA_PRINT_STRING $message