BeagleBone Black - screwdriver

From coreboot
Revision as of 22:04, 10 September 2016 by Dgut (talk | contribs) (→‎Prerequisites)
Jump to navigation Jump to search

The wiki is being retired!

Documentation is now handled by the same processes we use for code: Add something to the Documentation/ directory in the coreboot repo, and it will be rendered to Contributions welcome!

A tool for coreboot/libreboot/flashrom developers and users. The firmware itself is based on vanilla OpenWrt Chaos Calmer(15.04) with some modifications. This firmware is mainly intended for BeagleBone Black (BBB).

Installing screwdriver

To install screwdriver on the BeagleBone Black you have to create a bootable memory with the screwdriver. In this example we use a Micro-SD card. The card should be at least 128MB big.

1. Download recent screwdriver Version 0.3.0 from (sha512sum: 685f72aaa14342c848f15c933ea4f80deb33cd3751457e3e19e3b101659d2b96bae7f7be33b542cfdc4750cdd27e7e47ce35ffba15a5c2e76f8c41e7aad05f69 )

2. Insert the memory you want to install screwdriver on into your computer.

Linux users can check the latest messages in dmesg and if the memory is listed as /dev/sdb this have to be used together with 'dd' for installation from inside the directory containing the downloaded .img file: sudo dd if=openwrt-0.3.0-omap-beagleboneblack-sdcard-vfat-am335x_evm.img of=/dev/sdb bs=4M

Windows users have to use additional software like 'Win32 Disk Imager' from here:

3. Now you can insert the memory into your BeagleBone Black.

Starting screwdriver

In most cases screwdriver would boot automaticly when the memory is inserted and then the power(external 5V power plug).

Troubleshooting if it does not start automaticly: You can choose between tree solutions.

First and always working solution: Delete/wipe the internal memory of the BeagleBone black. This would force the BeagleBone Black to always boot from the memory you inserted.

Second solution: Pressing and holding every time the 'User Boot' button. This is the button next to the big, regular USB port.

Third solution: Rewrite internal memory to a recent official debian+u-boot image. It boots then automaticly when you insert the screwdriver memory.

Basic usage

There are two recommended ways to connect to the terminal of the screwdriver.

First and always working: Use a USB to TTL (for example CP2104 for about 2$) adapter and connect it to the serial port of the BeagleBone Black. You have to use just 3 wires. Ground, TX and RX. Connect your ttl-adapter ground to serial pin 1 (the one with the white dot), RX to serial pin 4 and TX to serial pin 5. For the serial connection you can use for example minicom -s. In most cases on a linux machine the usb-ttl adapter gets: /dev/ttyUSB0 . The BeagleBone Black default serial speed is 115200.

Second: Use a network cable and ssh. There is a dhcp server ( running on the screwdriver.

Using screwdriver for flashing SPI flash with flashrom

screwdriver already have flashrom preinstalled and the BeagleBone Black have connectors you can flash SPI flash memory with.

You can flash SPI flash chips that are not 'in-circuit' without the need of additional power source. The light 3,3V rail the BeagleBone Black delivers can power the SPI chip if you power up the BeagleBone Black with at least 5V 1,2A power supply over its round power connector.

This is a good article with pictures how to wire the BeagleBone Black to a SPI flash chip:


BeagleBoneBlack Pin on P9(written next to the big connector board) SPI SPI SOIC8 Pin SOIC16 CPU DTS
I2C1_SCL 17 CS 1 7 A16 spi0_cs0
I2C1_SDA 18 MOSI 5 15 B16 spi0_d1
UART2_RXD 22 CLK 6 16 A17 spi0_sclk
UART2_TXD 21 MISO 2 8 B17 spi0_d0
GND 1 + 2 GND 4 10 GND GND
VDD_3V3D 3 + 4 VCC 8 2 VDD_3V3D VDD_3V3D

After wiring everything up you can flash with this command: flashrom -p linux_spi:dev=/dev/spidev1.0 -w yourfile If you get the warning in flashrom that the flash chip is unsupported, you can force the flash with additional '-f' command and if everything worked fine, please directly report a logfile of the flash to the flashrom developers.

Using screwdriver as USB EHCI debugging tool

The BeagleBone Black have a great free(as in freedom) and flexible architecture we can use for USB EHCI debugging. It have to be powered by external power supply over the round power connector. You need: mini-usb cable Connect the mini-usb cable to the EHCI debug port of your device you want to debug coreboot/libreboot on. If you are not sure what usb port is using ehci debug, you can just try all of them out.

To run USB EHCI debugging you have to run: screen /dev/ttyGS0 cat /dev/ttyGS0 | tee -a /tmp/output

Then power on the target you want to debug and you would hopefully see the debug output.

Using screwdriver for flashing SPI flash with flashrom - IN-CIRCUIT


We can flash an SPI flash chip in-circuit, providing we have an external power source. We will need

  • Power source for BeagleBone Black: USB (connected to computer or standard wall supply) or 5V barrel connector
  • Power source for SPI Flash chip, 3.3V. Ideally, we should use a lab Power Supply Unit as it is possible to vary the voltage easily and be sure we are getting the required voltage. It may not be possible to power the flash chip from the BeagleBone Black's 3.3V pin as it is too unreliable. Some guides also recommend an ATX PSU, but this may not be reliable, and at any rate it is good practice to check if the PSU is actually outputting 3.3V!
  • Ideally, a clip over the SPI chip, such as those sold by Pomona: This clip is for SOIC-16 chips with 16 pins but other sizes are available e.g. for SOIC-8 chips. You should check what size your flash chip is by opening up the computer and identifying the chip. We can also solder the wires carefully, but the clip makes it easy to troubleshoot wiring issues. Other similar clips may work.
  • We should obtain wires. If we solder the flash chip the size doesn't matter, but we should use jumper cables for the SPI clip, with 2.54mm / 0.1" headers. Make sure to cut the wires as short as possible, less than 10cm, as interference may result in Flashrom not detecting the chip properly, or not at all.

Wiring the flash chip to the BeagleBone Black and power supply

Do not directly rest the BeagleBone Black on the computer motherboard which you are flashing, otherwise static electricity could damage components on the motherboard during flashing.

These numbers correspond to pins on the BeagleBone:

NC              -       - 21
1               -       - 17
NC              -       - NC
NC              -       - NC
NC              -       - NC
NC              -       - NC
18              -       - 3.3V (PSU)
22              -       - NC - pin 1 on flash chip

Consult the BeagleBone documentation if you are unsure how the pins on the BeagleBone are numbered. Remember to connect pin 2 of the BeagleBone to the ground of the power supply.

Testing connection

flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=128

  • Note that the SPI speed can be higher, if you want faster speeds. However, faster speeds are less stable. From experience, Flashrom sometimes doesn't detect the chip if there is too much interference, so a slower speed may be ideal. It may be possible to achieve over 512Hz as the SPI speed.
  • If Flashrom isn't sure what type of SPI chip you have after it detects the chip, you will need to open up the computer and look at what variation is printed on the chip. You will probably need a magnifying glass or microscope for this and some bright light. If you can't work it out, look on the internet and see what SPI chips your computer typically was manufactured with. You then specify with the -c option when you are using Flashrom to read or write the flash.

Dump factory ROM image

We should dump the factory ROM image in case the flashing process goes wrong somehow or the computer does not boot.

flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=128 -r factory.rom

Now we verify the dumped image:

flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=128 --verify factory.rom

You might want to do this multiple times too just to be sure that the dumped image was read correctly.

Write your compiled image

You will now send your compiled Coreboot ROM to the BeagleBone, such as through scp. If you have connected through SSH this is easy. Assuming the ROM is called "coreboot.rom", run flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=128 -w coreboot.rom -V

This may take a long time, especially at 128Hz. Experiment with higher SPI speeds to see how fast you can use Flashrom while achieving stability. For an 8k SPI chip it may take around 30 minutes at SPI speed of 128Hz.

Further notes

Some of this was copied from the Libreboot page on programming SPI chips with the BeagleBone Black: This is a good resource, and it has further notes about achieving stability during flashing. There are also more images to illustrate setup.

older/outdated screwdriver versions

Version 0.2: sha512sum: 26fc145b4b43b2589d500429c3bba379612870a63c2c03388cd663345a7c3a0792efc97cf3546c1e53b5d7eb958d43b9d21a9d6d0e4f13dd03f29878ef8dc753


The official screwdriver development repository:

1. how to wire spi chip:

2. Beagle bone black shematics:

3. BeagleBone CPU datasheet:

4. am335x CPU technical reference: