9260 SAM Boot Assistant

Atmel logo

Atmel AT91 CPUs contain a built-in bootstrap system called the SAM Boot Assistant. This is used as a debug facility when all other boot methods have failed. On the Snapper 9260 this can happen either when the module has been inadvertently erased, or if the 'SAMBA' button is held down during reset.

The SAM Boot Assistant allows access to all memory mapped peripherals over either USB or the Debug UART. This in turn means that drivers can be written to manipulate any secondary peripherals (such as NAND flash etc...). Using this functionality, it is possible to resurrect a completely erased module, without the use of the JTAG debug connector.

Bluewater Systems provide a scriptable command line SAM-BA utility, Samba Script which can re-flash the NAND flash on the Snapper 9260. This can be obtained from http://www.bluewatersys.com/public/linux/utilities/samba-script.tar.gz.

Samba Script

Samba Script is a simple tool designed to allow automated scripts to be written to re-program or debug a Snapper 9260 module. It includes a simple control script language to upload files into memory/NAND etc...

Command Overview

General

open [model] - Initialises the USB connection to the specied model, defaulting to 'sn9260' if not specified. Models available:
- sn9260
version - Read the internal SAM-BA version information from the CPU, and displays it
close - Disconnects from the at91 device
go address - Begins executing code from the supplied address. Note: Once this command has been issued, no further SAM-BA access is available, as the CPU will no longer be executing the internal SAM-BA boot agent

Memory

readb address - Reads a single 8-bit value from the specified memory address
readw address - Reads a single 16-bit value from the specified memory address
readl address - Reads a single 32-bit value from the specified memory address
read_file address filename length - Reads the amount of data specified in length, from address, and saves it into the local file filename
verify_file address filename - Reads the memory at address, and verifies that it matches the data stored in filename
writeb address value - Writes a single 8-bit value to the specified memory address
writew address value - Writes a single 16-bit value to the specified memory address
writel address value - Writes a single 32-bit value to the specified memory address
write_file address filename - Write the data contained in filename, and stores it into address

NAND

nand_id - Reads the NAND ID from CS0, and displays it as a 16-bit value. The Vendor is in bits 15-8, and the product is in bits 7-0
nand_read_file address filename length - Reads length bytes from NAND at address, and saves it into the local file filename
nand_erase address length - Erases length bytes of NAND flash from address. Note: NAND flash must be erased before it can be written to. Erasure will erase the entire 128kB block that contains the given address, so length should be a multiple of 128 * 1024
nand_write_file address filename - Writes the data stored in filename into NAND flash at address
nand_write_raw_file address filename - Writes the data stored in filename into NAND flash at address. The data includes the OOB information, and so the file length must be a multiple of 2112 bytes long (2048 bytes of page data, and 64 bytes of OOB data). The ECC bytes of the OOB data will be recalculated, and so do not need to be valid. This is uesful for writing pre-built YAFFS filesystem images. Bluewater maintains a slightly modified version of the YAFFS2 mkyaffs2image code, available from http://www.bluewatersys.com/public/linux/utilities/mkyaffs2image.tar.gz. This code is also incorporated into the samba-script tool with the yaffs2 command.

Debug UART

debug_init [baudrate] - Initialises the AT91 DBGU serial port to 8N1, with a speed of baudrate, defaulting to 115200 if not specified.
debug_print strings... - Sends each member of strings out on the DBGU serial port. Note: debug_init must be called before debug_print

Environment

environment_init - Initialises an area of memory to store a U-Boot style environment
environment_save - Saves the current U-Boot environment to NAND flash
environment_variable name [value] - Sets the variable name to the supplied value. If no value is supplied, the variable is removed from the environment.
environment_file filename - Loads environment settings from filename. This file is in the form of 'setenv variable value'. See the 'scripts' directory for more examples

YAFFS2

yaffs2 file directory - Creates a full YAFFS2 file image in file, containing files from directory. The resultant file can then be written using nand_write_raw_file to create a functioning YAFFS2 partition.

Script Examples

Uploading a debug U-Boot

This code uploads a version of U-Boot directly into SDRAM, and then executes it. This can be useful when testing a build of U-Boot, prior to permanently re-flashing the unit

open sn9260
write_file 0x23f00000 /home/andre/snapper/u-boot-1.1.6/u-boot.bin
go 0x23f00000

FAQ

When running samba-script under Linux I get permission denied errors?

By default most USB devices show up with restricted permissions. For a one-off change, use lsusb to determine the device numbers, and then chmod to fix up the device permissions:

andre@tutira:~$ lsusb
Bus 002 Device 004: ID 058f:6362 Alcor Micro Corp. Hi-Speed 21-in-1 Flash Card Reader/Writer (Internal/External)
Bus 002 Device 001: ID 0000:0000  
Bus 001 Device 106: ID 03eb:6124 Atmel Corp. at91sam SAMBA bootloader
Bus 001 Device 003: ID 045e:0040 Microsoft Corp. Wheel Mouse Optical
Bus 001 Device 002: ID 067b:2303 Prolific Technology, Inc. PL2303 Serial Port
Bus 001 Device 001: ID 0000:0000  
andre@tutira:~$ sudo chmod a+rw /dev/bus/usb/001/106
[sudo] password for andre:

For a long-term solution, if using the udev hotplug system, add a rule for the devices into /dev/udev/rules.d. To do this, create a new file called /etc/udev/rules.d/Bluewater-at91sam9.rules containing the following:

SUBSYSTEM!="usb_device", ACTION!="add", GOTO="Bluewater-at91sam9_rules_end"
# Atmel Corp. at91sam SAMBA bootloader
SYSFS{idVendor}=="03eb", SYSFS{idProduct}=="6124", MODE="0666"
LABEL="Bluewater-at91sam9_rules_end"

It doesn't seem to work on my Snapper 9g20?

The Atmel AT91SAM9G20 CPUs have a known errata regarding SAM-BA USB boot. At this stage our samba-script software does not support using the DBGU UART to transfer data. We are looking at adding this, and when we do this problem should be resolved. Until then, Snapper 9g20 is not supported by samba-script.

Please see http://support.atmel.no/bin/customer?action=viewKbEntry&id=717 for more details.

When I write a YAFFS image, it is unable to boot

When creating the YAFFS2 image there can be occasional issues with file ownership on the host PC. To avoid these, it is generally a good idea to run samba-script as root in these situations, to ensure that it correctly builds the YAFFS2 image. This issue is often seen with the following error:

Warning: unable to open an initial console.