Linux for ARM on TS-72XX User's Guide

Introduction

About this Manual

This manual is a brief introduction to the use of Linux on a Technologic Systems' (TS) ARM-based Single Board Computer (SBC) � TS-72XX series. Many technical questions are answered within this document This manual is not meant as a general tutorial on Linux (or Linux Development), but is designed specifically to cover issues related to using Linux on Technologic Systems' ARM SBCs.

Technologic Systems' ARM products offer a different set of tools than the x86 products. This manual documents the basic knowledge needed to work with the ARM products.

WARNING:

This document was created to be used with the TS-7200, TS-7250 and TS-7260 boards (TS-72XX series) and contains sections specific to these products only, such as the second chapter. However, most of the remaining sections will still be useful guidelines for other TS-ARM computers (TS-7300, TS-7400, etc).

If your project demands rapid application development, Technologic Systems does offer software engineering services. We also offers custom hardware design. Please contact us for more information.

TS-72XX Series

The TS-72XX series Single Board Computers (SBC's) run on a 200 MHz ARM9 processor with power as low as 1/2 Watt. Low board complexity, low component count, and low power/heat makes for an extremely reliable embedded engine. The TS-72XX SBC's are available in thousands of configurations, many of which are Commercial off the Shelf (COTS) and available to ship today.

The EP9302 processor from Cirrus is the highly integrated 200Mhz ARM9 processor that the TS-72XX SBC's are built around and includes an on-chip 10/100 ethernet, USB, serial, and Flash/SDRAM controller. For example, on the TS-7200 model there is 32 Mb of Micron SDRAM running at 66 Mhz and 8 Mb Intel Strata flash on-board. A supplemental PLD provides glue logic, watchdog timer, Compact Flash IDE, and 8 bit PC/104 support. Integer CPU performance is about 20% faster than our 133 Mhz x86 offerings.

Even with the standard power consumption of 2 Watts, the TS-72XX SBC�s run without fans or heat sinks in the temperature range of -20� to +70�C. Extended Temperature -40� to +85�C is also standard, but CPU clock must be decreased to about 166MHz for higher temperatures. Digital Signal Processing (DSP) is enabled through a standard 5 channel, 12bit A/D converter (Optional 8 channel, 12 bit A/D converter), 20 DIO lines and 2 standard serial ports.

The 8/16 bit PC/104 interface enables additional functionality through Technologic Systems� broad product line of PC/104 peripheral daughter boards. The TS-7KV adds video, CAN, Com Ports, and A/D conversion. The TS-ETH10 allows the addition of Ethernet ports. The TS-CAN adds CAN connectivity. The TS-Modem boards add both wired and cell phone capabilities.

The TS-72XX rugged ARM9 SBC's have found their way into many embedded applications. Customers are using the TS-72XX series SBC's in: energy generation, manufacturing process control, traffic management, printing system management, communication infrastructure, website hosting, data gathering and laboratory test equipment. We use a TS-7200 to host our complete website and to prepare and test your SBC prior to shipping.

Startup

WARNING:

This chapter is only applicable to the TS-72XX computers.

Console and Power Up

The TS-72XX SBCs have no video controller or keyboard interface. This was done to keep the board size small and the cost low. COM1 is typically used as a console port to interface the TS-72XX to a standard terminal emulation program on a Host PC.

An ANSI terminal or a PC running a terminal emulator is required to communicate with your Embedded PC. Simply connect an ANSI terminal (or emulator) to COM1 (DB9 female connector) using a null modem cable (this is included in the TS-ARM Development Kit), using serial parameters of 115,200 baud, 8 data bits, no parity, no flow control, 1 stop bit (8N1), and make sure jumper JP2 is installed. If you are running Linux, the minicom program works well, Windows users can run the Hyperterm application. Technologic Systems offers a null modem cable with both 25 pin and 9 pin connectors at each end as part number CB7-05. Some systems also require the 10-pin header to 9-pin Sub-D adapter which is P/N: RC-DB9.

The console can be changed to COM2 by installing JP4 (with JP2 also installed). If your application does not require a console or both COM ports are required, then removing the jumper JP2 easily disables all console output.

Connect a regulated 5VDC, (1A minimum) power source using the included 2 screw terminal strip/connector. Please note the polarity printed on the board. The boot messages, by default, are all displayed on COM1 at 115200 baud.

Boot Sequence

The boot sequence has four distinct stages:

1. TS-BOOTROM messages
2. RedBoot ROM monitor messages
3. Linux Kernel messages
4. Login prompts

After applying 5VDC power, the board mounted LED will blink, followed immediately by the display of TS-BOOTROM messages and RedBoot messages. RedBoot, if not interrupted by the user within one second, loads the Linux kernel from flash and boots to the on-board flash chip.

WARNING:

Ensure that JP5 is removed when booting from the default flash file-system. Special scripts look for it and, when found, run special test programs that will use up system resources.

TS-BOOTROM

Upon power up, the board executes proprietary Technologic Systems boot-code, then immediately executes RedBoot. The TS-BOOTROM is stored in flash memory and is used to perform the first hardware configuration, such as the EP9301 initialization and TS-72XX hardware specifics, and to load the eCos/RedBoot system. The TS-BOOTROM serves as reusable way of initializing and checking hardware in a way that it is not necessary to rewrite the code for every desirable OS. Some of the TS-BOOTROM configuration tasks include:

• initializes the processor
• turns off the watchdog timer
• configures the serial UART to 115200 bps
• initializes and tests SDRAM and FLASH
• loads and runs RedBoot from flash

There is an intermediate boot loader code on the TS-72XX SBCs which use the NAND flash technology, named TS-NANDBOOT. It is needed because the EP9301 processor can't handle NAND devices. Then, the TS-NANDBOOT contains specific routines to read the NAND flash memory and load the TS-BOOTROM.

eCos/RedBoot

RedBoot is a feature rich boot-ROM monitor, that allows manipulation of the on-board flash, JFFS and YAFFS images, loading and execution of a kernel or executable from either tftp (trivial ftp), http or flash, and gdb debugging stubs. From RedBoot, one can load and execute any standalone binary. Most commonly, a Linux kernel or a Windows CE binary is used. One can also write applications within the eCos environment and load them with RedBoot.

Using Redboot

By default, a pre-existing RedBoot script is executed on initialization time, if not interrupted by the user within one second. The default script instructs RedBoot to load the Linux kernel from the flash, and instructs the Linux kernel to use the JFFS/YAFFS image on the flash chip for its root file system. One can view the RedBoot defaults for the board, as well as the default script, by entering at the RedBoot command prompt (Ctrl+C within one second after power up):

RedBoot> fconfig -l
Run script at boot: true
Boot script:
.. fis load vmlinux
.. exec -c "console=ttyAM0,115200 root=/dev/mtdblock1"
Boot script timeout (100ms resolution): 1
Use BOOTP for network configuration: false
Gateway IP address: 192.168.0.11
Local IP address: 192.168.0.50
Local IP address mask: 255.255.255.0
Default server IP address: 192.168.0.11
dns_ip: 192.168.0.11
Network hardware address [MAC]: 0x00:0xD0:0x69:0x4F:0x34:0xA5
GDB connection port: 9000
Force console for special debug messages: false
Network debug at boot time: false

The defaults can be changed by simply entering �fconfig� at the RedBoot prompt and answering the prompts. A final chance to write or discard the changes to the board will be given by RedBoot. Also, the main RedBoot commands can be viewed by entering �help� at the prompt, and further information about a single command can be viewed by typing �help <command name>�.

Loading and execute kernel from RedBoot

RedBoot can load a kernel or executable via the serial console, a tftp server, http server, or directly from flash.

Note:

The Linux kernel must be loaded into memory address 0x00218000.

FLASH

Loading the kernel from flash is done automatically by RedBoot in the default script with the following command:

RedBoot> fis load zimage -b 0x00218000

One can see where in flash the kernel is and where in memory it will be loaded to by typing fis list, which shows the various areas of flash RedBoot is aware of. The following is a typical output of fis list:

Name FLASH addr Mem addr Length Entry point
(reserved) 0x60000000 0x60000000 0x00620000 0x00000000
RedBoot 0x60620000 0x60620000 0x00040000 0x00000000
vmlinux 0x60660000 0x00218000 0x00160000 0x00218000
RedBoot config 0x607C0000 0x607C0000 0x00001000 0x00000000
FIS directory 0x607E0000 0x607E0000 0x00020000 0x00000000

From the above example, the kernel executable labeled vmlinux is stored at flash address 0x60660000, and will be loaded into memory address 0x00218000. It is possible to write a new kernel loaded by the user in memory to flash, thereby overwriting the pre-existing kernel stored in flash. First, one must delete the existing kernel image file from flash, then write the new loaded one to disk. The following commands accomplish this:

fis delete <kernel name>
fis create -b 0x00218000 -l 0x160000 <new kernel name>

Note that the delete command specified <kernel name>, which refers to the name of the fis entry to delete. The create command specified <new kernel name>, which is the name of the executable loaded into memory. If the name of the downloaded executable is different, please specify that name when doing a create command.

HTTP

Prior to loading a new kernel into RebBoot using HTTP, make sure you have configured RedBoot with a network configuration that can reach the network. You may use the RedBoot "fconfig" command to set network parameters.

Get to the RedBoot prompt by hitting Ctrl+C key immediately after power on and type the following command:

load -v -r -b 0x00218000 -m http -h <http sever IP> <kernel name>

For example:

load -v -r -b 0x00218000 -m http -h 67.40.67.44
/ftp/ts7kv/vmlinuxts7200ts9.bin

If RedBoot gives you an error about not understanding the "m http" option, you have an older version of RedBoot and must instead load the kernel via a local TFTP server.

TFTP

To load a kernel from a simple TFTP server, the following command is needed:

load -r -b 0x00218000 -h <tftp server IP> <kernel name>

For example:

load �b 0x00218000 �h 192.168.0.1 vmlinux

Executing the Kernel and Booting the Root File System

Now that a kernel has been loaded into memory, it can be executed. This is accomplished with the following command:

exec -c "<kernel parameters>�

For example:

exec -c �console=ttyAM0,115200 ip=dhcp root=/dev/mtdblock1�

The �exec� command executes the loaded kernel image, passing to the kernel the arguments specified via the �-c� switch. In the previous example, kernel messages are sent out on the first serial port (note that ttyAM0 is used instead of the familiar ttyS0) at 115200 baud and the root file-system is on the first mtdblock of the flash chip.

On the TS-7200 modem, to load the root file system from the Compact Flash card, the following command should be used instead:

exec -c �console=ttyAM0,115200 ip=dhcp root=/dev/hda1�

To load a NFS Root file system from a NFS server, use the following command:

exec -c �console=ttyAM0,115200 ip=dhcp nfsroot=<IP of NFS server>:</path/to/NFSROOT>

Booting to an initrd Image from RedBoot

One may want to instruct the kernel to use an initrd image during the Linux initialization. This might be useful in situation additional hardware support or system configuration in needed prior to root file system load. Using RedBoot, an initrd image can be loaded through three main steps:

1. Load the initrd.gz image into memory (memory location used is 0x0080_0000 or 0x00600000, for example)

load -h <server IP> -r -b <memory address>

1. Load the kernel into memory (Follow previous intructions for kernel loading)
2. Using the �exec� comannd, instruct RedBood to execute the Kernel and initrd, for example:

exec -r 0x0080_0000 -b 0x00218000 -c "console=ttyAM0,115200
root=/dev/ram0 init=/linuxrc rw"

Logging In

After the desired Linux Kernel is loaded and executed through RedBoot, the file system loads and networking, logging, Apache web server, etc. are all started. When the login prompt is displayed, type �root� to login, with no password. A Bash login prompt will then appear. At this point, you are ready to enjoy your TS-72XX SBC running Linux.

Shutdown

Use the �shutdown �h now� command to halt the Linux system when running from Compact Flash, SD or USB memory card to avoid a potentially lengthy file system check on the next boot, since the file system running is EXT2 formatted. On the other hand, the JFFS/YAFFS file systems are highly tolerant of power cycles while the file systems are mounted. Therefore, the �shutdown� command is not required when the root file system is JFFS/YAFFS, but is still recommended.

Linux For ARM Operating System Support

The ARM processor (the EP9302) comes from Cirrus and the platform is very similar to the Cirrus EDB9302 evaluation board. Cirrus has strongly promoted running Linux on this chip and has done most of the legwork in creating a patch set to the Linux 2.4 kernels, but we have also had to modify the Linux Kernel (TS-Kernel) so it can support the 8MB onboard Flash chip (via mtd drivers), the compact flash IDE driver, and the A/D converter. If you want to use Linux and aren't tied to the x86 architecture, the TS-72XX boards can be very cost-effective.

The TS-72XX SBCs are shipped standard with the compact TS-Linux embedded operating system installed in the on-board Flash memory. The fullfeatured Debian Linux can also be used with an NFS root file system or larger Flash drives, such as Compact Flash cards, SD cards and USB flash drives. The TS-Kernel used is based upon the version 2.4.26, patched and compiled for the Cirrus EP9301 ARM920T processor, and is real-time capable through RTAI.

The root file system used by the Linux OS can be any of the following:

• JFFS/YAFFS file system image in the on-board Flash (RedBoot should include the option root=/dev/mtdblock1 to instruct the kernel to boot here)
• EXT2 file system image in the Compact Flash card (RedBoot should include the option root=/dev/hda)
• NFS root, via Ethernet port (RedBoot should include the option root=/dev/nfs nfsroot=<IP>:<DIRECTORY> ip=dhcp)

TS-Kernel

In order to support the Linux Kernel on TS-72XX ARM SBCs, Technologic Systems added modifications to the Linux Kernel for the EP9301 and EDB9301 platform shipped by Cirrus Logic, manufacturer of the processor. The Linux Kernel used is based upon the version 2.4.26, and additional patches are applied to the main 2.4.26 source tree so that the kernel will support ARM processors (RMK patches), the Cirrus EP9301 processor and, finally, TS-72XX hardware specifics. The final Linux Kernel is a Technologic Systems specific source, therefore called TS-Kernel.

TS-Kernel modifications include drivers for the Compact Flash IDE, for the extra A/D converter chip, for the NAND flash memory devices, MTD drives and YAFFS file system, framebuffer driver for video interface, second ethernet driver for TS-7300, driver support for the SJA1000 CAN controller on TS-CAN1, drivers for the SD Card interface, etc.

Technologic Systems is constantly improving the TS-Kernel so that it will support new ARM SBCs and PC/104 peripheral boards. Complete TS-Kernel source code is provided at Technologic Systems web site, allowing developers to implement modifications and compile their own kernels.

Note:

The TS-Kernel supports the Real-Time Application Interface (RTAI project), making the embedded operating system capable of handling applications with hard real-time restrictions.

For further information on the real-time extension and kernel development procedures, refer to the development section of this manual.

Note:

It is also possible to run the 2.6 version of the Linux Kernel on TS-72XX SBCs. However, this development is not officially supported by Technologic Systems yet. Contact Technologic Systems if your solution requires 2.6 kernel version.

TS-Linux

TS-Linux is a compact Linux distribution, based on Busybox, ideal for small footprint systems and used as a demonstration OS on the TS-72XX computers. Therefore, the TS- 72XX SBCs come with TS-Linux installed by default in the on-board flash. RedBoot is also configured to load the TS-Linux from on-board flash by default.

The use of TS-Linux is very similar to other common Linux systems. A experienced Linux user should find no problems when using TS-Linux. The initialization and configuration processes are all managed by the files located in the �/etc� directory. Devices entries are in the �/dev�, while libraries and kernel modules are inside �/lib�. Network services such as FTP and Telnet servers are also available. Even an HTTP server comes installed by default with TS-Linux and is loaded during initialization time.

Most of the Linux utilities you would expect are present on the TS-Linux distribution. In total there are over 120 utilities installed on the file system. Many of the basic utilities are implemented using Busybox. BusyBox combines tiny versions of many common UNIX utilities into a single small executable The utilities in BusyBox generally have fewer options than their full-featured GNU cousins; however, the options that are included provide the expected functionality and behave very much like their GNU counterparts. BusyBox provides a fairly complete environment for any small or embedded system.

Note:

In order to keep the distribution small, TS-Linux has small support for the GNU tools. Therefore, a C/C++ development environment is not installed. If the user's main target is development, the Debian Linux distribution is highly recommended A cross-compile environment based on a PC is also an option for development.

Debian Linux

The Debian is a full-featured and powerful Linux distribution mostly based upon GNU tools. It includes everything necessary to easily run Linux and develop Linux applications. In addition, various original Linux utilities and installation tools are available to make system utilization and packages updating easy. The Debian Linux is ported to ARM processors and runs with TS-72XX SBCs. With Debian Linux, experienced Linux users have a complete Linux system to take full advantage of their knowledge, and new users have an easy environment to get started with the Linux world.

Technologic Systems makes use of Debian Linux as a development distribution. For example, the 256 MB Compact Flash card is pre-installed with Debian. Along with the basic core utilities, some developer tools have been installed, including a native arm gcc toolchain, for C/C++ application development. In addition, the Perl interpreter and a wide variety of network services are available, such as FTP, Telnet, SSH and Apache HTTP servers. One can also use the Debian Linux distribution via an NFS root file system or an USB flash memory device.

apt-get

When using the Debian Linux file system, adding new packages and removing undesired ones is done all through Debian's package management. �apt�, �dpkg�, all behave as expected. With Debian, one can easily install and remove software packages. For a quick demonstration of how easy it is to remove and install programs with Debian, try the following commands:

apt-get install hexedit
hexedit /etc/passwd
^C (hit CTRL+C to safely exit)
apt-get remove hexedit

apt-get install installs a package name, while apt-get remove removes the named package. Visit the Debian home-page for further information, since a full in-depth discussion on Debian is outside the scope of this document.

• http://www.debian.org

Note:

Technologic Systems supports newer versions of the Debian Linux distribution, such as the 3.0, named Sarge. For newer Debian Linux support with your TS- 72XX SBC, contact Technologic Systems.

TS-ARM Linux CD

The TS-ARM Linux CD is an useful resource for TS-72XX users and developers. It contains the supporting files for Linux, including the TS-Kernel source code, sample applications, cross toolchain tarballs, Linux distributions, manuals, and other Linux utilities and binaries of interest. The files mentioned on the Linux for ARM User's Guide are all included on this CD. The following is the directory structure of the CD:

• root dir: Linux for ARM on TS-72XX manuals in PDF format
• /binaries: various binary packages for ARM, including Java, QtEmbedded, RTAI, etc
• /binaries/ts-bitstreams: default TS-Bitstreams for FPGAs
• /binaries/ts-images: ARM binaries of file systems images and other
• /binaries/ts-kernels: compiled TS-Kernels for TS-72XX SBCs
• /binaries/ts-modules: other drivers (Linux Kernel modules) for TS-72XX SBCs
• /binaries/ts-scripts: some Linux shell scripts used with the TS-72XX SBCs
• /binaries/ts-utils: some useful utilities distributed within a Linux distribution
• /cross-toolchains: pre-compiled GNU toolchain binaries for cross platform development with C/C++
• /distributions: binaries of linux distributions ready to install and run on TS-72XX SBCs
• /docs: various documents related to Linux for ARM on TS-72XX series, including data sheets and technical articles
• /manuals: all the hardware manuals for the TS-72XX series, including schematics
• /pictures: TS-72XX product views and related pictures
• /samples: source code and ARM binaries of some samples ready to compile and run
• /sources: source code of TS-Kernel and other related Linux for ARM packages

The TS-ARM Linux CD is included in the TS-ARM Development Kit and also can be downloaded through Technologic Systems website at:

• http://www.embeddedarm.com/linux/ARM.htm

Note:

Notice that the FTP server is frequently updated and will always contain the latest version of the TS-ARM Linux CD content. ftp://ftp.embeddedarm.com

TS-ARM Development Kit

The TS-ARM Development Kit for the TS-7200 Single Board Computer includes all equipment necessary to boot into the operating system of choice and start working. The development kit is highly recommended for a quick start on application development.

The TS-ARM Development Kit contains a 256 or 512 MB Flash drive (Compact Flash for 7200, USB for 7250 and 7260) which includes:

• a self-hosting ARM installation of the Debian Linux 2.0 distribution compiled for ARM
• gcc 2.95.4 and gcc 3.0 compiler with full tool-chain
• Build tools and source for JFFS/YAFFS file system in on-board NAND Flash.
• Hardware test routines source code and other example source code
• Debian package system: apt-get, tasksel, dselect

The development kit additionally includes:

• USB Compact Flash reader for TS-7200
• 5 VDC regulated power supply (international versions available)
• NULL modem cable
• Adapter cable from 10-pin header to DB9
• Various cables for connection DIO, LCD, Keypad, etc.
• Development CD with complete TS-Kernel source, manuals, example code, etc.
• Printed supporting documentation for TS-72XX's Hardware, Linux for ARM and Development Kit.

Note:

Single Board Computer is not included on the Development Kit (sold separately).

Configuring and Using Linux

This section provides basic and general information on how to configure and use Linux for ARM on TS-72XX SBCs. The following information is intended to be useful for both TSLinux and Debian Linux users. However, some of the mentioned utilities may not be available in the compact TS-Linux distribution.

This section is not intended to be a complete Linux Utilities tutorial. For further information, find the proper Linux documentation widely available on the Internet.

Basic Commands

Some very basic commands for one beginner user to start using Linux are:

• pwd: informs the current directory
• ls: lists current directory contents
• cd: changes directory
• man: accesses the system's manual pages of a given command
• cat: displays the entire content of a given file
• vi: Linux most common file editor (reading further documentation is recommended)

The most common file handling commands are �cp�, �mv�, �rm�, �mkdir�. Help information is provided by supplying �--help� to any given command, for example �cp �help�.

Users and Passwords

The TS-72XX SBCs come by default with the root user configured with no password. No additional user is added. All the existing users and groups can be viewed in the �/etc/passwd� and �/etc/group� files. The following utilities can be used for users and groups management:

• passwd: changes password for the logged user
• groupadd: add a group of users
• useradd: add a user
• chmod: change access permissions for files and directories
• chown: change owner of files

System Log and Information

Generally, all the log files of the Linux OS are stored on the �/var/log/� directory. Therefore, important system messages such as the kernel boot or some applications (HTTP server) outputs can be viewed by inspecting the log files. In addition, one can make use of the �dmesg� command to get the latest kernel messages. This might be useful when developing device drivers or watching kernel status.

Further utilities provide useful Linux environment information, such as:

• uname: prints system information such as kernel version and system date
• hostname: prints the hostname of the system
• printenv: prints the user's environment variable
• whoami: prints the current logged user name
• who: prints the current logged users

Further Linux system information of the currently running processes and running Kernel may be obtained through the files at the /proc virtual file system.

Initialization Scripts

After the �exec� command on RedBoot, the Kernel boots and drivers are loaded. Then, the initialization process reads the file �/etc/inittab�. The inittab file will call �/etc/rc.d/rcS.sysinit� as part of the system initialization. The run level then defaults to 3, which will run the �/etc/rcS� script and call all the scripts linked in the �/etc/rc3.d/� directory in numerical order. For example, the following are the initialization scripts for run level 3 found at TS-Linux:

/etc/rc.d/rc3.d# ls
S10Network S11portmap S20inetd S30telnetd S40apache

Changing the run level or re-invoking the initialization scripts is possible through the �init� command. A �halt� or �reboot� command will change the run level to 0 or 6 and execute the �/etc/rc0.d� scripts or �etc/rc6.d� scripts respectively.

Network Setup

The main utilities for network configuration under Linux are:

• ifconfig: prints network settings and configures ethernet interfaces
• ifup: turns given network interface up
• ifdown: turns given network interface down

Entering �ifconfig� shows the current ethernet settings. These utilities require a network device as parameter. On Linux, the ethernet devices are generally named eth0, eth1, etc. Therefore, the command �ifup eth0� or �ifconfig eth0 up� brings up the on-board ethernet interface on TS-72XX SBCs.

To configure the network, one needs to manage the proper configuration files. On TSLinux systems, these files are located in the �/etc/sysconfig/� directory. �/etc/network/� is used for Debian Linux. By default, Linux systems on TS-72XX boards are configured to assign the IP 192.168.0.50 to the on-board ethernet interface.

Setting Up the networking with TS-Linux

To configure the network when booting to the TS-Linux image on the flash chip, the files in �/etc/sysconfig/� must be edited. Network interfaces are configured on a file per interface basis. The first Ethernet device, eth0, is controlled by the file �/etc/sysconfig/ifcfg-eth0�. An example of �ifcfg-eth0� is shown below:

DEVICE=eth0 #Name of ethernet interface
IPADDR=192.168.0.50 #IP address of this ethernet interface
NETMASK=255.255.255.0 #Used with NETWORK to determine local IPs
NETWORK=192.168.0.0 #Used with NETMASK to determine local IPs
BROADCAST=192.168.0.255 #Broadcast IP for system wide messages
BOOTPROTO=static #Static IP (change �static� to �DHCP�)
ENABLE=yes #Load device on boot

The TCP/IP network settings are configured in the file �/etc/sysconfig/network_cfg�, here is a listing:

NETWORKING=yes #Enable networking on startup
GATEWAY=�192.168.0.1� #Gateway for internet access
GW_DEV=eth0 #Default gateway
HOSTNAME=ts7200 #Host name of this computer
BOOTPROTO=no
FORWARD_IPV4=no
DEFRAG_IPV4=no

The TCP/IP name resolution server is configured in �/etc/resolv.conf�. Here is a listing:

Nameserver 192.168.0.1 #Name server for domain name lookups

Those lines starting with a # symbol are comments. As the above example shows, eth0 is given the static address of 192.168.0.50. If one wishes eth0 to obtain its IP from a DHCP server, then change the line BOOTPROTO=static to BOOTPROTO=dhcp

Setting Up the networking with Debian

To configure the network interfaces when booting into Debian Linux, edit the file �/etc/network/interfaces�. A typical interfaces file would contain the following:

auto lo eth0
# The loopback interface
iface lo inet loopback
# The first network card
auto eth0
#iface eth0 inet dhcp
iface eth0 inet static
address 192.168.0.50
netmask 255.255.255.0
gateway 192.168.0.1

Those lines starting with a # symbol are comments. The line �auto lo eth0� means both the loopback interface and the first ethernet interface will be started automatically by the Debian networking scripts. The above example shows that eth0 would be assigned the static address of 192.168.0.50, using 192.168.0.1 as the default gateway. If one was to comment out those lines, and then uncomment the line iface eth0 inet dhcp, then eth0 would use a dhcp client to obtain it's IP and other relevant network information.

Note:

In order to test the default network settings with both TS-Linux and Debian Linux, open a web browser and use the embedded Apache web server by entering the default IP 192.168.0.50, or simple �ping� or �telnet� to 192.168.0.50.

Network Services

Linux is a well known OS suitable for network applications. As such, Linux offers a wide range of networking services which fully integrates the embedded systems to the external world and provides connectivity options for the end-users. TS-Linux and specially Debian Linux include solutions for the main network services, including Telnet (telnet utility), HTTP, FTP (ftp utility), SSH (ssh/scp utilities), NFS and Mail.

Some of these services can be started, restarted or stopped by management scripts located at the �/etc/init.d� directory. For example, the following command will restart the apache server:

/etc/init.d/apache restart

Also, the �/etc/inet.conf� file is used to configure the initialization and parameters of other network services.

Setting Data and Time

The Linux Kernel keeps the date and time of the day internally. In order to synchronize the Kernel/System time with an official and precise time source, one can use either the Real Time Clock (RTC) hardware or an NTP time server. System clock synchronization can be done during or after boot time with the help of the following commands:

• date: prints or sets the system date and time
• ntpdate: sets the system time according to a remote time server
• hwclock: sets the system time according to the RTC (if available)
• cal: displays a calendar

On the Debian distribution, the �/etc/init.d/hwclockfirst.sh� and �/etc/init.d/ntpdate� scripts provide system clock synchronization services.

Configuring and loading kernel modules

Kernel modules are binaries that can be inserted into the Linux Kernel during execution time. It is useful in order to load needed kernel features and services on demand. For example, one can turn on the support for a USB flash memory card by inserting the proper USB modules into the kernel. The main utilities used to handle kernel modules are:

• lsmod: lists the loaded kernel modules
• insmod: insert a given module into the kernel
• modprobe: insert a given module and its dependencies into the kernel
• modinfo: provides information about a kernel module

Memory

There are some useful utilities to check RAM memory and storage memory status:

• df: shows storage memory usage
• du: shows the total size of a given location
• free: shows RAM memory usage
• top: provides running processes and RAM memory utilization information

TS-Utilities

Besides the standard Linux set of utilities, the TS-Linux and Debian Linux distributions include Technologic Systems proprietary utilities which perform TS-72XX hardware specific and auxiliary operations. Some of the TS-Utilities are:

• bootload: Linux-based bootloader that enables booting of another Kernel
• busybox: compiled busybox for ARM with lots of Linux utilities
• peek8: reads 1 byte from the given memory location
• poke8: writes the given 1 byte to the given memory location
• peek16: reads 2 bytes from the given memory location
• poke16: writes the given 2 bytes to the given memory location
• peek32: reads 4 bytes from the given memory location
• poke32: writes the given 4 bytes to the given memory location
• ts7xxxctl: configures the hardware and turns on/off parts of the TS-72XX and EP9301
• jbi: programs the on-board CPLD through the JTAG interface using the DIO2 header
• jp: returns status of a given jumper
• hammer: blinks the on-board red led
• load_7kv: loads a hardware core (bitstream file) to the TS-7KV FPGA
• load_7300: loads a hardware core (bitstream file) to the TS-7300 FPGA
• bitblt-demo-ts7kv: performs bit blitting demo operations using the TS-7KV video
• bitblt-demo-ts7300: performs bit blitting demo operations using the TS-7300 video
• tsbootrom-update: updates the EEPROM with various bootroms options
• sdlock: handles SD Card security issues as password lock and write-protected mode

bootload: Linux Bootloader

Technologic Systems has developed a Linux application "bootload" that allows arbitrary booting of Linux and other OS kernels within Linux itself. The "bootload" program allows one to use the full facilities of Linux to retreive kernel files. Doing so also allows the use of standard shell scripts for the programmatic selection of appropriate kernels, Linux initrd's, and kernel command line arguments for maximum flexibility.

The �bootload� program is mostly implemented as a Linux user-space program using C. However, it requires a kernel module "bootloader.o" to be installed using "insmod" prior to invocation. No kernel patches or in-source modifications are required though:

insmod -f bootloader.o

The Technologic Systems' version of Linux uses a special device driver at /dev/misc/bootloader to accomodate the hooks needed by the "bootload" program to allow Linux to act as a bootloader and boot other Linux kernels and operating systems.

Command usage information for the �bootload� program follows:

$ bootload �help
Usage: bootload [OPTION] FILE
Linux to Linux bootloader - (re)boots a TS-7xxx board to another
kernel, OS
image, or raw executable by replacing the running Linux kernel.
General options:
-c, --cmdline=CMD Use CMD as the Linux kernel boot args
-r, --initrd=FILE Use FILE for Linux initial ramdisk
-s, --initrdsz=SZ Only read SZ bytes from the initrd file
-b, --base=ADDR Load the image at ADDR instead of 0x218000
--version Print version and copyright information
-h, --help This help
When FILE is -, reads from standard input.
Report bugs to <support@embeddedARM .com>

Some "one-line" examples of usage:

# Boot a compressed kernel image:
bunzip -c vmlinux.bin.bz2 | bootload -
# Reboot a kernel, but pass the 1MB running ramdisk to the new:
mount -o remount,ro /dev/rd/0 / bootload -c \
"console=ttyAM0,115200 root=/dev/ram0" -r /dev/rd/0 -s 0x100000
# Boot one of 2 kernels based on the state of DIO line #7:
if dio_data_get 7; then bootload vmlinux.backup.bin; else \
bootload vmlinux.bin; fi

tsbootrom-update: Changing/Updating the TS-BOOTROM

The tsbootrom-update is a Linux utility used to update the onboard EEPROM bootup firmware on the, allowing the board to perform different types of boot processes. For example, with the TS-7400, should you wish to actually load the kernel and initrd from an SD card, the default TS-FLASHBOOT bootup program, which boots from NAND flash, must be replaced with TS-SDBOOT using the tsbootrom-update utility. Usage and command line help for this command follows:

Usage: tsbootrom-update [OPTION] ...
Updates TS-BOOTROM bootup program stored on EEPROM
General options:
-n Do not actually write EEPROM
-s, --sdboot Write TS-SDBOOT bootup program
-f, --flashboot Write TS-FLASHBOOT bootup program
-u, --burninboot Write TS-BURNINBOOT bootup program
-p, --spiflashboot Write TS-SPIFLASHBOOT bootup program
-b, --blastboard Write to blast board EEPROM instead of SBC
-h, --help This help
EEPROM security block options:
-m, --mac=X Write X as ethernet MAC address
-l, --verifylen=N Checksum includes first N 512 byte sectors
-d, --device=FILE Use FILE to re-compute checksum value
-V, --verifydat=N Use N as pre-computed checksum value
-L, --lockdat=X Use X for the SD unlock data token from
previous "sdlock --set" command
-k, --verifylock Do not boot to an unlocked SD card
-c, --noconsole Disable serial console bootup messages
TS-production specific options:
-a, --alloc-mac Get MAC address from /var/tsproduction/mac

The TS bootup programs will by default print a banner message on bootup to the serial port displaying its build date, etc. If you wish to use all serial ports for your application and do not wish to have a serial console, the tsbootrom-update program can be used to silence early bootstrap banner messages so as to not confuse any potential external device UART#0 may be connected to.

Other bootstrap programs are available for-pay from Technologic Systems should you need them and custom ones may be designed for volume customers. For instance, the TS-ETHBOOT bootup program may be used to completely boot Linux from the network without NAND flash or SD card installed.

sdlock: SD flash card security features

Technologic Systems provides a "sdlock" Linux command which can be used to manipulate SD card hardware-enforced password locks and set the card's permanent write-protect feature. Using a password protected SD card is a great way to ensure software security and/or to make sure your TS-72XX SBC based product cannot be used in an unintended matter once deployed.

Usage: sdlock [OPTION] ...
Controls SD card lock and permanent write-protect features.
General options:
-p, --password=PASS Use PASS as password
-c, --clear Remove password lock
-s, --set Set password lock
-u, --unlock Unlock temporarily
-e, --erase Erase entire device (clears password)
-w, --wprot Enable permanent write protect
-h, --help This help

When the TS-72XX SBC is configured with the TS-SDBOOT bootup firmware, the SD unlock password can be stored in onboard EEPROM for automatic unlocking and booting of password protected SD cards. By default, TS-SDBOOT will still boot unlocked cards, but this behavior can be changed with the "--verifylock" option to the "tsbootrom-update" command described above-- with the "--verifylock" option the TS-72XX SBC will only boot locked SD cards.

TS-SDBOOT contains several features for high security. One feature is the ability to store a checksum of the SD card on the board to verify before bootup. If the checksum fails, the bootup firmware will refuse to boot the inserted SD card. TS-SDBOOT can also verify an arbitrary number of sectors of the SD flash card before allowing bootup. If the stored CRC does not match the actual CRC, the board will refuse to boot and blink the red LED continuously. Another feature is the ability to boot a password protected SD card. With this, it is possible to make an SD unreadable to any device except the TS-72XX SBC to which it is assigned. Although not directly a function of TS-SDBOOT, an SD card can also be made permanently write-protected through a software command. The combination of these features allows product designers several options on the security of their software and of their deployed TS-72XX SBC based devices.

The various SD commands that manipulate the password lock are marked as "optional" in the SD card specification. This means that not all SD card vendors may implement them in their devices. If they are not implemented, you will not be able to set the SD lock with the "sdlock" command.

TS-Scripts

Besides the standard Linux set of utilities, the TS-Linux and Debian Linux distributions include Technologic Systems proprietary utilities which perform TS-72XX hardware specific and auxiliary operations. Some of the TS-Utilities are:

• ts7kvfb: script that loads the framebuffer driver and linux console for TS-7KV
• loadUSBmodules.sh: loads modules for USB flash memory cards support
• loadUSB.sh: mounts the USB flash card and changes root file system to it
• ts7xxx.subr: various shell functions to handle hardware, including bits and peekpoke

ts7xxx.subr: Shell Functions for Hardware Access

The ts7xxx.subr shell functions enable control to some of the TS-72XX hardware functions without having to write/compile C code. These shell functions allow you to access various functions such as DIO, ADCs and so forth from the command line or in your own shell scripts.

There are two new commands added to the provided TS busybox to support these shell functions. These commands are "peekpoke" which is used to provide direct access to memory, and ADCread, which will provide a continuous stream of analog to digital readings (either on one channel or all channels) to stdout in text format. Both of these commands provide more info on what options are available if you type them without any arguments.

• dio_dir_get <n>: get the current direction (0=input,1=output) of DIO #n (n in 0..15)
• dio_dir_set <n> <dir>: set the direction of DIO #n to the specified direction
• 0=input,1=output)
• dio_data_get <n>: get the current value (0=Low,1=High) of DIO #n
• dio_data_set <n> <val>: set the current value (0=Low,1=High) of DIO #n (specified pin should be set to be an output already)
• usb_init: call this function to turn the USB ports on and initialize them
• usb_off: call this function to turn off the USB ports
• usb_numports: prints the number of USB ports on the board. this may be greater then
• the actual number of physical ports. the first port is port 0
• usb_port_devexists <port>: prints '1' if something is plugged into the specified port, or '0' otherwise.
• eth_off: turns off the ethernet port and phy
• eth_on: turns on the ethernet port and phy
• led0 <state>: sets the state of the green LED (0=OFF,1=ON)
• led1 <state>: sets the state of the red LED (0=OFF,1=ON)
• cpu_speed_max: set the CPU and bus speed to their maximum (normal) values, e.g. 200Mhz/100Mhz.
• cpu_speed_166: set the CPU speed to 166Mhz and the bus speed to 66Mhz.
• cpu_speed_42: set the CPU speed and bus speed to 41.5Mhz. This is the slowest speed that Ethernet will work at.
• cpu_speed_min: set the CPU and bus speed to their minimum values (14.7456Mhz)
• temp_read: returns the current Celsius temperature reading from the TMP124 chip.

Storage Devices and File Systems

This section describes the storage memory devices and the file system types used with TS-72XX SBCs. Occasionally, one may wish to boot into one device and access the other. This requires knowing what those devices are and where they are.

On-board Flash File Systems

The on-board flash contains a custom-made JFFS or YAFFS formatted file system image. JFFS2 is a compressed, Journaling Flash File System, for the NOR Strata Flash memory on TS-7200. The YAFFS file system is used for the on-board flash on the TS-7250 and TS-7260, which utilize NAND flash technology.

The NOR and the NAND flash devices are divided in three partitions. The first is a 16KB sized partition that contains the TS-BOOTROM. The last partition, which occupies 2MB- 3MB, contains the eCos/RedBoot system and the Linux Kernel. The remaining space in the middle partition is either for the JFSS or the YAFFS image used as the root file system. The following shows how a 8MB NOR chip is recognized by the Linux Kernel MTD system on a TS-7200:

TS-7200 flash: Found 1 x16 devices at 0x0 in 16-bit bank
Intel/Sharp Extended Query Table at 0x0031
Creating 3 MTD partitions on "TS-7200 flash":
0x00000000-0x00020000 : "TS-BOOTROM"
0x00020000-0x00620000 : "Linux"
0x00620000-0x00800000 : "RedBoot"

In both NOR and NAND cases, the Linux block device entry corresponding to the onboard flash is the �/dev/mtdblock�. Therefore, the following command can be used to mount the flash file system if you are not booted to the on-board flash:

mount /dev/mtdblock/1 /mnt

Updating the JFFS Image

The JFFS2 image can be created on your host computer, with binaries created via a cross compiler, then placed in a directory structure on the host computer. A new JFFS2 image can be constructed from that directory structure with the following command:

mkfs.jffs2 -p6291456 -e131072 -o /path/to/new_jffs.img

Pre-made JFFS images can be found in the Developer's CD or on Technologic Systems' web-site. The JFFS image file can then be copied over to the Single Board Computer and then written to the flash chip by using the following command:

dd if=/path/to/new_jffs.img of=/dev/mtdblock/1

Updating the YAFFS Image

To update the YAFFS image, erase the file system completely (either with �rm -fr� or �eraseall /dev/mtd/1�) and extract your new image onto the mounted file system. This way, YAFFS will auto-discover the bad sectors as you are extracting and work-around them.

The first step is to set up an NFS root file system and boot to it. Then, erase the second partition of your on-board flash using the char device, not the block device.

eraseall /dev/mtd/1

Mount the second partition of your on-board flash and extract the new filesystem:

mount /dev/mtdblock/1 /mnt
tar xzvf /path/to/7250_root_fs.tar.gz -C /mnt

Unmount the second partition of your on-board flash and reboot:

umount /mnt
shutdown -r now

Note:

The YAFFS file system runs on the TS-72XX boards that feature NAND chips with 512 byte page size, enabling up to 128 MB of on-board flash. The YAFFS2 file system supports the new NAND technology, with 2k page size, hence it will be installed on TS-72XX boards that are configured with 128-256 MB of flash.

Flash Memory Cards

Compact Flash

The format of the CF must be in EXT2 for proper operation with Linux as a root file system. The CF card is seen as the Primary Master IDE device, otherwise known as �/dev/hda�. The following command demonstrates mounting the Compact Flash card to the currently running system:

mount /dev/ide/host0/bus0/target0/lun0/part1 /mnt

SD Card

SD Card sockets are available on the TS-7260 and TS-7300 models. Technologic Systems has written a binary Linux driver module and a set of generic, OS-independent read/write routines for accessing the SD flash inside of an ARM object (.o) file. After the SD Card module is loaded, the device entry �/dev/sdcard0� is used to mount into the file system.

mount -t ext2 /dev/sdcard0/disc0/part3 /mnt

By default, the SD Card driver will be loaded during bootup time. However, in some cases the driver may not be loaded if a SD Card is not present in the socket. Therefore, it is necessary to call insmod for SD Card driver insertion. For example, In order to use a second SD Card on the TS-7300, the following command could be used to load the driver module prior to mount the filesystem:

insmod sdcard.o -o sdcard1 io=0x72000020 name="sdcard1"

After plugging the card into the socket and inserting the second SD Card driver, the device entry will appear at /dev/sdcard1� and the proper mount command can be used.

USB Flash Drives

USB Flash drives can supply additional storage that behaves very much like a CF card except that a Compact Flash card can be the root drive whereas a USB drive can not be the root file system without using an initrd and appropriate kernel. Drivers are available in the Linux distribution to support USB Flash Drives.

After booting into the TS-Linux OS, one can 'boot' into the Debian OS hosted on a USB thumb-drive with two scripts found on the TS-Linux distribution. First, invoke �/usr/bin/loadUSBModules.sh�, then run the script �/usr/bin/loadUSB.sh� to change root into the Debian OS on the USB thumb-drive to take full advantage of such things as the Debian Arm toolchain.

The script �loadUSBModules.sh� loads the following Kernel modules, in the right sequence: usbcore, pcipool, usb-ohci, usb-ohci-ep93xx, scsi_mod, sd_mod, usb-storage. In addition, it is possible to use an initial ram disk and a kernel that supports USB internally to boot to the USB file system on system initialization time. The kernel is loaded and then the initial ram disk script loads the USB modules and �pivot_root� to the USB file system.

For those who simply wish to load in the correct device drivers to access the USB thumbdrive when booted into the Linux OS, invoke the �/usr/bin/loadUSBModules.sh� script, and then use the following command to mount the file system:

mount /dev/scsi/host0/bus0/target0/lun0/part1 /mnt/

Note:

The TS-7200 always needs to be powered-off before swapping Compact Flash cards. USB Flash drives and SD cards can be hot swapped.

Updating the EXT2 Image

To create a CF/SD/USB flash card image from scratch, one must format the entire memory card as ext2, then unpack the file system (the Development Debian file system for NFS root or memory cards, for example). Latest versions of our pre-made Debian install can be found on our website or on the TS-ARM CD.

This should all be done from the host PC running Linux. The walk-through below assumes the memory card is plugged into the USB dongle and the memory card has been assigned to /�dev/sda�:

fdisk /dev/ide/host0/bus0/target0/lun0/disc

1. d (to delete existing partitions. Repeat for all partitions)
2. n (for new partition)
3. p (for Primary partition)
4. 1 (make the new partition primary number 1)
5. hit the enter key for the default starting cylinder
6. hit the enter key again for the default last cylinder
7. p (to print out the partition table)
8. If the first partition does not have a star in the boot field, then enter 'a' at the prompt and then '1' to make the first partition bootable.
9. To commit these changes to the disk, enter 'w' to write out the new partition table to the disk.

Now that the memory card has been partitioned, it must be formatted. The following command will format the first partition on the memory card as an ext2 file-system.

mkfs.ext2 /dev/sda1

All that is left is to mount the memory card and unpack the tar file of the Development Debian File System.

mount /dev/sda1 /mnt
tar -C /mnt -xvjf /path/to/debian-file-system.tar.bz2

The filename may change as updates are made and posted on the CD or on the website. A simple fsck will ensure file-system integrity.

fsck /dev/sda1

Note:

Compact Flash and SD Cards must use EXT2 format for file system. USB drives can use other formats, such as VFAT.

Network File System - NFS

NFS uses the Ethernet connection to mount the root file system for the SBC as an exported directory on a Linux host PC. This bypasses the need to download any files from the host to the SBC, because any file needed on the SBC is just copied to the exported directory on the host system and is instantly available to the embedded PC. Mounting the root file system via NFS allows the developer to use the editors, compilers, etc. from the single board computer.

Mounting NFS roots requires that the �portmap� daemon is running before executing the mount command. The following example demonstrates mounting an NFS file system hosted on a server at 192.168.0.1

portmap &
mount -t nfs 192.168.0.1:/path/to/nfsroot /mnt

Setting Up an NFS File System

To mount the root file system via NFS, Prepare the exported root directory on the NFS server: 1. Download the pre-made Debian tarfile from our website or the TS-ARM Linux CD to your Linux host machine. 2. Untar NFS root package to a directory on the host machine.

tar -C /path/to/nfsroot -xvjf /path/to/debian-file-system.tar.bz2

3. Export the directory by adding the following line to the file �/etc/exports�

/path/to/nfsroot 192.168.0.0/255.255.255.0
(rw,no_root_squash,insecure)

Note:

The IP mask in the above example will only allow NFS connections from computers having an IP starting with 192.168.0. Substitute the appropriate parameters for your local network.

4. Restart NFS so the directory is available for export. Typically, this would be:

/etc/init.d/nfs-server restart

5. Modify the /path/to/nfsroot/etc/fstab file on your host system for your local network settings.

Add: "192.168.0.1:/path/to/nfsroot / nfs exec,dev,suid 1 1"
Comment out: "/dev/hda1 / ext2 defaults 1 1"

6. Load the kernel from Redboot with the following command line options:

fis load vmlinux
exec �c �console=ttyAM1,115200 ip=dhcp
nfsroot=192.168.0.1:/path/to/nfsroot�

Product Notes

FCC Advisory

This equipment generates, uses, and can radiate radio frequency energy and if not installed and used properly (that is, in strict accordance with the manufacturer's instructions), may cause interference to radio and television reception. It has been type tested and found to comply with the limits for a Class A digital device in accordance with the specifications in Part 15 of FCC Rules, which are designed to provide reasonable protection against such interference when operated in a commercial environment. Operation of this equipment in a residential area is likely to cause interference, in which case the owner will be required to correct the interference at his own expense.

If this equipment does cause interference, which can be determined by turning the unit on and off, the user is encouraged to try the following measures to correct the interference:

Reorient the receiving antenna. Relocate the unit with respect to the receiver. Plug the unit into a different outlet so that the unit and receiver are on different branch circuits. Ensure that mounting screws and connector attachment screws are tightly secured. Ensure that good quality, shielded, and grounded cables are used for all data communications. If necessary, the user should consult the dealer or an experienced radio/television technician for additional suggestions. The following booklets prepared by the Federal Communications Commission (FCC) may also prove helpful:

How to Identify and Resolve Radio-TV Interference Problems (Stock No. 004-000-000345-4) Interface Handbook (Stock No. 004-000-004505-7) These booklets may be purchased from the Superintendent of Documents, U.S. Government Printing Office, Washington, DC 20402.

Limited Warranty

See our Terms and Conditions for more details.