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).
- 1 Installing screwdriver
- 2 Starting screwdriver
- 3 Basic usage
- 4 Using screwdriver for flashing SPI flash with flashrom
- 5 Using screwdriver as USB EHCI debugging tool
- 6 Using screwdriver for flashing SPI flash with flashrom - IN-CIRCUIT
- 7 older/outdated screwdriver versions
- 8 references
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.
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:
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/
|BeagleBoneBlack||Pin on P9(written next to the big connector board)||SPI||SPI SOIC8 Pin||SOIC16||CPU||DTS|
|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:
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: 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.
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 (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.
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
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