AM335x recovery

= AM335x recovery =

This page is how to recover ("unbrick") a broken/non-booting device that uses an AM335x processor. It should help you if you messed your boot configuration and doesn't boot any more the normal way ("bricked").

Booting scheme
The processor starts by executing rom code that is hard-wired into its processor. That code will in turn fetch and execute external code, typically a bootloader like u-boot. The peripherals(eMMC, microSD, NAND, etc) it tries to boot from and the order in which it does it is device dependent.

If it finds valid code, it will execute it, else it will continue looking for valid code on the next peripheral in the boot order.

What it consider valid is documented more formally in the technical reference manual of the AM335x.

BeagleBone Green
If the 'USER' button isn't pressed, the device will try to boot from: eMMC -> microSD -> UART -> USB

If the 'USER' button is pressed, it will instead try this order: SPI -> microSD -> USB -> UART.

Since we want to recover a non-booting device, and that the device boots first on the eMMC, we want it not to try the eMMC as it could load non-working code from there.

So during recovery, we will have to press the 'USER' button to switch the order to:

SPI -> microSD -> USB -> UART.

MMC recovery
The Beagle Board Recovery MMC instructions might be a useful starting point. In the case where it doens't work, it might be a good idea to compare them with what is in the AM335x technical reference manual.

BeagleBone Green USB recovery
When booting from USB, the processor will be presented as an RNDIS peripheral. It will then try to get an IP address trough the BOOTP protocol, and finally fetch and execute the bootloader trough TFTP.

So we will need to setup a BOOTP and TFTP server, we will use a GNU/Linux computer and dnsmasq to do that.

To make the device expose an RNDIS interface:
 * Remove the MicroSD card if there is one
 * Make sure the device is powered off
 * Plug the USB cable to the device but not to the computer yet
 * Press the the 'USER' button, and keep pressing it
 * Plug the USB cable: This will power up the device
 * Release the 'USER' button

Now an RNDIS network interface will appear on the GNU/Linux computer. Unfortunately if we unplug the USB cable, the RNDIS network interface will disapear.

This isn't very convenient as we need to setup a BOOTP and TFTP server, and we can't make dnsmasq listen on a inexisting interface. We also might not want to listen on all interfaces not to interfer with the rest of the system.

To handle this issue we can create a bridge network interface with the following commands:
 * 1) ip link add name am335x type bridge
 * 2) ip link set dev am335x up

And then add the following content in /etc/udev/rules.d/01-beaglebonegreen.rules: SUBSYSTEM=="net", ACTION=="add", ATTRS{idProduct}=="6141", ATTRS{idVendor}=="0451", RUN+="/usr/bin/ip link set dev $name master am335x", RUN+="/usr/bin/ip link set dev $name up"

This will make the RNDIS interface join the bridge when it appears under the GNU/Linux computer.

Now we can use dnsmasq to make a BOOTP and TFTP server.

Now we will create the dnsmasq.conf configuration file with the following content: no-daemon interface=am335x except-interface=lo bind-interfaces enable-tftp bootp-dynamic dhcp-script=/bin/echo dhcp-range=192.168.4.2,192.168.4.255,12h dhcp-option=121,192.168.4.1 dhcp-boot=start_am33xx_beaglebone_sram.pblx tftp-root=/home/gnutoo/work/devices/seedstudio/beaglebone-green/barebox/images/
 * 1) Settings you might want to change:
 * 1) You must change, at least the tftp-root, to the directory where the code to load resides

In the configuration file above:
 * We will tell the device to load and execute the file named start_am33xx_beaglebone_sram.pblx in /home/gnutoo/work/devices/seedstudio/beaglebone-green/barebox/images/. Change it to make it load the code you want.
 * We use the 192.168.4.1 IP address, you might need to change it if this IP range is already used in your local network.

Finally setup the network interface IP address and start dnsmasq: It is also a good idea to start tshark to see what is going on:
 * 1) ip addr add 192.168.4.1/24 dev am335x
 * 2) dnsmasq --conf-file=./dnsmasq.conf
 * 1) tshark am335x

Now that everything is ready, we can start the device by:
 * Makeing sure the device is powered off
 * Pluging the USB cable to the device but not to the computer yet
 * Pressing the the 'USER' button, and keep pressing it
 * Pluging the USB cable: This will power up the device
 * Releasing the 'USER' button

The device will now configure itself trough BOOTP and start downloading the code.

Building a recovery image
TODO

Recovery image constraints
According to the technical reference manual: "The boot image is downloaded directly into internal RAM at the location 0x402F0400 on GP devices. The maximum size of downloaded image is 109 KB."