BeagleBone Black - screwdriver

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

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

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: http://uk.farnell.com/pomona/5252/test-clip-16-pos-1-27mm-soj-soic/dp/2406245. 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

Instable connection may not even detect the chip.

Reducing the speed could help when facing instable connections, but it's recommend to reduce the spi cable length instead or check the power supply.

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.