# Raspberry Pi

Dusk OS runs on the RPi models 1, 2 and 3. The kernels for those machines are
based on [xcomp/arm/kernel.fs] with RPi-specific modifications. The kernel for
the model 1 is at [xcomp/arm/rpi/kernel1.fs] and the kernel for the model 2 and
3 (it's the same kernel) is at [xcomp/arm/rpi/kernel2.fs].

Those kernels, along with their associated boot payload, are expected to be
loaded by the RPi firmware at address $8000 and then ran. A default config.txt
works fine. All you need to do is to place the kernel+payload in "kernel.img"
for the RPi1 and "kernel7.img" for the RPi 2 and 3.

The simplest possible configuration is a UART [doc/hw/arm/rpi/uart] and eMMC
[doc/hw/arm/rpi/emmc] one, but there's also support for the DWC USB controller
[doc/hw/arm/rpi/dwc] as well as its video framebuffer [doc/hw/arm/rpi/vcore].

The GPIOs [doc/hw/arm/rpi/gpio] provide a good way to implement a break
[doc/break] mechanism, which is described in [doc/hw/arm/rpi/break].

The RPi image can be built with `make rpifat.img` and can be ran under QEMU with
`make rpirun`. This builds a kernel for the RPi model 1. To build a kernel for
models 2 and 3 (they can run the same kernel), modify "kernel1" for "kernel2"
in /xcomp/arm/rpi/build.fs and then run `make rpifat.img`. To run this kernel
with QEMU, modify the Makefile and change "raspi1ap" for "raspi2b".

Note that CTRL+D isn't sufficient to quit QEMU, you have to go
through QEMU's monitor by pressing CTRL-A, then C. From there, you can type
"quit" to quit.

## Deploying on a real machine

To deploy on a real machine, you do:

1. "make rpifat.img"
2. "dd" "rpifat.img" to a SD card
3. Mount that SD card.
4. Copy "rpikernel.img" to mounted FAT as "kernel.img". If it's a "kernel2"
   image, copy to "kernel7.img" instead.
5. Copy the "bootcode.bin" and "start.elf" files from the "firmware/rpi"
   directory into the root of the SD card.
6. Insert your SD card in the Raspberry Pi and power it on. It should boot!

At this moment, only the GPIO-based UART is supported, so "power it on" means to
connect the RPi to a tty-UART adapter and send it power from there.

If you can't type, make sure you disable hardware flow control from your tty
line.

On the RPi 3, I've noticed a pretty big delay in EMMC initialization, I'm not
sure of its root cause. It can take up to 10 seconds before you see the "Dusk
OS" prompt.

## Further information

The main source of information for Raspberry Pi development is from the
Raspberry Pi foundation itself[1].

This Git repository contains, for example, the BCM2835 technical documentation,
which is the main document against which Dusk's first foray into the ARM world
is built.

[1]: https://github.com/raspberrypi/documentation.git
