Documentation/mainboard/ti/beaglebone-black.md

   1 # Beaglebone Black
   2 This page gives some details about the [BeagleBone Black] coreboot port and
   3 describes how to build and run it.
   4
   5 The port currently only supports booting coreboot from a micro SD card and has
   6 some other limitations listed below.
   7
   8 ## Supported Boards
   9 The Beaglebone port supports the following boards:
  10
  11 - Beaglebone Black
  12 - Beaglebone Black Wireless
  13 - Beaglebone Pocket (untested, may need tweaking)
  14 - Beaglebone Blue (untested, may need tweaking)
  15 - Beaglebone Original (untested, may need tweaking)
  16
  17 ## Use Cases
  18 This port was primarily developed as a learning exercise and there is
  19 potentially little reason to use it compared to the defacto bootloader choice of
  20 U-Boot. However, it does have some interesting practical use cases compared to
  21 U-Boot:
  22
  23 1. Choosing coreboot as a lightweight alternative to U-Boot. In this case,
  24    coreboot is used to do the absolute minimum necessary to boot Linux, forgoing
  25    some U-Boot features and functionality. Complex boot logic can then instead
  26    be moved into Linux where it can be more flexibly and safely executed. This
  27    is essentially the LinuxBoot philosophy. [U-Boot Falcon mode] has similar
  28    goals to this as well.
  29 2. Facilitating experimenting with coreboot on real hardware. The Beaglebone
  30    Black is widely available at a low pricepoint (~$65) making it a great way to
  31    experiment with coreboot on real ARMv7 hardware. It also works well as a
  32    development platform as it has exposed pads for JTAG and, due to the way it
  33    boots, is effectively impossible to brick.
  34 3. The Beaglebone Black is often used as a external flasher and EHCI debug
  35    gadget in the coreboot community, so many members have access to it and can
  36    use it as a reference platform.
  37
  38 ## Quickstart
  39 1. Run `make menuconfig` and select _TI_/_Beaglebone_ in the _Mainboard_ menu.
  40 2. Add a payload as normal.
  41 3. Run `make`.
  42 4. Copy the resulting `build/MLO` file to the micro SD card at offset 128k - ie
  43    `dd if=build/MLO of=/dev/sdcard seek=1 bs=128k`.
  44
  45 **NOTE**: By default, the Beaglebone is configured to try to boot first from
  46 eMMC before booting from SD card. To ensure that the Beaglebone boots from SD,
  47 either erase the internal eMMC or hold the _S2_ button while powering on (note
  48 that this has to be while powering on - ie when plugging in the USB or DC barrel
  49 jack - the boot order doesn't change on reset) to prioritize SD in the boot
  50 order.
  51
  52 ## Serial Console
  53 By default, coreboot uses UART0 as the serial console. UART0 is available
  54 through the J1 header on both the Beaglebone Black and Beaglebone Black
  55 Wireless. The serial runs at 3.3V and 115200 8n1.
  56
  57 The pin mapping is shown below for J1.
  58
  59     ```{eval-rst}
  60     +----------------------------+------------+
  61     | Pin number                 | Function   |
  62     +============================+============+
  63     | 1 (Closest to barrel jack) | GND        |
  64     +----------------------------+------------+
  65     | 4                          | RX         |
  66     +----------------------------+------------+
  67     | 5                          | TX         |
  68     +----------------------------+------------+
  69     ```
  70
  71 ## Boot Process
  72 The AM335x contains ROM code to allow booting in a number of different
  73 configurations. More information about the boot ROM code can be found in the
  74 AM335x technical reference manual (_SPRUH73Q_) in the _Initialization_ section.
  75
  76 This coreboot port is currently configured to boot in "SD Raw Mode" where the
  77 boot binary, with header ("Table of Contents" in TI's nomenclature), is placed
  78 at the offset of 0x20000 (128KB) on the SD card. The boot ROM loads the coreboot
  79 bootblock stage into SRAM and executes it.
  80
  81 The bootblock and subsequent romstage and ramstage coreboot stages expect that
  82 the coreboot image, containing the CBFS, is located at 0x20000 on the SD card.
  83 All stages directly read from the SD card in order to load the next stage in
  84 sequence.
  85
  86 ## Clock Initialization and PMIC
  87 To simplify the port, the TPS65217C Power Management IC (PMIC) on the Beaglebone
  88 Black is not configured by coreboot. By default, the PMIC reset values for
  89 VDD_MPU (1.1V) and VDD_CORE (1.8V) are within the Operating Performance Point
  90 (OPP) for the MPU PLL configuration set by the boot ROM of 500 MHz.
  91
  92 When using Linux as a payload, the kernel will appropriately scale the core
  93 voltages for the desired MPU clock frequency as defined in the device tree.
  94
  95 One significant difference because of this to the U-Boot port is that the DCDC1
  96 rail that powers the DDR3 RAM will be 1.5V by default. The Micron DDR3 supports
  97 both 1.35V and 1.5V and U-Boot makes use of this by setting it to 1.35V to
  98 conserve power. Fortunately, Linux is again able to configure this rail but it
  99 involves adding an entry to the device tree:
 100
 101     &dcdc1_reg {
 102     regulator-name = "vdd_ddr3";
 103     regulator-min-microvolt = <1350000>;
 104     regulator-max-microvolt = <1350000>;
 105     regulator-boot-on;
 106     regulator-always-on;
 107     };
 108
 109 If this port was to be extended to work with boards or SoCs with different
 110 requirements for the MPU clock frequency or different Operating Performance
 111 Points, then the port may need to be extended to set the core voltages and MPU
 112 PLL within coreboot, prior to loading a payload. Extending coreboot so that it
 113 can configure the PMIC would also be necessary if there was a requirement for
 114 coreboot to run at a different MPU frequency than the 500 MHz set by the boot
 115 ROM.
 116
 117 # Todo
 118 - Allow coreboot to run from the Beaglebone Black's internal eMMC. This would
 119   require updating the `mmc.c` driver to support running from both SD and eMMC.
 120 - Support the boot ROMs *FAT mode* so that the coreboot binary can be placed on
 121   a FAT partition.
 122 - Increase the MMC read speed, it currently takes ~15s to read ~20MB which is a
 123   bit slow. To do this, it should be possible to update the MMC driver to:
 124     - Increase the supported blocksize (currently is always set to 1)
 125     - Support 4-bit data width (currently only supports 1-bit data width)
 126 - Convert the while loops in the MMC driver to timeout so that coreboot does not
 127   hang on a bad SD card or when the SD card is removed during boot.
 128
 129
 130 [Beaglebone Black]: https://beagleboard.org/black
 131 [U-Boot Falcon mode]: https://elixir.bootlin.com/u-boot/v2020.07/source/doc/README.falcon