ABLE User Guide

Simtec Electronics

V R Sanders

B J Dooks

D J Silverstone

  • Linux® is a registered trademark of Linus Torvalds.

  • UNIX® is a registered trademark of The Open Group.

  • I2C® is a registered trademark of Philips Semiconductors Corporation

  • All other trademarks are acknowledged.

While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions, or for damages resulting from the use of the information contained herein.


Table of Contents

I. Usage
1. Overview
2. Getting Started
2.1. Using hyperterm as a serial console
2.2. Using minicom as a serial console
3. Command Line Interface
3.1. Command line editing
3.2. Simple commands
3.3. Quoting
3.4. Filesystem navigation
3.5. Getting help
3.6. Setting Options
4. The ABLE shell
4.1. Conditional execution
4.2. Shell variables
4.2.1. Simple variables
4.2.2. Non volatile variables
4.2.3. Positional variables
4.2.4. Special variables
4.2.5. Accessing variables
4.2.6. Variables with special meanings
4.3. Functions
4.4. Command substitution
4.5. Shell script
5. ABLE Console
5.1. Console drivers
5.2. Setting parameters on serial drivers
5.3. Configuring the console system
5.4. Setting the logging level
5.5. Practical use of the console system
5.5.1. Basic serial debug console
5.5.2. No console at all
5.5.3. Displaying a logo and boot abort
6. Starting an Operating System
6.1. Data sources
6.2. Alias sources
6.3. Network sources
6.4. XModem source
6.5. Navigating a filesystem
6.6. How ABLE identifies files.
6.6.1. ABLE shell script
6.6.2. ABLE executable
6.6.3. ARM Linux zImage
6.6.4. ELF and AOUT files
6.6.5. UNIX Compress files
6.6.6. Gzip files
6.6.7. Images, text and data files
6.6.8. Motorola S-Record
6.7. Starting an Operating System
6.7.1. The "setargs, load and boot" method
6.7.2. The "command line" method
6.8. Starting an Operating System Automatically
7. Networking
7.1. Finding a network interface
7.2. Configuring a network interface
7.3. Using the network to obtain files
8. Upgrading
8.1. Upgrading a NAND based systems
8.1.1. Obtaining Upgrades
8.1.2. Applying the update
8.2. Upgrading NOR based systems
8.2.1. Obtaining Upgrades
8.2.2. Loading the Upgrade
8.2.3. Running the upgrade
II. Built-in Command Reference
9. Core Commands
autoboot — Attempt to locate and boot suitable images automatically.
console — Controls ABLE console.
date — Show the current real time clock date and time.
dev — Manipulate and display the ABLE device tree.
help — Display help on built in commands
history — Lists the commands in the command line history.
hwinfo — Print hardware information.
meminfo — Shows memory information.
modules — List ABLE modules
mutexes — Display the internal mutual exclusion states for ABLE.
passwd — Alter ABLE interactive shell passwd
pmu — Power management control
reset — Reset machine
sbcd — Manipulates the board configuration data.
setdate — Sets the date in the real time clock
setopt — Sets device options.
settime — Sets the real time clock
shadow — Moves ABLE into RAM
showhz — Shows how long a system has been running
sysmsg — Show system messages.
sysspeed — Sets the system clockspeed
tasks — Displays task threads currently running on system.
uname — Print system identification
version — Display ABLE shell version
10. Shell Commands
echo — Output some text to standard output
exit — Exit ABLE shell
read — Reads a line of input into shell variables
set — Set or clear shell options and positional parameters
sh — Start a new ABLE shell
sleep — Delay for a specified amount of time
test — Performs test operations
11. Network operations
ifconfig — Network device configuration and selection
dhclient — Automatically configure a network interface using DHCP.
host — Look up hostnames and optionally set DNS server values.
mii — MII phy control
nc — Read and display data from a network socket
12. File Navigation
cd — Change present working directory
dumpfile — List files in a directory.
pwd — Show present working directory
13. File manipulation commands
cat — Displays contents of a text file
cp — Copy a file.
dumpfile — Displays a file in a hexadecimal dump
file — Tests each argument in an attempt to classify it.
more — Page output.
sum — Checksum a file
14. Non-volatile settings
nvclear — Reset non-volatile settings to defaults
nvsave — Save altered non-volatile settings
nvset — Set non-volatile parameters
nvshow — Show non-volatile parameters
nvunset — Clears non-volatile parameter
15. OS manipulation commands
boot — Starts loaded OS images
load — Load executable images
showargs — Shows arguments to be passed to any booted OS
setargs — Sets arguments to be passed to an OS started with the boot command
16. Debugging commands
dump — Displays an area of memory in hex dump
memset — Set range of memory to a specific value.
nand — Display contents or OOB data from a range of NAND blocks.
peek — Examine memory location
poke — Poke memory location
III. External Command Reference
17. Framebuffer commands
display — Display a bitmap image on framebuffer.
fbset — Set a framebuffers video mode and timings.
18. I2C commands
i2c-rd — Read from an I2C® device.
i2c-wr — Write to an I2C® device.
i2c-scan — Scan all available I2C busses for devices.
19. Miscellaneous commands
ablefis — Flash Information Services (FIS) tool for ABLE.
batty — Hardware unit test tool for ABLE.
detect-large-nand — Shows if boot NAND device has 128KiB blocks.
IV. Creating external commands
20. Tools and libraries
20.1. Obtaining a suitable toolchain
20.2. Obtaining development libraries and headers
21. ABLE C Library
22. A new ABLE command
22.1. Execution environment
22.2. How the libraries fit together
22.3. A hello world command
22.4. A simple command built with two objects
22.5. A simple command using floating point maths
A. Non-Volatile Variables Reference — Enable auto boot
boot.cmd — Command line to use for auto boot
boot.timeout — Time to wait before auto boot
boot.fs — The filesystems to be scanned by the autoboot command.
console.write — Default Console output stream — Default Console input stream
console.level — Console logging level
console.password — Console password for interactive use
fb.enable — Framebuffer driver - enable output
fb.output — Framebuffer driver - output target
fb.x — Framebuffer driver - Display X size (width)
fb.y — Framebuffer driver - Display Y size (height)
fb.refresh — Framebuffer driver - Display refresh frequency
ide.multi-limit — IDE multiple sector read limit
shell.hist — Shell history depth
sys.autoshadow — Determines if ABLE will automatically moved into RAM at system start
sys.speed — System speed set at start time
usb.enable — USB system enable
usb.hubdepth — USB system depth hubs should be searched for devices to
B. Changelog

List of Figures

2.1. Hyperterm settings window
2.2. Hyperterm displaying ABLE output
2.3. Minicom settings window
2.4. Minicom displaying ABLE output
6.1. Outline of Motorola S-Record
6.2. Initial boot operations
8.1. IM2440D20 firmware page
8.2. EB2410ITX firmware page
9.1. Autoboot command flowchart

List of Tables

4.1. Non-volatile data types
4.2. Special variables
4.3. Variables with special meanings
5.1. Available console drivers
6.1. S-Record loader error codes
6. Commands in alphabetical order
9.1. Defined console log levels
10.1. Escaped echo characters
10.2. Possible test expressions
10. Commands in alphabetical order
21.1. ISO headers provided in ABLE C library
21.2. Additional headers available in ABLE libc
A.1. Alphabetical list of non-volatile variables

List of Examples

2.1. Display after starting ABLE on EB2410ITX
3.1. Navigating a filesystem
3.2. Getting help on the uname command
3.3. Using the nvshow command to list the default variables
4.1. Using the test command and conditional operators
4.2. Using curly braces to disambiguate variables
4.3. Accessing positional parameters
4.4. Defining and using functions.
4.5. Using substitutions.
4.6. Example shell script
5.1. Using the console command to show available drivers
5.2. Setting serial console driver parameters
5.3. Showing the consoles of an unconfigured system
5.4. Adding console drivers to a running system
5.5. Setup of basic serial console
5.6. Using the null drivers safely
5.7. A method to display logo and boot abort
6.1. Using the dumpfile(1) command to list available sources.
6.2. Using the dumpfile(1) command to list cooked sources
6.3. Using the tftpboot source
6.4. Using the XModem source
6.5. An example S-Record
6.6. Using the "setargs, load and boot" method to start a Linux kernel
6.7. Using the "command line" method to start a Linux kernel
6.8. Displaying a logo during the automatic boot process
7.1. Executing a program using the tftpboot pseudo filesystem
8.1. The romwrite command requiring the shadow command
8.2. The romwrite command producing warnings
8.3. The romwrite command completing successfully
9.1. Using the console command
9.2. Using the date command
9.3. Using the help command
9.4. Using the history command
9.5. Using the hwinfo command
9.6. Using the meminfo command
9.7. Using the modules command
9.8. Using the passwd command
9.9. Using the setdate command to set the real time clock
9.10. Using the setopt command to alter serial port options.
9.11. Using the settime command to set the real time clock
9.12. Using the showhz command
9.13. Displaying the system messages after a default boot
9.14. Using the syspeed command on a EB2410ITX
9.15. Using the tasks command
9.16. Using the uname command on the EB2410ITX
9.17. Using the version command
10.1. Using the echo command
10.2. Using the read command
10.3. Subshell variable scope
10.4. Using the sleep command to delay execution
10.5. Performing assorted tests
11.1. Using the ifconfig command to select default interface
11.2. Using the ifconfig command to configure a fixed address
11.3. Using the dhclient command
11.4. Using the host command to resolve an address.
11.5. Using the mii command to show all the registers in a phy
12.1. Using the cd and ls commands to navigate a filesystem
12.2. Using the ls command
12.3. Using the pwd command and PWD variable to show the present working directory
13.1. Using cat command to display files contents
13.2. Using the dumpfile command
13.3. Using the file command to determine filetypes
13.4. Checksumming a file with the sum command
14.1. Using the nvset command and shell method to alter a non-volatile variables
14.2. Using the nvset command
14.3. Using the nvshow command
15.1. Using the boot command
15.2. Using the showargs command
15.3. Using the setargs command
16.1. Using the dump command to examine memory
16.2. Using the nand command to display a range of NAND blocks
17.1. Using the display command
17.2. Using the fbset command
18.1. Using the i2c-rd command
18.2. Using the i2c-wr command
18.3. Using the i2c-scan command
19.1. Starting ABLE FIS
19.2. ABLE FIS creating a default FIS table
19.3. Removing a partition from a FIS table
19.4. Adding and Editing a FIS table partition
19.5. Adding partition to FIS table
19.6. Shortening a FIS table
19.7. Writing current FIS partition table
19.8. Editing the name of a FIS partition
19.9. Changing the length of a partition.
19.10. Starting batty from the command line
19.11. Using detect-large-nand from the command line
22.1. Hello World command
22.2. Example using a makefile
22.3. Command using math functions