Reference compatibility table in README
[rpi-open-firmware.git] / README.md
index c5ff226..18a66f3 100755 (executable)
--- a/README.md
+++ b/README.md
@@ -1,39 +1,35 @@
 # Minimal Raspberry Pi VPU firmware\r
-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.\r
 \r
-This has been tested on RPi1 Model B (Hynix PoP DDR), RPi 2 Model B and RPi 3 Model B (both Elpida DDR). \r
+`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 for the time being, though not strictly necessary. Additionally, there is a second-stage chainloader running on ARM capable of initializing eMMC, FAT, and the Linux kernel.\r
 \r
-If you want to contact me because you're interested in contributing, you can message `kristina` on Freenode, but I would suggest talking in `#raspberrypi-internals` instead.\r
+See [issue #31](https://github.com/christinaa/rpi-open-firmware/issues/31) for a compatibility table and related discourse.\r
 \r
-All Broadcom headers are licensed under 3-Clause BSD License while the rest of this is under GPLv2+. See `LICENSE` for more information.\r
+Technical discussion occurs in `#raspberrypi-internals` on [Freenode](http://webchat.freenode.net/?channels=#raspberrypi-internals). Please come on IRC before randomly hacking on the codebase :-)\r
 \r
-## Building\r
+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.\r
 \r
-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`. After you've done it, run `buildall.sh` and you should have a blob in `build/bootcode.bin`. \r
+## Building\r
 \r
-## Technical Details\r
-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. \r
+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.\r
 \r
-The current iteration of ARM chainloader (which I've still yet to commit) can actually initialize the eMMC controller and access the boot partition with a FAT driver. From here, it would be trivial to chainloaded the next stage bootloader *but* you still face the issues of missing a substantial portion of the drivers that were previously provided by the firmware.\r
+### Building on macOS\r
 \r
-The current makefiles in the ARM 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. I tested it on all RPi models and it works without any issues as far as I can tell (ARM can access peripherals and memory just fine as AXI supervisor). However it cannot access any secure peripherals (OTP/SDRAM/etc) since they appear to be on a separate bus accessible only to VC4.\r
+macOS compilation is similar to GNU/Linux, save platform errata described here. Instructions to build the ARM toolchain are [here](https://launchpadlibrarian.net/287100910/How-to-build-toolchain.pdf). Due to symlinking by default, GCC must be installed manually, and, an older version of guile is necessary (homebrew packages `gcc-6` and `guile18`, respectively). Finally, set the environment variable `LIBRARY_PATH` to `/lib:/lib64` when running `buildall.sh. \r
 \r
-**Beware:** This doesn't handle SMP at the moment so if you run this on RPi2 and above, all ARM cores will start executing the ARM bootloader code at the start which could cause problems. I will fix this soon.\r
+## Technical Details\r
+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.\r
 \r
-## Issues/Fixes\r
- * PLL rate on ARM is slow, it's a bit annoying. Need to tweak the PLL rate later.\r
- * All SDRAM configurations (including 1GB work), however, I'm not certain whether they will be reliable or not . ARM detection works for all of the RPi models I got to test it on which was two RPi2s, 1 RPi1 and 1 RPi3.\r
- * SD card support kind of works now, can parse MBR, parse the FAT boot partition but it still needs to pull off a next stage bootloader of it (possibly u-boot/LittleKernel or maybe even just start Linux straight from bootcode.bin).\r
- * The VPU still needs some sort of a firmware since ARM can't access all registers by itself, at the moment I'm trying to figure out how the VC4 interrupt controller works and how I can wake the sleeping VPU from ARM and get it to do things via a mailbox.\r
+The ARM chainloader initializes the eMMC controller and accesses the FAT boot partition. From here, it chainloads the Linux kernel (other payloads likely do not work due to mailbox usage).\r
 \r
-## Does/Will it boot Linux?\r
+## Does it boot Linux?\r
 \r
-Eventually maybe. Since `start.elf` is responsible for clock and power management (all registers in the `cpr` block), these drivers will have to be rewritten on ARM (or even on the open source VC4) to have any meaningful peripherals working properly (for example HDMI/DMA/Pixel Valve/Whatever). You can boot a very minimal version of Linux without the firmware and get it to work with UART and some USB devices, but you can expect half of the things to be broken (most importantly, video and DMA).\r
+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 for USB, 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, drivers for power management need to written.\r
 \r
 ## Thanks To\r
- * **Herman Hermitage** for his VC4 documentation and for helping me with working out suitable ARM PLL configurations.\r
- * **Julian Brown** for reviewing my code and for his awesome VC4 toolchain.\r
- * **David Given** for his initial LLVM project which I used as the base for my LLVM toolchain before moving to GCC.\r
- * **phire** for reviewing my code.\r
- * **Broadcom** for their header release.\r
+ * **[Herman Hermitage](https://github.com/hermanhermitage)** for his VC4 documentation and for helping determine suitable ARM PLL configurations.\r
+ * **[Julian Brown](https://github.com/puppeh)** for reviewing the code and for his awesome VC4 toolchain.\r
+ * **[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.\r
+ * **[David Given](https://github.com/davidgiven)** for his initial LLVM project used as the base for the initial LLVM toolchain before moving to GCC.\r
+ * **[Scott Mansell](https://github.com/phire)** for reviewing the code.\r
+ * **[Broadcom](https://github.com/broadcom)** for their header release.\r
  * Various other people not mentioned here.\r
This page took 0.028735 seconds and 4 git commands to generate.