Monterey Linux - CiteSeerX

Monterey Linux User’s Guide, DM320/DM342 Edition Release 2.1

Monterey Linux

User’s Guide DM320/DM342 Edition

Release 2.1


© 2003, 2004 Pigeon Point Systems. All rights reserved. Monterey Linux This manual is furnished under license and may be used or copied only in accordance with the terms of such license. The contents of this manual is furnished for informational use only, is subject to change without notice, and should not be construed as a commitment by Pigeon Point Systems. Pigeon Point Systems assumes no responsibility or liability for any errors or inaccuracies that may appear in this book. Except as permitted by such license, no part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, manual, recording, or otherwise, without the prior written permission of Pigeon Point Systems. Pigeon Point Systems and Monterey Linux are both trademarks of Pigeon Point Systems. Linux is a registered trademark of Linus Torvalds.


Table of Contents 1. MONTEREY LINUX OVERVIEW ..................................................................................... 1-1

1.1. Monterey Linux Features............................................................................................ 1-1 1.2. Monterey Linux Support and Contacts ....................................................................... 1-2

2. MONTEREY LINUX CROSS DEVELOPMENT PLATFORM ........................................... 2-3 2.1. Installing Monterey Linux............................................................................................ 2-3

2.1.1. Development Host System................................................................................... 2-3 2.1.2. Monterey Linux Distribution Media ....................................................................... 2-3 2.1.3. Supported Host Systems ..................................................................................... 2-4

2.1.3.1. Host System Requirements ........................................................................... 2-4 2.1.3.2. Installing to a Linux System that is Not Explicitly Supported.......................... 2-4

2.1.4. Mounting the Distribution Media........................................................................... 2-4 2.1.4.1. Mounting the CD ............................................................................................ 2-4 2.1.4.2. Mounting the ISO9660 Image ........................................................................ 2-5

2.1.5. Installation Media Layout ..................................................................................... 2-5 2.1.6. installit Utility ........................................................................................................ 2-6 2.1.7. Sample Installation............................................................................................... 2-6

2.2. Understanding the Monterey Linux Cross Development Platform .............................. 2-8 2.2.1. Cross Development Tools and Target Components ............................................ 2-8 2.2.2. Monterey Linux Installation Layout....................................................................... 2-8

2.3. Activating Monterey Linux .......................................................................................... 2-9 2.4. Using the Monterey Linux RPM Tool ........................................................................ 2-10

2.4.1. Introducing the Monterey Linux RPM Tool ......................................................... 2-10 2.4.2. Using RPM to Get Full List of RPM Packages ................................................... 2-11 2.4.3. Using RPM to Understand Which RPM a File Comes From .............................. 2-11 2.4.4. Using RPM to Display Package Information ...................................................... 2-11 2.4.5. Using RPM to Add New RPM Packages to Monterey Linux .............................. 2-12

2.5. Monterey Linux RPM Packages ............................................................................... 2-12 2.6. Using the Monterey Linux Source Image.................................................................. 2-17

2.6.1. Understanding the Monterey Linux Source Image ............................................. 2-17 2.6.2. Source Image Layout ......................................................................................... 2-17 2.6.3. Using RPM to Re-Build a Target RPM ............................................................... 2-18

2.7. Enabling Additional Linux Features .......................................................................... 2-19


2.7.1. Installing Kermit.................................................................................................. 2-19 2.7.2. Configuring TFTP............................................................................................... 2-20

2.7.2.1. Configuring TFTP on Red Hat 6.x................................................................ 2-20 2.7.2.2. Configuring TFTP on Red Hat 7.x, 8.0, 9..................................................... 2-20

2.8. Uninstalling Monterey Linux ..................................................................................... 2-21 3. DEVELOPING MONTEREY LINUX APPLICATIONS.................................................... 3-22

3.1. Development Process Overview............................................................................... 3-22 3.1.1. Monterey Linux Development Tree .................................................................... 3-22 3.1.2. Key Boot Mechanisms ....................................................................................... 3-24

3.1.2.1. Compressed Kernel ..................................................................................... 3-24 3.1.2.2. Uncompressed Kernel ................................................................................. 3-25 3.1.2.3. Compressed File System............................................................................. 3-25 3.1.2.4. Uncompressed File System ......................................................................... 3-25 3.1.2.5. NFS-Mounted File System........................................................................... 3-25

3.2. Monterey Linux Kernel Development........................................................................ 3-26 3.2.1. Monterey Linux Kernel Source Tree................................................................... 3-26 3.2.2. Configuring the Monterey Linux Kernel .............................................................. 3-26 3.2.3. Building the Monterey Linux Kernel.................................................................... 3-27 3.2.4. Kernel Images .................................................................................................... 3-29

3.3. Developing Monterey Linux User Applications ......................................................... 3-30 3.3.1. Building Simple Monterey Linux Applications..................................................... 3-30

3.3.1.1. Building Multi-Threaded Monterey Linux Applications ................................. 3-30 3.3.2. Developing C++ Applications ............................................................................. 3-30

3.3.2.1. Building C++ Applications ............................................................................ 3-31 3.4. Developing Monterey Linux File Systems................................................................. 3-31

3.4.1. Creating a Prototype File System....................................................................... 3-31 3.4.2. Generating a Root File System Image ............................................................... 3-32 3.4.3. Creating a File System Image for ARMboot ....................................................... 3-33

3.5. Multiple Embedded Applications............................................................................... 3-33 4. USING ARMBOOT FIRMWARE .................................................................................... 4-35

4.1. Introducing ARMboot................................................................................................ 4-35 4.2. Using ARMboot on the Target .................................................................................. 4-36

4.2.1. Serial Console Command Prompt...................................................................... 4-36 4.2.2. Environment Variables ....................................................................................... 4-37

4.2.2.1. Creating ARMboot Command Scripts .......................................................... 4-39 4.2.3. Downloading Images.......................................................................................... 4-40

4.2.3.1. Downloading Images over the Network ....................................................... 4-40 4.2.3.2. Downloading Images over a Serial Line....................................................... 4-42

4.2.4. Booting Linux ..................................................................................................... 4-43 4.2.5. Flash Management ............................................................................................ 4-45 4.2.6. Autoboot............................................................................................................. 4-46

4.3. Command Reference ............................................................................................... 4-47 4.3.1. go ....................................................................................................................... 4-47 4.3.2. run...................................................................................................................... 4-48


4.3.3. bootm ................................................................................................................. 4-50 4.3.4. tftpboot ............................................................................................................... 4-52 4.3.5. loads .................................................................................................................. 4-52 4.3.6. loadb .................................................................................................................. 4-53 4.3.7. md...................................................................................................................... 4-53 4.3.8. mm ..................................................................................................................... 4-54 4.3.9. mw ..................................................................................................................... 4-55 4.3.10. cp ....................................................................................................................... 4-57 4.3.11. cmp .................................................................................................................... 4-58 4.3.12. printenv .............................................................................................................. 4-58 4.3.13. setenv ................................................................................................................ 4-59 4.3.14. saveenv.............................................................................................................. 4-60 4.3.15. protect ................................................................................................................ 4-61 4.3.16. erase .................................................................................................................. 4-62 4.3.17. flinfo ................................................................................................................... 4-63 4.3.18. mtest .................................................................................................................. 4-63 4.3.19. reset ................................................................................................................... 4-64 4.3.20. version ............................................................................................................... 4-65 4.3.21. help .................................................................................................................... 4-65 4.3.22. ? ......................................................................................................................... 4-66

5. INTRODUCING THE ARM INJECTOR .......................................................................... 5-68 5.1. Intended Use ............................................................................................................ 5-68 5.2. Operational Modes ................................................................................................... 5-69 5.3. Target Hardware Interfaces...................................................................................... 5-69

5.3.1. JTAG Connector Summary ................................................................................ 5-69 5.3.2. Auxiliary I/O Connector Summary ...................................................................... 5-71

5.4. Functional Block Diagram......................................................................................... 5-72 5.5. Target I/O Interfaces................................................................................................. 5-73

5.5.1. JTAG Interface................................................................................................... 5-73 5.5.2. Serial Interface ................................................................................................... 5-73 5.5.3. Opto-Isolated Relays.......................................................................................... 5-74

5.6. ARM Injector LEDs................................................................................................... 5-75 5.7. Intended Application ................................................................................................. 5-76

5.7.1. Development Tool .............................................................................................. 5-76 5.7.2. Debug Tool......................................................................................................... 5-76 5.7.3. Testing Automation Tool .................................................................................... 5-77 5.7.4. Field Service Tool .............................................................................................. 5-77 5.7.5. Manufacturing Tool ............................................................................................ 5-77

5.8. ARM Injector Command Reference.......................................................................... 5-79 5.8.1. inj ....................................................................................................................... 5-79 5.8.2. inj info................................................................................................................. 5-80 5.8.3. inj ctl ................................................................................................................... 5-81 5.8.4. inj install ............................................................................................................. 5-82 5.8.5. inj mfg ................................................................................................................ 5-84 5.8.6. inj fwload ............................................................................................................ 5-85


5.9. Configuring the Monterey Linux Development Host for the ARM Injector................. 5-86 5.9.1. Configuring a Host System with Hot Plug Support ............................................. 5-86 5.9.2. Configuring a Host System without Hot Plug Support ........................................ 5-86 5.9.3. Accessing ARM Injector as a Regular User ....................................................... 5-87

5.10. ARM Injector Troubleshooting .................................................................................. 5-87 6. INSTALLING MONTEREY LINUX IMAGES ON THE DM320/DM342 EVM BOARD.... 6-89

6.1. Setting Up Target Hardware..................................................................................... 6-89 6.1.1. DM320/DM342 EVM Board Jumpers ................................................................. 6-89 6.1.2. Serial Interface ................................................................................................... 6-90 6.1.3. Ethernet Interface............................................................................................... 6-90 6.1.4. JTAG Interface................................................................................................... 6-90

6.1.4.1. Connecting the Target JTAG Port to the ARM Injector ................................ 6-90 6.1.4.2. Connecting the Target JTAG Port to TI's Emulator Tools ............................ 6-91

6.2. Setting Up the Development Hosts........................................................................... 6-91 6.2.1. Monterey Linux Development Host .................................................................... 6-91 6.2.2. Windows Host .................................................................................................... 6-92

6.3. Installing Monterey Linux Using the ARM Injector .................................................... 6-92 6.3.1. ARM Injector Set Up Summary .......................................................................... 6-92 6.3.2. ARM Injector Installation Procedure Overview................................................... 6-93 6.3.3. Installing ARMboot Using the ARM Injector ....................................................... 6-93

6.3.3.1. Using the ARM Injector to Program u-boot.bin to Flash............................... 6-93 6.4. Installing Monterey Linux Using Texas Instruments Emulator Tools ........................ 6-95

6.4.1. TI's Tools Set Up Summary ............................................................................... 6-95 6.4.2. TI's Tools Installation Procedure Overview ........................................................ 6-95 6.4.3. Installing ARMboot Using TI's Tools................................................................... 6-96

6.4.3.1. Loading u-boot.elf to the Target Using Code Composer Studio................... 6-96 6.4.3.2. Using ARMboot to Download and Program u-boot.bin to Flash................. 6-101

6.5. Installing Monterey Linux Images ........................................................................... 6-102 7. DEBUGGING WITH MONTEREY LINUX..................................................................... 7-103

7.1. Debugging with Monterey Linux Overview ............................................................. 7-103 7.1.1. GDB Debugger................................................................................................. 7-103 7.1.2. GDB GUI.......................................................................................................... 7-107 7.1.3. Cross Debug Environment ............................................................................... 7-108

7.1.3.1. Introduction to the GDB Remote Protocol .................................................. 7-110 7.1.4. Intrusive vs. Non-Intrusive Debugging ............................................................. 7-110 7.1.5. Building for Debugging..................................................................................... 7-111 7.1.6. GDB Binary Files.............................................................................................. 7-113

7.2. Debugging with Monterey Linux Cross GDB .......................................................... 7-113 7.2.1. Debugging the Kernel ...................................................................................... 7-113

7.2.1.1. Debugging a Statically Linked Kernel and Drivers ..................................... 7-113 7.2.1.2. Debugging Kernel Modules........................................................................ 7-117

7.2.2. Debugging User Applications ........................................................................... 7-118 7.2.2.1. Debugging Simple Applications ................................................................. 7-118 7.2.2.2. Debugging Multi-Threaded Applications .................................................... 7-118


7.2.2.3. Debugging C++ Applications...................................................................... 7-121 7.2.2.4. Debugging Several Applications Simultaneously ....................................... 7-122 7.2.2.5. Debugging Applications and Kernel Simultaneously.................................. 7-123

7.2.3. Cross Debugging Communication Channels ................................................... 7-123 7.2.3.1. Using a Serial Port for Debugging.............................................................. 7-123 7.2.3.2. Using a TCP/IP Connection for Debugging................................................ 7-126 7.2.3.3. Using the ARM Injector for Debugging....................................................... 7-127

7.2.4. Additional Debugger Features.......................................................................... 7-130 7.2.4.1. Executing Remote Commands .................................................................. 7-130 7.2.4.2. Attaching to a Running Process................................................................. 7-130 7.2.4.3. Native Kernel Debugging ........................................................................... 7-131

8. DSP SUPPORT ............................................................................................................ 8-135 8.1. Inter-Core Communication Mechanisms ................................................................ 8-135

8.1.1. Shared RAM..................................................................................................... 8-135 8.1.2. DSP Boot Sequence ........................................................................................ 8-136 8.1.3. Control of DSP from ARM ................................................................................ 8-136 8.1.4. Interrupt Signals ............................................................................................... 8-136

8.2. DSP Manager ......................................................................................................... 8-137 8.2.1. DSP Control Interface ...................................................................................... 8-137

8.2.1.1. DSP Control Kernel Interface..................................................................... 8-137 8.2.1.2. DSP Control User Space Interface ............................................................ 8-139

8.3. DSP API ................................................................................................................. 8-139 8.3.1. Monterey Linux Kernel DSP API ...................................................................... 8-140 8.3.2. DSP Assembly API .......................................................................................... 8-141 8.3.3. DSP C API ....................................................................................................... 8-141 8.3.4. Sample Use of the DSP API ............................................................................ 8-142

8.4. GNU Toolchain Targeting the C54x DSP Core ...................................................... 8-143 8.4.1. GNU Binutils for the DSP ................................................................................. 8-143 8.4.2. Sample Use of the GNU binutils....................................................................... 8-144

9. MONTEREY LINUX SAMPLE PROJECTS.................................................................. 9-145 9.1. Sample Projects Overview ..................................................................................... 9-145

9.1.1. What is a Monterey Linux Sample Project? ..................................................... 9-145 9.1.2. Sample Projects Summary............................................................................... 9-146 9.1.3. A Sample Project's Directory Layout ................................................................ 9-146 9.1.4. Building a Sample Project ................................................................................ 9-147 9.1.5. A Sample Project's Target Images................................................................... 9-148

9.2. Sample Project Reference...................................................................................... 9-148 9.2.1. telnet Sample Project ....................................................................................... 9-148 9.2.2. ftp Sample Project............................................................................................ 9-152 9.2.3. tinylogin Sample Project................................................................................... 9-157 9.2.4. nfsroot Sample Project..................................................................................... 9-162 9.2.5. boa Sample Project.......................................................................................... 9-168 9.2.6. ssh Sample Project .......................................................................................... 9-171 9.2.7. dsp Sample Project .......................................................................................... 9-176


10. MONTEREY LINUX ADVANCED FEATURES ...........................................................10-181 10.1. Real-Time Patches ................................................................................................10-181

10.1.1. Preemption and Low-Latency Patches: What is it? .........................................10-181 10.1.1.1. Preemption Patch .....................................................................................10-181 10.1.1.2. Low-Latency Patch ...................................................................................10-182

10.1.2. Configuring the Real-Time Patches ................................................................10-183 10.1.2.1. Configuring the Preemption Patch ............................................................10-183 10.1.2.2. Configuring the Low-Latency Patch ..........................................................10-183

10.1.3. realfeel Sample Project ...................................................................................10-183 10.1.4. Analyzing the Real-Time Patches ...................................................................10-189

10.1.4.1. Both Patches Disabled..............................................................................10-190 10.1.4.2. Preemption Patch Enabled .......................................................................10-191 10.1.4.3. Both Patches Enabled ..............................................................................10-192

10.2. Frame Buffer .........................................................................................................10-192 10.2.1. Monterey Linux Frame Buffer Driver Overview ...............................................10-192 10.2.2. Double Buffering .............................................................................................10-193 10.2.3. Configuring the Frame Buffer ..........................................................................10-194 10.2.4. Connecting TV ................................................................................................10-194 10.2.5. framebuffer Sample Project ............................................................................10-194

10.3. DirectFB GUI Framework and Interface ................................................................10-197 10.3.1. DirectFB Overview ..........................................................................................10-197 10.3.2. Serial Mouse Support......................................................................................10-198 10.3.3. Using DirectFB in Your Applications ..............................................................10-198 10.3.4. directfb Sample Project ...................................................................................10-198

Monterey Linux User’s Guide, DM320/DM342 Edition Release 2.1 Chapter 1 - 1

1. Monterey Linux Overview Welcome to Monterey Linux!

Monterey Linux is a professionally packaged Linux distribution designed for DM320/DM342 processor embedded systems development. Monterey Linux focuses on the goal of providing the necessary tools and infrastructure needed by software engineers to develop robust Linux-based products. This includes tools needed to support the full cycle of development, including bring-up (JTAG emulation), firmware development (ARMboot) as well as kernel and application development.

1.1. Monterey Linux Features

The key features of Monterey Linux include:

• Cross Development Environment. The key organizing principle of Monterey Linux is that it is a cross development toolkit (it runs on a Linux x86 host system and generates code for the DM320/DM342 target processor). The toolkit is packaged as a collection of RPM images that install on the development host using a specially modified RPM toolset. This allows Monterey Linux to be installed into its own local directory with its own private RPM database. Monterey Linux can be conveniently managed, updated and extended using familiar RPM commands. The entire Monterey Linux installation (compilers, tools, kernel source, applications, sample projects, and so on) install under a single directory, allowing multiple installations to reside on a single shared machine (within user private directories, for instance).

• ARMboot (U-boot) support. Monterey Linux provides the software and tools needed to get boot loader firmware up and running on your target board. Monterey Linux includes enhanced ARMboot (U-boot) firmware, including full source, to facilitate the development of monitor code for target hardware. In addition, Monterey Linux provides JTAG emulation tools and GDB

Chapter

1


support for loading firmware into target RAM and Flash, as well as low-level JTAG assisted debugging.

• ARM Injector. Monterey Linux can be used with the PPS ARM Injector USB JTAG emulator and development tool1. This device allows the developer to control the target hardware from a single USB connection on the host. JTAG emulation, serial port redirect, board reset, and 4 optoisolated relays for jumper or switch control are provided. GDB support over the ARM Injector device is included, as well as standalone operation via a powered JTAG connection for manufacturing-time in-system software injection to Flash.

• Project based development. Monterey Linux includes tools that facilitate the creation and management of your Linux project. Makefile based projects completely specify and automate the building of both the kernel component and the associated file system image (both of which are loaded to the target board). Sample projects are included to provide quick-start product development. Multiple separate projects can be maintained within a single Monterey Linux installation. Projects can be shared between development teams.

• Flexible Environment. Developers are not locked into a development scheme. Users are free to use the Monterey Linux cross development tools within a different context familiar to the developer. Monterey Linux does things “the Linux way”, so it is a flexible and extendable environment.

• Up-to-date kernel source and driver support. Monterey Linux is based on a recent Linux 2.4 kernel. Source code for all kernel and developed drivers is included in the distribution.

• Special support for the DM320/DM342 processor. Monterey Linux is focused on supporting the ARM9 CPU core and the DM320/DM342 processor in particular. This includes DM320/DM342-optimized code and drivers for the on-chip integrated devices.

1.2. Monterey Linux Support and Contacts

Support questions can be emailed to [email protected], or you can visit our website www.montereylinux.com.

1 ARM Injector is not included in Monterey Linux but can be purchased separately from Pigeon Point Systems.

mailto:[email protected]

http://www.montereylinux.com/


2. Monterey Linux Cross Development Platform This chapter describes the Monterey Linux distribution media and installation procedure. Layout of the Monterey Linux cross development platform is detailed and explained.

2.1. Installing Monterey Linux

The following sections describe how to install the Monterey Linux distribution onto a host development machine.

2.1.1. Development Host System

Monterey Linux is a cross development platform. Among other things, it means that the Monterey Linux distribution is installed onto a development machine setup with the requirements described in section 2.1.3.

2.1.2. Monterey Linux Distribution Media

Monterey Linux is distributed in the form of an ISO image, which can be either burned onto a CD or mounted directly in the Linux file system, using the loopback Linux device driver. The ISO image contains an installation utility and a number of RPM packages, which are installed onto a hard disk of the cross development host.

Chapter

2


2.1.3. Supported Host Systems

Monterey Linux supports the following Linux x86 host environments:

Red Hat Linux 6.1, 6.2, 7.1, 7.2, 7.3, 8.0, 9

SuSE Linux 7.2, 7.3

2.1.3.1. Host System Requirements The development host must meet the requirements below before attempting installation of Monterey Linux:

510 Mbytes of free disk space.

CD-ROM drive, if you install from CD.

Support for loopback device configured in the Linux kernel, if you install from the ISO9660 file image mounted as a loopback device.

Standard set of Linux utilities (such as bash, make, rm, cp, etc.) and libraries (such as libc, libncurses, libX11, etc.). These utilities are included in default installations of Red Hat Linux and SuSE Linux.

2.1.3.2. Installing to a Linux System that is Not Explicitly Supported It may be possible to install and run Monterey Linux on a host system not explicitly listed in section 2.1.3. One caution is that different Linux environments have their own peculiarities, so if you install to a Linux system Monterey Linux does not explicitly support and test with, there is a possibility that specific features of Monterey Linux will not work as expected. Non-supported host operating systems should be used at your own risk.

2.1.4. Mounting the Distribution Media

2.1.4.1. Mounting the CD To mount the Monterey Linux CD on the Linux development host, insert the CD into the CD-ROM drive and run the following command as super user:

# mount –r /dev/cdrom /mnt/cdrom

Please note that some Linux desktop environments such as Red Hat Linux GNOME may auto mount the CD. You have to make sure that the CD is mounted with the options exec and suid to permit execution of binaries from the CD, and allow the set-


user-identifier bit to take effect, respectively. For instance, on a Red Hat Linux host, login as super user and modify /etc/fstab to contain the following line:

/dev/cdrom /mnt/cdrom iso9660 -noauto,user,ro,exec,suid 0 0

Alternatively, simply disable the auto mount feature and mount the CD manually.

2.1.4.2. Mounting the ISO9660 Image To mount the Monterey Linux ISO9660 image on the Linux development host as a loopback device, run the following command as super user:

# mount –o loop <iso_image> /mnt/cdrom

Note that if you install Monterey Linux from the ISO9660 soft image, you must have support for loopback devices configured in the Linux kernel. The corresponding option, Loopback device support, is located in the Block devices submenu when configuring the kernel.

2.1.5. Installation Media Layout

When mounted, the Monterey Linux installation image has the following directory layout:

cdrom.tag installit

bin/rpm

usr/

rpm.list

ACTIVATE.sh

installit.tools/

RPMS/

RPMS/

arm926ejs/

rpm/

/mnt/cdrom

/mnt/cdrom Distribution image mount point.

cdrom.tag ASCII file that contains the release information data (Product, Release, Build).

installit The installation utility used to install Monterey Linux from the distribution image to the host machine.

installit.tools/ Directory that contains the tools required by installit to perform the installation. Essentially, this is the Monterey Linux RPM tool, a list of RPM packages to install, and some auxiliary files.


bin/rpm The Monterey Linux RPM binary, prebuilt for the host machine environment.

usr/ Auxiliary RPM files and tools. rpm.list List of the RPMs installed by the RPM tool from the

distribution image (order is important!). ACTIVATE.sh The shell script used to activate the Monterey Linux

Cross Development Environment (CDE) on the host machine. installit copies ACTIVATE.sh to the top of the installation directory.

rpm/ Directory that contains all the Monterey Linux RPM packages.

RPMS/ Binary RPMs of the Monterey Linux cross development tools.

arm926ejs/ Directory that contains binary RPMs prebuilt for the ARM9 processor core.

RPMS/ Binary RPMs of the Monterey Linux target components.

2.1.6. installit Utility

Installation of Monterey Linux is performed under control of the installit utility residing at the top of the Monterey Linux distribution media.

Please note that you do not have to be super user (root) to install Monterey Linux. A regular Linux user can install Monterey Linux as long as the user has write permission on the specified installation directory.

installit has the following syntax::

SYNOPSIS installit [-d <dstdir>] [<target>]

PARAMETERS

-d <dstdir> Specifies the destination directory Monterey Linux installs to. If omitted, installs into the current directory.

<target> Specifies the target, such as arm926ejs.

2.1.7. Sample Installation

The following sample output illustrates a typical Monterey Linux installation on the host system:


[tester@host1]$ mkdir ML [tester@host1]$ cd ML [tester@host1 ML]$ /mnt/cdrom/installit Installing to /home/tester/ML Installing the cross rpm tool Initializing rpm database Installing the cross development tools Preparing... ########################################### [100%] 1:popt ########################################### [100%] Preparing... ########################################### [100%] 1:rpm ########################################### [100%] Preparing... ########################################### [100%] 1:rpm-build ########################################### [100%] Preparing... ########################################### [100%] 1:binutils ########################################### [100%] Preparing... ########################################### [100%] 1:cpp ########################################### [100%] Preparing... ########################################### [100%] 1:gcc ########################################### [100%] Preparing... ########################################### [100%] 1:gcc-c++ ########################################### [100%] Preparing... ########################################### [100%] 1:mkimage ########################################### [100%] Preparing... ########################################### [100%] 1:gdb ########################################### [100%] Preparing... ########################################### [100%] 1:genext2fs ########################################### [100%] Preparing... ########################################### [100%] 1:make ########################################### [100%] Preparing... ########################################### [100%] 1:genromfs ########################################### [100%] Preparing... ########################################### [100%] . . . Installation successful To activate Monterey Linux, run . ACTIVATE.sh <target> [tester@host1 ML]$


2.2. Understanding the Monterey Linux Cross Development Platform

2.2.1. Cross Development Tools and Target Components

The Monterey Linux installation can be logically divided into two parts:

Cross Development Tools. These tools are run on the development host and are used to compile and prepare kernel code, drivers and applications to run on the target hardware.

Target Components. These are target tools, libraries, and other components that will be executed or used on the target system. Monterey Linux provides prebuilt and tested versions of these components for inclusion in the target system download images. These components have been built and optimized for the specific target architecture (ARM9 CPU core).

Cross development tools are located under the $CDE_ROOT installation directory. All Target Components are located under the $CDE_ROOT/arm926ejs directory.

2.2.2. Monterey Linux Installation Layout

Monterey Linux provides the following directory structure under the $CDE_ROOT installation:

bin/

bin/

arm-linux/

doc/

usr/ var/ lib/

include/

linux-2.4.19/

linux/

busybox/

u-boot/

sample/

src/

lib/

man/

doc/

bin/

sbin/

usr/ lib/

bin/

boot/

etc/

httpd/

home/

sbin/

arm926ejs/ ACTIVATE.shetc/ dev/

bin Cross development tools


usr/bin More cross development tools

usr/arm-linux GNU toolchain targeting DM320/DM342

usr/doc Documentation files var Used by cross development tools etc Used by cross development tools dev Auxiliary links to Injector device files lib Used by cross development tools arm926ejs Top of target directory arm926ejs/usr/include Target include files arm926ejs/usr/src/linux-2.4.19 Monterey Linux kernel

arm926ejs/usr/src/linux Convenient soft link to the kernel directory

arm926ejs/usr/src/busybox Full source for busybox tools arm926ejs/usr/src/u-boot Full source for ARMboot (U-boot) arm926ejs/usr/src/sample Monterey Linux sample projects arm926ejs/usr/lib Target libraries arm926ejs/usr/bin Target /usr/bin utilities arm926ejs/usr/sbin Target /usr/sbin utilities arm926ejs/lib Target libraries arm926ejs/bin Target /bin utilities arm926ejs/sbin Target /sbin utilities

arm926ejs/boot Binary ARMboot (U-boot) image directory

arm926ejs/etc Target /etc directory

2.3. Activating Monterey Linux

Each time you begin a working session with Monterey Linux, you need to set up the proper environment. To accomplish this, a shell script, ACTIVATE.sh has been provided at the top of the installation. This shell script must be “sourced” into your current shell environment (that is, you cannot run this script directly, but, instead, use the “.” or source command, as in . ACTIVATE.sh <target> or source ACTIVATE.sh <target>.


Sample activation is as follows:

[tester@host1]$ . ACTIVATE.sh arm926ejs ML(arm926ejs):[tester@host1]$

ACTIVATE.sh is a regular shell script that creates and modifies a few of the existing environment variables needed for Monterey Linux to properly run. Specifically, the following environment variables are affected:

Environment Variable

Value

PATH $CDE_ROOT/usr/arm-linux/bin: $CDE_ROOT/usr/bin:$CDE_ROOT/bin:$PATH

PS1 ML(arm926ejs):$PS1

CDE_ROOT `pwd` (== top of Monterey Linux installation)

TARGET_ROOT $CDE_ROOT/arm926ejs

CROSS_COMPILE arm926ejs -

MANPATH $CDE_ROOT/usr/share/man: $CDE_ROOT/usr/man: $CDE_ROOT/arm926ejs/usr/share/man: $CDE_ROOT/arm926ejs/usr/man:$MANPATH

Table 1: Environment Variables

ACTIVATE.sh makes sure that the proper $PATH is set up so that calls to the GNU development tools result in invocation of the Monterey Linux cross development tools (vs. Linux host native tools). CDE_ROOT and TARGET_ROOT can be used as convenient shortcuts, but also are important for the cross development tools to function properly. Do not change these variables while running Monterey Linux.

2.4. Using the Monterey Linux RPM Tool

2.4.1. Introducing the Monterey Linux RPM Tool

The Monterey Linux specific RPM functionality consists of a modified RPM utility ($CDE_ROOT/bin/rpm) and a local RPM database ($CDE_ROOT/var/lib/rpm). The Monterey Linux RPM tool has been modified to work from within the $CDE_ROOT directory – that is, it views $CDE_ROOT as its root file system and manages and installs RPMs only within this installation directory. It knows and cares nothing about the host system RPM database.

This allows developers already familiar with the RPM toolset to use this capability within Monterey Linux. Not only can users perform RPM package management functions such as listing installed packages and files within installed packages, but they


can also extend and update the collection of target packages that are installed and available under Monterey Linux. This can be very useful when porting RPM packaged code into the Monterey Linux environment.

2.4.2. Using RPM to Get Full List of RPM Packages

To get a full list of installed RPM packages, use the following command:

ML(arm926ejs):[tester@host1]$ rpm -qa rpm-4.0.4-7x.17 binutils-2.11.94-1 gcc-3.2-1 mkimage-0.2.1-1 genext2fs-1.3-2 genromfs-0.5.1-1 binutils_dsp-2.11.94-1 kernel-headers-arm926ejs-2.4.19-1 kernel-arm926ejs-2.4.19-1 glibc-arm926ejs-2.3.1-38 glibc-profile-arm926ejs-2.3.1-38 glibc-utils-arm926ejs-2.3.1-38 ...

2.4.3. Using RPM to Understand Which RPM a File Comes From

To find out which RPM package contains a file, use the following command:

ML(arm926ejs):[tester@host1]$ rpm -qf arm926ejs/sbin/hwclock hwclock-arm926ejs-2.4c-1

2.4.4. Using RPM to Display Package Information

To display package information, including name, version, and description, use the following command:

ML(arm926ejs):[tester@host1]$ rpm -qi hwclock-arm926ejs Name : hwclock-arm926ejs Relocations: (not relocateable) Version : 2.4c Vendor: (none) Release : 1 Build Date: Tue 23 Mar 2004 11:04:34 PM GMT Install date: Tue 23 Mar 2004 11:04:35 PM GMT Build Host: ml Group : System Environment/Base Source RPM: hwclock-2.4c-1.src.rpm Size : 57605 License: GPL Summary : The hwclock utility. Description : This package contains hwclock utility. Hwclock is a tool for accessing the Hardware Clock.You can display the current time, set the Hardware Clock to a specified time, set the Hardware Clock to the System Time, and set the System Time from the Hardware Clock.


2.4.5. Using RPM to Add New RPM Packages to Monterey Linux

The example below shows how to incorporate and build an RPM package into the Monterey Linux distribution. Depending on a particular package, adding packages to the Monterey Linux distribution may require porting the code to run in the DM320/DM342 target environment. For this demonstration, we picked an RPM package (dos2unix) that doesn’t need any source code modification to compile/link correctly for operation on the DM320/DM342 CPU.

The goal of this example is to include the utility dos2unix into the collection of prebuilt target components under Monterey Linux.

The first step is to obtain and install the dos2unix RPM source package from the Red Hat distribution:

ML(arm926ejs):[tester@host1]$ rpm –iv dos2unix*.src.rpm

The Monterey Linux rpm tool will install the RPM source spec file and tar image to the directory: $CDE_ROOT/usr/src/ml/SPECS and $CDE_ROOT/usr/src/ml/SOURCES.

ML(arm926ejs):[tester@host1]: cd $CDE_ROOT/usr/src/ml/SPECS ML(arm926ejs):[tester@host1]: rpm –bs dos2unix*.spec ML(arm926ejs):[tester@host1]: rpm –iv $CDE_ROOT/usr/src/ml/SRPMS/dos2unix*.rpm ML(arm926ejs):[tester@host1]: rpm –bb dos2unix*.spec ML(arm926ejs):[tester@host1]: rpm –iv $CDE_ROOT/usr/src/ml/RPMS/arm/dos2unix*.rpm ML(arm926ejs):[tester@host1]: rpm –q –l dos2unix-arm926ejs /home/tester/ML/arm926ejs/usr/bin/dos2unix /home/tester/ML/arm926ejs/usr/doc/dos2unix-3.1 /home/tester/ML/arm926ejs/usr/doc/dos2unix-3.1/COPYRIGHT /home/tester/ML/arm926ejs/usr/share/man/man1/dos2unix.1.gz

The utility dos2unix is now available as a target component that can be included in a target file system image (described in a later chapter).

2.5. Monterey Linux RPM Packages

The Monterey Linux installation contains the following RPM packages:

RPM Description Host/Target

bind-arm926ejs A DNS (Domain Name System) server

Target

bind-devel-arm926ejs

Include files and libraries for bind DNS development

Target



bind-utils-arm926ejs Utilities for querying DNS name servers

Target

binutils A GNU collection of binary utilities

Host

binutils_dsp A GNU collection of binary utilities

Host

boa-arm926ejs A single-tasking high performance http server

Target

busybox-arm926ejs The BusyBox utilities Target cpp GNU Compiler Collection -

The C Preprocessor Host

cron-arm926ejs The cron daemon Target dhcp-arm926ejs A DHCP (Dynamic Host

Configuration Protocol) server and relay agent.

Target

dhclient-arm926ejs Development headers and libraries for interfacing to the DHCP server

Target

directfb-arm926ejs Hardware graphics acceleration library

Target

directfb-devel-arm926ejs Header files for compiling DirectFB applications

Target

dspctl-arm926ejs Monterey Linux DSP control utility

Target

fprog-arm926ejs fprog is a Flash programming application for use with the ARM Injector

Target

freetype-arm926ejs A free and portable TrueType font rendering engine

Target

freetype-devel-arm926ejs Header files for the freetype library

Target

ftp-arm926ejs The standard UNIX FTP (File Transfer Protocol) client

Target

gcc GNU Compiler Collection - Core package including C compiler

Host



gcc-c++ C++ support for the GNU Compiler Collection

Host

gdb A GNU source-level debugger for C, C++ and Fortran

Host

gdbserver-arm926ejs A GNU source-level debugger for C, C++ and Fortran

Target

genext2fs The genext2fs utility Host genromfs The utility for building a

ROMFS file system image Host

glibc-arm926ejs The GNU libc libraries Target glibc-common-arm926ejs Common binaries and locale

data for glibc Target

glibc-debug-arm926ejs Static standard C libraries with debugging information

Target

glibc-devel-arm926ejs Header and object files for development using standard C libraries

Target

glibc-profile-arm926ejs The GNU libc libraries, including support for gprof profiling

Target

glibc-utils-arm926ejs Development utilities from GNU C library

Target

gtermcap-arm926ejs A basic system library for accessing the termcap database

Target

hwclock-arm926ejs The hwclock utility Target inetd-arm926ejs The Internet Superserver Target injector_tools ARM Injector tools collection Host kernel-arm926ejs The Linux kernel (the core of

the Linux operating system) Target

kernel-headers-arm926ejs Header files for the Linux kernel

Target

kernel-source-arm926ejs The source code for the Linux kernel.

Target

libjpeg-arm926ejs A library for manipulating JPEG image format files

Target



libjpeg-devel-arm926ejs Development tools for programs which will use the libjpeg library

Target

libpng-arm926ejs A library for manipulating PNG image format files

Target

libpng-devel-arm926ejs Development tools for programs to manipulate PNG image format files

Target

libstdc++-arm926ejs GNU Compiler Collection - Core package including C compiler

Target

make A GNU tool which simplifies the build process for users

Host

mkimage ARMboot (U-boot) mkimage utility

Host

mtd_utils-arm926ejs The MTD utilities Target openssh-arm926ejs The OpenSSH

implementation of SSH Target

openssh-clients-arm926ejs The OpenSSH clients Target openssh-server-arm926ejs The OpenSSH server daemon Target openssl-arm926ejs The OpenSSL toolkit Target openssl-devel-arm926ejs Files for development of

applications which will use OpenSSL

Target

pkgconfig A tool for determining compilation options

Host

popt A C library for parsing command line parameters

Host

rpm The RPM package management system

Host

rpm-build Scripts and executable programs used to build packages

Host

rsh-arm926ejs Clients for remote access commands (rsh, rlogin, rcp)

Target



rsh-server-arm926ejs Servers for remote access commands (rshd, rlogind, rcpd)

Target

sample-arm926ejs The Monterey Linux sample target configurations

Target

sash-arm926ejs A shell, including some built-in basic commands

Target

strace-arm926ejs Tracks and displays system calls associated with a running process

Target

tcp_wrappers-arm926ejs A security tool which acts as a wrapper for TCP daemons

Target

telnet-arm926ejs The client program for the telnet remote login protocol

Target

telnetd-arm926ejs The server program for the telnet remote login protocol

Target

tinylogin-arm926ejs A tiny utility suite for login and password handling

Target

u-boot-arm926ejs ARMboot (U-boot) is a firmware suite for ARM based platforms

Target

ucdsnmp-arm926ejs A collection of SNMP protocol tools

Target

wu-ftpd-arm926ejs An FTP daemon originally developed by Washington University

Target

zlib-arm926ejs The zlib compression and decompression library

Target

zlib-devel-arm926ejs Header files and libraries for Zlib development

Target

Table 2: RPM Packages


2.6. Using the Monterey Linux Source Image

2.6.1. Understanding the Monterey Linux Source Image

Monterey Linux includes a source code installation image. This image is similar to the installation image in that it can be either burned onto a CD or mounted directly in the Linux file system, using the loopback Linux device driver. Refer to 2.1 for detailed information on how to mount an ISO image.

The source ISO image contains a full collection of source RPMs for all GPL-licensed RPM packages available in the Monterey Linux distribution. These can be used to build any of the target RPMs in the Monterey Linux development environment.

The source release is provided for situations where the user wants to make an enhancement to a target Linux tool or a library. In most cases this will not be required, but support for this activity is provided by Monterey Linux should the need arise.

2.6.2. Source Image Layout

When mounted, the Monterey Linux source ISO image has the following directory layout:

SRPMS/

SRPMS/

rpm/

/mnt/cdrom

arm926ejs/

/mnt/cdrom Source image mount point.

rpm/ Directory that contains all the Monterey Linux RPM packages that are distributed under the GPL license.

SRPMS/ Source RPMs of the Monterey Linux cross development tools.

arm926ejs/ Directory that contains source RPMs of the Monterey Linux target components.

/SRPMS Source RPMs of the Monterey Linux target components.


2.6.3. Using RPM to Re-Build a Target RPM

The example below shows how to install the hwclock RPM from the source image and rebuild it in the Monterey Linux environment. This provides a general outline that can be followed for any of the source RPMs.

Assuming you have mounted the source ISO image at /mnt, the following command will install the RPM source spec file and tar ball images to the directories: $CDE_ROOT/usr/src/ml/SPEC and $CDE_ROOT/usr/src/ml/SOURCES:

ML(arm926ejs):[tester@host1]$ rpm -i /mnt/cdrom/rpm/arm926ejs/SRPMS/\ hwclock-2.4c-1.src.rpm

The next step is to unpack the tar ball and apply any necessary patches:

ML(arm926ejs):[tester@host1]$ rpm -bp usr/src/ml/SPECS/hwclock.spec Executing(%prep): /bin/sh -e /home/tester/ML/var/tmp/rpm-tmp.16956 + umask 022 + cd /home/tester/ML/usr/src/ml/BUILD + cd /home/tester/ML/usr/src/ml/BUILD + rm -rf hwclock + /bin/gzip -dc /home/tester/ML/usr/src/ml/SOURCES/hwclock.tar.gz + tar -xf - + STATUS=0 + [ 0 -ne 0 ] + cd hwclock + exit 0

The step above installs the source and build environment of the hwclock utility in the directory $CDE_ROOT/usr/src/ml/BUILD/hwclock. The sources in this directory can be modified if required.

As a final step, you need to build the updated sources:

ML(arm926ejs):[tester@host1]$ rpm -bc --short-circuit usr/src/ml/SPECS/hwclock.spec Executing(%build): /bin/sh -e /home/tester/ML/var/tmp/rpm-tmp.44214 + umask 022 + cd /home/tester/ML/usr/src/ml/BUILD + cd hwclock + make for i in src ; do make -C $i all || exit ; done make[1]: Entering directory `/home/tester/ML/usr/src/ml/BUILD/hwclock/src' cc -DHAVE_locale_h -DHAVE_nanosleep -c -o hwclock.o hwclock.c cc -DHAVE_locale_h -DHAVE_nanosleep -c -o shhopt.o shhopt.c cc -DHAVE_locale_h -DHAVE_nanosleep -c cmos.c -o cmos.o cc -DHAVE_locale_h -DHAVE_nanosleep -c -o rtc.o rtc.c cc -DHAVE_locale_h -DHAVE_nanosleep -c -o kd.o kd.c cc hwclock.o shhopt.o cmos.o rtc.o kd.o -o hwclock make[1]: Leaving directory `/home/tester/ML/usr/src/ml/BUILD/hwclock/src' + exit 0

A successful build results in an updated hwclock binary created in the build directory: $CDE_ROOT/usr/src/ml/BUILD. This binary can be copied to the Monterey Linux target directory for later inclusion in a root file system image ($CDE_ROOT/arm926ejs/sbin) or it can be copied to the target machine and executed.


2.7. Enabling Additional Linux Features

As detailed in later chapters, the Monterey Linux cross development platform assumes some connectivity to the target. Specifically, the following section describes the minimal connections needed between the Linux development host and the target:

Serial terminal application to monitor and control the target system console

Ethernet link for TFTP downloads to the target.

Theoretically speaking, these connections do not need to be made from the same Linux host that runs the Monterey Linux development environment. Any machine in the LAN would do for these purposes. It is, however, much more convenient to use a single Linux machine both as the Monterey Linux development host and as a provider of necessary connections to the target.

If you already have the TFTP host and serial terminal functions set up on your Linux host, just skip this section.

2.7.1. Installing Kermit

kermit is one of most popular serial terminal applications used in Linux and Unix. If this utility is not already installed on the Linux host, it can easily be located and installed from the Internet.

Here is an example of installing the kermit program on the Monterey Linux host machine:

1. Go to http://www.columbia.edu/kermit.

2. Follow the C-Kermit 8.0.209 for Unix and VMS link.

3. At the C-Kermit page, follow the Binaries link.

4. At the C-Kermit Binaries page, select a binary appropriate for your Linux host system (there are binaries available for all flavors of Linux supported by Monterey Linux), download it, and install it as a kermit executable onto your Linux host (for instance, you may install it to the /usr/bin directory).

Note: If your Web browser is set up to automatically unpack archived files, click the Stop button immediately after you have started downloading of a C-Kermit binary, and use the File->Save As button to download the binary file.


2.7.2. Configuring TFTP

The following section explains how to configure the TFTP service on a Red Hat Linux host. Installing on other supported Linux distributions might vary slightly.

2.7.2.1. Configuring TFTP on Red Hat 6.x To configure TFTP on Red Hat 6.x, do the following:

1. Add (or uncomment) the following line in the /etc/inetd.conf file as a single string:

tftp dgram udp wait root /usr/sbin/tcpd in.tftpd /tftpboot

2. Create the /tftpboot directory:

mkdir /tftpboot

3. Use the following command to have inetd reread its configuration file:

killall -HUP inetd

2.7.2.2. Configuring TFTP on Red Hat 7.x, 8.0, 9 To configure TFTP on Red Hat 7.x, 8.0, 9, do the following:

1. Create or edit the tftp file located in the /etc/xinetd.d/ directory. For instance, the following is a typical tftp file that results from installation of the TFTP package on a Red Hat 7.x host:

service tftp { socket_type = dgram protocol = udp wait = yes user = root server = /usr/sbin/in.tftpd server_args = -s /tftpboot disable = yes }


2. Set the following parameters for the disable and server_args fields:

no in the disable field

/tftpboot in the server_args field

3. Create the /tftpboot directory:

mkdir /tftpboot

4. Use the following command to have xinetd reread its configuration file:

/etc/rc.d/init.d/xinetd restart

2.8. Uninstalling Monterey Linux

To remove an entire installation of Monterey Linux from the host machine, go to the directory where your Monterey Linux installation resides and remove the entire tree.

ML(arm926ejs):[tester@host1]$ cd $CDE_ROOT ML(arm926ejs):[tester@host1]$ rm -rf *

Note that the last command just removes silently the entire Monterey Linux tree and its contents, so make sure that you do not need any files you might have created or updated within the Monterey Linux directory and most of all that you are removing the correct directory before you issue the rm -rf command.


3. Developing Monterey Linux Applications This chapter explains how to develop Monterey Linux kernels and applications.

A goal of Monterey Linux is not to get in the way of developers who are already familiar with the process of configuring and building Linux kernels and developing application code. What is presented is a well organized, tested and enhanced collection of development tools and source code all in the standard Linux format.

Monterey Linux does provide a higher level organization mechanism (“sample projects”) that combines the files needed to build kernels and applications into a single development directory. Once the concepts presented in this chapter are understood, the user can refer to Chapter 9 to learn about the sample projects and see how the steps presented below can all be accomplished with a collection of specification files and a top level Makefile. The use of the sample projects is an optional step – developers can chose to work directly with the distribution, or they can start with a sample project, copying it as a starting point for their own project development.

3.1. Development Process Overview

3.1.1. Monterey Linux Development Tree

Once you have installed Monterey Linux to the development host using installit utility and activated it using the ACTIVATE.sh script, the Monterey Linux development tree root directory can be referenced by the $CDE_ROOT variable. This is a convenient way to refer to the development root directory. The Monterey Linux development tree has the following hierarchy:

Chapter

3


$CDE_ROOT

$TARGET_ROOT

Cross Development Tools

Target Components

...

... ...

...

...

$PATH+=

...

bin

...

lib

...

usr ...

linux sample u- boot

src include

usr lib bin

arm926ejs

Monterey LinuxInstallation directory

Figure 1: Monterey Linux Development Tree

The Monterey Linux development tree is composed of two main components:

Cross development tools area. This area can be reached as $CDE_ROOT.

Target components area. This area can be reached as either $CDE_ROOT/arm926ejs or simply as $TARGET_ROOT.

The organization of both the $CDE_ROOT and $TARGET_ROOT directories resembles a normal Linux root installation. That is, each has directories such as bin/, usr/, lib, and so on. As a reminder, the $CDE_ROOT components are for cross development, and therefore are compiled to run in the development host environment (Linux x86 based). The $TARGET_ROOT components are compiled to run in the DM320/DM342 environment, and therefore are compiled and linked using the cross development tools.

The $CDE_ROOT collection of tools is not a complete distribution of those utilities and libraries found in the root directory of the desktop PC Linux. Instead, it is just a subset of utilities needed for DM320/DM342 cross development. The ACTIVATE.sh script sets up the user $PATH variable so that the $CDE_ROOT utilities supercede those of the development host. This way, the $CDE_ROOT cross development tools are kept to just those needed to support cross development, and do not duplicate tools already available on the host.

The target components area, on the other hand, contains a carefully trimmed view of the Linux tree that can be conveniently used for target development specific to the DM320/DM342. The following table summarizes the $TARGET_ROOT directories:

Directory Content

$TARGET_ROOT/usr/src/linux Linux kernel sources $TARGET_ROOT/bin Prebuilt target utilities $TARGET_ROOT/usr/bin Prebuilt target utilities


Directory Content

$TARGET_ROOT/lib Prebuilt target libraries $TARGET_ROOT/usr/lib Prebuilt target libraries $TARGET_ROOT/usr/include Linux include files $TARGET_ROOT/usr/src/sample Sample Monterey Linux projects $TARGET_ROOT/usr/src/u-boot ARMboot (U-boot) source and build

environment $TARGET_ROOT/boot Prebuilt ARMboot (U-boot) binaries for the

supported reference platform $TARGET_ROOT/usr/src/busybox busybox source and build environment

Table 3: The $TARGET_ROOT Directories

3.1.2. Key Boot Mechanisms

Monterey Linux provides a number of boot mechanisms for the target. Typically, both kernel and file system images are stored in Flash (although there are certainly useful exceptions to this, for instance when the root file system in NFS-mounted). Even here, there are a number of variations.

The kernel may be compressed in Flash and then relocated to RAM by the firmware at boot time. Alternatively, the kernel may be kept uncompressed in Flash, which allows faster bootstrap.

The root file system can also be stored in Flash, either compressed or uncompressed. Each configuration has its pros and cons. It is important to understand these differences in order to determine which boot approach suits the resources and requirements of the target application. Details on these different options, and the steps required to implement them are provided below.

3.1.2.1. Compressed Kernel In this approach, the kernel executable is compressed using gzip before installing to Flash. When the kernel boots using the bootm command, the ARMboot firmware decompresses it to the beginning of RAM and starts the kernel from there. Thus, the kernel code is running fully from RAM.

The advantage of this boot approach is a smaller footprint for the compressed kernel image in Flash (vs. uncompressed image).

The tradeoff is a delay during the target bootstrap needed to get the kernel decompressed.


3.1.2.2. Uncompressed Kernel It is possible to install in Flash an uncompressed image of the kernel. This way, ARMboot simply copies the kernel to the beginning of RAM and starts it from there. No boot-time decompression is needed. The kernel code is running fully from RAM.

The obvious advantage of this approach is a faster boot-up time (vs. compressed image). The downside is a bigger footprint of the kernel image in Flash. An uncompressed kernel image is typically about two times larger than a compressed image of the same configuration.

3.1.2.3. Compressed File System A file system image can be compressed with gzip and installed in Flash. When a kernel boots, it can automatically detect a compressed file system image and decompress it before mounting it as the root file system. The main advantage of having a compressed root file system image is that it uses less Flash storage. The disadvantage is a delay during kernel boot-up while it decompresses the file system image.

3.1.2.4. Uncompressed File System File system images can also be stored in Flash in an uncompressed format. When the kernel boots, it just copies the file system image directly into a ramdisk, which is then mounted as the root file system. Even if the file system image is installed in Flash, the kernel copies its contents to RAM before mounting.

The main advantage of using uncompressed file system images is a faster kernel bootstrap since file system decompression is not required. The tradeoff with this approach is a larger Flash footprint.

3.1.2.5. NFS-Mounted File System One file system option that is particularly convenient during development is to have the kernel mount its root file system from an NFS server machine (for instance, from the Linux host development machine). With this approach, only the kernel needs to be downloaded to the target board and booted – the file system is accessed over the Ethernet network. An obvious advantage to this approach is convenience - update and maintenance of the file system can be performed from the Linux host system. The disadvantages of this mechanism are slower file system operation due to network latencies, longer boot up time, and a bigger kernel size, both at run-time and in Flash - NFS support adds more than 110K to the kernel executable (around 50K, when compressed).


3.2. Monterey Linux Kernel Development

3.2.1. Monterey Linux Kernel Source Tree

The Monterey Linux kernel tree resides in the following location:

$TARGET_ROOT/usr/src/linux This pathname is actually just a convenient soft link to the following directory where the actual kernel files reside:

$TARGET_ROOT/usr/src/linux-2.4.19 The structure and layout of the Monterey Linux tree is the same as that of the "vanilla" Linux kernel, version 2.4.19, and so any Linux developer should not have any problems finding things in the Monterey Linux kernel tree.

The following is a brief summary of the important areas of the Monterey Linux kernel tree:

Directory Description

kernel Core kernel files fs File system-related code and drivers mm Memory management code drivers Device drivers net Networking code init High-level kernel initialization files arch/arm Files specific for ARMboards. arch/arm/mach-dm320 Low-level DM320/DM342-specific code.include/asm-arm ARM-specific header files include/asm-arm/arch-dm320 Header files specific to DM320/DM342

Table 4: Kernel Directory Hierarchy

3.2.2. Configuring the Monterey Linux Kernel

The Monterey Linux kernel is configured in the same way as the standard Linux kernel. Configuration is performed within the $TARGET_ROOT/usr/src/linux directory, using any of the standard Linux kernel configuration tools. For instance, you can use make menuconfig, make xconfig, or a simpler make config.

The following snapshots illustrate the configuration procedure:


Change to the $TARGET_ROOT/usr/src/linux directory:

ML(arm926ejs):[tester@host1]$ cd $TARGET_ROOT/usr/src/linux

Configure the kernel:

ML(arm926ejs):[tester@host1]$ make xconfig Making asm-arm/arch -> asm-arm/arch-dm320 symlink Making asm-arm/proc -> asm-arm/proc-armv symlink rm -f include/asm ( cd include ; ln -sf asm-arm asm) make -C scripts kconfig.tk make[1]: Entering directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/scripts' PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/tester/bin gcc -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -c -o tkparse.o tkparse.c PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/tester/bin gcc -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -c -o tkcond.o tkcond.c PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/tester/bin gcc -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -c -o tkgen.o tkgen.c PATH=/usr/local/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/tester/bin gcc -o tkparse tkparse.o tkcond.o tkgen.o cat header.tk >> ./kconfig.tk ./tkparse < ../arch/arm/config.in >> kconfig.tk echo "set defaults \"arch/arm/defconfig\"" >> kconfig.tk echo "set ARCH \"arm\"" >> kconfig.tk cat tail.tk >> kconfig.tk chmod 755 kconfig.tk make[1]: Leaving directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/scripts' wish -f scripts/kconfig.tk

make xconfig can be used if the Linux host development system has a GUI windowing system. make config or make menuconfig should be used if you are working in a text terminal environment.

Each of the configuration tools, when successfully run, will create a new $TARGET_ROOT/usr/src/linux/.config file.

This is an ASCII file representation of the current kernel configuration that is used by the kernel build process to enable or disable particular features in the kernel.

3.2.3. Building the Monterey Linux Kernel

To build the Monterey Linux kernel, simply invoke the make pImage command while in the $TARGET_ROOT/usr/src/linux directory.

The snapshot below illustrates the Monterey Linux kernel build process.

Change to the $TARGET_ROOT/usr/src/linux directory:

ML(arm926ejs):[tester@host1]$ cd $TARGET_ROOT/usr/src/linux


Build the kernel:

ML(arm926ejs):[tester@host1]$ make pImage PATH=/usr/bin:/bin:/usr/bin:/usr/X11R6/bin:/home/tester/bin gcc -Wall -Wstrict-prototypes -O2 -fomit-frame-pointer -o scripts/split-include scripts/split-include.c scripts/split-include include/linux/autoconf.h include/config arm926ejs-gcc -D__KERNEL__ -I/part2/home/tester/arm926ejs/usr/src/linux-2.4.19/include -mapcs-frame -Wall -Wstrict-prototypes -Wno-trigraphs -Os -fno-strict-aliasing -fno-common -Uarm -fno-common -pipe -g -mapcs-32 -D__LINUX_ARM_ARCH__=5 -march=armv5 -mtune=arm9tdmi -mshort-load-bytes -msoft-float -Uarm -DKBUILD_BASENAME=main -c -o init/main.o init/main.c . scripts/mkversion > .tmpversion arm926ejs-gcc -D__KERNEL__ -I/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/include -mapcs-frame -Wall -Wstrict-prototypes -Wno-trigraphs -Os -fno-strict-aliasing -fno-common -Uarm -fno-common -pipe -g -mapcs-32 -D__LINUX_ARM_ARCH__=5 -march=armv5 -mtune=arm9tdmi -mshort-load-bytes -msoft-float -Uarm -DUTS_MACHINE='"arm"' -DKBUILD_BASENAME=version -c -o init/version.o init/version.c make[1]: Entering directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/arch/arm/tools' cmp constants.h /home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/include/asm-arm/constants.h >/dev/null 2>&1 || cp -p constants.h /home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/include/asm-arm/constants.h make[1]: Leaving directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/arch/arm/tools' make CFLAGS="-D__KERNEL__ -I/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/include -mapcs-frame -Wall -Wstrict-prototypes -Wno-trigraphs -Os -fno-strict-aliasing -fno-common -Uarm -fno-common -pipe -g -mapcs-32 -D__LINUX_ARM_ARCH__=5 -march=armv5 -mtune=arm9tdmi -mshort-load-bytes -msoft-float -Uarm " -C kernel make[1]: Entering directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/kernel' make all_targets make[2]: Entering directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/kernel' make[2]: Nothing to be done for `all_targets'. make[2]: Leaving directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/kernel' make[1]: Leaving directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/kernel' make CFLAGS="-D__KERNEL__ -I/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/include -mapcs-frame -Wall -Wstrict-prototypes -Wno-trigraphs -Os -fno-strict-aliasing -fno-common -Uarm -fno-common -pipe -g -mapcs-32 -D__LINUX_ARM_ARCH__=5 -march=armv5 -mtune=arm9tdmi -mshort-load-bytes -msoft-float -Uarm " -C drivers make[1]: Entering directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/drivers' make -C block make[2]: Entering directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/drivers/block' make all_targets ...

It will take some time for the kernel to compile.

make[1]: Leaving directory `/home/tester/ML/arm926ejs/usr/src/linux-2.4.19/arch/arm/lib'

At the end of the build you will see the final kernel link stage that produces the kernel ELF image:

arm926ejs-ld -p -X -T arch/arm/vmlinux.lds arch/arm/kernel/head-armv.o arch/arm/kernel/init_task.o init/main.o init/version.o init/do_mounts.o --start-group arch/arm/kernel/kernel.o arch/arm/mm/mm.o arch/arm/mach-dm320/dm320.o kernel/kernel.o mm/mm.o fs/fs.o ipc/ipc.o drivers/serial/serial.o drivers/char/char.o drivers/block/block.o drivers/misc/misc.o drivers/net/net.o drivers/media/media.o net/network.o arch/arm/lib/lib.a /home/tester/DM320/arm926ejs/usr/src/linux-


2.4.19/lib/lib.a --end-group -o vmlinux arm926ejs-nm vmlinux | grep -v '$compiled$\|$\.o$$\|$ [aUw] $\|$\.\.ng$$\|$LASH[RL]DI$' | sort > System.map

To install the kernel in Flash, it needs to be converted from ELF format to plain binary format:

arm926ejs-objcopy -O binary -R .note -R .comment -S /home/tester/ML/arm926ejs/usr/src/linux-2.4.19/vmlinux piggy

To save Flash space, the kernel image can be compressed:

gzip -9 < piggy > piggy.gz make[2]: Leaving directory `/home/tester/ML/arm926ejss/usr/src/linux-2.4.19/arch/arm/boot/compressed'

The mkimage tool is invoked to prepare the kernel for booting with ARMboot:

mkimage -A arm -O linux -T kernel -C gzip -a 0x00908000\ -e 0x00908000 -n 'linux-2.4.19' \ -d compressed/piggy.gz pImage Image Name: linux-2.4.19 Created: Wed Mar 24 16:59:25 2004 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 438664 Bytes = 428.38 kB = 0.42 MB Load Address: 0x00908000 Entry Point: 0x00908000 mkimage -A arm -O linux -T kernel -C none -a 0x00908000\ -e 0x00908000 -n 'linux-2.4.19' \ -d compressed/piggy pImage.uncompressed Image Name: linux-2.4.19 Created: Wed Mar 24 16:59:25 2004 Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 916144 Bytes = 894.67 kB = 0.87 MB Load Address: 0x00908000 Entry Point: 0x00908000 make[1]: Leaving directory `/home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/arch/arm/boot'

3.2.4. Kernel Images

A successful kernel build creates the following kernel images:

Image File Name Description

linux ELF kernel executable

arch/arm/boot/pImage Compressed kernel image ready to be booted by ARMboot (refer to 3.1.2.1)

arch/arm/boot/pImage.uncompressed Uncompressed kernel image ready to be booted by ARMboot (refer to 3.1.2.2).

Table 5: Kernel Images


3.3. Developing Monterey Linux User Applications

3.3.1. Building Simple Monterey Linux Applications

To build a simple Monterey Linux application in one pass, invoke GCC as follows:

gcc <app>.c -o <app>

For example, a simple hello-world program can be compiled as follows:

ML(arm926ejs):[tester@host1]$ gcc hello.c -o hello ML(arm926ejs):[tester@host1]$ ls -la hello -rwxr-xr-x 1 tester users 12979 Jun 10 02:17 hello

3.3.1.1. Building Multi-Threaded Monterey Linux Applications To build multi-threaded applications, the -lpthread option must be specified during final linking. Apart from this link-time flag, compilation is the same as with other applications. This option is not required when GCC is invoked for compilation only.

For example:

ML(arm926ejs):[tester@host1]$ gcc file.c -c ML(arm926ejs):[tester@host1]$ gcc file.o -o file -lpthread

which is equivalent to:

ML(arm926ejs):[tester@host1]$ gcc file.c -o file -lpthread

Note that the -lpthread option must come last, otherwise undefined reference errors may occur.

3.3.2. Developing C++ Applications

Monterey Linux fully supports building, running and debugging C++ applications. C++ language support in Monterey Linux is based upon the GNU libstdc++ library (version 3), which provides all the basic language support functions (new(), delete(), etc), along with a powerful set of reusable tools (in the form of C++ classes) defined by the ISO C++ Standard.


3.3.2.1. Building C++ Applications C++ applications in Monterey Linux are built in the same way as all other applications, the only difference being that the compiler must be invoked by the name g++. For example:

ML(arm926ejs):[tester@host1]$ g++ hello.cpp -o hello

which is equivalent to:

ML(arm926ejs):[tester@host1]$ g++ hello.cpp -c ML(arm926ejs):[tester@host1]$ g++ hello.o -o hello

(note how g++ was also used for linking).

There is no need to specify any additional options because g++ automatically includes the libstdc++ library for linking.

3.4. Developing Monterey Linux File Systems

A typical embedded system based on Monterey Linux uses an ext2fs-based root file system. Creating a root file system image that can be booted by ARMboot is a three-stage process.

Create and populate a directory on the development host. This will be a prototype of your target file system.

Run the genext2fs utility to create a root file system image of the prototype file system. This image can be optionally compressed by using gzip.

Use the mkimage tool to furnish the root file system image with a header that lets ARMboot correctly handle the image.

The sections that follow describe each of the steps in detail.

3.4.1. Creating a Prototype File System

First step is to create an empty directory anywhere on your host system and populate it with files from the target component of Monterey Linux. Normally, you will start by copying such important binaries as init, sash, and busybox. Do not forget to include an empty /var directory, and /proc. It is a good idea to use the contents of the rfs directory from one of the Monterey Linux sample projects as a base for developing your own file system.

Device nodes must be listed in the device file (for example dev.txt). This file has the following format:


drwx /dev <node_type>rw- <major>,<minor> /dev/<node_name> <node_type>rw- <major>,<minor> /dev/<node_name> ....

where:

<node_name> Name of the device node as it will appear in the target file system.

<node_type> Exactly one letter, c or b, denoting the type of the device node, character or block, respectively.

<major> Major number of the device node

<minor> Minor number of the device node.

For instance, to create a device node for the console character device, with the major number 5 and minor number 1, use the following device file:

drwx /dev crw- 5,1 /dev/console

3.4.2. Generating a Root File System Image

Once the prototype file system has been created on the host, a root file system image can be generated. This is done using the genext2fs tool:

ML(arm926ejs):[tester@host1]$ genext2fs –h Usage: genext2fs [options] image Create an ext2 filesystem image from directories/files -x image Use this image as a starting point -d directory Add this directory as source -b blocks Size in blocks -i inodes Number of inodes -r reserved Number of reserved blocks -g path Generate a block map file for this path -e value Fill unallocated blocks with value -z Make files with holes -D,-f Use the named FILE as a device table file -q Squash permissions and owners making all files be owned by root -U Squash owners making all files be owned by root -P Squash permissions on all files -v Print resulting filesystem structure -h Show this help Report bugs to [email protected] ML(arm926ejs):[tester@host1]$

Typically, you will use only the -d, -b, -f, and possibly -v switches. For instance, to create an image (named my_image.rfs) of the prototype file system located under the myrfs subdirectory of the current directory and nodes from the device file my_def.txt, the following command can be used:


ML(arm926ejs):[tester@host1]$ genext2fs -d myrfs -f my_dev.txt -b 1440 my_image.rfs

Once the image has been created, it can be compressed using gzip. This step is optional. Refer to 3.1.2.3 for details. To compress the image, use the following command:

ML(arm926ejs):[tester@host1]$ gzip –9 my_image.rfs

The compressed image will be written to the my_image.rfs.gz file.

3.4.3. Creating a File System Image for ARMboot

The final downloadable image created from the image (either compressed or uncompressed) must have a header which instructs the ARMboot bootm command about the type of image it is and whether it is compressed or not. This header also includes checksums. The mkimage tool is used to add this header to the root file system image.

A typical invocation of mkimage looks like this:

ML(arm926ejs):[tester@host1]$ mkimage -n 'Example Ramdisk Image' -A arm \ -O linux -T ramdisk -C none -d my_image.rfs my_image.rfs

The example above creates a files system image named my_image.rfs from the root file system image my_image.rfs.

To create a compressed root file system image, mkimage can be invoked as follows:

ML(arm926ejs):[tester@host1]$ mkimage -n 'Example Ramdisk Image' -A arm \ -O linux -T ramdisk -C gzip -d my_image.rfs.gz my_image.rfs

3.5. Multiple Embedded Applications

In a typical development scenario, the developer maintains several embedded applications in parallel. These multiple applications may provide similar target functionality (for instance, there can be two network enabled configurations, one supporting a single network port, another supporting two ports with routing capability) or they may be very different, depending on the application needs. Still, the need to maintain several separate embedded applications is typical, be it due to the need to develop software components by different developers or because you simply want to keep embedded systems as "references" (that is, where a system that is known to provide a specific functionality on the target reliably).


Monterey Linux illustrates how separate embedded systems may be maintained in parallel. This is done using the sample projects, which reside in $TARGET_ROOT/usr/src/sample.

The Monterey Linux sample projects are described in detail in Chapter 9, but the main idea is that each sample project keeps its own configuration of the kernel (in the <sample>.config file) and its own definition of the contents of the target file system (in <sample>.spec file). These two files are enough to rebuild both the kernel and the file system used in the sample (embedded) system from scratch.

For the kernel it works as follows. When the kernel used in a sample project is being built, the <sample>.config file local to the sample project directory gets copied to the kernel .config file (that is, the command cp <sample>.config $TARGET_ROOT/usr/src/linux/.config is performed). After the kernel has been built, the resulting kernel images (refer to 3.2.4) get copied back from the kernel tree to the sample project directory.

For the file system, the <sample>.spec file simply defines the contents of the prototype file system (refer to 3.4.1) that is created on the host before running the genext2fs utility in order to generate a target file system image.


4. Using ARMboot Firmware This chapter describes the ARMboot firmware included in Monterey Linux. ARMboot is a firmware program that implements power-up initialization of target hardware and provides a foundation for booting the Linux operating system. Features typically used for development and deployment of ARMboot based targets, such as TFTP boot, environment variables, autoboot, and so on, are discussed and illustrated with examples.

Note: Recently, the ARMboot firmware (targeting ARM embedded processors) has been merged with another popular derivative of the same firmware family, PPCboot (targeting PowerPC embedded processors). The resulting firmware is called U-boot, for "Universal Bootloader". It is important to note that the U-boot project and source is maintained by the author and main developer of PPCboot and is a version of the firmware that embraces all the recent features and enhancements. Monterey Linux has upgraded its firmware component to one of the recent versions of U-boot. Monterey Linux continues to refer to the firmware as either ARMboot or U-boot, interchangably. In this document, whenever ARMboot is mentioned, you can assume that it is a reference to the U-boot firmware.

A detailed command reference is provided for the most important ARMboot commands.

4.1. Introducing ARMboot

ARMboot (U-boot) is an open-source firmware monitor (sourceforge.net/projects/u-boot) that provides a Linux-friendly firmware environment and user interface for ARM-based platforms.

The primary objectives of ARMboot are portability and functionality. Key features of ARMboot include:

Serial console command-driven user interface

Chapter

4


Network download via BOOTP, DHCP, TFTP

Extensive support for Flash memory

Powerful mechanism of environment variables

Autoboot mode.

4.2. Using ARMboot on the Target

The following sections describe the use of the ARMboot firmware monitor.

4.2.1. Serial Console Command Prompt

ARMboot implements a serial-console based command-driven user interface. When the target is powered-on or reset, you will see a banner message on the serial console with details about the ARMboot version, build date and amounts of RAM and Flash available on the target. After displaying this information, ARMboot will present a command prompt:

U-Boot 0.2.2 (Mar 22 2004 - 22:30:22) U-Boot code: 01800000 -> 0181381C BSS: -> 01816B30 DRAM Configuration: Bank #0: 00900000 16 MB Flash: 2 MB dm320evm #

By typing help, without arguments, you will get the list of all supported commands with brief descriptions. For instance:

dm320evm # help autoscr - run script from memory base - print or set address offset bdinfo - print Board Info structure bootm - boot application image from memory bootp - boot image via network using BootP/TFTP protocol bootd - boot default, i.e., run 'bootcmd' cmp - memory compare coninfo - print console devices and informations cp - memory copy crc32 - checksum calculation echo - echo args to console erase - erase FLASH memory flinfo - print FLASH memory information go - start application at address 'addr' help - print online help iminfo - print header information for application image loadb - load binary file over serial line (kermit mode) loads - load S-Record file over serial line loop - infinite loop on address range md - memory display mm - memory modify (auto-incrementing) mtest - simple RAM test


mw - memory write (fill) nm - memory modify (constant address) printenv- print environment variables protect - enable or disable FLASH write protection rarpboot- boot image via network using RARP/TFTP protocol reset - Perform RESET of the CPU run - run commands in an environment variable saveenv - save environment variables to persistent storage setenv - set environment variables sleep - delay execution for some time tftpboot- boot image via network using TFTP protocol and env variables ipaddr and serverip version - print monitor version ? - alias for 'help' dm320evm #

To get more detailed information about a specific command, invoke help with the name of the command as an argument. For instance, to get help on the cp command, type:

dm320evm # help cp cp [.b, .w, .l] source target count - copy memory dm320evm #

Note: The default baud rate of the console port on the DM320/DM342 EVM is 115200 bps.

4.2.2. Environment Variables

Environment variables control many aspects of ARMboot operation. Such settings as serial console baud rate, IP address of the network interface, the command line to be passed to the Linux kernel, and others, can be adjusted on the target using these ARMboot environment variables.

The following environment variables are defined for use by ARMboot:


Description

bootcmd The ARMboot command executed when autoboot is enabled. Normally, this is something similar to bootm 0x00120000, which starts the Linux image stored in Flash.

baudrate Serial console baudrate value, in bits per second. bootdelay Autoboot delay value, in seconds.



Description

ipaddr IP address used by the on-chip Ethernet interface. This variable can be passed as a part of the kernel command line to automatically configure the corresponding kernel network interface.

serverip IP address of the TFTP server bootargs Command line to be passed to the Linux kernel. This may

contain references to other ARMboot environment variables, which will be resolved at run-time. For instance, if the value of bootargs is root=/dev/mtdblock2 ip=$(ip1addr), and ipaddr has the value 192.168.0.23, then the Linux kernel will receive the following command line: root=/dev/mtdblock2 ip=192.168.0.23

Table 6: Environment Variables

To set an environment variable, use the setenv command. As an example, the following command sets the value of the bootdelay variable to 5:

dm320evm # setenv bootdelay 5

To display the current value of a variable, use the printenv command:

dm320evm # printenv bootdelay bootdelay=5

To display the values of all currently set environment variables, use the printenv command without any arguments:

dm320evm # printenv baudrate=115200 ethaddr=00:02:03:56:78:9e filesize=b157e ipaddr=192.168.0.1 serverip=192.168.0.23 bootargs=root=/dev/ram0 bootdelay=5 Environment size: 133/65532 bytes dm320evm #

ARMboot uses a Flash sector for persistent storage of environment variables. At boot-up, it reads the environment from Flash into RAM and then works with the in-RAM copy. If you modify any ARMboot environment variables and want the modifications to be permanent, you have to manually save the environment to Flash using the saveenv command. For instance, the following commands changes the IP address of the TFTP server and saves it back to Flash:


dm320evm # setenv serverip=192.168.0.1 dm320evm # saveenv Saving Environment to Flash... Un-Protected 1 sectors Erasing Flash... . done Erased 1 sectors Writing to Flash... done Protected 1 sectors dm320evm #

4.2.2.1. Creating ARMboot Command Scripts Environment variables can be used to hold ARMboot command scripts. Scripts can then be executed using the run command. What makes this feature really useful is the ability of ARMboot to substitute references to environment variables dynamically. This can be illustrated by the following example. You can set up an environment variable named bootargs with the following contents:

ip=$(ipaddr)

The value of the bootargs variable is passed by ARMboot to the Linux kernel as a kernel command line (discussed further below). In this example, the reference to $(ipaddr) will be resolved at run-time, such that if the ipaddr variable has a value of 192.168.0.23 at the time the kernel is being booted, the kernel will receive the command line

ip=192.168.0.23

A good example of this might be where ARMboot obtains the value of the ipaddr variable from a BOOTP/DHCP server.

To create an environment variable that contains references to other variables or other special symbols like a semicolon, the symbol must be escaped with a backslash. For instance, to create the bootargs variable from the example above, type:

dm320evm # setenv bootargs ip=\$(ipaddr)

To illustrate the use of the run command, consider the following example. Create a ramroot environment variable, as follows:

dm320evm # setenv ramroot setenv bootargs \$(bootargs) root=/dev/ram0 \;echo Modifying kernel comand line

So the ramroot variable would have the following value:

dm320evm # printenv ramroot ramroot=setenv bootargs $(bootargs) root=/dev/ram0 ;echo Modifying kernel comand line dm320evm #


Now use the run ramroot command to add root=/dev/ram0 to the current value of the bootargs variable:

dm320evm # printenv bootargs bootargs=ip=$(ipaddr) dm320evm # run ramroot Modifying kernel comand line dm320evm # printenv bootargs bootargs=ip=$(ipaddr) root=/dev/ram0 dm320evm #

4.2.3. Downloading Images

This section explains how to download Monterey Linux images to the target.

4.2.3.1. Downloading Images over the Network ARMboot allows images to be downloaded over the network using the TFTP protocol. The IP addresses of the target and server, as well as the file to download can be specified by means of ARMboot environment variables and command arguments. Alternatively, they can be obtained automatically from a BOOTP/DHCP server.

To download an image from a TFTP server, you can use the tftpboot command. For this command to work, the following environment variables must be set:

ipaddr IP address of the network interface

serverip IP address of the TFTP server

For instance, the following command downloads a telnet.kernel image from a TFTP server with the IP address specified in the serverip environment variable to the address 0x00A00000 in RAM:

dm320evm# tftpboot 00a00000 /tftpboot/telnet.kernel

The first argument of the tftpboot command specifies the address in RAM where the image is to be downloaded. On the DM320/DM342 EVM, SDRAM starts at address 0x00900000, and ARMboot runs at high RAM addresses. The ARMboot code starts at address 0x01800000 leaving the lower 15MBbytes available for downloads and applications. You should keep in mind that when the Linux kernel is booting, it is decompressed to the beginning of RAM, starting at the address 0x00900000. This means that a compressed image of the Linux kernel must be downloaded at an address sufficiently distant from the beginning of RAM so as to leave space for the decompressed kernel. It is a good idea to download kernel images at a 4MB offset in RAM, and root files system images at the 8MB offset. Typical ARMboot commands to download a Monterey Linux sample project, for instance, telnet, are as follows.


Download the kernel image:

dm320evm # tftpboot 00a00000 /tftpboot/telnet.kernel ARP broadcast 1 ARP broadcast 2 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'telnet.kernel'. Load address: 0xa00000 Loading: ################################################################# ################################################################# ######################################### done Bytes transferred = 874252 (d570c hex) dm320evm #

Download the file system image:

dm320evm # tftpboot 00d00000 /tftpboot/telnet.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'telnet.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ###################################### done Bytes transferred = 4187200 (3fe440 hex) dm320evm #

Run the kernel:

dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 874188 Bytes = 853.7 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK OK ## Loading Ramdisk Image at 00d00000 ... Image Name: telnet RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #3 Tue Mar 23 23:35:57 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096


zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 11088KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.23-22:49+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) /> reboot

4.2.3.2. Downloading Images over a Serial Line ARMboot allows images to be downloaded over a serial line. Both binary and Motorola S-record file downloads are supported. Typically, downloading binary images works faster because binary images are usually smaller in size and because ARMboot supports switching to a higher baudrate when downloading a binary image. For instance, the following command downloads a binary image to the address 0x00A00000 in RAM, at a baudrate of 115200:

dm320evm # loadb 0x00a00000 115200 ## Ready for binary (kermit) download ...


At this point, you can switch your terminal application on the host to 115200 bps and start sending the image. For instance, if you use kermit, press Ctrl-\ C to get to the kermit prompt, then type set speed 115200, and then send <file_name>, as follows:

ML(arm926ejs):[tester@host1]$ C-Kermit>send /tftpboot/telnet.kernel

Once the transmission is done, type connect at the kermit prompt to get to ARMboot console again:

ML(arm926ejs):[tester@host1]$ C-Kermit>connect Connecting to /dev/ttyS1, speed 115200. The escape character is Ctrl-\ (ASCII 28, FS) Type the escape character followed by C to get back, or followed by ? to see other options. ## Start Addr = 0x00a00000 dm320evm #

Now switch the baudrate back to the default baud rate, re-connect to ARMboot, and press the Esc key:

ML(arm926ejs):[tester@host1]$ C-Kermit>set speed 9600 /dev/ttyS1, 9600 bps ML(arm926ejs):[tester@host1]$ C-Kermit>connect Connecting to /dev/ttyS1, speed 9600. The escape character is Ctrl-\ (ASCII 28, FS) Type the escape character followed by C to get back, or followed by ? to see other options. dm320evm #

4.2.4. Booting Linux

Once a Linux kernel image and optionally a root file system image are downloaded in RAM, Linux can be booted using the bootm command. The most common way of booting Linux on a DM320/DM342 target is by issuing a bootm command with two arguments: the RAM addresses of the kernel image and root file system image. For instance, if you have downloaded a kernel image to address 0x00A00000 and a root file system image to address 0x00D00000, the following sequence of commands will boot the Linux kernel (and perform two very important things):

Set up a command line that gets passed to the Linux kernel specifying the root device - /dev/ram0 in this example:

dm320evm # setenv bootargs root=/dev/ram0

Tell the kernel the address of the root file system image.

dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (uncompressed)


Data Size: 874188 Bytes = 853.7 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK OK ## Loading Ramdisk Image at 00d00000 ... Image Name: telnet RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #3 Tue Mar 23 23:35:57 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 11088KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.23-22:49+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh'


Sash command shell (version 1.1.1) />

Note that the addresses passed to the bootm command do not have to be in RAM. They may also be Flash addresses, pointing to Linux kernel and file system images you have installed in Flash. A detailed description of installing and booting from Flash is given in 4.2.5.

Using ARMboot, you can boot a Linux kernel without a root file system image. A typical example of a situation when this may be desired is booting the kernel with a NFS-based root file system. To achieve this, simply omit the second argument of the bootm command. Note that in this case, it is left up to the kernel to find from where the root file system is to be mounted. For instance, you may enable support for kernel IP autoconfiguration when building your kernel, along with one or more boot configuration protocols, such as BOOTP, RARP, or DHCP. Alternatively to enabling the BOOTP/RARP/DHCP protocols, you may pass the NFS configuration information in the kernel command line.

4.2.5. Flash Management

ARMboot allows the user to store Linux images in Flash and boot them. First, you need to load the image into RAM, for instance via TFTP.

dm320evm # tftpboot 00a00000 /tftpboot/telnet.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'telnet.kernel'. Load address: 0xa00000 Loading: ################################################################# ################################################################# ######################################### done Bytes transferred = 874252 (d570c hex) dm320evm #

Notice above that ARMboot reports the length of the image transferred, in bytes (0xdd8ab, in this example). Remember this figure.

Next, you need to erase a region in Flash, of sufficient length, where you want to install the image. Use the flinfo command to understand the Flash layout:

dm320evm # flinfo Bank # 1: TOSHIBA AM29LV160B (16 Mbit, bottom boot sect) Size: 2 MB in 35 Sectors Sector Start Addresses: 00100000 (RO) 00104000 (RO) 00106000 (RO) 00108000 (RO) 00110000 (RO) 00120000 00130000 00140000 00150000 00160000 00170000 00180000 00190000 001A0000 001B0000 001C0000 001D0000 001E0000 001F0000 00200000 00210000 00220000 00230000 00240000 00250000 00260000 00270000 00280000 00290000 002A0000 002B0000 002C0000 002D0000 002E0000 002F0000 (RO) dm320evm #


Note that on the DM320/DM342 EVM board, ARMboot occupies the first sector of Flash, and the ARMboot environment occupies the last sector, at offset 0x021f0000. It is not recommended to erase these sectors.

The example below erases a Flash region starting at offset 0x2020000:

dm320evm # erase 00120000 002effff Erase Flash from 0x00120000 to 0x002effff ......... done Erased 29 sectors dm320evm #

Once the Flash region has been erased, copy the image from RAM into Flash:

dm320evm # cp.b 0xa00000 00120000 d570c Copy to Flash... done dm320evm #

After this is done, you can boot the image from Flash using the bootm command:

dm320evm # bootm 00120000

4.2.6. Autoboot

The autoboot feature of ARMboot is controlled by two environment variables: bootcmd and bootdelay. The bootcmd variable is the command that will be executed after the number of seconds specified in the bootdelay variable has elapsed (after power-on/reset). Note that the bootcmd variable actually enables the autoboot feature. That is, even if the bootdelay variable is not set and bootcmd is set, the autoboot sequence will be executed right after ARMboot is up as if bootdelay had a value of zero. This means the only way to disable autoboot is to unset the bootcmd variable.

You can stop the autoboot sequence by pressing a key before autoboot counts down to zero.

These commands disable the autoboot feature:

dm320evm # setenv bootcmd dm320evm # saveenv

The commands below enable autoboot and instruct ARMboot to boot the nfsroot sample automatically after 5 seconds have elapsed after boot-up:

dm320evm # setenv bootcmd tftpboot 00a00000 nfsroot.kernel \; run nfsargs addip \; bootm dm320evm # setenv bootdelay 5 dm320evm # saveenv


4.3. Command Reference

This section provides a summary of the available ARMboot commands.

4.3.1. go

Start an application at the specified address.

SYNOPSIS go <addr> go <addr> <arg1>[,…,<argN>]

PARAMETERS

<addr> Specifies the physical address to transfer control.

<arg1>,…,<argN> The list of arguments (if any) required by the application.

ENVIRONMENT VARIABLES

None

SUMMARY

The go command is used to start an application at the address <address> with the required arguments specified as a list of <arg1>,…,<argN> parameters.

EXAMPLES

The following example boots an application (ARMboot binary) at address 0x00A00000 and then starts it:

dm320evm # tftpboot 00a00000 /tftpboot/u-boot.bin ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'u-boot.bin'. Load address: 0xa00000 Loading: ################ done Bytes transferred = 79900 (1381c hex) dm320evm # go 00a00000 ## Starting application at€0x00a00000... U-Boot 0.2.2 (Mar 22 2004 - 22:30:22) U-Boot code: 01800000 -> 0181381C BSS: -> 01816B30 DRAM Configuration: Bank #0: 00900000 16 MB Flash: 2 MB dm320evm #


4.3.2. run

Run commands in an environment variable

SYNOPSIS run <var1>[,…,<varN>]

PARAMETERS

<var1>[,…,<varN>] Specifies the names of existing environment variables.


The values of the environment variables specified as the command arguments are treated as ARMboot commands and executed.

SUMMARY

run is used to run commands in one or more specified environment variables.

EXAMPLES

The following example prints the commands stored in a user-defined environment variable bsample and executes them:

dm320evm # printenv bsample bsample=tftpboot 00a00000 .kernel; tftpboot 00d00000 .rfs; setenv bootargs root=/dev/ram0; bootm 00a00000 00d00000dm320evm # printenv bsample bsample=tftpboot 00a00000 $(sample).kernel; tftpboot 00d00000 $(sample).rfs; setenv bootargs root=/dev/ram0; bootm 00a00000 00d00000 dm320evm # printenv sample sample=telnet dm320evm # run bsample ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'telnet.kernel'. Load address: 0xa00000 Loading: ################################################################# ################################################################# ######################################### done Bytes transferred = 874252 (d570c hex) ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'telnet.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ###################################### done Bytes transferred = 4187200 (3fe440 hex) ## Booting image at 00a00000 ...


Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 874188 Bytes = 853.7 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK OK ## Loading Ramdisk Image at 00d00000 ... Image Name: telnet RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #3 Tue Mar 23 23:35:57 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 11088KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.23-22:49+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh'


Sash command shell (version 1.1.1) />

4.3.3. bootm

Boot an application image from memory.

SYNOPSIS bootm <addr> [<arg1>[,…,<argN>]]

PARAMETERS

<addr> Specifies a physical address of the application image.

<arg1>[,…,<argN>] Specifies a list of arguments (if any) required by the application.


If an application is the Linux kernel, the contents of the bootargs environment variable are treated as a command line and passed to the kernel.

SUMMARY

The bootm command is used to boot an application image stored in memory at the address <addr> with the required arguments specified as a list of <arg1>[,…,<argN>] parameters. When booting a Linux kernel, the list of arguments may consist of the only parameter <arg> as the address of the initrd image.

EXAMPLES

The following example prints the contents of the bootargs environment variable and then boots the Linux kernel stored in memory at address 0x00A00000 passing the start address of the root file system (0x00D00000) as the parameter:

dm320evm # setenv bootargs root=/dev/ram0 dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 874188 Bytes = 853.7 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK OK ## Loading Ramdisk Image at 00d00000 ... Image Name: telnet RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ...


Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #3 Tue Mar 23 23:35:57 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages.

Notice that the kernel command line is taken from the bootargs environment variable.

Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 11088KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.23-22:49+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />


4.3.4. tftpboot

Boot an image via network using TFTP protocol.

SYNOPSIS tftpboot <load_addr> <bootfilename>

PARAMETERS

<load_addr> Specifies the address to download the image to.

<bootfilename> Specifies the name of the file to be booted.


ipaddr Specifies the IP address of the target.

serverip Specifies the IP address of the server.

SUMMARY

The tftpboot command is used to boot the <bootfilename> image via the network using TFTP protocol and the environment variables ipaddr and serverip to the address <load_addr>.

EXAMPLES

The following command boots the u-boot.bin image file from the /tftpboot directory at address 0x00A00000.

dm320evm # tftpboot 00a00000 tftpboot/u-boot.bin ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.23 Filename 'u-boot.bin'. Load address: 0xa00000 Loading: ################ done Bytes transferred = 79900 (1381c hex) dm320evm #

4.3.5. loads

Load the S-Record file over serial line.

SYNOPSIS loads <off>

PARAMETERS

<off> Specifies the memory address that the S-Record file will be loaded to.


None


SUMMARY

The loads command is used to load the S-Record file over serial line to the memory address <off>.

EXAMPLES

The following command loads the S-record file at address 0x00A00000:

dm320evm # loads 0x00a00000 ## Ready for S-Record download ...

4.3.6. loadb

Load a binary file over serial line.

SYNOPSIS loadb <off> <baud>

PARAMETERS

<off> Specifies the memory address for a binary file to be loaded to.

<baud> Specifies the baud rate.


None

SUMMARY

The loadb command is used to load the binary file over the serial line to the memory address <off> at the baud rate <baud>.

EXAMPLES

The following command downloads a binary image to the address 0x00A00000 in RAM at a baudrate of 115200:

dm320evm # loadb 0x00a00000 115200 ## Switch baudrate to 115200 bps and press ENTER ...

4.3.7. md

Memory display.

SYNOPSIS md [<width>] <addr> [<count>]


PARAMETERS

<width> Specifies the width of the memory objects to be displayed:

.b Byte

.w Word

.l Long word.

If no width is specified, memory will be displayed as long words.

<addr> Specifies the address to start at.

<count> Specifies the number of memory objects to display.


None

SUMMARY

The md command is used to display the specified memory range starting at the address <addr>. If the <count> parameter is provided, then <count> memory objects are displayed.

EXAMPLES

The following example displays a memory range starting at the offset 0x0:

dm320evm # md.1 0 00000000: bde40000 2df03fd5 50081dac 0e21981b .....?.-...P..!. 00000010: d894b3f7 5b454e28 0ce38350 9501e7a8 ....(NE[P....... 00000020: eb8a5ddf 3460f8cf fe827f47 31346eaa .]....`4G....n41 00000030: f35ea1f1 ccb4531e 40c0a77d e502bac9 ..^..S..}..@.... 00000040: 3ade5f12 5adc8afc 0d18e687 5d7ebc32 ._.:...Z....2.~] 00000050: b485ee66 6ebbe4f6 a83fa73b 2e8f7a11 f......n;.?..z.. 00000060: 642d013d 9052e015 052957d7 b68a8d80 =.-d..R..W)..... 00000070: b41f6a69 bb751dad 486848d1 15c21dd2 ij....u..HhH.... 00000080: 0f7e3bd7 7333bd2b 01ce8b09 067c6e59 .;~.+.3s....Yn|. 00000090: f5b2007e 9989899d ca434f35 02ab1023 ~.......5OC.#... 000000a0: 43c6961c 84b1d0c9 cf294aab e7f2693b ...C.....J).;i.. 000000b0: aa274cfc 5b054257 dc8b91d5 40ac089a .L'.WB.[.......@ 000000c0: 4b406db9 18f8ae32 3f2f99a4 0842a4fd .m@K2...../?..B. 000000d0: 9c684d8b 1ca635cb 62a35e19 7698353e .Mh..5...^.b>5.v 000000e0: d74e9ae2 8273985d 71bd0632 46b9f4a9 ..N.].s.2..q...F 000000f0: 95e16bc3 e5377b43 3771ce41 4d0ade6d .k..C{7.A.q7m..M dm320evm #

4.3.8. mm

Memory modify.


SYNOPSIS mm [<width>] <addr>

PARAMETERS

<width> Specifies the width of the memory objects to be modified:

.b Byte

.w Word

.l Long word.

If no width is specified, memory will be modified as long words.



None

SUMMARY

The mm command is used to view and change the contents of memory. The command reads and displays the contents of memory at the specified address <addr> and prompts for new values to write with a question mark ?. To leave the memory location unchanged, press the Enter key without typing a new value. That memory location is unchanged and the next location is displayed. To terminate the mm command and return control to the ARMboot firmware, enter ..

EXAMPLES

The following command displays a memory range starting from address 0x00A00000 and prompts for new values to be written:

dm320evm # mm 00a00000 00a00000: c00d7d10 ? 00a00004: c00d7d10 ? 00a00008: 000000c0 ? 00a0000c: c01000c0 ? 00a00010: 00000024 ? 00a00014: ffffffff ? 00a00018: 00000001 ? 00a0001c: 00000002 ? 00a00020: 00000003 ? 00a00024: 00000004 ? . dm320evm #

4.3.9. mw

Memory write.


SYNOPSIS mw[<width>] <addr> <value> [<count>]

PARAMETERS

<width> Specifies the width of the memory objects to be filled:

.b Byte

.w Word

.l Long word.

If no width is specified, memory will be filled as long words.


<value> Specifies the value the memory to be filled with.

<count> Specifies the number of memory objects to be filled.


None

SUMMARY

The mw command is used to fill the memory range starting at the address <addr> with the value <value>. If the <count> parameter is provided, then <count> memory objects are filled with the specified value.

EXAMPLES

The following example writes value 0x35 to each of 0x500 long words of RAM starting at the address 0x00A00000 and displays the updated memory:

dm320evm # mw 00a00000 0x35 0x500 dm320evm # md 00a00000 00a00000: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00010: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00020: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00030: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00040: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00050: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00060: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00070: 00000035 00000035 00000035 00000035 5...5...5...5... 00a00080: 00000035 00000035 00000035 00000035 5...5...5...5...


00a00090: 00000035 00000035 00000035 00000035 5...5...5...5... 00a000a0: 00000035 00000035 00000035 00000035 5...5...5...5... 00a000b0: 00000035 00000035 00000035 00000035 5...5...5...5... 00a000c0: 00000035 00000035 00000035 00000035 5...5...5...5... 00a000d0: 00000035 00000035 00000035 00000035 5...5...5...5... 00a000e0: 00000035 00000035 00000035 00000035 5...5...5...5... 00a000f0: 00000035 00000035 00000035 00000035 5...5...5...5... dm320evm #

4.3.10. cp

Memory copy.

SYNOPSIS cp[<range>] <source> <target> <count>

PARAMETERS

<range> Specifies the memory range to be copied:

.b Byte

.w Word

.l Long word.

If no range is specified, memory will be copied as long words.

<source> Specifies the address to copy from.

<target> Specifies the address to copy to.

<count> Specifies the number of memory objects to be copied.


None

SUMMARY

The cp command is used to copy <count> memory objects from the address <source> to the address <target>.

EXAMPLES

The following command copies 0xd570c bytes from RAM address 0x00A00000 to Flash address 0x00120000:

dm320evm # cp.b 00a00000 00120000 d570c Copy to Flash... done dm320evm #


4.3.11. cmp

Memory compare.

SYNOPSIS cmp <range> <addr1> <addr2> <count>

PARAMETERS

<range> Specifies the memory range to compare:

.b Byte

.w Word

.l Long word.

If no range is specified, memory will be compared as long words.

<addr1> <addr2> Specifies the addresses in memory to start at.

<count> Specifies the number of memory objects to be compared.


None

SUMMARY

The cmp command is used to compare the <count> memory objects from the addresses <addr1> with the <count> memory objects from the address <addr2>.

EXAMPLES

The following example demonstrates the use of the cmp and cp ARMboot commands:

dm320evm # cmp 0x0 00a00000 0x100 word at 0x00000000 (0xbde40000) != word at 0x00a00000 (0x00000035) Total of 0 words were the same dm320evm # cp 0x0 00a00000 0x100 dm320evm # cmp 0x0 00a00000 0x100 Total of 256 words were the same dm320evm #

4.3.12. printenv

Print environment variables.


SYNOPSIS printenv [<var1>,…,<vareN>]

PARAMETERS

<var1>,…,<varN> Specifies the list of the environment variables to be printed.


None

SUMMARY

The printenv command is used to print environment variables

<var1>,…,<varN>. If no names are specified, printenv prints values of all the environment variables.

EXAMPLES

The following command prints values of all the environment variables:

dm320evm # printenv bootdelay=8 baudrate=115200 v=setenv bootargs $(bootargs) video=dm320fb:mem:2048 c=setenv bootargs $(bootargs) console=ttyS0,115200 ethaddr=00:01:02:2C:6D:18 filesize=b0983 ipaddr=192.168.0.23 serverip=192.168.0.1 mb=tftp 00a00000 $(bootkernel);tftp 00d00000 $(bootrfs);run v;bootm 00a00000 00d00000 sample=telnet bsample=tftpboot 00a00000 $(sample).kernel; tftpboot 00d00000 $(sample).rfs; setenv bootargs root=/dev/ram0; bootm 00a00000 00d00000 bootargs=root=/dev/ram0 Environment size: 471/65532 bytes dm320evm #

4.3.13. setenv

Set the value of an environment variable.

SYNOPSIS setenv <var> [<value>]

PARAMETERS

<var> Specifies the name of the environment variable to be set.

<value> Specifies the value for the environment variable.



Environment variable <var> is updated.

SUMMARY

The setenv command is used to set the specified environment variable <var> to the value <value>. If no value is specified, setenv will delete the environment variable <var> .

EXAMPLES

The following command sets the serverip environment variable to the IP address of the TFTP server:

dm320evm #setenv serverip 192.168.0.1 dm320evm #

4.3.14. saveenv

Save environment variables.

SYNOPSIS saveenv

PARAMETERS

None


None

SUMMARY

The saveenv command is used to save all the environment variables to persistent storage.

EXAMPLES

The following command saves all the environment variables:

dm320evm # saveenv Saving Environment to Flash... Un-Protected 1 sectors Erasing Flash... . done Erased 1 sectors Writing to Flash... done Protected 1 sectors dm320evm #


4.3.15. protect

Enable or disable Flash write protection.

SYNOPSIS protect on <start> <end>

protect on <N>:<SF>-<SL>

protect on bank <N>

protect on all

protect off <start> <end>

protect off <N>:<SF>-<SL>

protect off bank <N>

protect off all

PARAMETERS

<start> <end> Specify the start and end addresses in Flash for enabling/disabling write protection.

<N>:<SF>-<SL> Specifies the first and the last sectors from in Flash bank <N> for enabling/disabling write protection.

bank <N> Specifies the Flash bank enabling/disabling write protection.


None

SUMMARY

The protect command is used to enable or disable the Flash write protection. If issued with the all parameter, the protect command enables or disables write protection for all the Flash banks.

EXAMPLES

The following example demonstrates how sectors 5 up to 7 of the Flash bank are protected, and then the protection of all Flash sectors is disabled.

dm320evm # flinfo Bank # 1: TOSHIBA AM29LV160B (16 Mbit, bottom boot sect) Size: 2 MB in 35 Sectors Sector Start Addresses: 00100000 (RO) 00104000 (RO) 00106000 (RO) 00108000 (RO) 00110000 (RO) 00120000 00130000 00140000 00150000 00160000 00170000 00180000 00190000 001A0000 001B0000 001C0000 001D0000 001E0000 001F0000 00200000 00210000 00220000 00230000 00240000 00250000 00260000 00270000 00280000 00290000 002A0000 002B0000 002C0000 002D0000 002E0000 002F0000 (RO)


dm320evm # protect on 1:5-7 Protect Flash Sectors 5-7 in Bank # 1 dm320evm # flinfo Bank # 1: TOSHIBA AM29LV160B (16 Mbit, bottom boot sect) Size: 2 MB in 35 Sectors Sector Start Addresses: 00100000 (RO) 00104000 (RO) 00106000 (RO) 00108000 (RO) 00110000 (RO) 00120000 (RO) 00130000 (RO) 00140000 (RO) 00150000 00160000 00170000 00180000 00190000 001A0000 001B0000 001C0000 001D0000 001E0000 001F0000 00200000 00210000 00220000 00230000 00240000 00250000 00260000 00270000 00280000 00290000 002A0000 002B0000 002C0000 002D0000 002E0000 002F0000 (RO) dm320evm # protect off all Un-Protect Flash Bank # 1 dm320evm # flinfo Bank # 1: TOSHIBA AM29LV160B (16 Mbit, bottom boot sect) Size: 2 MB in 35 Sectors Sector Start Addresses: 00100000 00104000 00106000 00108000 00110000 00120000 00130000 00140000 00150000 00160000 00170000 00180000 00190000 001A0000 001B0000 001C0000 001D0000 001E0000 001F0000 00200000 00210000 00220000 00230000 00240000 00250000 00260000 00270000 00280000 00290000 002A0000 002B0000 002C0000 002D0000 002E0000 002F0000 dm320evm #

4.3.16. erase

Erase Flash memory.

SYNOPSIS erase <start> <end>

erase <N>:<SF>-<SL>

erase bank <N>

erase all

PARAMETERS

<start> <end> Specify the start and end addresses in Flash for memory to be erased.

<N>:<SF>-<SL> Specifies the first and the last sectors from in Flash bank <N> to be erased.

bank <N> Specifies the Flash bank to be erased.


None

SUMMARY

The erase command is used to erase the Flash memory. If issued with the all parameter, the erase command clears all the Flash banks.


EXAMPLES

The following command erases a Flash region starting at offset 0x00120000:

dm320evm # erase 00120000 002effff Erase Flash from 0x00120000 to 0x002effff ......... done Erased 29 sectors dm320evm #

4.3.17. flinfo

Print the Flash memory information.

SYNOPSIS flinfo [<N>]

PARAMETERS

<N> Specify the memory bank in Flash to be printed.


None

SUMMARY

The flinfo command is used to print the Flash memory information. If no parameter is specified, the flinfo command prints information for all the Flash banks.

EXAMPLES

The following command prints the Flash memory information: dm320evm # flinfo Bank # 1: TOSHIBA AM29LV160B (16 Mbit, bottom boot sect) Size: 2 MB in 35 Sectors Sector Start Addresses: 00100000 (RO) 00104000 (RO) 00106000 (RO) 00108000 (RO) 00110000 (RO) 00120000 00130000 00140000 00150000 00160000 00170000 00180000 00190000 001A0000 001B0000 001C0000 001D0000 001E0000 001F0000 00200000 00210000 00220000 00230000 00240000 00250000 00260000 00270000 00280000 00290000 002A0000 002B0000 002C0000 002D0000 002E0000 002F0000 (RO) dm320evm #

4.3.18. mtest

Simple RAM test.

SYNOPSIS mtest


PARAMETERS

None


None

SUMMARY

The mtest command performs simple SDRAM read/write test.

EXAMPLES

The following command starts a simple SDRAM read/write test:

dm320evm # mtest Pattern 00000000 Writing... Reading... Pattern FFFFFFFF Writing... Reading... Pattern 00000001 Writing... Reading... Pattern FFFFFFFE Writing... Reading... Pattern 00000002 Writing... Reading... Pattern FFFFFFFD Writing... Reading... Pattern 00000003 Writing... Reading... Pattern FFFFFFEC Writing... Reading... Pattern 00000004 Writing... Reading... ...

4.3.19. reset

Reset the CPU.

SYNOPSIS reset

PARAMETERS

None


None

SUMMARY

The reset command performs reset of the CPU.

EXAMPLES

The following command resets the CPU: dm320evm # reset U-Boot 0.2.2 (Mar 24 2004 - 21:53:49) U-Boot code: 01800000 -> 0181381C BSS: -> 01816B30 DRAM Configuration: Bank #0: 00900000 16 MB


Flash: 2 MB dm320evm #

4.3.20. version

Print monitor version.

SYNOPSIS version

PARAMETERS

None


None

SUMMARY

The version command is used to print the monitor version.

EXAMPLES

The following command prints the monitor version:

dm320evm # version U-Boot 0.2.2 (Mar 22 2004 - 22:30:22) dm320evm #

4.3.21. help

Print online help.

SYNOPSIS help [<command>]

PARAMETERS

<command> Displays usage information for the command <command>


None

SUMMARY

The help command is used to print online help.

EXAMPLES

The following command displays online help for setenv:


dm320evm # help setenv setenv name value ... - set environment variable 'name' to 'value ...' setenv name - delete environment variable 'name' dm320evm #

4.3.22. ?

Print online help.

SYNOPSIS ?

PARAMETERS

None


None

SUMMARY

The ? command is used to print online help.

EXAMPLES

The following command prints online help:

dm320evm # ? autoscr - run script from memory base - print or set address offset bdinfo - print Board Info structure bootm - boot application image from memory bootp - boot image via network using BootP/TFTP protocol bootd - boot default, i.e., run 'bootcmd' cmp - memory compare coninfo - print console devices and informations cp - memory copy crc32 - checksum calculation echo - echo args to console erase - erase FLASH memory flinfo - print FLASH memory information go - start application at address 'addr' help - print online help iminfo - print header information for application image loadb - load binary file over serial line (kermit mode) loads - load S-Record file over serial line loop - infinite loop on address range md - memory display mm - memory modify (auto-incrementing) mtest - simple RAM test mw - memory write (fill) nm - memory modify (constant address) printenv- print environment variables protect - enable or disable FLASH write protection rarpboot- boot image via network using RARP/TFTP protocol reset - Perform RESET of the CPU run - run commands in an environment variable


saveenv - save environment variables to persistent storage setenv - set environment variables sleep - delay execution for some time tftpboot- boot image via network using TFTP protocol and env variables ipaddr and serverip version - print monitor version ? - alias for 'help' dm320evm #


5. Introducing the ARM Injector Monterey Linux can be used with the PPS ARM Injector device1. Monterey Linux utilizes the ARM Injector device for target installation, development, debugging, and manufacturing.

This chapter provides a high-level overview of the ARM Injector architecture. For completeness and convenience of use, a reference for the ARM Injector Linux utilities included in the Monterey Linux distribution is provided.

Note: Since USB support is present only in version 2.4 Linux kernels, use of the ARM Injector device is possible only on Red Hat 7.x and SuSE 7.x (or newer) Linux hosts.

5.1. Intended Use

The ARM Injector is an indispensable tool for engineers who work with JTAG enabled target systems based on an ARM processor core with Debug and EmbeddedICE capability. The ARM Injector provides JTAG emulation, opto-isolated relays, target reset, and UART serial connectivity to a target development system via a single USB link. In addition, the ARM Injector can operate in “stand-alone” mode, powered by the target connection, and providing JTAG control commands to the target hardware from an on-board MultiMedia Flash card device. This stand-alone feature allows the ARM Injector to be used in automated post-engineering tasks such as manufacturing and test.

The ARM Injector has practical use in development, debugging, manufacturing, field service, and remote control of ARM based products.

1 ARM Injector is not included in Monterey Linux but can be purchased separately from Pigeon Point Systems.

Chapter

5


5.2. Operational Modes

The ARM Injector can operate in two modes:

USB Connected: In this mode, the ARM Injector is powered from a USB cable attached to a development host. Utilities on the Monterey Linux development host system interactively control the ARM target via the ARM Injector.

Stand-alone: In this mode, the ARM Injector is powered from the target connector, and is detached from the USB host. Operation of the Injector is controlled from JTAG commands stored in on-board MMC Flash.

5.3. Target Hardware Interfaces

The ARM Injector implements the following hardware interfaces to an ARM target:

JTAG

UART serial link

Reset

Opto-isolated relays for target jumper control

Power supply input

The ARM Injector supports hot plugging of the target interface.

The target interface is implemented as two separate connectors.

The JTAG connector provides an industry-standard 14-pin interface to the target JTAG port

The Auxiliary I/O connector implements the serial link, opto-isolated relays, target reset control, and power supply input.

5.3.1. JTAG Connector Summary

The following table details the pin outs of the JTAG connector.


Pin (on the target

side of the 14-pin ribbon

cable)

Signal Type Description

13 RTCK In Return Test Clock signal from the target JTAG port to the ARM Injector. This signal is used by the ARM Injector firmware to dynamically control the TCK rate. Targets that do not need adaptive clock timing may simply ground this pin or connect it to the TCK signal (pin 9).

11 TDO In Test Data Out signal from the target JTAG port to the ARM Injector.

9 TCK Out Test Clock signal from the Injector to the target JTAG port. This pin should be pulled to a defined state on the target.

7 TMS Out Test Mode Select signal from the Injector to the target JTAG port. This pin should be pulled up on the target.

5 TDI Out Test Data In signal from the ARM Injector to the target JTAG port. It is recommended that this pin be pulled to a defined state on the target.

3 /TRST Out Test port reset. Open drain output from the ARM Injector to the Reset signal on the target JTAG port. This pin should be pulled up on the target.

1 V3 Power +3.3 V power input supply to the Injector in standalone mode. The Injector draws its supply current from this pin directly if no other power source is available. This pin is also used in the USB-tethered mode to detect the target presence and power-on state. If the target supply voltage or its current is insufficient, the Injector must be powered via the USB bus.


Pin (on the target

side of the 14-pin ribbon

cable)


14, 12, 10, 8, 6, 4, 2

Gnd Power Ground

Table 7: ARM Injector JTAG Connector

5.3.2. Auxiliary I/O Connector Summary

The following table details the pin outs of the Auxiliary I/O connector.

Pin (on the

target side of the 16-pin

ribbon cable)


2, 16 Gnd Power Ground

15 SRST OD Open Drain output from the Injector to the target system reset. This pin should be pulled up on the target.

14 RxD In Serial data to the Injector from the target serial port (RS-232)

13 RD In Serial data to the Injector from the target serial port (CMOS)

12 TxD Out Serial data from the Injector to the target serial port (RS-232)

11 TD Out Serial data from the Injector to the target serial port (CMOS)

9, 10 NC1 Opto Normally Closed Pole 1*

7, 8 NO1 Opto Normally Open Pole 1*

5, 6 NC0 Opto Normally Closed Pole 0*


Pin (on the

target side of the 16-pin

ribbon cable)


3, 4 NO0 Opto Normally Open Pole 0*

1 V5 Power +5V power input supply to the Injector in standalone mode. The Injector draws its supply current from this pin via LDO regulator. If the target supply voltage or its current is insufficient, the Injector must be powered via the USB bus.

Table 8: ARM Injector Target Auxiliary I/O Connector

*Note: Each NO/NC Pole is a target side of the Clare OptoMOS Relay (Form A and Form B respectively) and is controlled individually. Alternatively, NO and NC Poles may be combined to form one Form C relay.

5.4. Functional Block Diagram

The following block diagram summarizes the interfaces of the ARM Injector:

ARM InjectorUSBHost Target

SanDiskMMC

USB Device

Serial Opto-Relays

Auxilary I/O Interface

JTAGJTAG

Figure 2: Function Block Diagram


5.5. Target I/O Interfaces

The firmware running on the ARM Injector device implements a number of interfaces. These connections are made both over the JTAG physical interface and the AUX physical interface (refer to section 5.3).

5.5.1. JTAG Interface

The JTAG interface is a standard IEEE1149.1-compliant target JTAG interface. Its primary use is debugging of the target in non-intrusive mode over the JTAG.

Additionally, the JTAG interface can be used as a communication channel for exchange of data between the ARM Injector and a running ARM9 target. The ARM Injector uses this mode of operation to provide a number of virtual (emulated), multiplexed serial connections between the target and the development host over the JTAG port.

5.5.2. Serial Interface

The ARM Injector provides a number of serial interfaces on the Linux development host using a single USB connection. The following table gives the relationshipbetween the USB serial device nodes on the Linux host and the ARM Injector serial interfaces:

USB Serial Node Injector Port Notes

/dev/ttyUSB0 Target COM port Physical serial port using the pins on the Auxiliary I/O port

/dev/ttyUSB1 gdbserver port The ARM Injector firmware uses this port to present the ARM target to the host as a GDB stub accessible over a serial port

/dev/ttyUSB2 JTAG-emulated serial port 1 Implemented over the JTAG port

/dev/ttyUSB3 JTAG-emulated serial port 2 Implemented over the JTAG port

Table 9: ARM Injector Serial Interfaces


Note that in order to use the ARM Injector serial interfaces, the usbserial kernel module must be installed on the host. To do this, execute the following command (requires root priveleges):

bash# insmod usbserial vendor=0x116b product=0x414c

Note: Some kernels (e.g. 2.4.18 in RedHat 7.3) have a bug in the USB serial driver that causes a system lock-up when a USB serial device is closed. For instance, if kermit is run on such a system, it will hang up immediately, creating an unkillable process. This problem can be fixed by updating to a more recent version of the Linux kernel, or by making the following modifications to the /usr/src/linux-2.4/drivers/usb/serial/usbserial.c file:

Find the generic_close() function definition.

In this function, find the line containing the down (&port->sem) operator and delete it.

In the same function, find the line containing the up (&port->sem) operator and delete it.

Note that the usbserial.o module must be rebuilt and restarted for the above changes to take effect. If it is compiled into the kernel, the whole kernel must be rebuilt and restarted.

5.5.3. Opto-Isolated Relays

The ARM Injector provides a number of optoisolated relays for control of the target. The optoisolated relays are used by the ARM Injector as follows:

Relay Auxiliary I/O Signal Target Connection

0 normally-open relay 0 (NO0) Target reset

1 normally-open relay 1 (NO1) Target power control

2 normally-closed relay 0 (NC0) User defined

3 normally-closed relay 1 (NC1) User defined

Table 10: ARM Injector Optoisolated Relays

Note that the first relay (NO0) is reserved for target reset control, and should be connected to the target reset control signal in order for the ARM Injector software to function correctly.

The second relay (NO1) is normally used for target power control but can be reassigned without any negative impact on the Injector functionality.


Note: On the DM320/DM342 EVM board a remote power control is impossible, and the NO1 relay is available for custom use.

5.6. ARM Injector LEDs

The ARM Injector has 3 on-board LEDs, maintained by the firmware in the following manner:

Yellow

JTAG activity, target connection indicator. When blinking, data is being transferred over the JTAG port. When permanently lit, the target connection is not established (e.g. no cable, target is down, etc.).

Green

USB/MMC activity. When blinking, data is being transferred over the USB port, or to/from the Injector MMC device.

Red

General failure indicator.

Upon device connection, all three LEDs should flash several times, indicating that the Injector firmware is up and running.

The following table shows ARM Injector operational states:

Yellow Green Red Mode Description

OFF ON OFF Standalone Standalone programming completed successfully

OFF OFF ON Standalone Standalone programming failed

OFF ON ON Standalone Injector is not imprinted, or manufacturing counter exceeds limit

ON X X Any Target is not connected


Yellow Green Red Mode Description

OFF OFF ON USB-connected Fatal firmware failure: Injector needs to be reconnected

OFF OFF BLINK USB-connected Operation failed

Table 11: ARM Injector LED Conditions

Note: In the above table ON means "permanently lit", and BLINK means "steady blinking".

5.7. Intended Application

The ARM Injector is a tool that can be used during all phases of Monterey Linux based product development and deployment. The sections below identify some of these possible uses.

5.7.1. Development Tool

When connected to a target board, the ARM Injector and associated development host toolset provide unmatched development convenience. The ARM target device can be completely controlled via a single USB connection, thereby speeding development and freeing the developer from needing to maintain close proximity to the target board (e.g. reaching over and switching jumpers, pressing reset, etc). Repetitive actions such as loading Flash or configuring a booted Linux operating system via a serial port login can all be automated from the development host using shell scripting languages.

For remote developers who are collaborating on ARM product development via network connections, the ARM Injector provides a convenient way for them to completely control the target device. Through a serial port connection to the target monitor, these remote developers can share development systems with local developers, and not require local assistance for setting up or rebooting the device.

5.7.2. Debug Tool

The Monterey Linux GDB debug capability makes the ARM Injector a perfect debugging tool for a Linux host based development environment. The GDB debugging feature of the ARM Injector allows debugging ARM targets at all levels, from the initial firmware debugging and bring-up of targets up to source-level debugging of OS kernels and applications. Refer to Chapter 7 for details.


5.7.3. Testing Automation Tool

The same features that make the ARM Injector an excellent development tool also make it a good device for testing ARM based products. Test suites can be developed that automatically load a version of the target software onto the ARM target, and exercise them via the serial or other login channels (e.g. Ethernet). These test suites can have complete scripted control of the loading and execution of all software on the device, from firmware on up.

A single test machine can potentially control several ARM Injector devices on the USB bus, thereby consolidating the test machine and not requiring expensive serial port servers (using less expensive USB hubs instead).

5.7.4. Field Service Tool

In stand-alone mode, the ARM Injector can be an indispensable field service tool. Software updates can be created as JTAG records, and programmed into the onboard Flash card via the USB connection to the host. Once disconnected, the ARM Injector becomes a stand-alone upgrade device that is capable of performing Flash updates or other arbitrary programs. A typical Field Update would involve bringing an appropriately programmed ARM Injector to the customer site, plugging it into the connector on the target equipment and powering up. The ARM is controlled via the JTAG interface. Three LEDs provide status and can report successful or non-successful updates.

In situations where a laptop PC with Monterey Linux installed on it is available as part of the Field Service, the ARM Injector can run as a tethered USB device, and perform additional diagnostic activities via the serial port, or via programs loaded from the host.

5.7.5. Manufacturing Tool

One issue confronting companies is the design of the software manufacturing process line. Traditionally single or multiple “golden” software images need to be programmed into the end product, but customized with distinct software identifiers such as a serial number or network MAC address. An example of this might be an embedded Linux internet device that rolls off the production line and needs to have its Linux image programmed into Flash with a unique serial #, MAC address, and potentially a host name and initial IP address.

The ARM Injector firmware has been designed to support this important need by implementing the following scheme.

The ARM Injector USB firmware maintains an integer counter and a counter limit in the ARM Injector Flash device.

The counter and the counter limit can be set and read from the host when the ARM Injector is attached to the USB bus.


Each time an ARM target is programmed in stand-alone mode, the ARM Injector increases the internal counter by one. If the counter reaches the limit, the ARM Injector stops functioning as a stand-alone programming device and indicates this through the onboard LEDs to the operator.

The current value of the counter is supplied to the target as a parameter command each time the image is transferred to the target from the ARM Injector MMC Flash device. This value is then available to target programs such as the Flash programming code to use when generating serial numbers or MAC addresses, etc.

As an example of using the ARM Injector for a manufacturing line, suppose there is a need to manufacture 1000 ARM target boards with a unique serial number (e.g. 0-999) and a unique MAC addresses (e.g. x:x:x:n1:n2:x). The goal is to do this from a single Flash “master” (that is. not requiring unique Flash images for each of the 1000 targets). The process is performed using 10 separate ARM Injectors in parallel (as a way of increasing manufacturing line throughput). As a first step in preparing these 10 Injector devices, they are each connected to the USB host, and each assigned a starting counter of N*100, and limit counter of N*100+99. That is, Injector 1 handles programming 0-99, Injector 2 handles programming 100-199, and so on. The “golden” Flash image that is to be programmed into the target systems is loaded via the USB cable into the ARM Injector onboard Flash.

When an ARM Injector is used as a stand-alone device to program targets, it passes the current counter value to the target Flash programming software as a parameter and increases the counter number in the ARM Injector Flash. The user-defined portion of the target Flash programming software interprets the counter in target-specific way (e.g. as a value of serial number and as a piece of the target MAC address), modifies the image it read from the Injector with the target software identifiers, and then programs the image to Flash.

When the counter reaches its limit, the ARM Injector ceases to function in stand-alone mode, thus preventing manufacturing more than one "identical" board.


ARM Injector

ARMUART

Flash

PC Computer

USB bus

User-definedtarget counter

Flashprogramming

code

JTAG

Target Reset

standalone mode

Firmware

SPI Flash serial line

target serial console

Firmware/OS image

target images

target images

target image

target control

Opto-isolated relays

Power Input

Figure 3: ARM Injector Control and Data Flows

5.8. ARM Injector Command Reference

This section provides a command summary for the ARM Injector “inj” utility. .

5.8.1. inj

NAME

inj – a collection of ARM Injector host utilities combined into a single executable

SYNOPSIS inj <command> [OPTIONS] <inj_spec>

DESCRIPTION

inj is a common invocation prefix for all ARM Injector management utilities. Running inj without arguments will list all the available sub-commands. For a detailed description of any sub-command, please refer to the corresponding manual page (e.g. man inj_info, or man inj_ctl, etc.)

Each ARM Injector command requires a mandatory <inj_spec> argument. This argument specifies which ARM Injector device to work with (more that one Injector might be attached to a system). An ARM Injector specification can be in one of the following formats:

<VendorID>:<ProductID>

where <VendorID> and <ProductID> are the vendor and product IDs of the corresponding USB device. Example: 116b:414c


/<bus>/<num>

where <bus> is the bus number and <num> is the device number of the corresponding USB device. Example: /1/56

<symbolic_name>

A symbolic name of the corresponding USB device. Symbolic names are defined in the $CDE_ROOT/etc/injector/devices file. This file contains text lines of the form:

<name> <spec>

where <name> is the symbolic name being defined, and <spec> is the corresponding USB device specification. Examples: loader, injector

OPTIONS

-h,--help Print a help message.

-v, --verbose Verbose mode.

Apart from -h and -v, each sub-command has its own set of command line options. Please refer to the corresponding manual pages for more details.

5.8.2. inj info

NAME

inj info – report information about one or more USB devices connected to the host system

SYNOPSIS inj info [OPTIONS] [<inj_spec>]...

DESCRIPTION

The inj info command prints information about one or more USB devices connected to the host system. This information includes:

Bus and device numbers

Vendor and product IDs

Revision and serial numbers.

If the <inj_spec> argument is omitted, inj info -a lists all USB devices connected to the host system.

An example output of the inj info -a command is given below:

- /001/001 0000:0000:00.00 #10a0 - /001/031 116B:414C:100.01 #PPS-001


The first line corresponds to a virtual root HUB, and the second line corresponds to an ARM Injector device (all ARM Injector devices have the same vendor/product IDs, specifically, 0x116B and 0x414C).

Refer to section 5.8.1 for a description of the <inj_spec> argument.

OPTIONS


-a, --all List all USB devices connected to the host system.

5.8.3. inj ctl

NAME

inj ctl – target reset/power and opto-isolated relays control

SYNOPSIS inj ctl [OPTIONS] <inj_spec>

DESCRIPTION

The inj ctl command is used to control target power/reset lines and opto-isolated relays. The ARM Injector device provides four opto-isolated relays with user-defined functionality: the first two are "open" by default, and the rest are "closed". Note that the first two relays are normally reserved to drive the reset/power pins.


OPTIONS



-r, --reset Perform target reset.

-p, --power [on|off] Control target power line status.

Example: inj ctl -p on -- turn on the target board.


-<N> [on|off] Control the opto-isolated relay number N. The opto-isolated relays are enumerated as follows:

0 – normally-open relay 0 (NO0)

1 – normally-open relay 1 (NO1)

2 – normally-closed relay 0 (NC0)

3 – normally-closed relay 1 (NC1)

Note that the first two relays are reserved for target power/reset control, and should not normally be activated manually. Any number of -<N> options can be specified in a single command. For example: inj ctl -2 on -3 off

Note, however, that reassigning the function of NO0 (normally-open relay 0) could have a negative effect on the Injector functionality. Specifically, if NO0 is not connected to the target reset pin, target Flash programming might fail in some situations.

5.8.4. inj install

NAME

inj install – installs an image into target or Injector Flash

SYNOPSIS inj install [OPTIONS] <inj_spec>

DESCRIPTION

The inj install command is used to install images into the target or ARM Injector Flash devices. The first form of this command can be used to install a firmware image (such as ARMboot) into target Flash. The second form (selected by the -I option, see below) prepares an ARM Injector device for stand-alone operation (this process is called "imprinting" an ARM Injector device). A previously imprinted ARM Injector device can be used for target Flash programming, without the need for a USB host connection, by connecting directly to the target JTAG connector without a corresponding USB connection.

Target Flash programming involves running a target application called a Flash programming agent. Prior to downloading this application into target RAM, the ARM Injector software must perform target RAM initialization. This procedure is controlled by a text file named initscript (located in the $CDE_ROOT/etc/injector/ directory by default). The init script file that comes with the Monterey Linux distribution contains the RAM initialization sequence for the DM320/DM342 EVM board.


Init script file format summary:

# Starts a comment. *<addr> = <value> Writes <value> to target memory at <addr>.

Example: *0xffff2e00 = 0x000004c5 r<N> = <value> Sets register <N> contents to <value>.

Example: r5 = 0x100 lr = <value> Sets the link register to <value>. sp = <value> Sets the stack pointer to <value>. base = <value> Specifies a base RAM address. delay <N> Performs a short delay (N/100 sec).


OPTIONS



-q, --quiet Do not ask for confirmation.

-I, --imprint Imprint an ARM Injector device for stand-alone operation.

-i, --init-script=<file> Specify a custom init script file. The default init script resides in the $CDE_ROOT/etc/injector/ directory.

-p, --flash-prog=<file> Specify a custom Flash programmer image (must be in the ELF format). By default, the $TARGET_ROOT/boot/fprog.elf image is used (comes with the Monterey Linux distribution).

-f, --file=<file> Specify a custom image file to be programmed into target Flash. By default, the $TARGET_ROOT/boot/u-boot.bin file is used (comes with the Monterey Linux distribution).

-c, --counter=<value> Specify a manufacturing counter value. Please see the inj_mfg manual page for more information on this parameter. If the -c option is omitted; a zero counter will be used.


-l, --limit=<value> Specify a manufacturing counter limit. Please see the inj_mfg manual page for more information on this parameter. If the -l option is omitted, a -1 value will be used (e.g. no limit).

-a, --address=<value> Specify a target Flash offset (in bytes) where the image file should be programmed. By default, the image is placed at the beginning of Flash, which is equivalent to specifying a zero offset (-a = 0)

-d, --descr=<str> Specify a custom image description. Please see the inj_mfg manual page for more information on this parameter. If the -d option is omitted; the description field will contain the absolute host path to the image being programmed.

5.8.5. inj mfg

NAME

inj mfg – manipulates manufacturing parameters stored in the ARM Injector device

SYNOPSIS inj mfg [OPTIONS] <inj_spec>

DESCRIPTION

The inj mfg command is used to obtain/modify the manufacturing parameters stored in the ARM Injector device. These parameters include two integer values and one string value, which are, respectively: the manufacturing counter, manufacturing limit and image description. The manufacturing counter is an integer value that is passed on to the target software agent (in general purpose register "r3", or as the fourth argument to the entry function) and is incremented after each successful stand-alone programming session. This value can be interpreted by the target Flash programming agent to produce unique Flash installations.

The manufacturing counter limit is a value that specifies the upper bound of the manufacturing counter. When the manufacturing counter reaches this value, the ARM Injector device stops functioning in stand-alone mode, and reports solid RED and GREEN LEDs when plugged in. An Injector that has reached its limit can be reconnected to the development host via the USB cable, and reprogrammed with new limits. A value of -1 means no limit.

An image description is a text string identifying the image stored on an Injector MMC card. Image descriptions are used for convenience only, and are not interpreted in any way.


The manufacturing parameters are stored in the first sector of the ARM Injector MMC card. When the card is replaced, the new parameters (that is, those associated with the image stored on the new card) will take effect immediately.


OPTIONS



-c, --counter=<value> Specify a new manufacturing counter value.

-l, --limit=<value> Specify a new manufacturing limit value.

-d, --descr=<str> Specify a new image description.

5.8.6. inj fwload

NAME

inj fwload – loads firmware onto an ARM Injector device

SYNOPSIS inj fwload [OPTIONS] <inj_spec>

DESCRIPTION

The inj fwload command is used to load firmware onto an ARM Injector device. This procedure must be performed each time the device is connected to the host system. If your system supports USB hot plug, it can be configured to perform this step automatically upon a device connection. Please refer to 5.9.3 for detailed instructions on how this can be done.


OPTIONS



-f, --file=<file> Specify a firmware image file name.


5.9. Configuring the Monterey Linux Development Host for the ARM Injector

5.9.1. Configuring a Host System with Hot Plug Support

Before the ARM Injector device can be used, the Linux host system must be configured appropriately. To do this, step through the following procedure (it is assumed that USB support is compiled into your kernel):

1. Ensure that your system supports USB hot plug. This can be done by typing cat /proc/sys/kernel/hotplug. If USB hot plug is enabled, this file will be present. If USB hot plug is disabled, either enable it in the kernel configuration (enable the Support hot-pluggable devices option in the General setup menu) or skip to the following section.

2. Add the following line to the /etc/hotplug/usb.usermap file (this requires root permissions):

fwload 0x3 0x116b 0x414b 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0

3. In the /etc/hotplug/usb directory, create a new file named fwload with the following contents:

#!/bin/sh <CDE_ROOT>/usr/bin/inj fwload -f <CDE_ROOT>/etc/injector/fw.hex 116b:414b

where <CDE_ROOT> must be replaced with the absolute path to the Monterey Linux installation directory.

Note that the /etc/hotplug/usb/fwload file you create should be given execute permissions.

5.9.2. Configuring a Host System without Hot Plug Support

If your Linux host system does not have support for hot plugging, it is still possible to use the ARM Injector device. However, every time it is plugged into the host USB port, the following command will have to be executed from the Monterey Linux environment:

inj fwload -vf $CDE_ROOT/etc/injector/fw.hex loader


An example output of this command is shown below:

ML(arm926ejs):[tester@host1]$ inj fwload -vf $CDE_ROOT/etc/injector/fw.hex loader Loading firmware from file /ML/etc/injector/fw.hex...done (transfered 1162 packets, 18289 bytes total) ML(arm926ejs):[tester@host1]$

5.9.3. Accessing ARM Injector as a Regular User

By default, the USB nodes corresponding to ARM Injector devices are given read-only permissions for a regular user. This means that on such a system most ARM Injector commands must be executed as root. However, it is possible to set up the hotplug system to change permissions upon device connection. To do this, perform these two steps:

1. Add the following line to the /etc/hotplug/usb.usermap file (requires root permissions):

chmode 0x3 0x116b 0x414c 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0 0x0

2. In the /etc/hotplug/usb directory, create a new file named chmode with the following contents:

#!/bin/sh chmod a+w $DEVICE

Note that the /etc/hotplug/usb/chmode file should be given execute permissions.

5.10. ARM Injector Troubleshooting

Thje following table provides the ARM Injector troubleshooting information:

Problem Solution

The ARM Injector stops responding, and the usb_control/bulk_msg: timeout messages appear on the host console.

Reconnect the Injector on the host USB interface.

Linux kernel crashes when an ARM Injector device is plugged in.

Try upgrading to a newer Linux kernel. If this does not help contact Customer Support with details of your system setup (kernel version, USB controller information, etc).


Problem Solution

kermit hangs up when connecting to a USB serial port.

Some kernels (e.g. 2.4.18-3 in RedHat 7.3) have a bug in the USB serial driver that causes a system lock-up when a USB serial device is used. Please refer to Note on page 5-74 for more details. Upgrate to a newer Linux kernel on the host, or fix the problem manually.

During target power off/on, the Injector disappears from the USB bus.

Disconnect the power input wires from the target board. When the Injector is powered from both the USB and the target, it gets reset when a target power cycle occurs.

Table 12: ARM Injector Troubleshooting


6. Installing Monterey Linux Images on the DM320/DM342 EVM Board This section explains how to install Monterey Linux images on the DM320/DM342 EVM reference platform. The first step in the procedure is to install the ARMboot firmware. Once ARMboot is installed on the board, it can be used to further install Monterey Linux kernels and file system images into RAM or Flash.

Monterey Linux emphasizes use of the ARM Injector (refer to Chapter 5) for installation of the initial ARMboot binary to the DM320/DM342 EVM reference platform. As an alternative means of installation, this chapter explains how you can install ARMboot on the target using Texas Instruments' emulator tools (hardware JTAG emulators and the Code Composer Studio Integrated Development Environment).

6.1. Setting Up Target Hardware

This section describes setting up the DM320/DM342 EVM board hardware in preparation for loading Monterey Linux images.

6.1.1. DM320/DM342 EVM Board Jumpers

The following jumper settings should be configured on the DM320/DM342 EVM board to allow programming of the ARMboot firmware image:

Jumper Settings Description

SW4 3 JTAG Debug Configuration BJ4 2-3 JTAG Header Configuration SW1 2-5 Flash on Base Board

Table 13: DM320/DM342 EVM Board Jumpers

Chapter

6


For more details on the DM320/DM342 EVM board switches and jumpers, please refer to the corresponding board documentation.

6.1.2. Serial Interface

The DM320/DM342 EVM board has two onboard serial ports (connectors RS232C_UART0 and RS232C_UART1). The first serial port (RS232C_UART0) is utilized throughout the installation process, as the console for ARMboot and Monterey Linux. A serial cable connection (male-to-female, 9-pin, straight-through) to this port is necessary.

A terminal program (such as kermit) on the development host should be configured to 115200 bps, 8bits, no parity, 1 stop bit, and no flow control.

6.1.3. Ethernet Interface

The DM320/DM342 EVM board Ethernet port (connector 10BASE-T1) must be hooked-up to a LAN that includes a TFTP server host.

The installation procedure uses this Ethernet connection to download images from the TFTP host to the target.

6.1.4. JTAG Interface

The BB_JTAG interface of the DM320/DM342 EVM board must be connected either to the JTAG port of the ARM injector device or to a Windows host machine running Code Composer Studio v2.1 for OMAP.

Note: Contact Texas Instruments for the software patches to Code Composer Studio required to support DM320/DM342.

6.1.4.1. Connecting the Target JTAG Port to the ARM Injector If the ARM Injector will be used to load ARMboot, then DM320/DM342 EVM JTAG connector needs to be connected to the Injector “JTAG” port using the Injector 14 pin ribbon cable. The following table summarizes the signal connections that must be made:


ARM Injector: JTAG DM320/DM342 EVM: BB_JTAG

Pin Number Pin Name Pin Number Pin Name

3 JTRST 2 PPTRST 5 JTDI 3 PPTDI 7 JTMS 1 PPTMS 9 JTCK 11 PPTCK 11 JTDO 7 PPTDO 2, 4, 6, 8, 10, 12, 14

GND 4, 8, 10, 12 GND

Table 14: ARM Injector to DM320/DM342 EVM Signal Connections

In addition, for target Flash programming to work reliably, the NO0 opto-isolated relay of the ARM Injector device (pins 3 and 4 of the AUX connector) must be connected to the Reset button on the DM320/DM342 EVM board (BBRESET SW1).

6.1.4.2. Connecting the Target JTAG Port to TI's Emulator Tools The DM320/DM342 EVM board has a standard TI JTAG connector (BB_JTAG), which can be used to attach emulation devices manufactured by TI. Typically, it would be a PCI-based JTAG emulator such as the XDS560. The XDS560 can be installed in a host PCI slot, and the target cable/Pod connects the XDS560 PCI card with the target JTAG interface.

6.2. Setting Up the Development Hosts

6.2.1. Monterey Linux Development Host

The installation procedure requires a Monterey Linux development platform running on a Linux host meeting the requirements specified in Chapter 2, with fully installed and activated Monterey Linux on it.

It is expected that the Monterey Linux development host will be used to:

Connect to the serial port of the target and provide the target serial console (via kermit, minicom, or similar utility). Refer to 2.7.1 for suggestions on how to obtain the kermit serial terminal application for your Linux host.

Provide TFTP host services for download of images to the target. Refer to 2.7.2 for a description of the procedure used to enable TFTP on your Linux host.


Connect to the USB port of the ARM Injector device, in case you decide to use the ARM Injector for installation of ARMboot to the target. Refer to Chapter 5 for description of the procedure used to configure the ARM Injector on your Linux host.

6.2.2. Windows Host

In case you decide to use the Texas Instruments emulator tools to install ARMboot on the target, the procedure requires a Windows PC with Code Composer Studio 2.1 for OMAP (and the DM320/DM342 specific patches; refer to 6.1.4) installed and running on it. There must be a connection to the DM320/DM342 EVM target JTAG interface from the Windows box. Refer to 6.1.4 for details.

You must copy the ARMboot binary from the Monterey Linux development host to the Code Composer directory on the Windows host. On the Monterey Linux host, the ARMboot binary is $TARGET_ROOT/boot/u-boot.elf.

6.3. Installing Monterey Linux Using the ARM Injector

6.3.1. ARM Injector Set Up Summary

The following diagram illustrates the connections required to install Monterey Linux on the target using the ARM Injector:

Figure 4: ARM Injector Set Up Summary

Serial Console( kermit , cu, etc)

DM320/DM342 EVM

“Flying Leads” cables

Ethernet link(for TFTP downloads)

Linux PC

Monterey LinuxDevelopment Host

JTAG

Serial Ethernet

LAN

USBhost

ARM Injector

USB

JTAG AUX

Reset button(BBRESET SW1)

(BB_JTAG)


6.3.2. ARM Injector Installation Procedure Overview

The following steps are used for an ARM Injector-based installation of ARMboot:

1. When an inj install command is executed on the Linux host, the ARM Injector performs appropriate target RAM initialization. The initialization is defined by a target specific configuration script residing in $CDE_ROOT/etc/injector/initscript (location of the configuration script can be changed using the -i option to the inj install command). Monterey Linux places an appropriate configuration script for the DM320/DM342 EVM board to the $CDE_ROOT/etc/injector directory, so you should not worry about defining or updating the target script.

2. inj install loads a Flash programming agent binary into the target RAM and prepares it for execution. The Flash programming agent resides in $TARGET_ROOT/boot/fprog.elf (location of the Flash programming agent can be changed using the –p option to the inj install command). Monterey Linux places an appropriate Flash programming agent for the DM320/DM342 EVM board to the $TARGET_ROOT/boot/ directory, so you should not worry about defining or updating the agent.

3. The last stage performed by inj install is transferring the actual image data to the Flash programming agent, which collects it and stores it in consecutive sectors of the target Flash device.

4. Next reset/power-up of the target boots ARMboot from Flash in standalone mode.

5. You can now use the user commands of ARMboot to install Monterey Linux images to Flash or RAM.

6.3.3. Installing ARMboot Using the ARM Injector

This section explains how to install ARMboot to the target Flash using the ARM Injector device.

6.3.3.1. Using the ARM Injector to Program u-boot.bin to Flash To install the ARMboot binary into target Flash, use the following command from the Monterey Linux environment:

inj install <inj_spec>

where <inj_spec> is the specification of an Injector device. Refer to 5.8.4 or type man inj_install from the Monterey Linux development environment for a full description


of this utilty. If there is only one Injector device plugged in, it is safe to use the following specification: injector.

ML(arm926ejs):[tester@host1]$ inj install injector WARNING: old contents of the target Flash device will be lost! Proceed? (y/n) y Progress: [############################################################] (100%) ML(arm926ejs):[tester@host1]$

Otherwise, the inj info -a command should be used to obtain parameters of all connected USB devices. A specification of the form /<bus>/<num> can then be used to attach to a specific Injector device.

For example, the following snapshot shows output of inj info -a for a configuration where two ARM Injector devices are attached to the USB host interface. The lines with the USB Vendor ID of 116B correspond to ARM Injector devices:

ML(arm926ejs):[tester@host1]$ inj info -a - /001/001 0000:0000:00.00 #b400 injector - /001/030 116B:414C:00.00 #001 injector - /001/031 116B:414C:00.00 #002

Once the specification of the target ARM Injector device has been obtained, it should be used as a parameter to the inj install command:

ML(arm926ejs):[tester@host1]$ inj install /1/30 WARNING: old contents of the target Flash device will be lost! Proceed? (y/n) y Progress: [############################################################] (100%) ML(arm926ejs):[tester@host1]$

Note that the inj install command with no -f option assumes that the ARMboot binary resides in $TARGET_ROOT/boot/u-boot.bin. This is where the Monterey Linux installation places the ARMboot binary for the DM320EVM reference board, so you should not have any problems in case you do not specify a -f option. If however you have updated the ARMboot binary and copied it to a directory other than $TARGET_ROOT/boot/, be sure to use the -f option to specify a path to the ARMboot binary.

Another useful option to the inj install command is -v. This enables verbose output (turned off by default).


6.4. Installing Monterey Linux Using Texas Instruments Emulator Tools

6.4.1. TI's Tools Set Up Summary

The following diagram illustrates the configurations you must have set up in order to install Monterey Linux on the target using Texas Instruments emulator tools:

Figure 5: TI Tools Set Up Summary

6.4.2. TI's Tools Installation Procedure Overview

The Texas Instruments tools-based installation works as follows:

1. Code Composer on the Windows machine connects to the target via the JTAG interface.

2. Code Composer initializes the target RAM.

3. Code Composer downloads the ARMboot binary (u-boot.elf) to the target RAM and starts it.

4. ARMboot executes on the target from RAM and provides the ARMboot command interface over the serial console. You can now control ARMboot

Serial Console( kermit , cu , etc )

Ethernet link(for TFTP downloads)

Linux PC

Monterey LinuxDevelopment Host

Serial Ethernet

Windows PC

Code ComposerStudio OMAP

LAN

BB_JTAG

CodeComposer Session

JTAGEmulator

JTAG

DM320/342 EVM


operation from a serial terminal application (such as kermit) on the Linux development host.

5. ARMboot downloads the ARMboot image (u-boot.bin) from the TFTP host to the target RAM.

6. ARMboot programs the u-boot.bin image to the target Flash

7. Next reset/power-up of the target boots ARMboot from Flash in standalone mode.

8. You can now use the user commands of ARMboot to install Monterey Linux images to Flash or RAM.

6.4.3. Installing ARMboot Using TI's Tools

This section explains how to install ARMboot to the target Flash using Texas Instruments emulator tools.

6.4.3.1. Loading u-boot.elf to the Target Using Code Composer Studio On the Linux development host, start a serial terminal application on the serial port connected to the target. For instance, assuming the first serial port of the host is used to connect to the target, do the following:

ML(arm926ejs):[tester@host1]$ kermit -l /dev/ttyS0 –b 115200 -c

On the Windows host, use the following procedure to load the ARMboot binary (u-boot.elf) to the target memory from Code Composer Studio v2.1 for OMAP (if you already have a working CCS configuration for the DM320/DM342 EVM board, skip to step 2):

1. Invoke the Setup Application and select the configuration corresponding to your emulator device. In the Processor Configuration dialog, select TMS470R2x as CPU_1, and BYPASS as BYPASS_DSP (the instruction register size should be 8).

2. Prepare a .gel file (for instance, dm320.gel) for the DM320/DM342 EVM target. This file is needed to configure the target memory and should be as follows:


/*ARM GEL File for the DM320 */ /* Addresses for Clock Controller registers */ #define DM320_CLKC_PLLA 0x30880 /* PLLA */ #define DM320_CLKC_PLLB 0x30882 /* PLLB */ #define DM320_CLKC_SEL2 0x30888 /* SEL2 */ #define DM320_CLKC_BYP 0x30894 /* PLL Bypass */ #define DM320_CLKC_DIV0 0x3088A /* ARM PLL Divider */ #define DM320_CLKC_DIV1 0x3088C /* SDRAM and AXL(cop) Divider */ #define DM320_CLKC_DIV2 0x3088E /* DSP Divider */ #define DM320_CLKC_MOD0 0x30898 /* Module Enable #0 */ #define DM320_CLKC_MOD1 0x3089A /* Module Enable #1 */ #define DM320_CLKC_MOD2 0x3089C /* Module Enable #2 */ /* Values for Clock Controller registers */ #define DM320_CLKC_PLLA_VALUE 0x00D2 /* PLLA: 0x00D1 -> 27 * 14 / 2 = 189.0 MHz */ #define DM320_CLKC_PLLB_VALUE 0x00A2 /* PLLB: 0x00A1 -> 27 * 11 / 2 = 148.5 MHz */ #define DM320_CLKC_SEL2_VALUE 0x0001 /* SEL2: 0x0001 -> AXL, SDR, DSP = PLLA, * ARM = PLLB */ #define DM320_CLKC_BYP_VALUE 0x0000 /* 0x0000 -> NO Bypass */ #define DM320_CLKC_DIV0_VALUE 0x0003 /* 0x0003 -> ARM clock is SYSCLK/4 */ #define DM320_CLKC_DIV0_VALUE2 0x0002 /* 0x0002 -> ARM clock is SYSCLK/3 */ #define DM320_CLKC_DIV1_VALUE 0x0300 /* 0x0300 -> SDRAM clock = SYSCLK, * AXL clock = SYSCLK/4 */ #define DM320_CLKC_DIV1_VALUE2 0x0001 /* 0x0001 -> SDRAM clock = SYSCLK/2, * AXL clock = SYSCLK */ #define DM320_CLKC_DIV1_VALUE3 0x0304 /* 0x0304 -> SDRAM clock = SYSCLK/5, * AXL clock = SYSCLK / 4 */ #define DM320_CLKC_DIV1_VALUE4 0x0103 /* 0x0103 -> SDRAM clock = SYSCLK/4, * AXL clock = SYSCLK / 2 */ #define DM320_CLKC_DIV2_VALUE 0x0300 /* 0x0300 -> DSP clock = SYSCLK/4 */ #define DM320_CLKC_MOD0_VALUE 0x0DF7 /* Enable all except EXHOST and ETM */ #define DM320_CLKC_MOD1_VALUE 0x0FFF /* Enable all clocks */ #define DM320_CLKC_MOD2_VALUE 0x7FFF /* Enable all clocks except TEST */ /* Addresses for SDRAM Controller registers */ #define DM320_SDRC_SDMODE 0x309A6 /* SDRAM Mode Register */ #define DM320_SDRC_REFCTL 0x309A8 /* SDRAM Ref Control Register */ /* Values for SDRAM Controller registers */ #define DM320_SDRC_REFCTL_VALUE 0x0140 /* Refresh command sent after every 145*8 SDRAM clock cycles*/ #define DM320_SDRC_SDMODE_VAL 0xB280 /* SDRAM config - DQM Control = force '1' */ #define DM320_SDRC_SDMODE_NOP 0x0000 /* SDRAM initialization - NOP */ #define DM320_SDRC_SDMODE_MSR 0x0001 /* SDRAM initialization * - Mode Status Register Set */ #define DM320_SDRC_SDMODE_PREA 0x0002 /* SDRAM initialization - Precharge All */ #define DM320_SDRC_SDMODE_AUTOREF 0x0004 /* SDRAM initialization - AutoRefresh */ #define DM320_SDRC_SDMODE_AUTOPDN 0x0040 /* SDRAM initialization - Auto PowerDown */ #define DM320_SDRC_SDMODE_EMRS 0x0011 /* SDRAM initialization * - Extended Mode Register Set */ #define DM320_SDRC_SDMODE_DSNORM 0x0011 /* SDRAM initialization – * Drive Strngth = Normal */ #define DM320_SDRC_SDMODE_DSHALF 0x0111 /* SDRAM initialization – * Drive Strngth = 1/2 */ #define DM320_SDRC_SDMODE_DSQUART 0x0211 /* SDRAM initialization * - Drive Strngth = 1/4 */


#define DM320_SDRC_SDMODE_VALUE32 0x0000 /* SDRAM initialization for MSR for 32 bit * mode and CAS latency of 2 cycles */ #define DM320_SDRC_SDMODE_VALUE16 0x2000 /* SDRAM initialization for MSR for 16 bit * mode and CAS latency of 2 cycles */ #define DM320_SDRC_SDMODE_DQM 0x0080 /* SDRAM config - DQM Control bit */ menuitem "MemoryMap" /* GEL Menu item for ARM9 memory map releated functions */ /**************************************************************************** Function : memMapInitDM320() Description : This routine initializes the ARM9 memory map. Refer to the DM320 TRM for information on the ARM9 memory map. ****************************************************************************/ hotmenu memMapInitDM320() { GEL_TextOut("Initializing the ARM9 Memory Map...\n"); GEL_MapOn(); GEL_MapReset(); // ARM Internal Memory - 16kByte, Access Size is Auto GEL_MapAdd(0x00000000, 0, 0x00004000, 1, 1); /* for QT */ // ARM Peripheral Registers - 8KByte, Access Size is 16Bits GEL_MapAddStr(0x00030000, 0, 0x00001000, "RAM|AS2", 0); // C5409 DSP DARAM - ~128kBytes, Access Size is 16Bits GEL_MapAddStr(0x00040000, 0, 0x00020000, "RAM|AS2", 0); // Image Buffer , Access Size is 16Bits GEL_MapAddStr(0x00080000, 0, 0x0010000, "RAM|AS2", 0); // External Memory (SRAM/FLASH) - 16MBytes // (Note: The DM320EVM and DM320TB each have 512KBytes of SRAM) GEL_MapAddStr(0x00100000, 0, 0x01000000, "RAM", 0); // SDRAM - 256MB, Access Size is Automatic GEL_MapAdd(0x00900000, 0, 0x10000000, 1, 1); // External CFC - 16MB, Access Size is Automatic GEL_MapAdd(0x40000000, 0, 0x01000000, 1, 1); // External SSFDC - 16MB, Access Size is Automatic GEL_MapAdd(0x48000000, 0, 0x01000000, 1, 1); // External SRAM - 64MB, Access Size is Automatic GEL_MapAdd(0x50000000, 0, 0x01000000, 1, 1); // External SRAM - 64MB, Access Size is Automatic GEL_MapAdd(0x60000000, 0, 0x01000000, 1, 1); // VLYNQ Remote - 64MB, Access Size is Automatic GEL_MapAdd(0x70000000, 0, 0x04000000, 1, 1); // USB - 64MB, Access Size is Automatic GEL_MapAdd(0x80000000, 0, 0x04000000, 1, 1); // Mirror External Memory - 64KB, Access Size is Automatic GEL_MapAdd(0xFFFF0000, 0, 0x00010000, 1, 1); GEL_TextOut("Done initializing the ARM9 Memory Map.\n\n"); } menuitem "Clock" /* GEL Menu item for ARM9 clkc releated functions */ /****************************************************************************


Function : clkcInitDM320() Description : This routine initializes the ARM9 CLKC. Refer to the DM320 TRM for information on the ARM9 CLKC. ****************************************************************************/ hotmenu clkcInitDM320() { GEL_TextOut("\n"); GEL_TextOut("Setting DM320 clocks to \n"); GEL_TextOut("Initializing the clocks...\n"); GEL_TextOut("\n"); /* Set PLL configuration registers */ *(unsigned short *) DM320_CLKC_PLLA = DM320_CLKC_PLLA_VALUE; *(unsigned short *) DM320_CLKC_PLLB = DM320_CLKC_PLLB_VALUE; *(unsigned short *) DM320_CLKC_SEL2 = DM320_CLKC_SEL2_VALUE; *(unsigned short *) DM320_CLKC_DIV0 = 0x0081; /* ARM clock = * clock selection / 2 */ *(unsigned short *) DM320_CLKC_DIV1 = 0x0001; /* SDRAM clock = * clock selection / 2 */ *(unsigned short *) DM320_CLKC_DIV2 = 0x0100; /* DSP clock = * clock selection / 2 */ *(unsigned short *) DM320_CLKC_BYP = DM320_CLKC_BYP_VALUE; *(unsigned short *) DM320_CLKC_MOD0 = DM320_CLKC_MOD0_VALUE; *(unsigned short *) DM320_CLKC_MOD1 = DM320_CLKC_MOD1_VALUE; *(unsigned short *) DM320_CLKC_MOD2 = DM320_CLKC_MOD2_VALUE; GEL_TextOut("Done ....\n\n"); } menuitem "SDRAM" /* GEL Menu item for SDRAM releated functions */ /**************************************************************************** Function : sdram32InitDM320() Description : This routine initializes the DM320 EVM's SDRAM chip in 32-bit data bus mode. Note: The ARM9 memory map and the DM320 clocks must be initialized before you execute sdram32InitDM320(). You can initialize the memory map and clocks by executing memMapInitDM320() and clockInitDM320(), respectively. ****************************************************************************/ hotmenu sdram32InitDM320() { GEL_TextOut("Initializing SDRAM in 32-bit data bus mode...\n"); *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_PREA; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_MSR;


*(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_DSNORM; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_VALUE32; *(unsigned short *) DM320_SDRC_SDMODE &= ~DM320_SDRC_SDMODE_DQM; *(unsigned short *) DM320_SDRC_SDMODE |= DM320_SDRC_SDMODE_AUTOPDN; *(unsigned short *) DM320_SDRC_REFCTL = DM320_SDRC_REFCTL_VALUE; GEL_TextOut("Done initializing SDRAM in 32-bit data bus mode.\n\n"); } /**************************************************************************** Function : sdram16InitDM320() Description : This routine initializes the DM320 EVM's SDRAM chip in 16-bit data bus mode. Note: The ARM9 memory map and the DM320 clocks must be initialized before you execute sdram16InitDM320(). You can initialize the memory map and clocks by executing memMapInitDM320() and clockInitDM320(), respectively. ****************************************************************************/ hotmenu sdram16InitDM320() { GEL_TextOut("Initializing SDRAM in 16-bit data bus mode...\n"); *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_PREA; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_AUTOREF; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_MSR; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_DSNORM; *(unsigned short *) DM320_SDRC_SDMODE = DM320_SDRC_SDMODE_VAL | DM320_SDRC_SDMODE_VALUE16; *(unsigned short *) DM320_SDRC_SDMODE &= ~DM320_SDRC_SDMODE_DQM; *(unsigned short *) DM320_SDRC_SDMODE |= DM320_SDRC_SDMODE_AUTOPDN; *(unsigned short *) DM320_SDRC_REFCTL = DM320_SDRC_REFCTL_VALUE; GEL_TextOut("Done initializing SDRAM in 16-bit data bus mode.\n\n"); } StartUp(){ memMapInitDM320(); clkcInitDM320(); sdram32InitDM320(); }


Note: The above GEL file can cause warnings during Code Composer startup. These warnings should be ignored, as they don't seem to affect the initialization process. The GEL file was provided by Texas Instruments, and all requests and suggestions regarding its contents should be directed to TI.

3. In the Board Properties combo box, click on Startup GEL File(s), and for the first CPU (CPU_1), navigate to the dm320.gel file and open it.

4. Click on Finish on the Board Properties combo box.

5. Close the Setup Application and click Yes when prompted to save current settings and start Code Composer Studio.

6. From the main CCS window, select Debug, then Reset CPU.

7. Select File, then Load Program. The Load Program combo box pops up.

8. In the Load Program combo box select *.* for the Files of types.

9. Navigate to u-boot.elf and click on Open on the Load Program combo box.

10. From the main CCS window, select Debug, then Run.

At this time, you should see the ARMboot prompt appear in the serial terminal application window.

6.4.3.2. Using ARMboot to Download and Program u-boot.bin to Flash On the Monterey Linux development host, copy the u-boot.bin binary to the TFTP home directory. For instance:

ML(arm926ejs):[tester@host1]$ cp $TARGET_ROOT/boot/u-boot.bin /tftpboot

On the target, do the following from the ARMboot command interface:

1. Unprotect the Flash:

dm320evm # protect off all


2. Erase the Flash:

dm320evm # erase all Erasing sector 70 ... ok. Done.

3. Prepare to download images from TFTP host:

dm320evm # setenv ipaddr 192.168.52.201 dm320evm # setenv serverip 192.168.52.200 dm320evm # setenv ethaddr 08:00:3e:26:0a:5b dm320evm # saveenv Erasing sector 70 ... ok. Saving Environment to Flash...done. Protected 1 sectors

4. Download ARMboot binary (u-boot.bin) from the TFTP host:

dm320evm # tftpboot 8000000 u-boot.bin ARP broadcast 1 eth addr: 00:01:03:32:ea:1a TFTP from server 192.168.52.200; our IP address is 192.168.52.201 Filename 'u-boot.bin'. Load address: 0x08000000 Loading: ############### done Bytes transferred = 74596 (12364 hex)

5. Burn u-boot.bin to Flash:

dm320evm # cp.b 8000000 2000000 12364 Copy to Flash... done.

6. Close the main Code Composer Studio window.

ARMboot is now programmed into Flash of the DM320/DM342 EVM board. Disconnect the JTAG interface of the DM320/DM342 EVM target from the Windows host. The next power-up/reset should bring-up ARMboot on the target in standalone mode.

6.5. Installing Monterey Linux Images

Chapter 4 provides a detailed description of how to use the Flash management features of ARMboot to install Monterey Linux images into Flash and prepare the target for standalone operation.


7. Debugging With Monterey Linux This chapter discusses the debugging facilities and interfaces provided by Monterey Linux. Monterey Linux uses the GDB debugger for debugging target software components running on the DM320/DM342 processor core, including Linux kernel and drivers, and user space applications and libraries.

Monterey Linux runs GDB in a cross configuration. In this set up the GDB debugger front-end resides on the development host and communicates with a light-weight debugging agent (either gdbserver or a GDB stub) running on the target for low-level access to target resources (memory, registers, and so on). Monterey Linux supports various communication channels for interacting with the GDB debugger on the host and gdbserver/GDB stub on the target, including serial TCP/IP, and the ARM Injector-based JTAG port.

Additionally, Monterey Linux supports non-intrusive debugging of ARM9 targets. In this mode of operation, there is no debugging agent on the target. Instead, the GDB debugger on the host uses the JTAG interface to the target provided by the ARM Injector device for low-level control of the target..

7.1. Debugging with Monterey Linux Overview

This section provides an introduction into the concepts and use of the debugging features supported by Monterey Linux.

7.1.1. GDB Debugger

GDB is a full featured, command driven debugger that allows the user to trace the execution of programs and examine their internal state at any time. GDB works for C and C++ applications compiled with the GNU C compiler (GCC).

Chapter

7


GDB can help the user do the following:

Start a program, specifying anything that might affect its behavior (command line arguments, initial values of global variables, and so forth).

Make the program stop on specified conditions.

Examine what has happened when the program has stopped.

Change things in the program (variable values, memory contents, etc), so that one can experiment with correcting the effects of one bug and go on to learning about another.

To facilitate the debugging process, GDB supports the following features:

Machine code and source-level symbolic debugging

Single-stepping

Debugging of multi-threaded applications

Remote debugging (over network and/or serial links)

Data inspection (including language-specific data structures)

Breakpoints and watchpoints (hardware-assisted, if supported by the architecture)

Tracepoints (points in the application where certain expressions must be evaluated and the result stored for further inspection)

Internal variables and simple scripting facilities

Signal handling (catching/sending of signals, debugging signal handlers)

The above list is, of course, incomplete; for more information on GDB usage and capabilities please refer to the Linux GDB documentation (for instance, use info gdb on the Linux development host).

The following example demonstrates the basic features of the GDB debugger in the Monterey Linux environment:

Start up gdbserver on the target machine:

/> gdbserver :1234 ./myprog 5 Process ./myprog created; pid = 21


Start up GDB on the development host:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./myprog GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb)

Connect to the remote target:

(gdb) target remote dm320:1234 Remote debugging using dm320:1234 0x40001120 in ?? () (gdb)

List the program source:

(gdb) l 1,100 1 #include <stdio.h> 2 3 /* Calculate (n!) */ 4 int f(int n) 5 { 6 int ret = 1; 7 8 while (n) { 9 ret *= n; 10 --n; 11 } 12 return ret; 13 } 14 15 int main(int argc, char ** argv) 16 { 17 int n; 18 19 if (argc < 2) { 20 printf("need an argument\n"); 21 exit(1); 22 } 23 n = strtol(argv[1], NULL, 0); 24 printf("%d! = %d\n", n, f(n)); 25 return 0; 26 } (gdb)

Set a breakpoint at the start of function f:

(gdb) b f Breakpoint 1 at 0x84f4: file myprog.c, line 6. (gdb)


Continue the program:

(gdb) c Continuing. Breakpoint 1, f (n=5) at myprog.c:6 6 int ret = 1; (gdb)

Breakpoint hit, now obtain stack trace:

(gdb) bt #0 f (n=5) at myprog.c:6 #1 0x00008598 in main (argc=2, argv=0xbffffef4) at myprog.c:24 #2 0x40033504 in __libc_start_main () from /home/tester/DM320/arm926ejs/lib/libc.so.6 #3 0xca000002 in ?? () (gdb)

Step to the next line:

(gdb) n 8 while (n) { (gdb)

Print the value of ret:

(gdb) p ret $1 = 1 (gdb)

Set a watchpoint on the value of ret:

(gdb) watch ret Watchpoint 2: ret (gdb)

Continue the program:

(gdb) c Continuing. Watchpoint 2: ret Old value = 1 New value = 5 f (n=5) at myprog.c:10 10 --n; (gdb)


ret changed its value, program stopped on a watchpoint that was set earlier. Continue the program:

(gdb) c Continuing. Watchpoint 2: ret Old value = 5 New value = 20 f (n=4) at myprog.c:10 10 --n; (gdb)

The value of ret changed again. Now remove the watchpoint and continue the program:

(gdb) d b 2 (gdb) c Continuing. Program exited normally. (gdb)

The text 5! = 120 should now appear on the target console.

7.1.2. GDB GUI

Historically, GDB was intended as a command-line debugger, however there are quite a few GUI extensions to GDB available as well. Monterey Linux includes one such GUI interface, called Insight. Insight can be used by those users who prefer a GUI-based debugger interface to the standard GDB command-line interface.

Insight is a version of GDB that uses Tcl/Tk to implement a graphical user interface. It is a fully integrated GUI, not a separate front-end program. The interface consists of several separate windows, each of which use standard elements like buttons, scrollbars, entry boxes and such to create a fairly easy to use interface. Each window has distinct content and purpose, and can be enabled or disabled individually. The windows contain things like the current source file, a disassembly of the current function, text commands (for things that aren't accessible via a button), and so forth.

The real advantage of the Insight GUI (or any real debugger GUI) is that it provides multiple simultaneous views. One can have a console window to type commands, a source window to see what code is currently executing, a variable display to see the current contents of variables (including structures, linked lists, etc.), the program's call stack, etc. All the displays are updated automatically as GDB steps through the program.

To start the Insight GUI, specify the -w option to GDB on the Monterey Linux host:


ML(arm926ejs):[tester@host1]$ arm-linux-gdb -w ./myprog

The following screenshot illustrates use of Insight in the Monterey Linux development environment for debugging of a target user-space application:

Figure 6: Debugging a Target User-Space Application Using Insight

7.1.3. Cross Debug Environment

Monterey Linux only supports remote debugging. This means that a proper setup for debugging Monterey Linux applications and/or kernel must include gdbserver (or GDB stub, see below) running on the target, GDB running on the Linux host, and a communication channel between the host and the target.

gdbserver is a small application that contains low-level debugging code, along with an interface module that is responsible for communicating with the GDB debugger. Due to its simplicity, gdbserver has been ported to a wide variety of embedded platforms. GDB itself is mostly run on development host machines as it requires significantly more system resources than gdbserver. It is important to understand that gdbserver is not a replacement for GDB, it is a part of GDB that runs on the target. The main GDB code that implements the higher-level functionality and user interface still runs on the host machine.


GDB and gdbserver communicate through a serial or network link (Monterey Linux also supports debugging over JTAG). The following diagram shows the main components of the remote debugging setup described above:

GDB

kernel

gdbserver applicationscommunicationchannel

TargetHost

Figure 7: Remote Debugging Using gdbserver

As an alternative, the user may want to use a GDB stub instead of gdbserver. Like gdbserver, a GDB stub also contains low-level debugging code, but it differs from gdbserver in that it does not exist as a standalone application, but rather as one or more object files that must be linked with the application being debugged.

Another difference is that a GDB stub can communicate directly with the process being debugged, whereas gdbserver uses kernel services for that purpose. The main advantage of using GDB stubs is that they do not rely on any particular kernel interface, and can actually execute ’inside ’ the kernel. This means that GDB can be used not only for application debugging, but also for kernel debugging, provided that a corresponding kernel stub is linked in the kernel.

The following diagram shows the main components of the remote debugging setup when using a GDB stub:

GDB

kernel

TargetHost

communicationchannel

GDBstub

Figure 8: Remote Debugging Using GDB Stub


7.1.3.1. Introduction to the GDB Remote Protocol GDB and gdbserver (or GDB stub) communicate using a simple stream-based protocol. All GDB commands and responses (other than acknowledgments) are sent as packets. A packet consists of a $ character, the actual packet data, and a terminating # character followed by a two-digit checksum. When either the host or the target machine receives a packet, the first response expected is an acknowledgment: either + (to indicate the package was received correctly) or - (to request retransmission):

<- `$'PACKET-DATA`#'CHECKSUM -> `+'

The packet data includes a single character specifying a command, and one or more arguments following it (if required). For example, the continue command is encoded as cADDR, where ADDR is the address to resume (if omitted, the current address will be used).

Other commands include "read registers" (g), "write registers" (G...), "read memory" ("m..."), "write memory" (M...), "step" (s...), "insert breakpoint or watchpoint" (Z...), "remove breakpoint or watchpoint" (z...), and so forth.

GDB packets and acknowledgments travel through serial and TCP/IP communication channels as sequences of characters, that is without any additional encoding.

As an example, below is a fragment of a transfer diagram corresponding to a real debugging session:

<- $Hc-1#xx ; set current thread -> + -> $OK#9a ; OK <- + <- $qOffsets#xx ; query text and data offsets -> + -> $Text=10f48040;Data=10f48050;Bss=10f48050;#06 <- + <- $s#xx ; step -> + ...

To turn on the protocol debug output, specify a -d option when invoking gdbserver on the target.

7.1.4. Intrusive vs. Non-Intrusive Debugging

Debugging of the target can be intrusive or non-intrusive. Intrusive debugging is characterized by the need to run specialized debugging agent software on the target to make debugging possible. The debugging methods described in the previous section are both intrusive, since they require that a separate software component (gdbserver or GDB stub) be run on the target. The biggest advantage of intrusive debugging is that it can be used to debug user-level applications. This is made possible by the fact that a


target component, such as gdbserver, runs under the control of the operating system, and is therefore fully synchronized with it.

For instance, gdbserver uses the ptrace interface to receive notifications of various OS-specific events related to the process being debugged, such as a receipt of a signal or creation of a new thread. Without a target component such as gdbserver, it would be virtually impossible to synchronize with these events.

The disadvantage is that intrusive debugging cannot be used at an early firmware development stage, when no target software is available yet. Also, each debugging event must be serviced by the target software, which alters the system state in the process (thus the term intrusive debugging).

Non-intrusive debugging, on the other hand, does not rely on any particular software running on the target, but rather on hardware assistance from the target CPU. This hardware assistance is needed to get low-level control of the target resources such as memory, data registers, program counters, etc.

The DM320/DM342 processor provides such hardware assistance (through the CPU JTAG interface), and can therefore be used for non-intrusive debugging (hence referred to as JTAG debugging). A standard JTAG debugging setup consists of a hardware component called JTAG emulator, which addresses the electrical and logical incompatibilities between the target JTAG interface and a host interface, for instance, the USB-tethered ARM Injector device and a software debugger running on the host, such as the GDB front-end. The main advantage of non-intrusive debugging is that it can be used to debug low-level firmware and kernel code, without the need to develop or port a specialized target component. The disadvantage is that it only provides a low-level view of the target system. This means that a non-intrusive debugger knows nothing about the operating system that may be running on the target. What it can do is examine CPU registers and memory contents at any time, but it knows nothing about Linux signals, system calls, processes, threads, etc. Consequently, non-intrusive debugging works well for debugging of single-tasked, no-OS context programs (such as firmware programs, for instance), but is much less suited for debugging of OS kernels or applications.

7.1.5. Building for Debugging

The GDB debugger needs additional bits of information about the program to be able to debug n application at the source-code level (for instance, step through its source code, examine its variables and data structures, etc). This additional information includes such things as the names of its source files and the correspondence between lines in the source code and instruction addresses. All this is called debug information. Usually, executables do not contain such information, since it is not required for normal execution and bloats the size of the object files.

To include debug information in an executable, the -g flag must be specified in the GCC command line.


For example:

ML(arm926ejs):[tester@host1]$ gcc ./hello.c -o ./hello -g

Also note the absence of optimization options in the above example. In general, code optimization makes debugging much harder and sometimes even impossible. For this reason, applications intended for debugging should be compiled with optimization disabled.

Another thing to keep in mind when building applications for debugging is that for source-level debugging to be possible, the source code should be retained in the same directory where it was compiled.

To dump the debug information contained in an executable file, the objdump command can be used (available as arm-linux-objdump in the Monterey Linux development environment).

For example:

ML(arm926ejs):[tester@host1]$ arm-linux-objdump --debug ./hello ./hello: file format elf32-littlearm /usr/local/ML/build/linux//usr/src/ml/BUILD/glibc-2.3.1-20030117/csu/init.c: typedef int32 int; typedef uint8 char; typedef int32 long int; typedef uint32 unsigned int; typedef uint32 long unsigned int; typedef int64 long long int; typedef uint64 long long unsigned int; typedef int16 short int; typedef uint16 short unsigned int; typedef int8 signed char; typedef uint8 unsigned char; typedef float float; typedef double double; typedef double long double; typedef struct %anon1 { /* size 8 */ int real; /* bitsize 32, bitpos 0 */ int imag; /* bitsize 32, bitpos 32 */ } complex int; typedef complex double complex float; ...

In fact, the actual output produced by objdump is much more substantial, but only the first page is shown here for brevity. Interpretation of this debug output is quite straightforward. The typedefs define various synonyms for system types. The lines of the form:

/* file hello.c line 4 addr 0x848c */

tie the source lines to their corresponding instruction addresses.


7.1.6. GDB Binary Files

The following table summarizes pathnames to various components of the debugging tools included in the Monterey Linux distribution.

Use the specified pathnames to call the tools on the host or install them on the target:

Component Binary File Directory Host/Target

GDB debugger (configured for low-level kernel and JTAG debugging)

arm-elf-gdb $CDE_ROOT/usr/bin/ Host

GDB debugger (configured for debugging of Linux applications)

arm-linux-gdb $CDE_ROOT/usr/bin/ Host

GDB server gdbserver $TARGET_ROOT/usr/bin/ Target

Table 15: Pathnames to the Debugging Tools Components

7.2. Debugging with Monterey Linux Cross GDB

This section provides a detailed description of using the cross GDB for debugging of Monterey Linux software.

7.2.1. Debugging the Kernel

7.2.1.1. Debugging a Statically Linked Kernel and Drivers

7.2.1.1.1 Building the Kernel for Debugging

Like any other program, the kernel has to be compiled with debug information to make source-level debugging possible. To do this, start a kernel configuration tool (for instance make xconfig) and use it to configure the kernel build procedure so that it builds the kernel with debug information.

From the kernel configuration tool, turn on the Include debugging information in kernel binary configuration option (it is located in the Kernel hacking menu).

Then rebuild the kernel in the Monterey Linux environment. For example:


ML(arm926ejs):[tester@host1]$ cd $TARGET_ROOT/usr/src/linux ML(arm926ejs):[tester@host1]$ make pImage

The resulting binary can be used for debugging of the kernel at the source level. Use the objdump tool to analyze the debug information from the Monterey Linux development environment:

ML(arm926ejs):[tester@host1]$ cd $TARGET_ROOT/usr/src/linux ML(arm926ejs):[tester@host1]$ arm-linux-objdump --debugging ./vmlinux ./vmlinux: file format elf32-littlearm /home/tester/DM320/arm926ejs/usr/src/linux-2.4.19/arch/arm/kernel/init_task.c: typedef int32 int; typedef uint8 char; typedef int32 long int; typedef uint32 unsigned int; typedef uint32 long unsigned int; typedef int64 long long int; typedef uint64 long long unsigned int; typedef int16 short int; typedef uint16 short unsigned int; typedef int8 signed char; typedef uint8 unsigned char; typedef float float; typedef double double; typedef double long double; typedef struct %anon1 { /* size 8 */ int real; /* bitsize 32, bitpos 0 */ int imag; /* bitsize 32, bitpos 32 */ } complex int;

(only the first page of the output is shown).

7.2.1.1.2 Debugging the Kernel Using GDB Stub

Monterey Linux includes GDB stub software that can be used for intrusive debugging of the Linux kernel.

7.2.1.1.2.1. Configuring the Kernel

To enable this functionality, turn on the Remote (serial) kernel debugging with the GDB option in the Kernel Hacking menu of the kernel configuration. By default, the kernel GDB stub uses the target serial port 2 for communicating with the GDB debugger on the host. However, even if both serial ports on your target board are used as conventional serial ports, kernel stub debugging is still possible using the ARM Injector device. As explained in 4.5.2, the ARM Injector provides two emulated serial ports multiplexed over the JTAG interface as a communication channel between the Monterey Linux development host and the target. On the Linux host, these two ports are available as /dev/ttyUSB2 and /dev/ttyUSB3. On the target, these two ports are available as /dev/ttyS16(minor=80) and /dev/ttyS17(minor=81). For purposes of the kernel debugging, any of these simulated serial lines can be used as a communication channel between the GDB debugger on the host and the GDB stub on the target.


Note: if several ARM Injectors are connected to the host, the ttyUSB numbers will be 2 and 3 for the first Injector, 6 and 7 for the second, 10 and 11 for the third, etc.).

This configuration can be selected by enabling the Use JTAG-emulated serial port option in the Kernel Hacking menu (the ARM JTAG serial emulation support option in the Character devices/Serial drivers menu should also be enabled). The following table summarizes the option settings for the standard serial and JTAG-emulated serial configurations:

Setting Option Menu

Standard UART

JTAG-Emulated

Remote (serial) kernel debugging with GDB

Kernel hacking on on

Use JTAG-emulated serial port

Kernel hacking off on

ARM JTAG serial emulation support

Character devices/Serial drivers

do not care on

Table 16: Kernel Debugging Configuration Options

The Serial console number and JTAG serial port number integer options (not shown in the table above) are used to select the port number used by the GDB stub on the target.

7.2.1.1.2.2. Kernel Stub Operation

The kernel GDB stub is activated whenever a critical exception occurs, or when a breakpoint is hit. Another event that can cause entering the GDB stub is pressing the Ctrl-C key sequence in the host GDB window. This allows the user to interrupt kernel execution at any moment to examine the kernel state. If the Enter debugger on boot option in the Kernel hacking menu is enabled in the kernel configuration, the GDB stub will be activated when the kernel starts booting.

Once the kernel GDB stub is entered, it starts listening on the serial communication port for GDB requests. Now the user can invoke GDB on the host and start a remote debugging session.

An example debug session with the kernel GDB stub is shown below:

Target view:

Linux version 2.4.19-rmk7-ds1-omap (tester@host1) (gcc version 3.2) #2 Thu Mar 25 17:36:06 … 2004 CPU: ARM926EJ-Sid(wb) revision 3


Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 KGDB: Waiting for connection from remote gdb...

Host view:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./vmlinux GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) (gdb) target remote /dev/ttyS1 Remote debugging using /dev/ttyS1 0xc001a5c4 in gdbstub_breakinst () (gdb) b printk Breakpoint 1 at 0xc00215fc: file printk.c, line 430. (gdb) c Continuing. Breakpoint 1, printk (fmt=0xc00e0c74 "root=/dev/ram0") at printk.c:430 430 if (oops_in_progress) { (gdb) l 425 int printed_len; 426 char *p; 427 static char printk_buf[1024]; 428 static int log_level_unknown = 1; 429 430 if (oops_in_progress) { 431 /* If a crash is occurring, make sure we can't deadlock */ 432 spin_lock_init(&logbuf_lock); 433 /* And make sure that we print immediately */ 434 init_MUTEX(&console_sem); (gdb)

7.2.1.1.3 Debugging the Kernel Using the ARM Injector

The ARM Injector device can be used for non-intrusive debugging of the kernel. As explained earlier, non-intrusive debugging is not aware of any kernel task or synchronization primitives and views the software under debugging as a single-tasked, “no-context” program.

Clearly, this view is hardly acceptable for the Linux kernel. Still, the non-intrusive debugging based on the ARM Injector may be useful for limited debugging of Monterey Linux kernels. Kernel-level events will not be visible to the GDB debugger, however, the basic features, such as breakpoints, single-stepping, and the like will be accessible.

Note: Debugging with the ARM Injector requires the usbserial kernel module to be installed on the host. Please refer to 5.5.2 for details.


7.2.1.2. Debugging Kernel Modules Kernel modules can be debugged in the same way as the kernel itself. The only difference is that every time a new module is loaded, the user must notify GDB of this event by issuing an add-symbol-file command. This command accepts a module name along with the code and data segment locations, as reported by the kernel when the module is loaded. To enable load map reporting, use the –m option in the insmod command line.

The following example demonstrates how kernel module debugging is performed in Monterey Linux:

Target view:

/test> insmod -m hello.o Using hello.o Sections: Size Address Align .this 0000006Hello, World! 0 c1800000 2**2 .text 00000098 c1800060 2**2 .rodata 00000010 c18000f8 2**2 .data 00000000 c1800108 2**0 .kstrtab 00000006 c1800108 2**0 .bss 00000014 c1800110 2**2 .plt 00000020 c1800128 2**3 __ksymtab 00000000 c1800148 2**2

Host view:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./vmlinux GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote /dev/ttyS1 Remote debugging using /dev/ttyS1 0xc001d5c4 in gdbstub_breakinst () (gdb) c Continuing. Program received signal SIGTRAP, Trace/breakpoint trap. default_idle () at process.c:75 75 local_irq_disable(); (gdb) add-symbol-file hello.o 0xc1800060 -s .rodata 0xc18000f8 -s .data oxc1800108 -s .bss 0xc1800110 add symbol table from file "hell.o" at .text_addr = 0xc1800060 .rodata_addr = 0xc18000f8 .data_addr = 0x0 .bss_addr = 0xc1800110 (y or n) y Reading symbols from hello.o...done. (gdb)


The following output appears on the target console:

/> Hello, World!

Also note that to enable source-level debugging, kernel modules also have to be compiled with debug information. For standalone modules, this is usually achieved by adding the -g option to the CFLAGS definition in the module's makefile. For modules included in the kernel distribution, no special actions are required other than rebuilding the kernel with debug info (see 7.2.1.1.1).

7.2.2. Debugging User Applications

7.2.2.1. Debugging Simple Applications User applications in Monterey Linux can be debugged using GDB in conjunction with gdbserver. As described in section 7.1.3 , this setup requires GDB running on the host, gdbserver running on the target, and a communication channel (serial, network, or JTAG link) between the host and the target.

Before debugging can begin, gdbserver must be started on the target machine. It accepts the following options and arguments:

gdbserver [-d] [:<port>|<device>] [<application>]

The -d option causes gdbserver to produce debug output. The :<port> argument specifies the TCP port number to be used for incoming GDB connections (for example, :1234). The <device> argument specifies the serial device node to be used for communicating with GDB (for example, /dev/ttyS1).

Note that the :<port> and <device> arguments are mutually-exclusive. The last argument (<application>) specifies the file name of the application to be debugged, along with the arguments. If it is omitted, no application will be started right away (the GDB attach command can then be used to attach to an already-running process, see section 7.2.4.2 for more details.

Please refer to sections 7.2.3.1 and 7.2.3.2 for more information on debugging through serial and network links.

7.2.2.2. Debugging Multi-Threaded Applications The usual GDB-gdbserver setup can also be used to debug multi-threaded applications. GDB supports a number of features/extensions to facilitate multi-threaded debugging, such as:

Automatic notification of new threads


thread THREADNO, a command to switch among threads

info threads, a command to inquire about existing threads

thread apply [THREADNO] [ALL] ARGS, a command to apply a command to a list of threads

thread-specific breakpoints

scheduler locking to prevent other threads from running when one particular thread is being debugged

For more information on these features, please refer to the GDB info page (type info gdb on the Linux host).

The use of some of these features in a simple debugging session is demonstrated below:

On the target:

/> gdbserver :1234 ./threads Process ./thread created; pid = 100

On the host:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./threads GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote dm320:1234 Remote debugging using dm320:1234 0x40001120 in ?? ()

The following output should appear on the target console:

Remote debugging from host 192.168.0.2

Back to the host: list the program source:

(gdb) l 1,100 1 #include <stddef.h> 2 #include <stdio.h> 3 #include <unistd.h> 4 #include "pthread.h" 5 6 int global; 7 pthread_mutex_t lock; 8 9 void * process(void * arg)


10 { 11 pthread_mutex_lock(&lock); 12 global += (int)arg; 13 pthread_mutex_unlock(&lock); 14 return NULL; 15 } 16 17 int main(int argc, char **argv) 18 { 19 pthread_t th_a; 20 void * retval; 21 22 pthread_mutex_init(&lock, NULL); 23 pthread_create(&th_a, NULL, process, (void *) 1); 24 pthread_mutex_lock(&lock); 25 global++; 26 pthread_mutex_unlock(&lock); 27 pthread_join(th_a, &retval); 28 29 return 0; 30 } (gdb)

Set a breakpoint at the thread entry point:

(gdb) b process Breakpoint 1 at 0x8608: file threads.c, line 11. (gdb) cont Continuing. [New Thread 16384] [New Thread 32769] [New Thread 16386] [Switching to Thread 16386] Breakpoint 1, process (arg=0x1) at threads.c:11 11 pthread_mutex_lock(&lock);

Obtain threads info:

(gdb) info threads * 3 Thread 16386 process (arg=0x1) at threads.c:11 2 Thread 32769 0x4013da3c in poll () from /home/tester/DM320/arm926ejs/lib/libc.so.6 1 Thread 16384 0x4009f88c in sigsuspend () from /home/tester/DM320/arm926ejs/lib/libc.so.6 (gdb)

Turn on scheduler locking (so that the other thread remains stopped) and do some debugging:

(gdb) set scheduler-locking on (gdb) n 12 global += (int)arg; (gdb) n 13 pthread_mutex_unlock(&lock); (gdb) p global $1 = 2


Turn off scheduler-locking and continue the program:

(gdb) set scheduler-locking off (gdb) cont Continuing. [Thread 16386 exited] [Thread 32769 exited] Program exited normally.

The following output should now appear on the target console:

Child exited with retcode = 0 Child exited with status 0 GDBserver exiting />

7.2.2.3. Debugging C++ Applications The GDB debugger supports debugging of C++ applications and provides a number of powerful features to facilitate this process, such as:

C++ name demangling

Debugging of C++ exceptions

Examining inheritance relationships of C++ objects

Setting breakpoints in overloaded functions

From the user's perspective, debugging of C++ applications is not much different from debugging of C applications. It involves running GDB on the host, gdbserver on the target, and establishing a connection between the two.

Below is a screenshot of a debugging session with a simple C++ application:

On the target:

/> gdbserver :1234 test Process test created; pid = 26

On the host:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./test GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote dm320:1234


Remote debugging using dm320:1234 0x40001110 in ?? () (gdb) (gdb) c

The following output will appear on the target:

Remote debugging from host 192.168.0.2 Simple C++ Hello World User Application Child exited with retcode = 0 Child exited with status 0 GDBserver exiting />

7.2.2.4. Debugging Several Applications Simultaneously Monterey Linux supports the simultaneous debugging of several applications. This can be achieved by running several separate GDB-to-gdbserver sessions, as shown in the example below:

Run several separate gdbserver sessions:

/> gdbserver :1234 hello & [21] /> Process hello created; pid = 28 /> gdbserver :1235 hello & [29] /> Process hello created; pid = 30/>

Do some debugging in window 1:

(gdb) target remote dm320:1234 Remote debugging using dm320:1234 0x40001110 in ?? () (gdb) l 1 #include <stdio.h> 2 3 int main (int argc, char ** argv) 4 { 5 printf("Hello, world!\n"); 6 return 0; 7 } (gdb) b 6 Breakpoint 1 at 0x8494: file hello.c, line 6. (gdb) c Continuing. Breakpoint 1, main (argc=1, argv=0xbffffef4) at hello.c:6 6 return 0; (gdb)

The Hello, World! output should appear on the target console. Now do some debugging in window 2:


(gdb) target remote dm320:1235 Remote debugging using dm320:1235 0x40001110 in ?? () (gdb) b 6 Breakpoint 1 at 0x8494: file hello.c, line 6. (gdb) c Continuing. Breakpoint 1, main (argc=1, argv=0xbffffef4) at hello.c:6 6 return 0; (gdb)

Another Hello, World! string should appear on the target console.

If a network link is present, the number of simultaneous debugging sessions is only limited by the system’s resources (each session uses its own port number).

If a network link is not available, only the serial channels can be used. The maximum number of simultaneous debugging sessions in this case is defined by the number of free serial ports (including the emulated JTAG serial ports). Even if no real serial ports are available, the JTAG communication channel can still be used for debugging purposes.

7.2.2.5. Debugging Applications and Kernel Simultaneously Monterey Linux supports the simultaneous debugging of several applications and the Monterey Linux kernel. This can be achieved by running several GDB-to-gdbserver sessions for the applications, and one GDB-to-GDB stub session for the kernel.

The maximum number of simultaneous debugging sessions can be determined in the same way as described in 7.2.2.4, but it is important to note that the kernel stub can only use a serial link.

7.2.3. Cross Debugging Communication Channels

This section describes in more detail the particular communication methods that can be used for remote debugging of Monterey Linux applications and kernel.

7.2.3.1. Using a Serial Port for Debugging Serial debugging is the simplest form of remote debugging. It is widely used for debugging of embedded software, at early firmware and kernel development stages, when no other communication channels are available. This mode of debugging is achieved by incorporating into the firmware or kernel a special interface module called a "GDB stub" (this concept was briefly discussed in 7.1.3). Note that non-intrusive debugging tools (such as the ARM Injector) eliminate the need to develop GDB stubs for firmware debugging. At the kernel level, however, GDB stubs can still be beneficial, since they provide a better level of "kernel-awareness" than non-intrusive debuggers.


Refer to 7.2.1.1.2 for a discussion of how serial links can be used for debugging of Monterey Linux kernel and modules.

Serial links can also be used for intrusive user-level debugging, which is done with the help of gdbserver. To use GDB and gdbserver for application debugging, the following actions must be performed:

On the target machine:

Make sure that the gdbserver binary and the program to be debugged are present on the target file system. Next, use the following command to start gdbserver: gdbserver [-d] <device> [<application>]

where <device> is the serial device node to be used as the communication channel, and <application> is the name of the application to be debugged, along with the arguments. The <application> part is optional. If it is specified, the application will be started right away, otherwise gdbserver will wait until an attach request is issued by GDB (see section 7.2.4.2 for more information on the attach feature).

Example: /> gdbserver /dev/ttyS1 ./myprog arg1 arg2 arg3

On the GDB host machine:

Make sure an unstripped ELF object file for the program to be debugged is available on the host. Next, start up GDB, specifying the application ELF file name as an argument. In addition, if the serial line is running at a speed different from 9600, a --baud option has to be specified, as in the following example: ML(arm926ejs):[tester@host1]$ arm-linux-gdb --baud 115200 ./myprog

When the (gdb) prompt appears, enter a target remote command to establish communication with gdbserver. Its argument is a serial device name. For example: (gdb) target remote /dev/ttyS1

After that, GDB establishes a connection with gdbserver, and debugging can begin.

In the following example, the host and the target are assumed to be connected via a serial cable, with both host and target endpoints being /dev/ttyS1 (that is, there is a COM2-COM2 connection present):


On the target:

/> gdbserver /dev/ttyS1 ./hello Process ./hello created; pid = 29 Remote debugging using /dev/ttyS1

On the host:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./hello GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote /dev/ttyS1 Remote debugging using /dev/ttyS1 0x40001120 in ?? () (gdb) l 1 #include <stdio.h> 2 3 int main (int argc, char ** argv) 4 { 5 printf("Hello, world!\n"); 6 return 0; 7 } (gdb) b 6 Breakpoint 1 at 0x84d4: file hello.c, line 6. (gdb) c Continuing. [New Thread 16384] [Switching to Thread 16384] Breakpoint 1, main (argc=1, argv=0xbffffef4) at hello.c:6 6 return 0; (gdb) n 7 return 0; (gdb) c Continuing. Program exited normally. (gdb) Hello World Child exited with retcode = 0 Child exited with status 0 GDBserver exiting #

The following output should appear on the target:

Remote debugging from host 192.168.0.2 Hello, World! Child exited with retcode = 0 Child exited with status 0 GDBserver exiting />


7.2.3.2. Using a TCP/IP Connection for Debugging If a network link is present between the host and the target, it can be used for remote debugging of user applications. Similar actions must be performed in this case as those described in the previous section, with the following exceptions:

On the target machine:

Instead of the <device> argument, a string of the form :<port> must be passed to gdbserver. <port> stands for a TCP port number to be used for communicating with gdbserver. For example:

/> gdbserver :1234 ./myprog arg1 arg2 arg3

The port number can be any number in the range of 1000 to 65535, provided that it is not already used for another service.

Note: Ports with numbers lower than 1000 can also be used, but they require superuser privileges, and the chances of a conflict are much greater using that range.

On the GDB host machine:

Instead of a serial device name, a remote service specification must be used as an argument to the target remote command. A remote service specification is a string of the form: <target>:<port>, where <target> is the network name of the target machine (or its IP address), and <port> is the port number specified earlier when invoking gdbserver on the target. For example:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./myprog GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote 192.168.0.1:1234 Remote debugging using 192.168.0.1:1234 0x40001110 in ?? () (gdb)

In the following example, the host and the target connect over the TCP port 1234:

On the target:

/> gdbserver :1234 ./hello Process ./hello created; pid = 28


On the host:

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./hello GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote 192.168.0.1:1234 Remote debugging using 192.168.0.1:1234 0x40001110 in ?? () (gdb)

The following output should appear on the target:

Remote debugging from host 192.168.0.2 Hello, World! Child exited with retcode = 0 Child exited with status 0 GDBserver exiting />

7.2.3.3. Using the ARM Injector for Debugging

7.2.3.3.1 Non-Intrusive Debugging with the ARM Injector

Among other things, the ARM Injector device allows the user to do non-intrusive debugging of the target system. This resembles the standard remote debugging procedure described in the previous section, but this time there is no need for a target debug agent such as gdbserver or GDB stub.

To establish a non-intrusive debug session with the ARM Injector, simply run GDB on the host and specify the Injector gdbserver port name as an argument to the target remote command. For example:

ML(arm926ejs):[tester@host1]$ arm-elf-gdb GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf". (gdb) target remote /dev/ttyUSB1 Remote debugging using /dev/ttyUSB1 0x08f037a0 in ?? () (gdb)


Note: Debugging with the ARM Injector requires the usbserial kernel module to be installed on the host. Please refer to 5.5.2 for more information. Section 5.5.2 also contains information on the USB serial port mappings.

When the ARM Injector firmware receives a GDB connection, it stops the target CPU and acquires full control over the target resources. Note that while the target is stopped, it does not react to any events occurring in the "external" world, other than the GDB commands issued by the user.

The actual debugging is performed exactly as the application debugging process described in the previous sections. You can examine and modify system state (variables, memory, etc.), set breakpoints/watchpoints, do single-stepping, etc. There are several things to keep in mind, though:

There are two types of breakpoints: hardware breakpoints and software breakpoints. Software breakpoints are set by writing a special instruction opcode to the breakpoint address. Hardware breakpoints, on the other hand, do not require overwriting the existing instruction, and can therefore be used in code executing from ROM or Flash. The downside of hardware breakpoints is that there can be only one such breakpoint (or watchpoint, see below) active at a time.

To set a software breakpoint, use the b command, as shown in the example below: (gdb) b 62 Breakpoint 1 at 0x80081a0: file main.c, line 62.

To set a hardware breakpoint, use the hb command. For example: (gdb) hb 62 Hardware assisted breakpoint 2 at 0x80081a0: file main.c, line 62.

Likewise, there are two types of watchpoints: hardware and software. Software watchpoints work by stepping through the code and checking the watched value after each step. This dramatically slows down the execution, and may require hours of waiting until the desired condition is met. Hardware watchpoints, on the other hand, work by setting up the EmbeddedICE logic in a special way, so that when the address being watched appears in a bus transaction, the target CPU will be forced to debug state immediately. The execution speed is not affected by hardware watchpoints.

Note that a single EmbeddedICE watchpoint unit is used to implement both hardware watchpoints and breakpoints. This means that only one hardware watchpoint or breakpoint can be active at a time.


There is no way to select between hardware and software watchpoints. The rule is that the first watchpoint set will be a hardware watchpoint, and all subsequent watchpoints will be software watchpoints.

7.2.3.3.2 Application Debugging with the ARM Injector

As described in the previous sections, application debugging in Monterey Linux is performed either over a serial port, or over a network link. The ARM Injector device, however, can make application debugging possible even if a single serial port on the target is used as the system console, and a network driver has yet to be developed (or the network link is not available for some other reason). More specifically, one (or both) of the JTAG-emulated serial ports can be used for remote debugging in the same way as any other serial port. This is demonstrated in the following example:

On the target:

/> gdbserver /dev/ttyS16 ./hello Process ./hello created; pid = 23 Remote debugging using /dev/ttyS1

On the host::

ML(arm926ejs):[tester@host1]$ arm-linux-gdb ./hello GNU gdb 5.2.1 Copyright 2002 Free Software Foundation, Inc. GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i386-redhat-linux --target=arm-elf-linux"... (gdb) target remote /dev/ttyS1 Remote debugging using /dev/ttyS1 0x40001120 in ?? () (gdb) l 1 #include <stdio.h> 2 3 int main (int argc, char ** argv) 4 { 5 printf("Hello, world!\n"); 6 return 0; 7 } (gdb) (gdb) b 5 Breakpoint 1 at 0x8490: file hello.c, line 5. (gdb) c Continuing. Breakpoint 1, main (argc=1, argv=0xbffffef4) at hello.c:5 5 printf("Hello, world!\n"); (gdb) (gdb) n 6 return 0; (gdb) c Continuing. Program exited normally. (gdb) Remote debugging using /dev/ttyS1


Hello, world! Child exited with retcode = 0 Child exited with status 0 GDBserver exiting #

(for details on the special device driver nodes used in the example above, refer to 7.2.1.1.2.1.)

7.2.4. Additional Debugger Features

Monterey Linux supports a number of useful debugger extensions. The first allows running applications on the target without breaking the GDB-to-gdbserver link. The second allows attaching to an already running process. The third allows native debugging of the Monterey Linux kernel on the target.

7.2.4.1. Executing Remote Commands To execute a remote application from the (gdb) prompt, use the rshell command, specifying the application name as an argument. For example:

(gdb) rshell ps

The command will be executed in a separate shell on the target. It is also possible to specify commands with arguments.

7.2.4.2. Attaching to a Running Process To attach to an already-running process, use the attach command after GDB has been started. It accepts the PID (Process ID) of the target process to attach to. For example:

(gdb) rshell ps PID TTY Uid Size State Command 1 root 1476 S init 2 root 0 S [keventd] 3 root 0 S [ksoftirqd_CPU0] 4 root 0 S [kswapd] 5 root 0 S [bdflush] 6 root 0 S [kupdated] 7 root 0 S [rpciod] 13 root 1372 S inetd 15 ttyS0 root 1540 S /bin/sh 35 ttyS0 root 1300 S ./hello2 39 ttyS0 root 1408 S gdbserver :1234 40 ttyS0 root 1536 S /bin/sh -c ps 41 ttyS0 root 1548 R ps


(gdb) attach 35 Attaching to remote program `(null)' (process 35)... 0x400c0474 in ?? () (gdb)

Note that to be able to attach to an already-running process, gdbserver must be started with an empty <application> argument.

To terminate a debugging session, the detach command can be used. For more information on the attach and detach commands, please refer to the GDB documentation.

7.2.4.3. Native Kernel Debugging

7.2.4.3.1 Monterey Linux Native Kernel Debugger

The Monterey Linux kernel includes a native kernel debugger that can be extremely useful on platforms where use of the cross GDB debugger is not practical for some reason. One example of such an environment is a platform that has a single serial port allocated to the system console (that is, there is no dedicated serial port that can be used for connection between the host GDB and the target GDB stub) and use of the ARM Injector for kernel debugging is not convinient for some reason.

The Monterey Linux native kernel debugger is based on the well-known Linux KDB debugger. The KDB is an assembler-level command-driven debugger that allows the programmer to trace execution of the kernel and examine its internal state at any time.

The KDB support the following key capabilities:

Examining kernel memory

Disassembling kernel functions

Setting breakpoints in the kernel code

Displaying and modifying register contents.

For additional information on the KDB capabilities and usage please refer to the Linux KDB documentation in public domain.

Overall, while the KDB does not allow advanced debug capabilities supported by the Monterey Linux cross GDB (for instance, symbol level debugging of the kernel), it may be very useful when kernel debugging at the low level is sufficient.


7.2.4.3.2 Configuring Kernel for the Native Debugging

To enable the KDB functionality in the kernel, enable the Built-in Kernel Debugger Support option in the Kernel Hacking menu of the kernel configuration and rebuild the kernel.

7.2.4.3.3 Using KDB

Whenever an abnormal exception (such as, a system crash) occurs in the kernel, the KDB debugger is enabled and the interactive command interface appears on the system console (provided the KDB is enabled in the kernel). Another event that can cause entering the KDB is pressing the Ctrl-A key sequence on the serial console. This allows the developer to interrupt kernel execution at any moment to examine the kernel state.

Once the KDB command interface is entered, you can use the KDB commands to debug the kernel. The following sample session illustrates debugging of the kernel using the KDB:

Activate the KDB by pressing Ctrl-A on the system console:

/> <Ctrl-A> Entering kdb (current=0xc016e000, pid 0) due to Keyboard Entry

Set a breakpoint on _alloc_pages() function:

kdb> bp _alloc_pages Instruction(i) BP #0 at 0xc0061a38 (_alloc_pages) is enabled globally

Show the stack backtrace:

kdb> bt Stack traceback for pid 0 0xc016e000 0 0 1 0 R 0xc016e268 *swapper FP PC Function (args) 0xc003e784 cpu_idle+0x60 () kernel .text 0xc003b000 0xc003e724 0xc003e79c 0xc00087a4 start_kernel+0x140 () kernel .init 0xc0008000 0xc0008664 0xc0008848

Continue execution:

kdb> g


The KDB is entered due to a breakpoint hit::

0xc0061a38 _alloc_pages: str lr, [sp, -#4]! Entering kdb (current=0xc7d78000, pid 16) due to Breakpoint @ 0xc0061a38

List all the breakpoints:

kdb> bl Instruction(i) BP #0 at 0xc0061a38 (_alloc_pages) is enabled globally

Remove the breakpoint:

kdb> bc 0 Breakpoint 0 at 0xc0061a38 cleared

Continue execution:

kdb> g

7.2.4.3.4 Basic KDB Commands

The following table shows the key KDB commands. To get the list of all available commands, type ? at the KDB prompt.

Command Description

bc Clear breakpoint bd Disable breakpoint be Enable breakpoint bl Display breakpoints bp Set or display breakpoint bph Set or display hardware breakpoint bpa Set or display breakpoint globally bpha Set or display hardware breakpoint

globally bt Stack backtrace for current process btp Stack backtrace for specific process bta Stack backtrace for all processes btc Cycle over all live cpus and backtrace

each one cpu Display or switch CPUs


Command Description

dmesg Display system messages defcmd Define a command as a set of other

commands ef Print exception frame env Show environment go Restart execution help Display help message id Disassemble instructions ll Follow linked lists lsmod List loaded modules md Display memory contents mdwcn Display memory contents with width W

and count N mdr Display raw memory contents mds Display memory contents symbolically mm Modify memory contents, words mmw Modify memory contents, bytes ps Display process status reboot Reboot the machine rd Display register contents rm Modify register contents rmmod Remove a module sections List information on all known sections set Add/change environment variable sr Invoke SysReq commands ss Single step a CPU ssb Single step a CPU until a branch

instruction


8. DSP Support This chapter discusses the DSP application development support provided by Monterey Linux. The DSP Manager and DSP API interfaces are documented. Loading of images to the DSP core from a file in the Linux file system is described and illustrated with examples.

8.1. Inter-Core Communication Mechanisms

8.1.1. Shared RAM

The internal memory of the DSP (32-Kwords of DARAM), extended data memory (16-KWords of SARAM) and Page 1 program memory (16-KWords of SARAM) can be read and written by the ARM through the HPI-Bridge. The DSP internal memory is accessible from the ARM at a fixed address in the ARM physical memory map. The following figure shows the DSP memory block that the ARM can access:

Figure 9 : Shared Memory

Chapter

8

DSP ARM

000:0080h

000:7FFFh

000:8000h

000:BFFFh

1:С000h

1:FFFFh

DSP Memory (as seen from

ARM) - 128 KWords

On-Chip DARAMProgram/Data- 32 KWords

Data RAM-16 KWords

Program RAM-16 KWords

0004:0100h

0005:FFFFh


8.1.2. DSP Boot Sequence

On the C54x DSP, the reset vector is located at address 0x0FF80. Within the DM320/DM342, this memory location has been ROM'ed with a small bootloader. The DSP boot process is achieved in 6 steps:

The DSP comes out of reset and loads its program counter (PC) register with 0x0FF80

The ROM code found at this location branches the DSP to address 0x0FF60 where the initialization routine resides.

At address 0x0FF60, the DSP status register PMST is initialized to move the vector tables to 0x07F80, the interrupts are disabled except for INT0 and finally, the DSP is sent to a power down mode (Idle 1).

While in this mode, Monterey Linux loads the DSP internal 32k words of DARAM memory with the DSP code.

When Monterey Linux is done downloading the DSP code, it wakes it up from IDLE mode by asserting INT0.

The DSP then branches to address 0x7F80 where the new interrupt vector table is located, thus starting extension of the loaded DSP code.

8.1.3. Control of DSP from ARM

The ARM has the following control mechanisms over the DSP:

A bit in the HPIBCTL register controls the reset line of the DSP. It is possible to reset DSP to start the DSP Boot Sequence (refer to 8.1.2).

DSP PLL is a part of the Clock Controller module and is fully controlled by the ARM.

8.1.4. Interrupt Signals

The ARM sends an interrupt to the DSP core (INT0) by writing a 0 to the DSPINT0 bit (bit 7) of the HPIBCTL register (address 0x30600).

The DSP sends an interrupts (INT11) to the ARM core by setting to 1 the ARMINT bit (bit 3) of the co-processor Interrupt Control Register (0x280).


8.2. DSP Manager

Monterey Linux provides a Linux software component (DSP Manager) for control of and communication with the DSP. The DSP Manager provides initialization, reset, and booting of the DSP from Monterey Linux with an application image that can be either a DSP/BIOS compound application or a custom firmware image.

8.2.1. DSP Control Interface

Monterey Linux implements the following DSP control mechanisms:

Initialization of the DSP from the ARM9

Boot of a DSP application image to the DSP core

Reset of the DSP

8.2.1.1. DSP Control Kernel Interface Monterey Linux provides the following DSP control interface for Linux kernel level components (device drivers). The API is defined in the $TARGET_ROOT/usr/include/asm/dsp.h header file.

int dsp_claim(void);

This service claims control of the DSP and indicates that the calling application desires control of the DSP. The function returns -1 if another software component has already claimed the DSP. Otherwise, the function raises a lock and returns 0. An application must first successfully claim control of the DSP before attempting to use it. For example: #include <asm/dsp.h> ... if (!dsp_claim()) { /* The DSP is locked. Boot the DSP firmware. */ ... } else { /* Someone is using the DSP. Report an error. */ ... }

int dsp_reset(void);

This service resets the DSP and holds the DSP in reset state. For example:

#include <asm/dsp.h>


... /* Reset the DSP. */ if (!dsp_reset()) { /* The DSP is in the reset state now. */ ... } else { /* Unable to reset the DSP. Report an error. */ ... }

int dsp_boot(int freq, const void * image, int size);

This service initializes and boots up the DSP with an application image specified by the image pointer of size bytes in size. freq specifies the DSP clock in MHz. This function operates as follows:

- Ensure that the DSP is in reset state. Otherwise, return an error.

- Program the DSP clock divisor accordingly to the specified freq value.

- Load the specified image to the DSP RAM.

- Release the DSP from reset state.

When the function returns, the DSP is running the specified application. The function returns 0 on success, a negative errno code otherwise.

For example: #include <asm/dsp.h> ... /* Set the DSP to operate at 72MHz and boot the firmware. */ if (!dsp_boot(72, image_ptr, image_size)) { /* The DSP is set up and booted. */ ... } else { /* Unable to boot the DSP. Report an error. */ ... }

int dsp_release(void);

This service releases the DSP lock created by a call to dsp_claim() indicating that the calling application no longer needs the DSP.

For example: #include <asm/dsp.h> ... /* We are not using the DSP anymore. Release the lock. */


if (!dsp_release()) { /* A success. The DSP is free. */ ... } else { /* Unable to release the DSP. Report an error. */ ... }

8.2.1.2. DSP Control User Space Interface Monterey Linux provides the following DSP control utility for Linux user space applications:

dspctl -b <binary image> <pll>

dspctl -r

-b Sets the specified DSP clock speed (via the pll parameter measured in MHz) and boots the DSP with the specified binary firmware image, identified as a file in the Linux file system. This will fail if either the DSP is not in a reset state or the DSP is locked. On success, the DSP is locked. The firmware image is in COFF format and is generated either by the Monterey Linux DSP development tools or using the Code Composer Studio toolchain.

-r Resets the DSP and unconditionally releases the DSP lock.

For example:

Set the DSP to operate at 63MHz and boot the /etc/asmfw.out DSP firmware image:

/> dspctl -b /etc/asmfw.out 63

Reset the DSP and release the lock:

/> dspctl –r

8.3. DSP API

Monterey Linux provides an interface that simplifies and abstracts access to the DSP/ARM9 inter-core communication mechanisms (the shared RAM and inter-core interrupts; refer to 8.1). The API is provided for the following programming contexts:

ARM9 Monterey Linux kernel

DSP assembly code built using the Monterey Linux GNU binutils


DSP C built using the Code Composer Studio™ tools

8.3.1. Monterey Linux Kernel DSP API

The Monterey Linux kernel provides the following macros and functions (defined in $TARGET_ROOT/usr/include/asm/arch/apiram.h) for access to the ARM9/DSP inter-core communication mechanisms from kernel components (such as device drivers):

APIRAM_BASE

This macro defines the address the shared RAM is accessible at from the ARM9. APIRAM_SIZE

This macro defines the size (in 2-byte words) of the shared RAM accessible from the ARM9.

APIRAM_IRQ

This macro defines the IRQ number of the cross-interrupt the DSP generates to the ARM9.

APIRAM_ADDR(off)

This macro calculates the address of a particular position in the shared RAM (defined by the off offset in 2-byte words), as accessible from the ARM9.

APIRAM_COUNT(len)

This macro translates byte count to word count. APIRAM_SIZEOF(obj)

This macro calculates a C object size (via sizeof) and translates the size to a word count.

void apiram_copy_from(unsigned short *to, unsigned int from_off, int count);

This function copies the specified number of words (the count argument) from the shared RAM at offset from_off into the buffer pointed to by the to argument.

void apiram_copy_to(unsigned int to_off, unsigned short *from, int count);

This function copies the specified number of words (the count argument) to the shared RAM at offset to_off from the buffer pointed to by the from argument.

void apiram_copy_from_16to8(unsigned char *to, unsigned int from_off, int count);

This function copies the specified number of words (the count argument) from the shared RAM at offset from_off into the byte buffer pointed to by the to argument. Each word is translated to a byte.


void apiram_copy_to_8to16(unsigned int to_off, unsigned char *from, int count);

This function copies the specified number of bytes (the count argument) to the shared RAM at offset to_off from the buffer pointed to by the from argument. Each byte is translated to a word.

void apiram_intr(void);

This function generates a cross-interrupt to the DSP.

8.3.2. DSP Assembly API

Monterey Linux provides the following macros for access to the ARM9/DSP inter-core communication mechanisms from DSP assembly-level programs developed using the Monterey Linux GNU toolchain.

APIRAM_BASE

This macro defines the address the shared RAM is accessible at from the DSP. APIRAM_SIZE

This macro defines the size (in 2-byte words) of the shared RAM accessible from the DSP.

APIRAM_IRQ

This macro defines the DSP IRQ number of the cross-interrupt the ARM9 generates to the DSP.

APIRAM_INTR_HI

This macro drives the host interrupt line high. APIRAM_INTR_LO

This macro drives the host interrupt line low. APIRAM_INTR

This macro drives the host interrupt linehigh then low effectively generating a cross-interrupt from the DSP to the ARM9.

8.3.3. DSP C API

Monterey Linux provides the following macros and functions for access to the ARM9/DSP inter-core communication mechanisms from DSP/BIOS applications developed using the Code Composer Studio tools:


Note: Code Composer Studio or DSP/BIOS are not included in the Monterey Linux product and must be acquired separately.

APIRAM_BASE

This macro defines the address the shared RAM is accessible at from the DSP. APIRAM_SIZE

This macro defines the size (in 2-byte words) of the shared RAM accessible from the DSP.

APIRAM_IRQ

This macro defines the DSP IRQ number of the cross-interrupt the ARM9 generates to the DSP.

APIRAM_ADDR(off)

This macro calculates the address of a particular position in the shared RAM (defined by the off offset in 2-byte words), as accessible from the DSP.

void apiram_intr_hi(void)

This function drives the host interrupt line high. void apiram_intr_lo(void)

This function drives the host interrupt line low. void apiram_intr(void)

This function drives the host interrupt line high then low effectively generating a cross-interrupt from the DSP to the ARM9.

8.3.4. Sample Use of the DSP API

Monterey Linux includes a sample project (see Chapter 9) named dsp that uses the DSP API to illustrate communications between Monterey Linux running on the ARM9 core and DSP programs running on the DSP core. From the DSP side, use of the API in both assembly-level programs and DSP/BIOS applications is illustrated by the sample project.

The following files define the DSP assembly and C APIs and reside in the dsp sample project directory:

DSP assembly API (refer to 8.3.2): $TARGET_ROOT/usr/src/sample/dsp/asmfw/apiram.asm

DSP C API (refer to 8.3.3): $TARGET_ROOT/usr/src/sample/dsp/dspbiosfw/apiram.h


8.4. GNU Toolchain Targeting the C54x DSP Core

Monterey Linux includes the GNU binutils targeted to the C54x DSP core. These tools run on the Linux development host and allow the development of DSP assembly-level programs using the Monterey Linux cross development environment.

8.4.1. GNU Binutils for the DSP

The Monterey Linux binutils that target the DSP, include the following:

Tool Description

addr2line Convert addresses into file names and line numbers. ar Create, modify, and extract from archive. as The GNU Assembler. c++filt Demangle C++ symbols. ld The GNU linker. nm List symbols from object files. objcopy Copy and translate object files. objdump Display information from object files. ranlib Generate index to archive. readelf Displays information about ELF files. size List section sizes and total size. strings Print the strings of printable characters in files. strip Discard symbols from object files.

Table 17: DSP binutils

The corresponding binaries are accessible from within the Monterey Linux development environment and are prefixed with c54x-unknown-. For instance, to run the GNU assembler for the DSP, use the following as pathname to the binary: c54x-unknown-as.

Note: The unknown part of the GNU binutils pathnames denotes that the tools do not target a specific operating system on the DSP. The tools produce valid target code for the DSP without relying on a particular operating system environment controlling the DSP.

Monterey Linux includes man pages for the GNU binutils. These man pages contain full information about the tools command line parameters. You can view the man


pages from within the Monterey Linux development environment using the man command. For example:

ML(arm926ejs):[tester@host1]$ man c54x-unknown-as

Also, a tool can be run with the --help option to produce a quick reference of command line parameters. For example:

ML(arm926ejs):[tester@host1]$ c54x-unknown-addr2line ––help

8.4.2. Sample Use of the GNU binutils

The dsp sample project (refer to 8.3.4) makes use of the Monterey Linux DSP binutils tools to build the assembly-level DSP program included in the sample.

The sample project build procedure defined by the Makefile uses the following GNU binutils tools:

c54x-unknown-as

This assembler is used to build an object file of the sample DSP firmware from the sources (main.asm):

ML(arm926ejs):[tester@host1]$ c54x-unknown-as -o main.o main.asm

This produces the main.o object file. c54x-unknown-ld

This linker is used to link a firmware binary in COFF format: ML(arm926ejs):[tester@host1]$ c54x-unknown-ld -o asmfw.out -T asmfw.lds main.o

This step uses the asmfw.lds linker script file to organize the resulting object to adhere to the DSP firmware memory map.

The resulting asmfw.out binary can be booted on the DSP from the target using the dspctl DSP Manager utility.


9. Monterey Linux Sample Projects This chapter describes the sample (demonstration) projects included in the Monterey Linux distribution. The sample projects are just that - each of them is designed to showcase specific Monterey Linux functionality on the target. By selecting a sample project that provides the best match for the functionality you need in your custom embedded system, you can jump-start development of your Monterey Linux embedded application.

9.1. Sample Projects Overview

9.1.1. What is a Monterey Linux Sample Project?

The Monterey Linux distribution provides a number of target sample projects. Once you have completed the installation, the sample projects are available in the following directory:

$TARGET_ROOT/usr/src/sample

Within the sample directory are sample project sub-directories. Each sample project is independent of the other sample projects included in the installation. A sample project is a small (or in some cases, not so small) embedded system based on Monterey Linux that is dedicated to the goal of demonstrating certain target functionality. For instance, there is a sample project that shows how to configure, build, boot, and use telnet facilities on the Monterey Linux target. Since the provided sample projects span a wide range of the target functionality supported by Monterey Linux, typically you will be able to find a sample project that is closest to the ultimate functionality you need in your embedded application and can then modify it as appropriate for the application at hand.

A sample project is a complete Monterey Linux application, fully prepared for building from scratch using the Monterey Linux development tools and ready to run on the Monterey Linux target reference platforms. The kernel configuration and specification

Chapter

9

of the target file system is included with each sample project, enabling you to analyze the target configuration and fine-tune it to the needs of your particular custom configuration.

9.1.2. Sample Projects Summary

The following table summarizes the functionality of the sample projects included in the Monterey Linux distribution:

Sample Project Functionality Described In

telnet telnet client 9.2.1 ftp ftp client 9.2.2 tinylogin User account management and login

demonstration 9.2.3

nfsroot Network-enabled kernel configured to mount a root file system over NFS

9.2.4

boa Web server 9.2.5 ssh SSH demonstration 9.2.6 dsp Simple DSP demonstration 9.2.7 realfeel Real-time patches demonstration 10.1.3 framebuffer Frame buffer demonstration 10.2.5 directfb DirectFB demonstration 10.3.4

Table 18: Sample Projects

9.1.3. A Sample Project's Directory Layout

Each sample project has the following directory layout:

sample/


local/ Target Linux configuration files specific to the sample project. src/ Source files for project specific programs used in the sample

project. Makefile Makefile used to build the sample project <sample>.config Kernel configuration of the sample project.

local/ src/ Makefile <sample>.config <sample>.spec


This configuration file can be updated using a kernel configurator tool, such as make xconfig.

<sample>.spec Target file system specification file. This is an ASCII file that can be edited manually (using vi, for instance) to change the contents of the target file system. A Monterey Linux tool processes this file to generate the actual file image.

9.1.4. Building a Sample Project

Building a sample is as simple as typing make while in the directory containing the sample. This will build any custom programs that are to be included in the sample, as well as the kernel and root file system images. To facilitate development of a custom embedded system using an existing sample project as a base, Monterey Linux provides additional Makefile goals that allow for re-building only of specific parts of the system. The following Makefile goals are available:

make this

Steps into the src subdirectory and invokes make all. This goal is normally used to re-build any custom applications included in the sample project.

make rootfs

Builds the rfs file system image according to the spec file <sample>.spec. Note that due to an explicit dependency in the Makefile, the file system will not be rebuilt if it is newer than the spec file.

make kernel

Builds the kernel image according to the kernel configuration file <sample>.config. Note that if the kernel image is newer than the kernel configuration file, the former will not be re-built.

make all

Equivalent of the following command sequence:

make this

make rootfs

make kernel

make clean

Removes any files produced by the make all goal. Also, steps into the src directory and invokes make clean in that directory.


9.1.5. A Sample Project's Target Images

When built, a sample project produces the following target files ready for download and execution on the target via ARMboot:

<sample>.kernel Linux kernel image.

<sample>.rfs Root file system image of the root file system.

9.2. Sample Project Reference

9.2.1. telnet Sample Project

SAMPLE PROJECT telnet

LOCATION $TARGET_ROOT/usr/src/sample/telnet

DESCRIPTION

The telnet sample demonstrates functionality of a telnet client in a small, network-enabled embedded system based on Monterey Linux.

Once the telnet sample is booted, you are presented with a sash prompt. At this point you can manually bring up the network interface using the ifconfig command. The route command is also included in the file system, so you can use it to adjust the kernel routing table as needed. For instance, you can set up a default gateway to allow access to hosts outside of your LAN. At any time, you can use the ping command that is also included in the sample to verify that the network is accessible.

The focus of this sample is the telnet client. Once networking is set up, use the telnet command to initiate a telnet session to a host on the network. The telnet client provided by Monterey Linux works essentially the same as with a standard desktop Linux, so there should be no problems in connecting with another host system.

Note: Another Monterey Linux sample project, tinylogin, demonstrates a telnet server functionality. Please refer to 9.2.3 below.

BOOT SCENARIO

The telnet sample consists of an uncompressed kernel image and uncompressed image of the root file system. ARMboot copies both images into RAM, sets up


necessary parameters, such as the kernel command line, and transfers control to the Linux kernel.

Linux starts up and initializes the serial console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the telnet root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init. This version is included as part of the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The last step is to launch an interactive shell (sash).

The /etc/rc script performs the following actions:

/var/config, /var/tmp, /var/log, /var/run, and /var/lock subdirectories are created. The /tmp directory is a symbolic link to /var/tmp.

proc file system is mounted.

KERNEL BOOT PARAMETERS root = /dev/ram0

DM320/DM342 SPECIFIC DRIVERS

This sample project configures and uses the following DM320/DM342-specific device drivers:

Driver Kernel Configuration Options

Serial From the Character Devices menu go to Serial drivers and enable DM310/DM342 serial port support and Console on DM310/DM342 serial port

Ethernet From the Network Device Support menu go to the Ethernet (10 or 100 Mbit) submenu and enable Cirrus Logic CS8900A support

SAMPLE OUTPUT ON THE DM320/DM342 EVM REFERENCE PLATFORM

The following is a snapshot of the output produced by the sample project on the DM320/DM342 EVM reference platform. The output is annotated by comments illustrating important steps during bootstrap and operation.

From ARMboot on the target, download the kernel image from a TFTP host:

dm320evm # tftp 00a00000 telnet.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'telnet.kernel'. Load address: 0xa00000 Loading: ################################################################# ################################################################# #########################################


done Bytes transferred = 874252 (d570c hex)

Download the root file system image from a TFTP host:

dm320evm # tftp 00d00000 telnet.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'telnet.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ###################################### done Bytes transferred = 4187200 (3fe440 hex)

Specify the Monterey Linux kernel parameters:


Boot Monterey Linux on the target:

dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 874188 Bytes = 853.7 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK OK ## Loading Ramdisk Image at 00d00000 ... Image Name: telnet RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #3 Mon Mar 22 23:16:18 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 11088KB available (767K code, 182K data, 40K init)


Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-22:29+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

Once the telnet sample is booted, a sash prompt appears. At this point you can manually bring up the network interface using the ifconfig command:

/> ifconfig eth0 192.168.0.16 /> route add default gw 192.168.0.1

At any time, you can use the ping command included in the sample to verify that the network is accessible:

/> ping -c 3 192.168.0.1 PING 192.168.0.1 (192.168.0.1): 56 data bytes 64 bytes from 192.168.0.1: icmp_seq=0 ttl=255 time=0.0 ms 64 bytes from 192.168.0.1: icmp_seq=1 ttl=255 time=0.0 ms 64 bytes from 192.168.0.1: icmp_seq=2 ttl=255 time=0.0 ms --- 192.168.0.1 ping statistics --- 3 packets transmitted, 3 packets received, 0% packet loss round-trip min/avg/max = 0.0/0.0/0.0 ms


Once the networking is set up, use the telnet command to initiate a telnet session to a host on the network.

/> telnet 192.168.0.1 Trying 192.168.0.1 (5888)... Connected to 192.168.0.1. Escape character is '^]'. Red Hat Linux release 6.1 (Cartman) Kernel 2.2.19-6.2.12 on an i686 login: tester Password: Last login: Tue Mar 23 14:00:25 from host1 Use target-location utility to find target in Test Laboratory bash$ hostname host1 bash$ ls -la total 36 drwxr-xr-x 3 tester testing 4096 Jan 18 2001 . drwxr-xr-x 51 root root 4096 Mar 19 17:12 .. -rw-r--r-- 1 tester testing 1422 Aug 8 2000 .Xdefaults -rw------- 1 tester testing 348 Feb 3 18:15 .bash_history -rw-r--r-- 1 tester testing 24 Aug 8 2000 .bash_logout -rw-r--r-- 1 tester testing 230 Aug 8 2000 .bash_profile -rw-r--r-- 1 tester testing 124 Aug 8 2000 .bashrc -rw-r--r-- 1 tester testing 3394 Aug 8 2000 .screenrc drwx------ 2 tester root 4096 Sep 11 2000 .xauth bash$

9.2.2. ftp Sample Project

SAMPLE PROJECT ftp

LOCATION $TARGET_ROOT/usr/src/sample/ftp

DESCRIPTION

The ftp sample demonstrates functionality of a FTP client in a small, network-enabled embedded system based on Monterey Linux.

Once the ftp sample is booted, you are presented with a sash prompt. At this point you can manually bring up the network interface using the ifconfig command. The route command is also included in the file system, so you can use it to adjust the kernel routing table as needed. For instance, you can set up a default gateway to allow access to hosts outside of your LAN. At any time, you can use the ping command that is also included in the sample to verify that the network is accessible.

The focus of this sample is the FTP client. Once the networking is set up, use the ftp command to initiate an FTP session to a host on the network. The FTP client provided by Monterey Linux works essentially the same as a standard desktop Linux FTP client, so there should be no problems in connecting with another host system.


BOOT SCENARIO

The ftp sample consists of an uncompressed kernel image and compressed image of the root file system. ARMboot boots both images into RAM, decompresses the root file system image, sets up necessary parameters, such as the kernel command line, and transfers control to the Linux kernel.

Linux starts up and initializes the serial console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the ftp root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init. This version of init is included in the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The final step is to launch the interactive shell (sash).











The following is a snapshot of the output produced by the sample project on the DM320/DM342 EVM reference platform. The output is annotated by comments illustrating important steps of the sample project bootstrapping and operation.



dm320evm # tftp 00a00000 ftp.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'ftp.kernel'. Load address: 0xa00000 Loading: ################################################################# ################################################################# ######################################### done Bytes transferred = 874252 (d570c hex)


dm320evm # tftp 00d00000 ftp.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'ftp.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ############ done Bytes transferred = 724621 (b0e8d hex)




dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (uncompressed) Data Size: 874188 Bytes = 853.7 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK OK ## Loading Ramdisk Image at 00d00000 ... Image Name: ftp RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (gzip compressed) Data Size: 724557 Bytes = 707.6 kB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #1 Mon Mar 22 23:09:07 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 14472KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes)


Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: Compressed image found at block 0 Freeing initrd memory: 707K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-22:29+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

Once the ftp sample is booted, a sash prompt appears. At this point you can manually bring up the network interface using the ifconfig command:


At any time, you can use the ping command included in the sample to verify that the network is accessible:

/> ping -c 3 192.168.0.1 PING 192.168.0.1 (192.168.0.1): 56 data bytes 64 bytes from 192.168.0.1: icmp_seq=0 ttl=255 time=0.0 ms 64 bytes from 192.168.0.1: icmp_seq=1 ttl=255 time=0.0 ms 64 bytes from 192.168.0.1: icmp_seq=2 ttl=255 time=0.0 ms --- 192.168.0.1 ping statistics --- 3 packets transmitted, 3 packets received, 0% packet loss round-trip min/avg/max = 0.0/0.0/0.0 ms


Once the networking is set up, use the ftp command to initiate an ftp session to a host on the network.

/> ftp 192.168.0.1 Connected to 192.168.0.1. 220 host1 FTP server (Version wu-2.6.1-0.6x.21) ready. Name (192.168.0.1): tester 331 Password required for tester. Password: 230 User tester logged in. Remote system type is UNIX. Using binary mode to transfer files. ftp> bin 200 Type set to I. ftp> ha Hash mark printing on (1024 bytes/hash mark). ftp> cd /tftpboot 250 CWD command successful. ftp> mkdir arm926ejs 257 "/home/tftpboot/arm926ejs" new directory created. ftp> cd arm926ejs 250 CWD command successful. ftp> lcd /bin Local directory now /bin ftp> put busybox local: busybox remote: busybox 200 PORT command successful. 150 Opening BINARY mode data connection for busybox. ########################################################################################################################### 226 Transfer complete. 126220 bytes sent in 0.08 secs (1.5e+03 Kbytes/sec) ftp> ls -la 200 PORT command successful. 150 Opening ASCII mode data connection for directory listing. total 280 drwxr-xr-x 2 19999 100 4096 Mar 23 14:44 . drwxrwxrwx 75 root 100 8192 Mar 23 14:44 .. -rw-r--r-- 1 19999 100 126220 Mar 23 14:44 busybox 226 Transfer complete. ftp> lcd /tmp Local directory now /var/tmp ftp> get busybox local: busybox remote: busybox 200 PORT command successful. 150 Opening BINARY mode data connection for busybox (126220 bytes). ########################################################################################################################### 226 Transfer complete. 126220 bytes received in 0.13 secs (9.5e+02 Kbytes/sec) ftp> dele busybox 250 DELE command successful. ftp> ls -la 200 PORT command successful. 150 Opening ASCII mode data connection for directory listing. total 24 drwxr-xr-x 2 19999 100 4096 Mar 23 14:44 . drwxrwxrwx 75 root 100 8192 Mar 23 14:44 .. 226 Transfer complete. ftp> cd .. 250 CWD command successful. ftp> dele arm926ejs 250 DELE command successful. ftp> by 221-You have transferred 252440 bytes in 2 files. 221-Total traffic for this session was 253614 bytes in 2 transfers. 221 Thank you for using the FTP service on host1. />


9.2.3. tinylogin Sample Project

SAMPLE PROJECT tinylogin

LOCATION $TARGET_ROOT/usr/src/sample/tinylogin

DESCRIPTION

The tinylogin sample demonstrates the user management facilities provided by Monterey Linux as well as telnet server functionality.

Once the tinylogin sample is booted, you are presented with a login prompt. Log in as root by typing target as the password. This will bring you to a shell prompt. The tinylogin sample, unlike the other Monterey Linux samples, has msh as the default shell. msh is similar to sash or bash, so you should not have any problems using it.

The focus of this sample is the user account management utilities provided by Monterey Linux in the form of the tinylogin binary. The following utilities are available:

login

getty

passwd

adduser

addgroup

deluser

delgroup

su

sulogin

The /etc directory of the tinylogin sample is mounted to a JFFS2 partition in Flash. This means that you can use the utilities above to update the user account information. Any modifications you make will still be present after you reset the target and boot the sample next time.

Try changing the super user password:

# passwd Changing password for root Enter the new password (minimum of 5, maximum of 8 characters) Please use a combination of upper and lower case letters and numbers. Enter new password:


Re-enter new password: passwd[28]: password for `root' changed by user `root' Password changed.

To check whether the new password works, log out from the target by typing exit and log in again:

# exit Process '/bin/getty 115200, ttyS0' (pid 27) exited. Scheduling it for restart. Starting pid 29, console /dev/console: '/bin/getty' demo login: root Password: login[29]: root login on `ttyS0' BusyBox v0.60.5 (2004.03.22-23:19+0000) Built-in shell (msh)

Try adding a user. For instance:

# adduser john Changing password for john Enter the new password (minimum of 5, maximum of 8 characters) Please use a combination of upper and lower case letters and numbers. Enter new password: Re-enter new password: passwd[32]: password for `john' changed by user `root' Password changed.

An additional functionality the tinylogin sample demonstrates is a telnet server. The server is started automatically during the system bootstrap, so as soon as you set up networking, you can log into the target from a remote host using telnet.

Bring up the network interface on the target using the ifconfig command. Optionally, you can use the route command, which is also included in the file system, to adjust the kernel routing table as needed. For instance, you can set up a default gateway to allow access to hosts outside of your LAN. At any time, you can use the ping command that is also included in the sample to verify that the network is accessible.

Once the networking is set up on the target, try logging in from a remote host. For instance, assuming the target IP address is 192.168.0.16, you can use the following command on the host to initiate a telnet session to the target:

bash$ telnet 192.168.0.16

BOOT SCENARIO

The tinylogin sample consists of a compressed kernel image and uncompressed image of the root file system. ARMboot boots both images into RAM, decompresses the kernel, sets up necessary parameters, such as the kernel command line, and transfers control to the uncompressed Linux kernel.


When the tinylogin sample project is first loaded on the board, it expects to find an erased Flash partition. Use the erase command of ARMboot to erase the Flash before booting tinylogin for the first time.

Linux starts up and initializes the serial console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the tinylogin root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init - that is included in the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The final step is to invoke the login utility. When the user is authenticated, the interactive shell (busybox msh) is launched.




Mounts a JFFS2 partition to a temporary location (/mnt).

Checks if the mounted JFFS2 partition presents valid /etc contents. More specifically, it checks if files /mnt/passwd and /mnt/shadow exist and have a non-zero length. If they do, it is assumed that the JFFS2 partition has valid /etc contents.

If the contents of the mounted JFFS2 partition were found invalid, restores the default /etc contents by copying them from root file system.

Re-mounts the JFFS2 partition to /etc.









Flash Enable Memory Technology Device support in the Memory Technology Devices menu. Select the MTD partitioning support, Direct char device access to MTD devices, and Caching block device access to MTD device options. Go to the RAM/ROM Flash chip drivers sub-menu and enable the Detect flash chips by Common Interface (CFI) probe and Support for AMD/Fujitsu flash chips options. Then go to the Mapping drivers for chip access menu and select CFI Flash device mapped on DM310/DM342.


The following is a snapshot of the output produced by the sample project on the DM320/DM342 EVM reference platform. The output is annotated by comments illustrating important steps of the sample project bootstrapping and operation:

From ARMboot on the target, erase the Flash partition when booting tinylogin for the first time:

dm320evm # erase 001c0000 002effff Erase Flash from 0x001c0000 to 0x002effff ...... done Erased 19 sectors


dm320evm # tftp 00a00000 tinylogin.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'tinylogin.kernel'. Load address: 0xa00000 Loading: ################################################################# ############################# done Bytes transferred = 480789 (75615 hex)


dm320evm # tftp 00d00000 tinylogin.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'tinylogin.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# #################################################################


################################################################# ###################################### done Bytes transferred = 4187200 (3fe440 hex)




dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 480725 Bytes = 469.5 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: tinylogin RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #5 Mon Mar 22 23:19:55 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 10952KB available (891K code, 191K data, 44K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd JFFS2 version 2.1. (C) 2001, 2002 Red Hat, Inc., designed by Axis Communications AB. ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected Amd/Fujitsu Extended Query Table v1.1 at 0x0040 number of CFI chips: 1 cfi_cmdset_0002: Disabling fast programming due to code brokenness. Using static partition definition Creating 4 MTD partitions on "DM310 flash": 0x00000000-0x00020000 : "U-Boot" 0x00020000-0x000c0000 : "Kernel"


0x000c0000-0x001f0000 : "Filesystem" 0x001f0000-0x00200000 : "U-Boot environment" NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 44K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-23:19+0000) multi-call binary Starting pid 8, console /dev/ttyS0: '/etc/rc'

When you run the tinylogin sample for the first time, there is no valid /etc contents in the Flash-based JFFS2 partition. They are copied from the root file system image.

JFFS /etc contents were found invalid. Restoring from RFS. Starting pid 27, console /dev/console: '/bin/getty'

When the login prompt appears, log in as root. The password is target.

demo login: root Password: login[27]: root login on `ttyS0' BusyBox v0.60.5 (2004.03.22-23:19+0000) Built-in shell (msh)

Once the tinylogin sample is booted, a msh prompt appears. At this point you can examine the user account management utilities:

# passwd Changing password for root Enter the new password (minimum of 5, maximum of 8 characters) Please use a combination of upper and lower case letters and numbers. Enter new password: Re-enter new password: passwd[28]: password for `root' changed by user `root' Password changed. #

9.2.4. nfsroot Sample Project

SAMPLE PROJECT nfsroot

LOCATION $TARGET_ROOT/usr/src/sample/nfsroot


DESCRIPTION

The nfsroot sample demonstrates use of Monterey Linux with an NFS-based root file system.

The nfsroot sample directory on the host includes the make-nfsroot script (in the nfsroot/src subdirectory), which can be used to facilitate creation of an NFS-mounted root file system for the target. The script must be run on the development host, in an empty directory that you wish to export via NFS. You have to run make-nfsroot as root because the script creates device nodes for the target system, which requires super user privileges. To create a directory on the host that can be exported as an NFS-mounted root file system for the target, step through the following procedure:

Activate Monterey Linux installation:

[tester@host1]$ . ACTIVATE.sh arm926ejs

Log in as super user:

ML(arm926ejs):[tester@host1]$ su [root@host1]#

Create an empty directory that you would like to export, for instance:

[root@host1]# mkdir /arm926ej

Go to the directory you have created and invoke the make-nfsroot script:

[root@host1]# cd /arm926ej [root@host1 arm926ejs]# $TARGET_ROOT/usr/src/sample/nfsroot/src/make-nfsroot

At this point, the /arm926ejs creates the root file system for the DM320/DM342 target.

NFS-export the /arm926ejs directory on the host. Exact instructions may depend on the version and configuration of the host Linux operating system you are using. For instance, on a Red Hat 7.2 system, this can be done by adding the following line to the /etc/exports file:

/arm926ejs *(rw,no_root_squash)

then restart the nfs service using the following command:

bash# /etc/init.d/nfs restart


BOOT SCENARIO

The nfsroot sample consists only of a compressed kernel image. ARMboot boots the image into RAM, decompresses it, sets up necessary parameters, such as the kernel command line, and transfers control to the uncompressed Linux kernel.

KERNEL BOOT PARAMETERS root=/dev/nfs rw

nfsroot=<nfs_server_ip>:<nfs_root_dir>

ip=<target_ip>:<nfs_server_ip>:::::off

panic=1

where

<nfs_server_ip> IP address of the NFS server

<target_ip> IP address of the DM320/DM342 target

<nfs_root_dir> Directory on the NFS server to be mounted as the root file system.







The following is a snapshot of the output produced by the sample project on the DM320/DM342 EVM reference platform. The output is annotated by comments illustrating important bootstrap and operations steps of the sample project.



dm320evm # tftp 00a00000 nfsroot.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is .168.0.16 Filename 'nfsroot.kernel'. Load address: 0xa00000 Loading: ################################################################# ################################### done Bytes transferred = 507318 (7bdb6 hex)

Set up the command line to be passed to the kernel and boot Monterey Linux on the target:

dm320evm # setenv bootargs root=/dev/nfs rw nfsroot=192.168.0.1: /arm926ej ip=192.168.0.16:192.168.0.1:::::off panic=1 bootm 00a00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 507254 Bytes = 495.4 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #2 Mon Mar 22 23:12:00 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/nfs rw nfsroot=192.168.0.1: /arm926ej ip=192.168.0.16:192.168.0.1:::::off panic=1 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 14980KB available (917K code, 220K data, 52K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) IP-Config: Guessing netmask 255.255.0.0 IP-Config: Complete: device=eth0, addr=192.168.0.16, mask=255.255.0.0, gw=255.255.255.255, host=192.168.0.16, domain=, nis-domain=(none), bootserver=192.168.0.1, rootserver=192.168.0.1, rootpath= NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. Looking up port of RPC 100003/2 on 192.168.0.1


Looking up port of RPC 100005/1 on 192.168.0.1 VFS: Mounted root (nfs filesystem). Freeing init memory: 52K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-22:29+0000) multi-call binary Starting pid 8, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: ifconfig lo 127.0.0.1 Command: route add -net 127.0.0.0 netmask 255.255.255.0 lo Execution Finished, Exiting Starting pid 13, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

Once the nfsroot sample is booted, the network interface is already up. You can examine its parameters using the ifconfig command:

/> ifconfig eth0 eth0 Link encap:Ethernet HWaddr 00:01:02:2C:6D:18 inet addr:192.168.0.16 Bcast: 192.168.0.255 Mask:255.255.0.0 UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:1856 errors:0 dropped:0 overruns:0 frame:0 TX packets:367 errors:3 dropped:0 overruns:3 carrier:0 collisions:22 txqueuelen:100 RX bytes:1093922 (1.0 MiB) TX bytes:56474 (55.1 kiB) Interrupt:23

You can work with the target system as usual. If you have created the NFS-mounted root file system using the make-nfsroot script, all the standard busybox commands are available, as well as FTP and telnet clients.

/> ps -x PID TTY Uid Size State Command 1 0 1420 S init 2 0 0 S [keventd] 3 0 0 R [ksoftirqd_CPU0] 4 0 0 S [kswapd] 5 0 0 S [bdflush] 6 0 0 S [kupdated] 7 0 0 S [rpciod] 13 ttyS0 0 1328 S /bin/sh 15 ttyS0 0 1748 R ps -x /> cd /tmp /tmp> cp /bin/busybox . /tmp> ls -la drwxr-xr-x 2 0 0 4096 Mar 23 2004 . drwxr-xr-x 11 0 0 4096 Mar 23 2004 .. -rwxr-xr-x 1 0 0 126220 Jan 1 00:04 busybox /tmp> ls -la /etc drwxr-xr-x 8 0 0 4096 Mar 23 2004 . drwxr-xr-x 11 0 0 4096 Mar 23 2004 .. drwxr-xr-x 2 0 0 4096 Mar 23 2004 boa -rw-r--r-- 1 0 0 404 Mar 22 2004 ftpaccess -rw-r--r-- 1 0 0 538 Mar 22 2004 ftpconversions -rw------- 1 0 0 37 Mar 22 2004 ftpgroups -rw------- 1 0 0 190 Mar 22 2004 ftphosts -rw------- 1 0 0 83 Mar 22 2004 ftpusers -rw-r----- 1 0 0 151 Mar 23 2004 hosts -rw-r----- 1 0 0 43 Mar 23 2004 inittab -rw-r--r-- 1 0 0 0 Mar 22 2004 ld.so.conf


drwxr-xr-x 2 0 0 4096 Mar 23 2004 logrotate.d -rw-r--r-- 1 0 0 12704 Mar 22 2004 mime.types -rw-r--r-- 1 0 0 1744 Mar 22 2004 nsswitch.conf drwxr-xr-x 2 0 0 4096 Mar 23 2004 pam.d -rwxr-x--- 1 0 0 121 Mar 23 2004 rc drwxr-xr-x 3 0 0 4096 Mar 23 2004 rc.d -rw-r----- 1 0 0 1101 Mar 22 2004 rndc.conf -rw-r----- 1 0 0 77 Mar 22 2004 rndc.key -rw-r--r-- 1 0 0 1615 Mar 22 2004 rpc -rw-r----- 1 0 0 8205 Mar 23 2004 services drwxr-xr-x 2 0 0 4096 Mar 23 2004 ssh drwxr-xr-x 2 0 0 4096 Mar 23 2004 sysconfig /tmp> cat /etc/rc #!/bin/sh hostname demo mount -t proc proc /proc ifconfig lo 127.0.0.1 route add -net 127.0.0.0 netmask 255.255.255.0 lo /tmp> date Tue Mar 23 16:40:08 UTC 2004 /tmp> ping 192.168.0.1 PING 192.168.0.1 (192.168.0.1): 56 data bytes 64 bytes from 192.168.0.1: icmp_seq=0 ttl=255 time=0.0 ms 64 bytes from 192.168.0.1: icmp_seq=1 ttl=255 time=0.0 ms 64 bytes from 192.168.0.1: icmp_seq=2 ttl=255 time=0.0 ms --- 192.168.0.1 ping statistics --- 3 packets transmitted, 3 packets received, 0% packet loss round-trip min/avg/max = 0.0/0.0/0.0 ms /tmp> ftp 192.168.0.1 Connected to 192.168.0.1. 220 ts FTP server (Version wu-2.6.2-5) ready. Name (192.168.0.1): tester1 331 Password required for tester1. Password: 230 User tester1 logged in. Remote system type is UNIX. Using binary mode to transfer files. ftp> ls -la 200 PORT command successful. 150 Opening ASCII mode data connection for directory listing. total 56 drwx------ 2 20000 20000 4096 Nov 19 2002 . drwxr-xr-x 32 root root 4096 Mar 23 16:07 .. -rw------- 1 20000 20000 882 Mar 4 13:12 .bash_history -rw-r--r-- 1 20000 20000 24 Oct 14 2002 .bash_logout -rw-r--r-- 1 20000 20000 191 Oct 14 2002 .bash_profile -rw-r--r-- 1 20000 20000 124 Oct 14 2002 .bashrc -rw-r--r-- 1 20000 20000 854 Oct 14 2002 .emacs 226 Transfer complete. ftp> by 221-You have transferred 0 bytes in 0 files. 221-Total traffic for this session was 353 bytes in 0 transfers. 221-Thank you for using the FTP service on host1. 221 Goodbye. /tmp> telnet 192.168.0.1 Trying 192.168.0.1 (5888)... Connected to 192.168.0.1. Escape character is '^]'. Red Hat Linux release 7.3 (Valhalla) Kernel 2.4.18-3 on an i686 login: tester Password: Last login: Tue Mar 23 17:42:52 from 192.168.0.16 ----------------------------------------------------------------------------- Test_Name Serial Reset Power IP Using Time ----------------------------------------------------------------------------- vc5471 <com> <res> <pwr_on/off> 192.168.0.23 used by green Mar 23 17:01 trab <com> <res> <pwr_on/off> 192.168.0.28 is not used dripmc_com2 <com> --- --- --- is not used shmm2_1 <com> --- --- 192.168.0.15 is not used


dripmc <com> --- --- 192.168.0.21 is not used avr <com> --- --- --- is not used zfx86 <com> --- --- 192.168.0.22 is not used schroff <com> --- --- 192.168.0.17 is not used schroff2 <com> --- --- 192.168.0.19 is not used ipmc <com> --- --- --- is not used rpxlite <com> --- --- 192.168.1.53 is not used Use com <n> script to connect to line <n> Use res <n> script to reset line <n> Use pwr_[on/off] <n> scripts to power on/off line <n> Use testinfo utility to get state of lines [tester@host1 tester]$ ls -la total 28 drwx------ 2 tester tester 4096 Nov 19 2002 . drwxr-xr-x 32 root root 4096 Mar 23 16:07 .. -rw------- 1 tester tester 882 Mar 4 13:12 .bash_history -rw-r--r-- 1 tester tester 24 Oct 14 2002 .bash_logout -rw-r--r-- 1 tester tester 191 Oct 14 2002 .bash_profile -rw-r--r-- 1 tester tester 124 Oct 14 2002 .bashrc -rw-r--r-- 1 tester tester 854 Oct 14 2002 .emacs [tester@host1 tester]$

9.2.5. boa Sample Project

SAMPLE PROJECT boa

LOCATION $TARGET_ROOT/usr/src/sample/boa

DESCRIPTION

The boa sample demonstrates Web server functionality available within Monterey Linux.

Once the boa sample is booted, you are presented with a sash prompt. At this point you can manually bring up the network interface using the ifconfig command. The route command is also included in the file system, so you can use it to adjust the kernel routing table as needed. For instance, you can set up a default gateway to allow access to hosts outside of your LAN. At any time, you can use the ping command that is also included in the sample to verify that the network is accessible.

The focus of this sample is the boa Web server. Once the networking is set up, start the server by simply typing boa at the command prompt. The Web server starts and serves the index.htm example HTML page located in the /home/httpd/html directory on the target. You can access the Web server from any networking machine using the IP address of the target.

BOOT SCENARIO

The boa sample consists of a compressed kernel image and compressed image of the root file system. ARMboot boots both images into RAM, decompresses the kernel and file system, sets up necessary parameters, such as the kernel command line, and transfers control to the uncompressed Linux kernel.


Linux starts up and initializes the serial console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the boa image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init - that is included in the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The final step is to launch an interactive shell (sash).













dm320evm # tftp 00a00000 boa.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'boa.kernel'. Load address: 0xa00000 Loading: ################################################################# ################# done Bytes transferred = 418218 (661aa hex)



dm320evm # tftp 00d00000 boa.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'boa.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ############################ done Bytes transferred = 805465 (c4a59 hex)




dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 418154 Bytes = 408.4 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: boa RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (gzip compressed) Data Size: 805401 Bytes = 786.5 kB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #4 Mon Mar 22 23:18:57 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 14392KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0


IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: Compressed image found at block 0 Freeing initrd memory: 786K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-22:29+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir -m 777 /var/tmp Command: chmod 777 /var Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: ifconfig lo 127.0.0.1 Execution Finished, Exiting Starting pid 16, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

Once the boa sample is booted, a sash prompt appears. At this point you can manually bring up the network interface using the ifconfig command:

/> ifconfig eth0 192.168.0.16

Optionally, set up additional routing parameters.

/> route add default gw 192.168.0.1

Start the boa Web server:

/> boa /> [01/Jan/1970:00:00:23 +0000] boa: server version Boa/0.94.13 [01/Jan/1970:00:00:23 +0000] boa: server built Mar 22 2004 at 22:34:35. [01/Jan/1970:00:00:23 +0000] boa: starting server pid=20, port 80 />

At this point the boa Web server is accessible from any networking machine using the target IP address.

9.2.6. ssh Sample Project

SAMPLE PROJECT ssh

LOCATION $TARGET_ROOT/usr/src/sample/ssh


DESCRIPTION

The ssh sample demonstrates connecting between target and host using the secure enscrypted communications.

Once the ssh sample is booted, you are presented with a sash prompt. At this point you can manually bring up the network interface using the ifconfig command. The route command is also included in the file system, so you can use it to adjust the kernel routing table as needed. For instance, you can set up a default gateway to allow access to hosts outside of your LAN. At any time, you can use the ping command that is also included in the sample to verify that the network is accessible.

Once networking is set up, use the ssh command to initiate a Secure Shell session to a host on the network. The ssh client provided by Monterey Linux works essentially the same as with a standard desktop Linux, so there should be no problems in connecting with another host system.

Additionally, the ssh sample demonstrates a SSH server and secure copy functionalities. The SSH server is started automatically during the bootstrap, so as soon as you set up networking, you can log into the target from a remote host ssh and copy files via network.

BOOT SCENARIO

The ssh sample consists of a compressed kernel image and compressed image of the root file system. ARMboot copies both images into RAM, sets up necessary parameters, such as the kernel command line, and transfers control to the Linux kernel.

Linux starts up and initializes the serial console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the ssh root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init. This version is included as part of the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The last step is to launch an interactive shell (sash).














dm320evm # tftp 00a00000 ssh.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'ssh.kernel'. Load address: 0xa00000 Loading: ################################################################# ################# done Bytes transferred = 418218 (661aa hex)


dm320evm # tftp 00d00000 ssh.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'ssh.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ##################### done Bytes transferred = 1436436 (15eb14 hex)




dm320evm # bootm 00a00000 00d00000


## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 418154 Bytes = 408.4 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: ssh RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (gzip compressed) Data Size: 1436372 Bytes = 1.4 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #6 Mon Mar 22 23:21:14 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 13776KB available (767K code, 182K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: Compressed image found at block 0 Freeing initrd memory: 1402K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-22:29+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: Command: ifconfig lo 127.0.0.1


Command: daemon inetd Execution Finished, Exiting Starting pid 18, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

Once the ssh sample is booted, a sash prompt appears. At this point you can manually bring up the network interface using the ifconfig command:


Once the networking is set up, use the ssh command to initiate a SSH session to a host on the network.

/> ssh 192.168.0.1 The authenticity of host '192.168.0.1 (192.168.0.1)' can't be established. RSA key fingerprint is 32:64:0c:d1:8b:fd:d1:a0:c5:96:02:16:fd:ba:d1:1a. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added '192.168.0.1' (RSA) to the list of known hosts. [email protected]’s password: Last login: Tue Mar 23 17:31:38 2004 from from 192.168.0.1 [root@ts root]# cd /tmp [root@ts tmp]# mkdir dm320 bash# cd dm320 bash# echo "Test file" > file.tst bash# ls -la total 12 drwxr-xr-x 2 root root 4096 Mar 23 18:01 . drwxrwxrwt 4 root root 4096 Mar 23 18:01 .. -rw-r--r-- 1 root root 10 Mar 23 18:01 file.tst bash# exit

Use the ssh command to log in to the DM320/DM342 target from a remote host as root. The password is target.

bash$ ssh [email protected] [email protected]'s password: Sash command shell (version 1.1.1) /> cd /tmp /var/tmp> cp /etc/hosts . /var/tmp> ls -la drwxr-xr-x 2 root root 1024 Jan 1 00:22 . drwxr-xr-x 7 root root 1024 Jan 1 00:00 .. -rw-r----- 1 root root 151 Jan 1 00:22 hosts /var/tmp>exit

Use the scp command to copy files from the host to the DM320/DM342 target:

/> cd /tmp /var/tmp> scp 192.168.0.1:/tmp/dm320/file.tst . [email protected]'s password: warning: Executing scp1 compatibility. file.tst 100% |*****************************| 10 00:00 /var/tmp> ls -la drwxr-xr-x 2 root root 1024 Jan 1 00:28 . drwxr-xr-x 7 root root 1024 Jan 1 00:00 ..


-rw-r--r-- 1 root root 10 Jan 1 00:28 file.tst -rw-r----- 1 root root 151 Jan 1 00:22 hosts /var/tmp> exit

Or from the target to the host:

bash# scp 192.168.0.16:/tmp/hosts . Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? yes Host '192.168.0.16' added to the list of known hosts. [email protected]'s password: hosts | 0 KB | 0.1 kB/s | ETA: 00:00:00 | 100% bash# ls -la total 16 drwxr-xr-x 2 root root 4096 Mar 6 17:49 . drwxrwxrwx 10 root root 4096 Mar 6 17:16 .. -rw-r--r-- 1 root root 10 Mar 6 17:20 file.tst -rw-r----- 1 root root 151 Mar 6 17:49 hosts bash#

9.2.7. dsp Sample Project

SAMPLE PROJECT dsp

LOCATION $TARGET_ROOT/usr/src/sample/dsp

DESCRIPTION

The dsp sample is a simple demonstration of Monterey Linux DSP support.

The sample contains a loadable kernel module and a DSP firmware image. The Monterey Linux DSP Manager facilities are used to initialize the DSP and boot the firmware onto the DSP. The DSP firmware communicates with the ARM9 via the Monterey Linux DSP API.

Once the dsp sample is booted, you are presented with a sash prompt. At this point you can install the loadable kernel module using the standard insmod utility, included in the file system. Then you can boot the DSP with the sample firmware using the DSP Manager dspctl utility. Once booted, the firmware begins to communicate with the kernel module running on ARM9, which calculates the DSP CPU frequency based on the DSP interrupt rate and prints it onto the system console. You can stop the sample operation by resetting the DSP using the DSP Manager dspctl utility.

BOOT SCENARIO

The dsp sample consists of a compressed kernel image and uncompressed image of the root file system. ARMboot boots both images into RAM, decompresses the kernel, sets up necessary parameters, such as the kernel command line, and transfers control to the uncompressed Linux kernel.


Linux starts up and initializes the serial console and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the dsp root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init, which is included in the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The final step is to launch an interactive shell (sash).


/var/config, /var/log, /var/run, and /var/lock subdirectories are created. The /tmp directory is a symbolic link to /var/tmp.







DSP In the System Type menu, enable the DSP Management subsystem support and DSP Management device interface options.




dm320evm # tftpboot 00a00000 dsp.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'dsp.kernel'. Load address: 0xa00000 Loading: ############################################################### done Bytes transferred = 319300 (4df44 hex)



dm320evm # tftpboot 00d00000 dsp.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'dsp.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ###################################### done Bytes transferred = 4187200 (3fe440 hex)




dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 319236 Bytes = 311.8 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: dsp RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (uncompressed) Data Size: 4187136 Bytes = 3.10 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #7 Mon Mar 22 23:21:57 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.67 BogoMIPS Memory: 16MB = 16MB total Memory: 11296KB available (565K code, 181K data, 36K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes)


Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize NetWinder Floating Point Emulator V0.95 (c) 1998-1999 Rebel.com RAMDISK: ext2 filesystem found at block 0 RAMDISK: Loading 4089 blocks [1 disk] into ram disk... done. Freeing initrd memory: 4089K VFS: Mounted root (ext2 filesystem). Freeing init memory: 36K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-22:29+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Execution Finished, Exiting Starting pid 14, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

Once the dsp sample is booted, a sash prompt appears. At this point you can install the loadable kernel module using the standard insmod utility, included in the file system.

/> cd /etc /etc> insmod freq.o Using freq.o FREQ: successfully started.

Boot the DSP with a sample DSP application using the DSP Manager dspctl utility. The ARM9/DSP interaction will begin.

/etc> dspctl -b asmfw.out 120 s Booting: freq:120MHz size:416 words addr:0x13770FREQ: Found ASM frequency sample FREQ: clk_number=100 /etc> FREQ: int (1) FREQ: int (2), freq = 126MHz FREQ: int (3), freq = 125MHz FREQ: int (4), freq = 126MHz FREQ: int (5), freq = 126MHz FREQ: int (6), freq = 125MHz FREQ: int (7), freq = 126MHz FREQ: int (8), freq = 126MHz

Stop the DSP application by resetting the DSP using the DSP Manager dspctl utility.


/etc> dspctl -r

Now you can boot the DSP with the sample firmware using the DSP Manager dspctl utility, but initialize the DSP to run at a different clock rate. The ARM9/DSP interaction will begin.

/etc> dspctl -b asmfw.out 60 Booting: freq:60MHz size:416 words addr:0x13770FREQ: Found ASM frequency sample FREQ: clk_number=100 /etc> FREQ: int (1) FREQ: int (2), freq = 62MHz FREQ: int (3), freq = 62MHz FREQ: int (4), freq = 63MHz FREQ: int (5), freq = 62MHz FREQ: int (6), freq = 62MHz dspctl -r /etc>


10. Monterey Linux Advanced Features This chapter describes advanced software features provided by the Monterey Linux distribution.

10.1. Real-Time Patches

10.1.1. Preemption and Low-Latency Patches: What is it?

The real-time patches (preemption and low-latency patches) are two patches to the Monterey Linux kernel that, when enabled, substantially improve real-time responsiveness of the kernel.

Both patches are designed to improve the kernel scheduling latency (also sometimes called the interrupt latency). This is the time between an interrupt occurrence and the time when the task pending on the interrupt event wakes up. In other words, both patches attempt to improve the Linux task response times.

The mechanisms used by the two patches are quite different. This is described in further detail in the sections that follow. It is important to note that, while the two patches can be enabled independently, the best results are noticed when both patches are enabled simultaneously.

10.1.1.1. Preemption Patch In a very detailed and informative review of the preemption and low-latency patches published at www.linuxdevices.com, Clark Williams of Red Hat Inc describes the mechanisms behind the preemption patch in the following way:

The basic idea behind the preemption patches is to create opportunities for the scheduler to be run more often and minimize the time between the occurrence of an event and the running of the schedule() kernel function. The preemption patches do this by modifying the spinlock

Chapter

10

http://www.linuxdevices.com/


macros and the interrupt return code so that if it is safe to preempt the current process and a rescheduling request is pending, the scheduler is called.

What do I mean by "safe to preempt the current process"? Originally, the Linux kernel code assumed that upon entry to the kernel, be it from a trap or interrupt, the current process would not be changed until the kernel decides that it's safe to reschedule. This assumption was a simplifying assumption that allowed the kernel to modify kernel data structures without requiring that mutual exclusion primitives (such as spinlocks) be used to protect the modifications. Over time, the amount of code that modified kernel data structures without protecting those structures has been reduced, to the point that the preemption patches assume that if the code being executed is not an interrupt handler and no spinlocks are being held, then it is safe to context switch away from the current thread context.

The preemption patches added a variable to the task structure (the structure that maintains state for each thread) named preempt_count. The preempt_count field is modified by the macros preempt_disable(), preempt_enable() and preempt_enable_no_resched().

The preempt_disable() macro increments the preempt_count variable, while the preempt_enable*() macros decrement it. The preempt_enable() macro checks for a reschedule request by testing the value of need_resched and if it is true and the preempt_count variable is zero, calls the function preempt_schedule(). This function marks the fact that a preemption schedule has occurred by adding a large value to the preempt_count variable, calls the kernel schedule() function, then subtracts the value from preempt_count. The scheduler has been modified to check preempt_count for this active flag and so short-circuit some logic in the scheduler that is redundant when being called from the preemption routine.

The macro spin_lock() was modified to first call preempt_disable(), then actually manipulate the spinlock variable.

The macro spin_unlock() was modified to manipulate the lock variable and then call preempt_enable(), and the macro spin_trylock() was modified to first call preempt_disable() and then call preempt_enable() if the lock was not acquired.

In addition to checking for preemption opportunities when releasing a spinlock, the preemption patches also modify the interrupt return path code. This is assembly language code in the architecture specific directory of the kernel source that makes the same test done by preempt_enable() and calls the preempt_schedule() routine if conditions are right.

The effect of the preemption patch modifications is to reduce the amount of time between when wakeup occurs and sets the need_resched flag and when the scheduler may be run.

10.1.1.2. Low-Latency Patch In the same article (refer to 10.1.1.1), Clark Williams provides the following description of the low-latency patch:


Rather than attempting a brute-force approach (ala preemption) in a kernel that was not designed for it, the low-preemption patch focuses on introducing explicit preemption points in blocks of code that may execute for long stretches of time. The idea is to find places that iterate over large data structures and figure out how to safely introduce a call to the scheduler if the loop has gone over a certain threshold and a scheduling pass is needed (indicated by need_resched being set). Sometimes this entails dropping a spinlock, scheduling and then reacquiring the spinlock, which is also known as lock breaking.

10.1.2. Configuring the Real-Time Patches

This section describes how to enable the real-time patches in the Monterey Linux kernel. Note that both patches may be enabled at the same time.

10.1.2.1. Configuring the Preemption Patch Do the following to enable the preemption patch in the Monterey Linux kernel:

From the System Type menu enable the Preemptible Kernel option.

10.1.2.2. Configuring the Low-Latency Patch Do the following to enable the low-latency patch in the Monterey Linux kernel:

From the System Type menu enable the Low latency scheduling option.

10.1.3. realfeel Sample Project

The Monterey Linux distribution includes the realfeel sample project which is designed to illustrate the enhanced real-time responsiveness of the kernel when the real-time patches are enabled in the kernel.

SAMPLE PROJECT realfeel

LOCATION $TARGET_ROOT/usr/src/sample/realfeel

DESCRIPTION

The realfeel sample measures scheduling latency implemented by the Monterey Linux kernel. The sample includes two benchmarks, ported to Monterey Linux:

The realfeel benchmark. The benchmark is run on a loaded system to measure the scheduling latency. The original realfeel benchmark was designed for the x86 desktop PCs. It operates as follows. The benchmark uses


the /dev/rtc ioctl() interface to set up periodic interrupts from the RTC device. Having done that, the benchmark cycles in a loop. At each cycle, a read() call to /dev/rtc is made, effectively blocking until the driver gets an RTC interrupt and wakes up processes blocked on read(). At the same time, the benchmark measures the time each loop cycle takes to complete using the Pentium clock count register, running at the processor bus clock frequency. The difference between the measured time and the expected time each cycle would require based on the RTC periodic interrupt frequency is considered as a scheduling latency measurement. Measurement statistics (that is the number of samples that fall into a particular latency “backet”) are stored in RAM, and then written to a file when the benchmark stops.

The DM320/DM342 port of the benchmark required the following changes:

- A special device driver was developed (refer to src/module directory in the realfeel sample) that mimics the /dev/rtc behavior expected by the realfeel benchmark. The driver uses TIMER1 of the DM320/DM342 in a free running mode as a source of periodic interrupts.

- The time measurement function in the benchmark code was changed to use TIMER2 of the DM320/DM342 in a free running mode as a reference clock. The modified realfeel benchmark sources are available in the realfeel sample directory in src/realfeel2.

The dbench benchmark. The benchmark is a disk/file system benchmark. When run over an NFS mounted volume, the benchmark provides a system load. The dbench benchmark produces a system load typical for a file server. The dbench benchmark sources are available in the realfeel sample directory in src/dbench-2.0.

When the two benchmarks are run simultaneously, the realfeel benchmark provides measurements of a typical scheduling latency implemented by Monterey Linux.

Once the realfeel sample is booted, you are presented with a sash prompt. At this point you can configure the system and then run the scheduling latency benchmarks and view the measurements on a development host in a graphical histogram form.

BOOT SCENARIO

The realfeel sample consists of an uncompressed kernel image and uncompressed image of the root file system. ARMboot copies both images into RAM, sets up necessary parameters, such as the kernel command line, and transfers control to the Linux kernel.

Linux starts up and initializes the serial console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the telnet root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init. This version is included as part of the busybox package. init


examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The last step is to launch an interactive shell (sash).






This sample project configures and uses the following DM320/DM342-specific device drivers and kernel features:

Driver/ Kernel Feature

Kernel Configuration Options



Preemptible kernel From the System Type menu enable Preemptible Kernel

Low latency scheduling From the System Type menu enable Low latency scheduling




dm320evm # tftp 00a00000 realfeel.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'realfeel.kernel'. Load address: 0xa00000 Loading: ################################################################# ######################################### done Bytes transferred = 538051 (835c3 hex)



dm320evm # tftp 00d00000 realfeel.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'realfeel.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ##################### done Bytes transferred = 1770210 (1b02e2 hex)




dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 537987 Bytes = 525.4 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: realfeel RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (gzip compressed) Data Size: 1770146 Bytes = 1.7 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #9 Wed Mar 24 22:51:13 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Calibrating delay loop... 24.62 BogoMIPS Memory: 16MB = 16MB total Memory: 13144KB available (1039K code, 214K data, 40K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12)


ttyS01 at 0xe0030380 (irq = 13) pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 16384K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: Compressed image found at block 0 Freeing initrd memory: 1728K VFS: Mounted root (ext2 filesystem). Freeing init memory: 40K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.24-22:42+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Shell invoked to run file: /etc/rc Command: #!/bin/sh Command: Command: hostname demo Command: mount -t proc proc /proc Command: mkdir /var/config Command: mkdir /var/tmp Command: mkdir /var/log Command: mkdir /var/run Command: mkdir /var/lock Command: Command: ifconfig lo 127.0.0.1 Command: daemon inetd Command: Execution Finished, Exiting Starting pid 18, console /dev/console: '/bin/sh' Sash command shell (version 1.1.1) />

At this point you can manually bring up the network interface using the ifconfig command:


Once the networking is set up, use the mount command to mount an NFS volume with at least 50M of free space at the /mnt point:

/> mount -t nfs 192.168.0.1:/SCRATCH /mnt -o nolock

Run the dbench and realfeel benchmarks using the go.sh shell script. The measurements will be available in approximately 16 minutes. The measurements will be placed in the results.hist file at the root of the DM320 target file system. Also, it is possible to use ^C to terminate the benchmark before it completes and get the immediate results.

The go.sh script loads the device driver module that mimics /dev/rtc, starts the realfeel benchmark, and then provides a system load by running the dbench benchmark using the /mnt location (where an NFS volume is mounted) as a scratch area.


/> ./go.sh Shell invoked to run file: ./go.sh Command: #!/bin/sh Command: Command: # Start the load script. It will sleep a bit when Command: # started, thus giving some time to start the benchmark. Command: # Command: /etc/load.sh& [24] Command: Command: # Load the test module and start measuring scheduling latency. Command: # Runs for 1,000,000 samples or until interrupted by the user. Command: Command: insmod /etc/timer1.o Using /etc/timer1.o Shell invoked to run file: /etc/load.sh Command: #!/bin/sh Command: Command: # Sleep to allow realfeel to start. Command: sleep 20 Command: cd / Command: realfeel2 --samples 1000000 --hertz 1000 results.hist 0.048 MHz secondsPerTick=0.000021 ticksPerSecond=48373.416101 CPU frequency=49534378.087073 Interrupt frequency: 1000 Hz running for 1000000 samples 10000 cycles (max cycle time so far: 0.406ms) Command: Command: cd /mnt Command: rm -rf dbench 20000 cycles (max cycle time so far: 1.998ms) 30000 cycles (max cycle time so far: 2.204ms) 40000 cycles (max cycle time so far: 2.204ms) Command: rm -rf tbench_lo Command: mkdir dbench Command: mkdir tbench_lo Command: Command: cd /mnt/dbench Command: /etc/load_dbench.sh& Shell invoked to run file: /etc/load_dbench.sh Command: #!/bin/sh Command: Command: /dbench-2.0/dbench -c /dbench-2.0/client_oplocks.txt 2 [31] Command: cd /mnt/tbench_lo Command: /etc/load_tbench_lo.sh& Shell invoked to run file: /etc/load_tbench_lo.sh Command: #!/bin/sh Command: Command: /dbench-2.0/tbench_srv& waiting for connections [33] Command: Execution Finished, Exiting [35] Command: sleep 1 2 clients started Command: /dbench-2.0/tbench -c /dbench-2.0/client_oplocks.txt 2 localhost 50000 cycles (max cycle time so far: 2.204ms) 2 clients started 0.00 MB/sec 970000 cycles (max cycle time so far: 3.548ms) 980000 cycles (max cycle time so far: 3.548ms) 990000 cycles (max cycle time so far: 3.548ms) finished collecting 1000000 samples maximum cycle time: 3.548ms Command:


Command: # Done. Command: Command: echo 2 344 0.02 MB/sec Command: echo Command: echo === DONE 1,000,000 samples. Download /results.hist onto the host. === === DONE 1,000,000 samples. Download /results.hist onto the host. === Command: echo

To run the benchmark for a longer time, edit the local/go.sh script in the realfeel sample directory. The following line from the file runs the realfeel benchmark:

realfeel2 –samples 1000000 –hertz 1000 results.hist

The --samples option specifies the number of samples (interrupts) the benchmark will measure. Increase the argument to run the benchmark for a longer time.

Use the ssh command to copy the corrected measurements data from the DM320/DM342 target to a remote host. The login is root. The password is target.

ML(arm926ejs):bash$ ssh –l root 192.168.0.16 “cat /results.hist” >results.hist

On the host, use the hist2png.sh script available in the realfeel sample directory to convert the results.hist file into a viewable .png file:

ML(arm926ejs):bash$ hist2png.sh “Results for Mar 25” results.hist

The first argument to the script is the title that will appear at the top of the histogram. The second argument is the name of a .hist file to be converted.

View the results.png file (refer to 10.1.4 for sample snapshots):

ML(arm926ejs):bash$ display results.png

10.1.4. Analyzing the Real-Time Patches

What follows are some sample scheduling latency histograms produced by the realfeel projects obtained using different configurations of the patches.


10.1.4.1. Both Patches Disabled

Figure 10: Both Patches Disabled

The above measurements are obtained on the DM320/DM342 target with both patches disabled. The worst scheduling latency is up to 10 ms.


10.1.4.2. Preemption Patch Enabled

Figure 11: The Preemption Patch Enabled

The above measurements are obtained on the DM320/DM342 target with the preemption patch enabled. The scheduling latency times are substantially reduces, with no abrupt surges present.


10.1.4.3. Both Patches Enabled

Figure 12: Both Patches Enabled

The above measurements are obtained on the DM320/DM342 patches with both patches enabled. The overall scheduling latency is even lowed, as compared to the configuration that has only the preemption patch enabled. No abrupt surges are present.

10.2. Frame Buffer

10.2.1. Monterey Linux Frame Buffer Driver Overview

The frame buffer is a Monterey Linux kernel driver that provides interface to the On-Screen Display (OSD) and Video Encoder of the DM320/DM342 allowing a standard TV to be used as a graphical output device for the Linux console and applications. The Monterey Linux frame buffer implementation is based on the standard Linux frame buffer driver framework and implements the standard Linux frame buffer API.

The DM320/DM342 OSD module manages the display of several window types: video windows, bitmap windows, and cursor windows. The OSD module merges the


display data from all of the windows and outputs it in a format ready to be displayed by the Video Encoder module.

The Video Encoder module receives the output of the OSD module and generates the signals required to drive various displays. The Video Encoder can generate the composite NTSC or PAL signals, Y/C S-video signals, analog Red (R), Green (G), Blue (B) signals, and 8-bit digital RGB signals suitable for LCD interfaces.

The Monterey Linux frame buffer driver makes use of the OSD Bitmap Window 0. Other windows are not used.

The driver configures the display resolution to resolution 608x440 pixels (maximum resolution that fits onto an NTSC TV screen) and the color depth to 8 bits per pixel.

The Video Encoder is configured to generate a composite NTSC video signal.

10.2.2. Double Buffering

Double buffering is a technique aimed at reducing visual artifacts when displaying several successive images on the screen (for instance, when displaying moving objects). The idea behind double buffering is that the application uses two graphics buffers: “front buffer" and "back buffer".

The front buffer is visible to the user, while the back buffer is not. The application does all the drawing to the back buffer, and then when it has finished drawing, it instructs the graphics hardware (the OSD module) via the standard Linux frame buffer interface, to "flip" the buffers - make the back buffer the front one.

For the double buffering to be possible, both front and back buffers must reside in a video RAM of the graphics hardware. In case of the DM320/DM342, the video RAM (where the contents of all the bitmap, cursor, and video windows are located) is actually a part of the main system SDRAM. The frame buffer driver allocates an SDRAM area that is used as a video RAM, and specifies its location in the OSD control registers.

The amount of video RAM that needs to be allocated depends on the display resolution, color depth, and whether the double buffering is going to be used. By default, the frame buffer driver allocates a video RAM of size required for a single video buffer. More specifically, it allocates 608 * 440 = 267520 bytes. If your application requires double buffering, you need to instruct the driver to allocate more video RAM.

This can be done by passing a video parameter via the kernel command line. The syntax is as follows:

video=dm310fb:mem:<size_in_kb>

For instance, to reserve the amount of video RAM sufficient for double buffering, pass this parameter to the kernel (608 * 440 * 2 = 535040 bytes = 523 KB):


video=dm310fb:mem:523

10.2.3. Configuring the Frame Buffer

Do the following to enable the frame buffer driver in the Monterey Linux kernel:

From the Character Devices menu enable the Virtual Terminal option.

From the Console Drivers menu, go to the Frame-buffer support submenu and enable the Support for frame-buffer devices option and the DM310/DM342 OSD/Video Encoder support option.

10.2.4. Connecting TV

Use a video cable to connect the RCA_CVOUT1 jack of DM320/DM342 EVM to a video input of your TV.

10.2.5. framebuffer Sample Project

The Monterey Linux distribution includes the framebuffer sample project designed to illustrate the possibility of redirecting the Linux console output to a TV.From the functionality stand point, the framebuffer sample project is essentially identical to the ftp sample project (refer to 9.2.2).

SAMPLE PROJECT framebuffer

LOCATION $TARGET_ROOT/usr/src/sample/framebuffer

DESCRIPTION

The framebuffer sample demonstrates a TV-based console and functionality of a FTP client in a small, network-enabled embedded system based on Monterey Linux.

Once the framebuffer sample is booted, you are presented with an msh prompt on your TV. Console input is taken from the serial line port.

At this point you can manually bring up the network interface using the ifconfig command. The route command is also included in the file system, so you can use it to adjust the kernel routing table as needed. For instance, you can set up a default gateway to allow access to hosts outside of your LAN. At any time, you can use the ping command that is also included in the sample to verify that the network is accessible.

The focus of this sample is the FTP client and the video console. Once the networking is set up, use the ftp command to initiate an FTP session to a host on the network. The FTP client provided by Monterey Linux works essentially the same as a standard


desktop Linux FTP client, so there should be no problems in connecting with another host system.

BOOT SCENARIO

The framebuffer sample consists of a compressed kernel image and compressed image of the root file system. ARMboot boots both images into RAM, decompresses the root file system image, sets up necessary parameters, such as the kernel command line, and transfers control to the Linux kernel.

Linux starts up and initializes the video console, network interface, and other kernel services. After the kernel-level initialization is complete, Linux mounts the root file system from the framebuffer root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init. This version of init is included in the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The final step is to launch the interactive shell (msh).








Frame buffer From the Character Devices menu enable the Virtual Terminal option, and the Support for console on virtual terminal option.








dm320evm # tftp 00a00000 framebuffer.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'framebuffer.kernel'. Load address: 0xa00000 Loading: ################################################################# ############################ done Bytes transferred = 471176 (73088 hex) dm320evm #


dm320evm # tftp 00d00000 framebuffer.rfs ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'framebuffer.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ############ done Bytes transferred = 723327 (b097f hex)




dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 471112 Bytes = 460.1 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: framebuffer RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (gzip compressed) Data Size: 723263 Bytes = 706.3 kB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ...


At this point, the console output goes to the TV. You should see the traditional Linux penguin in the upper left corner, and the usual Linux boot up messages, followed by an msh prompt.

As mentioned above, functionally, the framebuffer sample project is identical to the ftp sample project. Please refer to 9.2.2 for detailed description of using the ftp sample project to set up the network and access FTP servers. Note that while the console output goes to the TV, the console input is taken from the /dev/ttyS0 serial line.

Note further that because of the fact that this sample project uses the TV console, while the input is redirected from the serial line, it is not possible to generate the SIGINT signal by pressing Ctrl-C on the terminal connected to the serial line. That is, for instance, you cannot stop the ping command in this sample project by pressing Ctrl-C. We recommend you invoke ping with the -c argument, to make it send a limited number of packets.

10.3. DirectFB GUI Framework and Interface

10.3.1. DirectFB Overview

DirectFB (see www.directfb.org) is an open-source thin graphics library that works on top of the Linux frame buffer device driver. DirectFB is a graphics hardware abstraction layer that provides the following interfaces:

Rectangle filling/drawing

Triangle filling/drawing

Line drawing

Flat shaded triangles

(Stretched) blitting

Blending

Color modulation

Source color keying

Destination color keying.

DirectFB has a modular structure that allows such components as input drivers, fonts, image and video providers to be loaded at run-time on an as-needed basis.


10.3.2. Serial Mouse Support

For the DM320/DM342 EVM, Monterey Linux does not support the serial mouse. This limitation is due to the fact that neither of the UART connectors on the DM320/DM342 EVM has the RTS signal connected to any of the DM320/DM342 pins. Control of the RTS signal is required for operation of the serial mouse driver.

10.3.3. Using DirectFB in Your Applications

From the application developer perspective, DirectFB is just a regular library. This means that in order to make use of DirectFB in your custom application, you must link with the DirectFB library. More specifically, your application must include directfb.h header file and be linked with libdirectfb.so (or libdirectfb.a, in case of static linking).

Please refer to the DirectFB applications built in the context of the directfb sample project (refer to 10.3.4) for examples of use of DirectFB in sample applications. Additional information is available at www.directfb.org.

10.3.4. directfb Sample Project

SAMPLE PROJECT directfb

LOCATION $TARGET_ROOT/usr/src/sample/directfb

DESCRIPTION

The directfb sample project demonstrates functionality of the DirectFB library and serial mouse support. The directfb sample project includes example applications that make use of the DirectFB library and the underlying frame buffer driver to display graphics on the TV screen. The root file system of the directfb sample project includes the following example applications:

Example Description

df_andi Penguin demo df_cpuload Graphical demonstration of CPU load df_dok DirectFB benchmark application df_fire The famous fire effect ported to DirectFB df_fonts Shows font character table. Invoke this demo as

df_fonts /usr/share/directfb-examples/fonts/decker.ttf & df_input Mouse test


Example Description

df_knuckles A 3D skull drawn using triangles that can be rotated using the mouse

df_neo Port of a gdk-pixbuf demo to DirectFB df_palette Shows a color palette df_window Shows DirectFB window stack and mouse support

Table 19: Example Applications

BOOT SCENARIO

The directfb sample consists of a compressed kernel image and compressed image of the root file system. ARMboot boots both images into RAM, decompresses the root file system image, sets up necessary parameters, such as the kernel command line, and transfers control to the Linux kernel.

Linux starts up and initializes the serial console, network interface, frame buffer, and other kernel services. While the console output goes to the serial line, a traditional Linux Penguin is displayed in the upper left corner of the TV screen during bootstrap. After the kernel-level initialization is complete, Linux mounts the root file system from the directfb root file system image residing in RAM. At this point, the /sbin/init program is started. Monterey Linux provides a simplified version of standard Linux init. This version of init is included in the busybox package. init examines the contents of the /etc/inittab file and invokes the /etc/rc shell script to complete initialization of the system. The final step is to launch the interactive shell (msh).









Frame buffer From the Character Devices menu enable the Virtual Terminal option.





The following is a snapshot of the output produced by the sample project on the DM320EVM reference platform. The output is annotated by comments illustrating important steps of the sample project bootstrapping and operation.


dm320evm # tftp 00a00000 directfb.kernel ARP broadcast 1 TFTP from server 192.168.0.1; our IP address is 192.168.0.16 Filename 'directfb.kernel'. Load address: 0xa00000 Loading: ################################################################# ############################ done Bytes transferred = 471292 (730fc hex)


dm320evm # tftp 00d00000 directfb.rfs ARP broadcast 1 TFTP from server 192.168.0.11; our IP address is 192.168.0.16 Filename 'directfb.rfs'. Load address: 0xd00000 Loading: ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ################################################################# ############################################# done Bytes transferred = 2557536 (270660 hex)





dm320evm # bootm 00a00000 00d00000 ## Booting image at 00a00000 ... Image Name: linux-2.4.19 Image Type: ARM Linux Kernel Image (gzip compressed) Data Size: 471228 Bytes = 460.2 kB Load Address: 00908000 Entry Point: 00908000 Verifying Checksum ... OK Uncompressing Kernel Image ... OK ## Loading Ramdisk Image at 00d00000 ... Image Name: directfb RFS Ramdisk Image Image Type: ARM Linux RAMDisk Image (gzip compressed) Data Size: 2557472 Bytes = 2.4 MB Load Address: 00000000 Entry Point: 00000000 Verifying Checksum ... OK Starting kernel ... Linux version 2.4.19-rmk7-ds1-omap (bin@ml) (gcc version 3.2) #10 Mon Mar 22 23:33:21 GMT 2004 CPU: ARM926EJ-Sid(wb) revision 3 Machine: DM320 On node 0 totalpages: 4096 zone(0): 4096 pages. zone(1): 0 pages. zone(2): 0 pages. Kernel command line: root=/dev/ram0 Console: colour dummy device 80x30 Calibrating delay loop... 24.62 BogoMIPS Memory: 16MB = 16MB total Memory: 12548KB available (840K code, 219K data, 60K init) Dentry cache hash table entries: 2048 (order: 2, 16384 bytes) Inode cache hash table entries: 1024 (order: 1, 8192 bytes) Mount-cache hash table entries: 512 (order: 0, 4096 bytes) Buffer-cache hash table entries: 1024 (order: 0, 4096 bytes) Page-cache hash table entries: 4096 (order: 2, 16384 bytes) POSIX conformance testing by UNIFIX Linux NET4.0 for Linux 2.4 Based upon Swansea University Computer Society NET3.039 Initializing RT netlink socket Starting kswapd ttyS00 at 0xe0030300 (irq = 12) ttyS01 at 0xe0030380 (irq = 13) Console: switching to colour frame buffer device 76x27 pty: 256 Unix98 ptys configured RAMDISK driver initialized: 16 RAM disks of 8192K size 1024 blocksize Cirrus Logic CS8900A driver for Linux (V0.02) eth0: CS8900A rev E detected NET4: Linux TCP/IP 1.0 for NET4.0 IP Protocols: ICMP, UDP, TCP IP: routing cache hash table of 512 buckets, 4Kbytes TCP: Hash tables configured (established 1024 bind 2048) NET4: Unix domain sockets 1.0/SMP for Linux NET4.0. RAMDISK: Compressed image found at block 0 Freeing initrd memory: 2497K VFS: Mounted root (ext2 filesystem).


Freeing init memory: 60K console=/dev/ttyS0 init started: BusyBox v0.60.5 (2004.03.22-23:19+0000) multi-call binary Starting pid 7, console /dev/ttyS0: '/etc/rc' Starting pid 16, console /dev/console: '/bin/sh' BusyBox v0.60.5 (2004.03.22-23:32+0000) Built-in shell (msh) #

Once the sample is booted, an msh prompt appears. At this point, you can launch any of the example applications listed above (they are located in the /usr/bin directory in the target root file system). Additionally, this sample project includes an informational DirectFB utility named dfbinfo. It displays information of the available display layers and input devices:

# dfbinfo *) parsing config file '/etc/directfbrc'. ---------------------- DirectFB v0.9.19 --------------------- (c) 2000-2002 convergence integrated media GmbH (c) 2002 convergence GmbH ----------------------------------------------------------- (*) Single Application Core. (2004-03-22 23:06) (*) DirectFB/GraphicsDevice: Generic Software Rasterizer 0.6 (convergence integrated media GmbH) (*) DirectFB/Layer: Enabled 'FBDev Primary Layer'. Display Layers (00) FBDev Primary Layer (primary layer) Type: graphics Caps: brightness contrast saturation surface Input Devices #

Normally, DirectFB applications can be stopped by pressing the Esc key on the keyboard. Unfortunately, this is not applicable to the DM320/DM342 currently as it lacks local keyboard. An implication of this fact is that you have to explicitly "kill" a running DirectFB application, if you want to launch another one. We recommend you start the example applications included with the DirectFB sample in the background, by specifying the ampersand (&) at the end of the command line:

# df_fire & 18

Notice that the PID number (17) of the application is printed out automatically.

# (*) parsing config file '/etc/directfbrc'. ---------------------- DirectFB v0.9.19 --------------------- (c) 2000-2002 convergence integrated media GmbH (c) 2002 convergence GmbH ----------------------------------------------------------- (*) Single Application Core. (2004-03-22 23:06)


(*) DirectFB/GraphicsDevice: Generic Software Rasterizer 0.6 (convergence integrated media GmbH) (*) DirectFB/Layer: Enabled 'FBDev Primary Layer'. #

When you want to start another example application, kill the one that is currently running before launching the new one.

# kill 18 # (!) ---> CAUGHT SIGNAL 15 <---

Monterey Linux - CiteSeerX

Documents

Transcript of Monterey Linux - CiteSeerX