explain building and running

1 files changed, 62 insertions, 0 deletions

diff --git a/Building-and-running-explained.txt b/Building-and-running-explained.txt
new file mode 100644
index 0000000..3493d2d
--- /dev/null
+++ b/Building-and-running-explained.txt
@@ -0,0 +1,62 @@
+Dependencies:
+1. Native GCC (+ binutils)
+2. ARM cross-compiler GCC (+ binutils) (arm-none-eabi works - other ones 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 it's binutils are in the PATH, the kernel can be built with:
+  $ make kernel.img
+or:
+  $ 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.
+
+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, because 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
+|
+v
+
++--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
+| 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.
+
+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.