Sam Lewis has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 134 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/44389/1
diff --git a/Documentation/mainboard/index.md b/Documentation/mainboard/index.md index 3a7dd31..19e2d08 100644 --- a/Documentation/mainboard/index.md +++ b/Documentation/mainboard/index.md @@ -158,6 +158,10 @@
- [Lemur Pro](system76/lemp9.md)
+## Texas Instruments + +- [Beaglebone Black](ti/beaglebone-black.md) + ## UP
- [Squared](up/squared/index.md) diff --git a/Documentation/mainboard/ti/beaglebone-black.md b/Documentation/mainboard/ti/beaglebone-black.md new file mode 100644 index 0000000..d63b6b5 --- /dev/null +++ b/Documentation/mainboard/ti/beaglebone-black.md @@ -0,0 +1,130 @@ +# Beaglebone Black +This page gives some details about the [BeagleBone Black] coreboot port and +describes how to build and run it. + +The port currently only supports booting coreboot from a micro SD card and has +some other limitations listed below. + +## Supported Boards +The Beaglebone port supports the following boards: + +- Beaglebone Black +- Beaglebone Black Wireless +- Beaglebone Pocket (untested, may need tweaking) +- Beaglebone Blue (untested, may need tweaking) +- Beaglebone Original (untested, may need tweaking) + +## Use Cases +This port was primarily developed as a learning exercise and there is +potentially little reason to use it compared to the defacto bootloader choice of +U-Boot. However, it does have some interesting practical use cases compared to +U-Boot: + +1. Choosing coreboot as a lightweight alternative to U-Boot. In this case, + coreboot is used to do the absolute minimum necessary to boot Linux, forgoing + some U-Boot features and functionality. Complex boot logic can then instead + be moved into Linux where it can be more flexibly and safely executed. This + is essentially the LinuxBoot philosophy. U-Boot "Falcon mode" has similar + goals to this as well. +2. Facilitating experimenting with coreboot on real hardware. The Beaglebone + Black is widely available at a low pricepoint (~$65) making it a great way to + experiment with coreboot on real ARMv7 hardware. It also works well as a + development platform as it has exposed pads for JTAG and, due to the way it + boots, is effectively impossible to brick. + +## Quickstart +1. Run `make menuconfig` and select _TI_/_Beaglebone Black_ in the _Mainboard_ + menu. +2. Add a payload as normal. +3. Run `make`. +4. Copy the resulting `build/MLO` file to the micro SD card at offset 128k - ie + `dd if=build/MLO of=/dev/sdcard seek=1 bs=128k`. + +**NOTE**: By default, the Beaglebone is configured to try to boot first from +eMMC before booting from SD card. To ensure that the Beaglebone boots from SD, +either erase the internal eMMC or hold the _S2_ button while powering on (note +that this has to be while powering on - ie when plugging in the USB or DC barrel +jack - the boot order doesn't change on reset) to prioritize SD in the boot +order. + +## Serial Console +By default, coreboot uses UART0 as the serial console. UART0 is available +through the J1 header on both the Beaglebone Black and Beaglebone Black +Wireless. The serial runs at 3.3V and 115200 8n1. + +The pin mapping is shown below for J1. + + ```eval_rst + +----------------------------+------------+ + | Pin number | Function | + +============================+============+ + | 1 (Closest to barrel jack) | GND | + +----------------------------+------------+ + | 4 | RX | + +----------------------------+------------+ + | 5 | TX | + +----------------------------+------------+ + ``` + +## Boot Process +The AM335x contains ROM code to allow booting in a number of different +configurations. More information about the boot ROM code can be found in the +AM335x technical reference manual (_SPRUH73Q_) in the _Initialization_ section. + +This coreboot port is currently configured to boot in "SD Raw Mode" where the +boot binary, with header ("Table of Contents" in TI's nomenclature), is placed +at the offset of 0x20000 (128KB) on the SD card. The boot ROM loads the coreboot +bootblock stage into SRAM and executes it. + +The bootblock and subsequent romstage and ramstage coreboot stages expect that +the coreboot image, containing the CBFS, is located at 0x20000 on the SD card. All +stages directly read from the SD card in order to load the next stage in +sequence. + +## Clock Initialization and PMIC +To simplify the port, the TPS65217C Power Management IC (PMIC) on the Beaglebone +Black is not configured by coreboot. By default, the PMIC reset values for +VDD_MPU (1.1V) and VDD_CORE (1.8V) are within the Operating Performance Point +(OPP) for the MPU PLL configuration set by the boot ROM of 500 MHz. + +When using Linux as a payload, the kernel will appropriately scale the core +voltages for the desired MPU clock frequency as defined in the device tree. + +One significant difference because of this to the U-Boot port is that the DCDC1 +rail that powers the DDR3 RAM will be 1.5V by default. The Micron DDR3 supports +both 1.35V and 1.5V and U-Boot makes use of this by setting it to 1.35V to +conserve power. Fortunately, Linux is again able to configure this rail but it +involves adding an entry to the device tree: + +``` +&dcdc1_reg { + regulator-name = "vdd_ddr3"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <1350000>; + regulator-boot-on; + regulator-always-on; +}; +``` + +If this port was to be extended to work with boards or SoCs with different +requirements for the MPU clock frequency or different Operating Performance +Points, then the port may need to be extended to set the core voltages and MPU +PLL within coreboot, prior to loading a payload. Extending coreboot so that it +can configure the PMIC would also be necessary if there was a requirement for +coreboot to run at a different MPU frequency than the 500 MHz set by the boot +ROM. + +# Todo +- Allow coreboot to run from the Beaglebone Black's internal eMMC. This would + require updating the mmc.c driver to support running from both SD and eMMC. +- Support the boot ROMs "FAT mode" so that the coreboot binary can be placed on + a FAT partition. +- Increase the MMC read speed, it currently takes ~15s to read ~20MB which is a + bit slow. To do this, it should be possible to update the MMC driver to: + - Increase the supported blocksize (currently is always set to 1) + - Support 4-bit data width (currently only supports 1-bit data width) +- Convert the while loops in the MMC driver to timeout so that coreboot does not + hang on a bad SD card or when the SD card is removed during boot. + + +[Beaglebone Black]: https://beagleboard.org/black \ No newline at end of file
Sam Lewis has uploaded a new patch set (#2). ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 134 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/44389/2
Paul Menzel has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Patch Set 3: Code-Review+1
(8 comments)
Thank you for writing documentation.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... File Documentation/mainboard/ti/beaglebone-black.md:
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 27: U-Boot "Falcon mode" Do you have a link?
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 33: boots, is effectively impossible to brick. Please remove the trailing space.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 34: Maybe also mention, that the BBB is often used as an external flasher and EHCI debug gadget.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 38: 2. Add a payload as normal. I guess only depthcharge and Linux are supported? Maybe the documentation can be extended later.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 99: ``` : &dcdc1_reg { : regulator-name = "vdd_ddr3"; : regulator-min-microvolt = <1350000>; : regulator-max-microvolt = <1350000>; : regulator-boot-on; : regulator-always-on; : }; : ``` If possible, I prefer indenting code blocks by four spaces, instead of using ```.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 119: mmc.c Mark up as code?
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 120: "FAT mode" Emphasize using *…* instead of quotes?
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 127: hang on a bad SD card or when the SD card is removed during boot. Maybe create issues at https://ticket.coreboot.org?
Hello build bot (Jenkins), Paul Menzel,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/44389
to look at the new patch set (#4).
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 135 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/44389/4
Sam Lewis has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Patch Set 4:
(8 comments)
Thanks for reading it!
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... File Documentation/mainboard/ti/beaglebone-black.md:
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 27: U-Boot "Falcon mode"
Do you have a link?
Have added one now.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 33: boots, is effectively impossible to brick.
Please remove the trailing space.
Done
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 34:
Maybe also mention, that the BBB is often used as an external flasher and EHCI debug gadget.
Done
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 38: 2. Add a payload as normal.
I guess only depthcharge and Linux are supported? Maybe the documentation can be extended later.
depthcharge I'm not sure about as I don't think it has BBB support. Linux, yes. Normal ELF payloads are supported as well - in theory I think even U-Boot could be added as a coreboot payload.
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 99: ``` : &dcdc1_reg { : regulator-name = "vdd_ddr3"; : regulator-min-microvolt = <1350000>; : regulator-max-microvolt = <1350000>; : regulator-boot-on; : regulator-always-on; : }; : ```
If possible, I prefer indenting code blocks by four spaces, instead of using ```.
Done
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 119: mmc.c
Mark up as code?
Done
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 120: "FAT mode"
Emphasize using *…* instead of quotes?
Done
https://review.coreboot.org/c/coreboot/+/44389/3/Documentation/mainboard/ti/... PS3, Line 127: hang on a bad SD card or when the SD card is removed during boot.
Maybe create issues at https://ticket.coreboot. […]
Sure, will do once this gets merged in!
Hello build bot (Jenkins), Paul Menzel,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/44389
to look at the new patch set (#6).
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 136 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/44389/6
Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Patch Set 8: Code-Review+2
Hello build bot (Jenkins), Paul Menzel, Arthur Heymans,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/44389
to look at the new patch set (#9).
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 135 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/44389/9
Hello build bot (Jenkins), Paul Menzel, Arthur Heymans,
I'd like you to reexamine a change. Please visit
https://review.coreboot.org/c/coreboot/+/44389
to look at the new patch set (#10).
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 135 insertions(+), 0 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/89/44389/10
Arthur Heymans has posted comments on this change. ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Patch Set 12: Code-Review+2
Hung-Te Lin has submitted this change. ( https://review.coreboot.org/c/coreboot/+/44389 )
Change subject: Documentation: Add Beaglebone Black documentation ......................................................................
Documentation: Add Beaglebone Black documentation
Change-Id: If1a9808d1f20ee61048182d416f25e9a81c631af Signed-off-by: Sam Lewis sam.vr.lewis@gmail.com Reviewed-on: https://review.coreboot.org/c/coreboot/+/44389 Tested-by: build bot (Jenkins) no-reply@coreboot.org Reviewed-by: Arthur Heymans arthur@aheymans.xyz --- M Documentation/mainboard/index.md A Documentation/mainboard/ti/beaglebone-black.md 2 files changed, 135 insertions(+), 0 deletions(-)
Approvals: build bot (Jenkins): Verified Arthur Heymans: Looks good to me, approved
diff --git a/Documentation/mainboard/index.md b/Documentation/mainboard/index.md index 95efe55..1f8f6bc2 100644 --- a/Documentation/mainboard/index.md +++ b/Documentation/mainboard/index.md @@ -176,6 +176,10 @@
- [Lemur Pro](system76/lemp9.md)
+## Texas Instruments + +- [Beaglebone Black](ti/beaglebone-black.md) + ## UP
- [Squared](up/squared/index.md) diff --git a/Documentation/mainboard/ti/beaglebone-black.md b/Documentation/mainboard/ti/beaglebone-black.md new file mode 100644 index 0000000..db37e28 --- /dev/null +++ b/Documentation/mainboard/ti/beaglebone-black.md @@ -0,0 +1,131 @@ +# Beaglebone Black +This page gives some details about the [BeagleBone Black] coreboot port and +describes how to build and run it. + +The port currently only supports booting coreboot from a micro SD card and has +some other limitations listed below. + +## Supported Boards +The Beaglebone port supports the following boards: + +- Beaglebone Black +- Beaglebone Black Wireless +- Beaglebone Pocket (untested, may need tweaking) +- Beaglebone Blue (untested, may need tweaking) +- Beaglebone Original (untested, may need tweaking) + +## Use Cases +This port was primarily developed as a learning exercise and there is +potentially little reason to use it compared to the defacto bootloader choice of +U-Boot. However, it does have some interesting practical use cases compared to +U-Boot: + +1. Choosing coreboot as a lightweight alternative to U-Boot. In this case, + coreboot is used to do the absolute minimum necessary to boot Linux, forgoing + some U-Boot features and functionality. Complex boot logic can then instead + be moved into Linux where it can be more flexibly and safely executed. This + is essentially the LinuxBoot philosophy. [U-Boot Falcon mode] has similar + goals to this as well. +2. Facilitating experimenting with coreboot on real hardware. The Beaglebone + Black is widely available at a low pricepoint (~$65) making it a great way to + experiment with coreboot on real ARMv7 hardware. It also works well as a + development platform as it has exposed pads for JTAG and, due to the way it + boots, is effectively impossible to brick. +3. The Beaglebone Black is often used as a external flasher and EHCI debug + gadget in the coreboot community, so many members have access to it and can + use it as a reference platform. + +## Quickstart +1. Run `make menuconfig` and select _TI_/_Beaglebone_ in the _Mainboard_ menu. +2. Add a payload as normal. +3. Run `make`. +4. Copy the resulting `build/MLO` file to the micro SD card at offset 128k - ie + `dd if=build/MLO of=/dev/sdcard seek=1 bs=128k`. + +**NOTE**: By default, the Beaglebone is configured to try to boot first from +eMMC before booting from SD card. To ensure that the Beaglebone boots from SD, +either erase the internal eMMC or hold the _S2_ button while powering on (note +that this has to be while powering on - ie when plugging in the USB or DC barrel +jack - the boot order doesn't change on reset) to prioritize SD in the boot +order. + +## Serial Console +By default, coreboot uses UART0 as the serial console. UART0 is available +through the J1 header on both the Beaglebone Black and Beaglebone Black +Wireless. The serial runs at 3.3V and 115200 8n1. + +The pin mapping is shown below for J1. + + ```eval_rst + +----------------------------+------------+ + | Pin number | Function | + +============================+============+ + | 1 (Closest to barrel jack) | GND | + +----------------------------+------------+ + | 4 | RX | + +----------------------------+------------+ + | 5 | TX | + +----------------------------+------------+ + ``` + +## Boot Process +The AM335x contains ROM code to allow booting in a number of different +configurations. More information about the boot ROM code can be found in the +AM335x technical reference manual (_SPRUH73Q_) in the _Initialization_ section. + +This coreboot port is currently configured to boot in "SD Raw Mode" where the +boot binary, with header ("Table of Contents" in TI's nomenclature), is placed +at the offset of 0x20000 (128KB) on the SD card. The boot ROM loads the coreboot +bootblock stage into SRAM and executes it. + +The bootblock and subsequent romstage and ramstage coreboot stages expect that +the coreboot image, containing the CBFS, is located at 0x20000 on the SD card. +All stages directly read from the SD card in order to load the next stage in +sequence. + +## Clock Initialization and PMIC +To simplify the port, the TPS65217C Power Management IC (PMIC) on the Beaglebone +Black is not configured by coreboot. By default, the PMIC reset values for +VDD_MPU (1.1V) and VDD_CORE (1.8V) are within the Operating Performance Point +(OPP) for the MPU PLL configuration set by the boot ROM of 500 MHz. + +When using Linux as a payload, the kernel will appropriately scale the core +voltages for the desired MPU clock frequency as defined in the device tree. + +One significant difference because of this to the U-Boot port is that the DCDC1 +rail that powers the DDR3 RAM will be 1.5V by default. The Micron DDR3 supports +both 1.35V and 1.5V and U-Boot makes use of this by setting it to 1.35V to +conserve power. Fortunately, Linux is again able to configure this rail but it +involves adding an entry to the device tree: + + &dcdc1_reg { + regulator-name = "vdd_ddr3"; + regulator-min-microvolt = <1350000>; + regulator-max-microvolt = <1350000>; + regulator-boot-on; + regulator-always-on; + }; + +If this port was to be extended to work with boards or SoCs with different +requirements for the MPU clock frequency or different Operating Performance +Points, then the port may need to be extended to set the core voltages and MPU +PLL within coreboot, prior to loading a payload. Extending coreboot so that it +can configure the PMIC would also be necessary if there was a requirement for +coreboot to run at a different MPU frequency than the 500 MHz set by the boot +ROM. + +# Todo +- Allow coreboot to run from the Beaglebone Black's internal eMMC. This would + require updating the `mmc.c` driver to support running from both SD and eMMC. +- Support the boot ROMs *FAT mode* so that the coreboot binary can be placed on + a FAT partition. +- Increase the MMC read speed, it currently takes ~15s to read ~20MB which is a + bit slow. To do this, it should be possible to update the MMC driver to: + - Increase the supported blocksize (currently is always set to 1) + - Support 4-bit data width (currently only supports 1-bit data width) +- Convert the while loops in the MMC driver to timeout so that coreboot does not + hang on a bad SD card or when the SD card is removed during boot. + + +[Beaglebone Black]: https://beagleboard.org/black [U-Boot Falcon mode]: +https://elixir.bootlin.com/u-boot/v2020.07/source/doc/README.falcon \ No newline at end of file
-
Arthur Heymans (Code Review) -
Hung-Te Lin (Code Review)
-
Paul Menzel (Code Review)
-
Sam Lewis (Code Review)