BeagleBone Black - screwdriver

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 https://doc.coreboot.org/. 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 http://repo.fe80.eu/screwdriver/0.3.0/omap/generic/default/openwrt-0.3.0-omap-beagleboneblack-sdcard-vfat-am335x_evm.img (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: https://sourceforge.net/projects/win32diskimager/

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


Starting screwdriver

In most cases screwdriver boots automatically when the memory is inserted and then the power(external 5V power plug). If not there are three solutions:

1) This should always work: Delete/wipe the internal memory of the BeagleBone black. This would force the BeagleBone Black to always boot from the memory you inserted.

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

3) Rewrite internal memory to a recent official debian+u-boot image. It boots then automatically when you insert the screwdriver memory.

If you get a Kernel panic on boot, edit the file uEnv.txt on the first partition (fat16 / 20MiB) and add the following line:

bootargs=console=ttyO0,115200n8 root=/dev/mmcblk0p2

See also https://github.com/lynxis/bbb_screwdriver_builder/issues/12

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. (This is not currently working. There is a bug to track this). If it was working, there would be a dhcp server (192.168.1.1) running on the screwdriver. Log in as root with the password coreboot.

To have rom images available for flashing, add them to the boot medium somewhere on the second partition (ext4, 48 MiB) after writing the screwdriver image to the medium. You should be able mount the partitions normally after writing the screwdriver image to eg. a microSD card.

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: https://www.linux.com/learn/tutorials/746860-how-to-access-chips-over-the-spi-on-beaglebone-black/

Connectors:

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

Prerequisites

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

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

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 (or whatever ROM you're flashing to the SPI chip) to the BeagleBone, such as through scp. If you have connected through SSH this is easy. Assuming the ROM is called "rom.rom", run flashrom -p linux_spi:dev=/dev/spidev1.0,spispeed=128 -w rom.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: https://libreboot.org/docs/install/bbb_setup.html. 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: http://repo.fe80.eu/screwdriver/0.2/omap/generic/openwrt-0.2-omap-beagleboneblack-sdcard-vfat-am335x_evm.img sha512sum: 26fc145b4b43b2589d500429c3bba379612870a63c2c03388cd663345a7c3a0792efc97cf3546c1e53b5d7eb958d43b9d21a9d6d0e4f13dd03f29878ef8dc753

references

The official screwdriver development repository: https://github.com/lynxis/bbb_screwdriver_builder

1. how to wire spi chip: http://www.linux.com/learn/tutorials/746860-how-to-access-chips-over-the-spi-on-beaglebone-black/

2. Beagle bone black shematics: https://raw.githubusercontent.com/CircuitCo/BeagleBone-Black/master/BBB_SRM.pdf

3. BeagleBone CPU datasheet: http://www.ti.com/lit/ds/symlink/am3358.pdf

4. am335x CPU technical reference: http://www.ti.com/lit/ug/spruh73l/spruh73l.pdf