Sam_I_Am -- Commands
Andrew Sterian
Padnos College of Engineering and Computing
Grand Valley State University
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 |
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.
© 2006, Copyright by Andrew
Sterian; All Rights Reserved. mailto: steriana@claymore.engineer.gvsu.edu