So you'd like to contribute to`rpi-open-firmware`?

First things first, please come on IRC before starting anything. While not strictly a rule, this prevents duplicate work. When you are ready after that, we accept pull requests over Github, or if you prefer you can email a patch or link to one over IRC.

A few notes on style:

* Contributors should use hard tabs.

* C++ is the preferred language for high-level code.

* Generally follow conventions of similar code in the project.

This is a small firmware for RPi VPU (VideoCore4) versions 1/2/3 that is capable of initializing UART, VPU PLL (PLLC) and ARM itself. It's intended to be used instead of stock`bootcode.bin` on RPi's SD card. You**need** to have UART to see anything meaningful as far as output goes. The project additionally maintains a second-stage chainloader running on ARM capable of initializing eMMC, FAT, and the Linux kernel, as well as a shrinking set of patches to the Linux kernel.

This has been tested on RPi1 Model B (Hynix PoP DDR),RPi 2 Model B and RPi 3 Model B (both Elpida DDR), but it should work with minimal modifications on all ofthemodels. Development primarily targets the RPi 2 Model B.

`rpi-open-firmware` is a small firmware for the[RPi VPU](https://en.wikipedia.org/wiki/VideoCore), capable of initializing UART, VPU PLL (PLLC),and ARM itself. It's intended as a libre replacement for the stock`bootcode.bin` normally loaded from the SD card. A UART cable is highly recommended forthetime being, though not strictly necessary. Additionally, there is a second-stage chainloader running on ARM capable of initializing eMMC, FAT, and the Linux kernel.

You need Julian Brown's VC4 toolchain to build this (https://github.com/puppeh/vc4-toolchain) as well as a arm-none-eabi-toolchain. You can tweak the paths to it in CROSS_COMPILE in`Makefile` (for VC4) and for ARM in`arm_chainloader/Makefile`, although by default it assumes they are currently in your path. Contributors should not commit their personal paths. Contributors should also use tabs for indentation. After you've done it, run`buildall.sh` and you should have a blob in`build/bootcode.bin`.

+ vc4-toolchain (https://github.com/puppeh/vc4-toolchain)

+ arm-none-abi-toolchain (https://launchpad.net/gcc-arm-embedded/+download)

+ compilation instructions for OSX in the[pdf](https://launchpadlibrarian.net/287100910/How-to-build-toolchain.pdf)

Compiling for osx is similar, but be careful with OSX's built-in "gcc" (LLVM-based) and the default version of guile (2.x), which is incompatible.

Install dependencies:

All Broadcom headers are licensed under 3-Clause BSD License while our code is under GPLv2+. See`LICENSE` for more information. Various external projects are mirrored under a mix of GPL-compatible licenses.

Install the arm toolchain.

Download the source and dependencies together for vc4-toolchain:

Once it’s done, you’ll need to add file paths to your $PATH variable:

From the main instructions ("After you've done it, run buildall.sh and you should have a blob in build/bootcode.bin"):

As a prerequisite, Julian Brown's[VC4 toolchain](https://github.com/puppeh/vc4-toolchain) is necessary as well as the`arm-none-eabi-` toolchain (Debian package`gcc-arm-none-eabi`). You can tweak the VC4 toolchain path in`CROSS_COMPILE` in`Makefile` and the ARM path in`arm_chainloader/Makefile` if necessary. Contributors should not commit their personal paths. After configuration, run`buildall.sh`. The binary is at`build/bootcode.bin`, ready to be copied to an SD card.

Note:onthe last step, the library path is set as it initially had a trailing ":" which broke the build.`CC=gcc-6` is just to ensure it's using the gcc install from the first step.

That's it! Your shiny new binary is sitting at rpi-open-firmware/build/bootcode.bin.

The firmware is split into two parts, a VC4 part and and ARM part. The VC4 part initializes PLLC and moves VPU over to it, and then brings up UART. It then performs SDRAM initialization, making SDRAM available at`0xC0000000` (uncached alias). The ARM loader will do ARM initialization and then copy the ARM bootloader that's embedded in it to the alias. It will then map it to`0x0` in ARM's memory space and start ARM. The code under`arm_chainloader` is what will run on the ARM.

The ARM chainloader then initializes the eMMC controller and access the boot partition with a FAT driver. From here, it chainloads the Linux kernel (other payloads are not tested and are not likely to work due to dependence on the firmware).

The firmware is split into two parts, one running on the VC4 and the other on ARM. The VC4 part initializes PLLC and moves VPU over to it, and then brings up UART. It performs SDRAM initialization, mapping it to`0xC0000000` (uncached alias). Next, ARM is initialized, and the embedded bootloader is mapped to ARM address`0x0`.`arm_chainloader` is then executed.

Thecurrent makefiles in theARM part of it aim at**RPi1** (ie. ARMv6) but they can be changed to ARMv7 if you want to build it for a newer model. It was tested on all RPi modelsandit seems to work without any issues (ARM can access peripherals and memory just fine as AXI supervisor). However, itcannot access any secure peripherals (OTP/SDRAM/etc) since they appear to be on a separate bus accessible onlytoVC4.

TheARM chainloader initializes theeMMC controllerandaccesses the FAT boot partition. From here, itchainloads the Linux kernel (other payloads likely do not work duetomailbox usage).

Yes, with some conditions. You can boot a very minimal version of Linux without the firmware and get it to work with UART. Support foreMMC, some USB devices, and Ethernet are in the works, which will be sufficient for certain headless systems. Still,you can expect half of the things to be broken (most importantly, video and DMA). Additionally,since`start.elf` is responsibleforclock andpower managementin the original firmware (all registers in the`cpr` block), these drivers will havetobe rewritten on ARM or our VC4 firmware to have most of the peripherals working properly (HDMI, for example).

Yes, with some conditions. You can boot a very minimal version of Linux without the firmware and get it to work with UART and eMMC. Support forUSB, DMA, and Ethernet are in the works, which will be sufficient for certain headless systems. Still,many other peripherals require bringup, such as video. Additionally,driversfor power managementneedtowritten.

***[Herman Hermitage](https://github.com/hermanhermitage)** for his VC4 documentation and for helping determine suitable ARM PLL configurations.

***[Julian Brown](https://github.com/puppeh)** for reviewing the code and for his awesome VC4 toolchain.

***[Alyssa Rosenzweig](https://github.com/bobbybee)** for her contributions to the firmware especially in areas of Linux bringup and early ARM side initialization, as well as fixing mailbox support.

***[David Given](https://github.com/davidgiven)** for his initial LLVM project used as the base for the initial LLVM toolchain before moving to GCC.

***[phire](https://github.com/phire)** for reviewing the code.

***[Scott Mansell](https://github.com/phire)** for reviewing the code.

***[Broadcom](https://github.com/broadcom)** for their header release.

* Various other people not mentioned here.