1 files changed, 82 insertions, 0 deletions
diff --git a/docs/Building-and-running-explained.txt b/docs/Building-and-running-explained.txt
new file mode 100644
index 0000000..257c75f
--- /dev/null
+++ b/docs/Building-and-running-explained.txt
@@ -0,0 +1,82 @@
+# Building and running
+
+Dependencies:
+
+1. Native GCC (+ binutils)
+2. ARM cross-compiler GCC (+ binutils) (arm-none-eabi works - others might or might not)
+3. GNU Make
+4. rpi-open-firmware (for running on the Pi)
+5. GNU screen (for communicating with the kernel when running on the Pi)
+6. socat (for communicating with the bootloader when running on the Pi)
+7. Qemu ARM (for emulating the Pi).
+
+For building rpi-open-firmware You will need more tools (not listed here).
+
+The project has been tested only in Qemu emulating Pi 2 and on real Pi 3. Running on Pis other than Pi 2 and Pi 3 is sure to require changing the definition in global.h (because peripheral base addresses differ between Pi versions) and might also require other modifications, not known at this time.
+
+## Building the project
+
+Assuming make, gcc, arm-none-eabi-gcc and its binutils are in the PATH, the kernel can be built with:
+
+    $ make kernel.img 
+which is the same as:
+
+    $ make
+The bootloader can be built with:
+
+    $ make loader.img
+
+Both loader and kernel can then be found in build/
+
+## Running in Qemu
+
+To run the kernel (passed as elf file) in qemu, run:
+
+    $ make qemu-elf
+
+If You want to pass a binary image to qemu, run:
+
+    $ make qemu-bin
+    
+If You want to pass loader image to qemu and pipe kernel to it through emulated uart, run:
+
+    $ make qemu-loader
+Note, that with qemu-loader the kernel will run, but will be unable to receive any keyboard input.
+
+The timer used by this project is the ARM timer ("based on an ARM AP804", with registers mapped at 0x7E00B000 in the GPU address space). It's absent in emulated environment, so no timer interrupts can be witnessed in qemu, as it would require to us to use simulated qemu clock.
+
+## Running on real hardware.
+
+First, build and test rpi-open-firmware. Now, copy either kernel.img or loader.img to the SD card (next to bootcode.bin) and rename it to zImage. Also copy .dtb file corresponding to your Pi (actually, any .dtb will do, it is not used right now) from stock firmware files to the SD card and name it rpi.dtb. Finally, create a cmdline.txt on the SD card (content doesn't matter).
+
+Now, connect RaspberryPi via UART to Your machine. GPIO on the Pi works with 3.3V, so You should make sure, that UART device on the other end is also working wih 3.3V. This is the pinout of the RaspberyPi 3 model B that has been used for testing so far:
+
+Top left of the board is here
+
++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+  
+| 2| 4| 6| 8|10|12|14|16|18|20|22|24|26|28|30|32|34|36|38|40|  
++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+  
+| 1| 3| 5| 7| 9|11|13|15|17|19|21|23|25|27|29|31|33|35|37|39|  
++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+  
+
+Under rpi-open-firmware (stock firmware might map UARTs differently):
+
+    pin 6 is Ground
+    pin 8 is TX
+    pin 10 is RX
+
+Once UART is connected, You can power on the board.
+
+Assuming a USB to UART adapter is used and it is seen by Your system as /dev/ttyUSB0:
+
+If You copied the kernel to the SD card, You can start communicating with it by running:
+
+    $ screen /dev/ttyUSB0 115200,cs8,-parenb,-cstopb,-hupcl
+    
+If You copied the loader, You can send it the kernel image and start communicating with the system by running:
+
+    $ make run-on-rpi
+
+To run again, replug USB to UART adapter and Pi's power supply (order matters!) and re-enter the command. Replugging power supply and running the command again should also work unless screen dies.
+
+Running under stock firmware has not been performed. In particular, the default configuration on RaspberryPi 3 seems to map other UART than used by the kernel (so-called miniUART) to pins 6, 8 and 10. This is supposed to be configurable through the use of overlays.