Sam_I_Am -- An interface for Atmel AT91SAM7S microcontrollers -- Commands

Sam_I_Am -- Commands

Andrew Sterian
Padnos College of Engineering and Computing
Grand Valley State University

Top-Level | Connecting the Device | Program Operation | Commands

Introduction

SAM-BA interprets single-line commands either typed interactively or from files (either a startup script or by using the source command). A command comprises a word followed by zero or more parameters. For example:

    dump 202000 20

executes the dump command with two parameters.

Numeric constants are, by default, interpreted as hexadecimal constants, unless otherwise noted. The numeric base of a constant can be explicitly specified with the following prefixes:

0x or 0X for hexadecimal constants (e.g., 0x202000)
0d or 0D for decimal constants (e.g., 0d500)
0b or 0B for binary constants (e.g., 0b101)

The Python readline module is used for input so that command-line recall and editing are available. A variety of key bindings can be used for line editing. The most common are shown in the following table.

Key Sequence Action

Left/Right Arrow Cursor left/right

Ctrl-A Cursor to start-of-line

Ctrl-E Cursor to end-of-line

Ctrl-D Delete character at cursor

Ctrl-K Delete to end-of-line

Ctrl-_ Undo last change

Ctrl-P Recall previous command in history

Ctrl-N Recall next command in history

Ctrl-R Begin incremental reverse search through history

Ctrl-S Begin incremental forward search through history

Key Sequence	Action
Left/Right Arrow	Cursor left/right
Ctrl-A	Cursor to start-of-line
Ctrl-E	Cursor to end-of-line
Ctrl-D	Delete character at cursor
Ctrl-K	Delete to end-of-line
Ctrl-_	Undo last change
Ctrl-P	Recall previous command in history
Ctrl-N	Recall next command in history
Ctrl-R	Begin incremental reverse search through history
Ctrl-S	Begin incremental forward search through history

Help can be obtained on any command by typing 'help command'.

Device Control

open [devname [baudrate [timeout]]]: This command must be issued before any attempt to communicate with SAM-BA. If specified, the command connects to the given device name, e.g., /dev/ttyUSB0, else a default device name is used. See the Connecting the Device page for more information on determining the appropriate device name. The optional baud rate parameter specifies a communication baud rate (115200 should work) while the timeout parameter specifies a time duration in milliseconds. If SAM-BA does not respond to a command within this time interval, Sam_I_Am gives up on expecting a response.
close: This command closes a currently open connection to a device. A close command is automatically issued when Sam_I_Am exits thus it is not necessary to explicitly type this command before closing the program.

Basic I/O

The following commands can be used for basic read/write operations on the microcontroller. In order to prevent an unintentional data abort, consider using the memory protection feature of Sam_I_Am (see the set command description in the Program Parameters section below).

readb address: Reads a single byte at the given address.
readh address: Reads a halfword (16 bits) at the given address. The address must be aligned to a halfword boundary.
readw address: Reads a word (32 bits) at the given address. The address must be aligned to a word boundary.
writeb address byte: Writes a byte at the given address.
writeh address hword: Writes a halfword (16 bits) at the given address. The address must be aligned to a halfword boundary.
writew address word: Writes a word (32 bits) at the given address. The address must be aligned to a word boundary.
dump address [bytes]: Prints a formatted display of words in memory beginning at the given address. With no third parameter, 128 bytes (32 words) are displayed, otherwise the specified number of bytes are displayed (rounded up to a multiple of 4 bytes). The address need not be aligned.

Sending/Receiving Files

The following commands can be used for transferring data in bulk between the microcontroller and local files. In order to prevent an unintentional data abort, consider using the memory protection feature of Sam_I_Am (see the set command description in the Program Parameters section below).

recv file.hex address numbytes

Download a sequence of numbytes from the microcontroller beginning at the given address and store them in the given file. The data is stored in the file in Intel HEX format.

send file.hex

Upload a file in Intel HEX format to the microcontroller. This command can only be used to upload data to RAM. The flash command must be used to upload data to FLASH.

The start address stored in the HEX file is saved. A subsequent go command without an explicit target address will use the address saved by the last send or flash command.

flash file.hex

This command can be used to program the FLASH. The given filename must be in Intel HEX format and must represent data stored at valid FLASH addresses. This command can only be used to program the FLASH. The send command must be used to modify RAM.

Note that this command does not automatically unlock the lock regions to be programmed. This must be done manually beforehand otherwise FLASH programming will fail.

Only the pages that represent data to be programmed are erased. All other pages are not erased.

The start address stored in the HEX file is saved. A subsequent go command without an explicit target address will use the address saved by the last send or flash command.

This command uploads a small program to RAM at address 0x202000 so whatever is already there will be overwritten.

Running Programs

In order to reduce the possibility of branching to an illegal address, consider using the memory protection feature of Sam_I_Am (see the set command description in the Program Parameters section below).

go [address]: Transfer program execution to the given word-aligned address in ARM mode (i.e., not Thumb mode). If no address is specified, the last start address specified from a send or flash command is used.
If the program returns, control passes back to SAM-BA, otherwise no further communication with SAM-BA is possible until the system is reset.
tgo [address]: Transfer program execution to the given halfword-aligned address in Thumb mode. If no address is specified, the last start address specified from a send or flash command is used.
If the program returns, control passes back to SAM-BA, otherwise no further communication with SAM-BA is possible until the system is reset.
disp: Displays any output from an executing user program. This command waits for the amount of time specified in the Timeout parameter of the open command (by default, 500 milliseconds) for any characters to be sent from the microcontroller. Any received characters are displayed. Once no characters arrive for the timeout interval, the command is complete.

Program Parameters

set [parameter [arguments ...]]

This command is used to set program operating parameters. Without any arguments, the command is equivalent to a show command, i.e., it displays all program parameters. The following parameters are implemented:

set readallow {all} | {startaddr numbytes}: This parameter defines a region of memory that may be read (e.g., using commands such as readb or recv). Attempted accesses outside this region are blocked before being passed to SAM-BA in order to prevent SAM-BA from generating a data abort exception. The memory region is defined by a start address and the number of bytes in the region. Multiple instances of this command can be used to construct a list of allowable regions. The special form set readallow all clears the list of regions and allows memory accesses anywhere.
set execallow {all} | {startaddr numbytes}: This parameter defines a region of memory that may contain executable code, thus is a valid target for the go command. Attemps to execute the go command at addresses outside this region are blocked before being passed to SAM-BA in order to prevent SAM-BA from generating a prefetch abort exception. The memory region is defined by a start address and the number of bytes in the region. Multiple instances of this command can be used to construct a list of allowable regions. The special form set execallow all clears the list of regions and allows program execution anywhere.
set ramwriteallow {all} | {startaddr numbytes}: This parameter defines a region of RAM memory that may be written (e.g., using commands such as writeb or send). Attempted accesses outside this region are blocked before being passed to SAM-BA in order to prevent SAM-BA from generating a data abort exception. The memory region is defined by a start address and the number of bytes in the region. Multiple instances of this command can be used to construct a list of allowable regions. The special form set ramwriteallow all clears the list of regions and allows RAM writes anywhere. The flash command is not affected by the regions defined with set ramwriteallow.
set flashwriteallow {all} | {startaddr numbytes}: This parameter defines a region of FLASH memory that may be written using the flash command. The memory region is defined by a start address and the number of bytes in the region. Multiple instances of this command can be used to construct a list of allowable regions. The special form set flashwriteallow all clears the list of regions and allows FLASH writes anywhere. Only the flash command is affected by the regions defined with set flashwriteallow.

show [parameter]

This command displays the current value of all parameters that can be set using the set command. Without an argument, all parameters are displayed.

Device Information

The following commands all read the microcontroller's peripheral registers and present a human-readable interpretation of the register contents.

info: This command displays a list of names for all the systems on the microcontroller. Each name can be used as an additional parameter to the info command, as described below.
info power: Display information on the Power Management Controller and Clock Generator peripherals.
info reset: Display information on the Reset Controller.
info rtt: Display information on the Real-Time Timer.
info pit: Display information on the Periodic Interval Timer.
info wd: Display information on the Watchdog Timer.
info memory: Display information on the Memory Controller.
info flash: Display information on the Flash Controller.
info aic: Display information on the Advanced Interrupt Controller.
info pio: Display information on the Parallel I/O Controller.
info spi: Display information on the SPI Controller.
info twi: Display information on the TWI Controller.
info usart: Display information on the USART Controller.
info ssc: Display information on the Synchronous Serial Controller.
info tc: Display information on the Timer/Counter.
info pwm: Display information on the Pulse-Width Modulation Controller.
info usb: Display information on the USB Controller.
info ad: Display information on the A/D Converter.
info dbgu: Display information on the Debug Unit.

Miscellaneous Commands

exit: This command exits Sam_I_Am. The quit command is a synonym, and pressing Ctrl-D also quits the program.
quit: This command exits Sam_I_Am. The exit command is a synonym, and pressing Ctrl-D also quits the program.
shell [program [args ...]]: This command runs the given program and arguments in a sub-shell. With no program or argument parameters, an interactive shell is launched. The single-letter command ! is a synonym for this command.
! [program [args ...]]: This is a synonym for the shell command.
source filename: This command will execute the lines in the given text file as if they had been typed interactively. The source command can be nested arbitrarily (i.e., script files can source other script files).
echo [args ...]: The given arguments are simply displayed. This command is only useful for debugging.
Version: This command displays the Sam_I_Am program version.