264
1237 E. Arques Ave. Sunnyvale, CA 94085 MontaVista™ Linuxfi Professional Edition Users Guide Version 3.0

Monta Vista Users Guide

  • Upload
    m92146

  • View
    3.086

  • Download
    5

Embed Size (px)

Citation preview

Page 1: Monta Vista Users Guide

1237 E. Arques Ave.Sunnyvale, CA 94085

MontaVista� Linux®Professional Edition

User�s Guide

Version 3.0

Page 2: Monta Vista Users Guide

CopyrightCopyright © 2002 MontaVista Software, Inc. All Rights Reserved. This product and related documentation are protected by copyright and distributed under licenses controlling its use, copying, and distribution. No part of this product or its related documentation may be reproduced in any form or by any means except under such licenses and this copyright notice.

MontaVista Software, Inc. makes no representations or warranties with respect to the contents or use of this manual, and speciÞcally disclaims any express or implied warranties of merchantability or Þtness for any particular purpose.

MontaVista Software, Inc. makes no representations or warranties with respect to MontaVista� Linux®, and speciÞcally disclaims any express or implied warranties of merchantability or Þtness for any particular purpose. MontaVista Linux, MontaVista and MontaVista Software are trademarks of MontaVista Software, Inc. Linux is a registered trademark of Linus Torvalds. All other names mentioned herein are trademarks, registered trademarks, and service marks are the property of their respective owners.

For more information see �Notices and License Agreements� on page 221.

Revision History

This document was prepared by MontaVista Software, Inc.

AcknowledgementsThank you to the Linux community for the kernel work. Thank you to Free Software Foundation and all of the GNU Developers. Thank you to the Debian team for their excellent efforts with user-space applications and distribution packaging. And thank you to everyone who has been committed to open-source by releasing your code to the public.

ContactYou are welcome to contact us: [email protected]

MontaVista Linux Professional Edition Version

Documentation Release Date

Notes

3.0 December 16, 2003 First Release

3.0 January 10, 2003 First typos.

Page 3: Monta Vista Users Guide

Contents

Chapter 1 Welcome to MontaVista� Linux® Professional Edition ...................1

What is MontaVista� Linux® Professional Edition? .................................. 1What Are Linux Support Packages? ........................................................ 1Pro Is Reproducible ................................................................................. 2Cross- and Local-Compilation Environments ......................................... 2

Developing Embedded Applications With Pro.............................................. 5Prepare the Development Environment ................................................... 5Develop Your Kernel and/or Application................................................. 6Integrate Your System Components......................................................... 9Deploy Your Embedded Application ....................................................... 10

About This Manual........................................................................................ 11Other Documentation .............................................................................. 11

Support .......................................................................................................... 12

Chapter 2 Installation ..............................................................................................13

Overview ....................................................................................................... 13

Requirements................................................................................................. 15Host.......................................................................................................... 15Target ....................................................................................................... 16

The hhl-host-install Tool ................................................................. 17Usage ....................................................................................................... 17Options..................................................................................................... 17

Displaying the Product Directory.................................................................. 20

Installing or Upgrading Pro........................................................................... 22Install ....................................................................................................... 22Upgrade ................................................................................................... 24

Installing or Upgrading an Additional LSP................................................... 28

Removing Pro................................................................................................ 30Remove a Single LSP .............................................................................. 30

MontaVista� Linux® Professional Edition i

Page 4: Monta Vista Users Guide

Remove All of Pro ................................................................................... 30

Installing, Upgrading, or Removing Optional Packages ............................... 32Install ....................................................................................................... 32Upgrade or Remove ................................................................................. 33

Trouble-Shooting........................................................................................... 34

Chapter 3 The Development Environment ............................................................37

Overview........................................................................................................ 37

Project Directories ......................................................................................... 38Create Project Directories........................................................................ 38Populate Project Directories .................................................................... 38

Running Pro Applications and Tools ............................................................. 40Cross-Development Application PreÞxes ................................................ 42

Accessing man and info Pages ...................................................................... 44man Pages ................................................................................................ 44info Pages................................................................................................. 45

Other Linux Documentation.......................................................................... 48

Chapter 4 Target ConÞguration and Boot .............................................................49

Overview........................................................................................................ 49

Booting the Target with the MontaVista Supplied Kernel............................. 50

Booting the Target with a Custom Kernel ..................................................... 52

Using Minicom.............................................................................................. 54ConÞgure Minicom.................................................................................. 54Start Minicom .......................................................................................... 55Exit Minicom ........................................................................................... 55Help.......................................................................................................... 55

Chapter 5 Target ConÞguration Tool (TCT) .........................................................57

Overview........................................................................................................ 57

Starting TCT.................................................................................................. 58Start TCT ................................................................................................. 58Create a New Project ............................................................................... 58Open a Project.......................................................................................... 60Remove a Project ..................................................................................... 60

TCT Project Menus ....................................................................................... 61The File Menu.......................................................................................... 61The View Menu........................................................................................ 64The Info Menu ......................................................................................... 67

Using TCT ..................................................................................................... 68Create a ConÞguration File...................................................................... 68Create/Edit Kernel ConÞguration ............................................................ 69Create/Edit File System ........................................................................... 70Build the Target Kernel and File System ................................................. 71

Using the Tar Archive Created by TCT ......................................................... 72

ii MontaVista� Linux® Professional Edition

Page 5: Monta Vista Users Guide

The targetpkg Utility............................................................................... 73Usage ....................................................................................................... 73Examples ................................................................................................. 73

Chapter 6 Linux Kernel Development ...................................................................75

Overview ....................................................................................................... 75

Building and ConÞguring the Kernel ............................................................ 76Build the Kernel With TCT ..................................................................... 76Build the Kernel Without TCT ................................................................ 76

Enabling Loadable Kernel Modules.............................................................. 80

Enabling Real-Time Performance Enhancements......................................... 81MontaVista Real-Time Scheduler............................................................ 81Preemptible Kernel .................................................................................. 82Limitations............................................................................................... 83

Enabling Standard Devices............................................................................ 84Framebuffer Support................................................................................ 84Videocard Support ................................................................................... 85PS/2 Keyboard and Mouse Support......................................................... 86

Building Custom Device Drivers .................................................................. 88Load and Unload the Driver (Kernel Module) ........................................ 89Code the Kernel Portions of the Driver ................................................... 90Initial Coding of the Driver ..................................................................... 91Wrap Up .................................................................................................. 101Additional Information ............................................................................ 102

Enabling File Systems ................................................................................... 103

Debugging the Kernel.................................................................................... 104KGDB...................................................................................................... 104Linux Trace Toolkit (LTT)....................................................................... 107Abatron BDI2000 .................................................................................... 108

Chapter 7 Application Development ......................................................................113

Overview ....................................................................................................... 113

Building Programs Using KDevelop............................................................. 114MontaVista Customizations..................................................................... 115Install KDevelop...................................................................................... 116Start KDevelop ........................................................................................ 117Use KDevelop for Cross-Development ................................................... 117Help ......................................................................................................... 127

Building Programs Using GCC and G++...................................................... 128Example of a C Program ......................................................................... 128Example of a C++ Program..................................................................... 129Additional Information ............................................................................ 129

Using Threads................................................................................................ 131

Debugging Programs Using GDB and DDD ................................................ 132Additional Documentation ...................................................................... 132Example of Using GDB........................................................................... 133Example of Using GDB and DDD Together ........................................... 134

MontaVista� Linux® Professional Edition iii

Page 6: Monta Vista Users Guide

Debugging Programs Which Call fork(), vfork(), and execve() .................... 135

Debugging Multi-Threaded Applications...................................................... 136Additional Information ............................................................................ 136

Additional Tools for Programming and Debugging ...................................... 137cbrowser................................................................................................... 137cßow......................................................................................................... 137cscope ...................................................................................................... 137dmalloc .................................................................................................... 138ltrace ........................................................................................................ 138mtrace ...................................................................................................... 138strace ........................................................................................................ 139showasm................................................................................................... 139

Using AltiVec� Technology by Motorola .................................................... 140Features.................................................................................................... 140Limitations ............................................................................................... 140Additional Information ............................................................................ 141

Chapter 8 System Integration .................................................................................143

Overview........................................................................................................ 143

Creating Your File-System Hierarchy............................................................ 145Select a Deployment File-System Type................................................... 145Use TCT to Select Applications............................................................... 149Add Your Custom Application ................................................................. 150

Booting the Target and NFS-Mounting Your File System............................. 151

ConÞguring the User-Space Environment..................................................... 152Enable Run-Level Services (Startup Scripts) .......................................... 152ConÞgure the Target for Serial Console or Virtual Terminal ................... 156Create Standard Device Nodes ................................................................ 158Add Shells................................................................................................ 158Start PCMCIA ......................................................................................... 160ConÞgure Networking ............................................................................. 160

Testing Your Environment ............................................................................. 165

Reducing the Size of Your File System ......................................................... 166Library Optimizer Tool (LOT)................................................................. 166Example ................................................................................................... 167

ProÞling Your Embedded Application ........................................................... 169

Chapter 9 Deployment .............................................................................................171

Overview........................................................................................................ 171

ConÞguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System........................................................................ 173

CramFS .................................................................................................... 175EXT2 and EXT3 ...................................................................................... 175Journaling FLASH Filesystem (JFFS)..................................................... 175ReiserFS................................................................................................... 175XFS .......................................................................................................... 176MTD ........................................................................................................ 176

iv MontaVista� Linux® Professional Edition

Page 7: Monta Vista Users Guide

Creating a File-System Image ....................................................................... 179CramFS.................................................................................................... 179JFFS/JFFS2.............................................................................................. 180EXT2/EXT3............................................................................................. 181ReiserFS................................................................................................... 182XFS.......................................................................................................... 183

Setting Up Your File Systems (/etc/fstab) ..................................................... 185Sample 2 .................................................................................................. 185

Booting the New Kernel ................................................................................ 186

Trouble-Shooting Deployment ...................................................................... 187Corrupt File System................................................................................. 187

Appendix A Pro File-System Layout .........................................................................189

Overview ....................................................................................................... 189

Base Directories ............................................................................................ 190

/hardhat Directory.......................................................................................... 191

/devkit Directory............................................................................................ 192/kernel Directory...................................................................................... 192/lsp Directory ........................................................................................... 192Architecture Family Directories .............................................................. 192/bin Directory........................................................................................... 194/etc Directory ........................................................................................... 194/include and /lib Directories .................................................................... 194/doc, /info, and /man Directories ............................................................. 194/share and /var Directories ....................................................................... 194

/host Directory............................................................................................... 195/bin Directory........................................................................................... 195/etc Directory ........................................................................................... 195/include and /lib Directories .................................................................... 195/doc, /info, and /man Directories ............................................................. 195/share and /var Directories ....................................................................... 196

Appendix B Pro Applications .....................................................................................197

Overview ....................................................................................................... 197

Cross-Development Application Packages.................................................... 198

Host Application Packages ............................................................................ 200

Target Application Packages ......................................................................... 204

Using RSH..................................................................................................... 219

Appendix C Notices and License Agreements..........................................................221

Notices........................................................................................................... 221

License Agreements ...................................................................................... 223

Target ConÞguration Tool End User License Agreement.............................. 224

The �Artistic License� ................................................................................... 227

GNU General Public License, or GNU GPL ................................................ 230

MontaVista� Linux® Professional Edition v

Page 8: Monta Vista Users Guide

How to Apply These Terms to Your New Programs ................................ 235

The GNU Lesser General Public License, or GNU LGPL ........................... 237How to Apply These Terms to Your New Libraries ................................. 245

The ModiÞed BSD License ........................................................................... 247

Appendix D Documentation Naming Conventions...................................................249

Naming Conventions ..................................................................................... 249Glossary of Terms............................................................................................................................. 253

vi MontaVista� Linux® Professional Edition

Page 9: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional Edition

What is MontaVista� Linux® Professional Edition?

Welcome to MontaVista� Linux® Professional Edition (Pro)!

Pro is an embedded Linux development kit, containing Linux kernel source for thesupported target CPUs, along with a full complement of development tools designedto help you design, develop, and deploy an embedded application. Whether you�rebuilding Internet appliances, portable devices, networking equipment, telephonyinterfaces, or other embedded and pervasive applications, you can count onMontaVista Software, Inc. to provide robust Linux kernel ports, device drivers,middleware, and development tools to streamline your development effort.

Pro supports the broadest array of CPU architectures and board and system-levelplatforms of any embedded Linux development solution available today.

Pro highlights include:

� Linux 2.4.18 kernel

� Linux, Solaris� and VMware® hosts

� CPU support for ARM®, IA-32/x86, PowerPC®, StrongARM®/xScale�, MIPS®, and SuperH®

� Over 78 Linux Support Packages (LSPs)

� Development and conÞguration tools

� Over 280 application packages

What Are Linux Support Packages?

A Linux Support Package (LSP) contains a set of Linux Þles, binary and source,designed for a speciÞc target board. These Þles can include: a run-time kernel(sometimes named vmlinux or vmlinuz); host-resident, target-executable programs

MontaVista� Linux® Professional Edition 1

Page 10: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionWhat is MontaVista� Linux® Professional Edition?

(shell and shell utilities: mkdir, cd, rm, etc.); and host-resident, host-executableprograms (compiler, binary Þle converters, debugger).

Pro includes LSPs for over 78 different reference boards. The advantage of using anLSP for kernel or Þle system development is that by using a system that is known towork as a base for your development, you can greatly decrease your developmenttime.

Pro Is Reproducible

Pro can be reproduced without using any proprietary products. The advantage to thisdesign is that you, the developer, can view the source code of the software, tailor thesoftware as needed, and learn from the software. You may not need to recompile anyportion of Pro; however, if you do need to recompile Pro (due to contract issues), it ispossible.

Cross- and Local-Compilation Environments

Pro is designed to be a cross-compilation environment that is capable of being used asa local-compilation system.

The cross-compilation environment

A cross-compilation environment consists of a host system and a target system.

Cross-compilation (or cross-development) refers to creating code on a machine of onearchitecture type, but being able to compile it for a machine of a different architecture.An example would be to create code on an x86 host, but compile the code so that itruns on a PowerPC or MIPS target. Though the architectures might not be the sameendian or process code the same way, the gcc compiler provided by MontaVistabuilds code that will run on the target.

Note: If the host and target architectures are different, then code built for the targetwill not run on the host.

A host is a system that is a typical workstation such as a PC system running Red Hat®or a Sun® system running Solaris�. Pro tools are installed on the host system and areused for compiling, linking, remote debugging, and associated development activities.

2 MontaVista� Linux® Professional Edition

Page 11: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionWhat is MontaVista� Linux® Professional Edition?

A target is a reference board that you plan to use as the base for your product. Mostembedded targets either don�t have an IDE drive or have a drive that is too small tohave a full set of tools for building kernels and applications.

For example, if you are using an x86 host running Red Hat 7.3 with a PowerPC target,your development environment appears as in the diagram below:

The advantage of a cross-compilation system is that the host system is generally fasterand easier to develop on compared to the target system. Another advantage is that it iseasier to recover your system should a change render your kernel un-bootable. Thoseof you with experience as Real-Time Operating System (RTOS) developers mayalready be accustomed to using a cross-compilation environment.

The local-compilation environment

In a local-compilation environment, all of the tools and applications required torebuild the system are installed directly on the target system. Local-compilation refersto creating code or developing applications on (and for) the architecture and operatingsystem being used.

For IA-32/x86 targets, Pro can be installed directly on the target for local-compilationdevelopment. Using a local-compilation environment, no network connection or

Host

Local Network

Serial

.....................................

Target

Pro 3.0 ---------------Red Hat 7.3

MontaVista Linux

Cross-Compilation Environment

MontaVista� Linux® Professional Edition 3

Page 12: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionWhat is MontaVista� Linux® Professional Edition?

4

cross-compilation host is needed. For a typical IA-32/x86 system, the local-compilation environment appears as in the diagram below:

Most open-source and commercial developers are already accustomed to developingapplications on (and for) the operating system that they use every day. This is one ofthe advantages of having a local-compilation system. Another advantage of having alocal-compilation system is that it can provide a quick development-to-deploymentenvironment. However, in the embedded-systems industry, most systems are small;therefore, local-compilation development could potentially increase costs and reduceproductivity.

Note: This manual focuses on the cross-compilation environment. Information aboutusing local compilation can be found in a separate MontaVista publication, UsingMontaVista Linux Professional Edition for Local Compilation.

....................................

Target (with keyboard and VGA display)

Pro 3.0(x86 development toolsand basic file system)

Local-Compilation Environment

MontaVista� Linux® Professional Edition

Page 13: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionDeveloping Embedded Applications With Pro

Developing Embedded Applications With Pro The following reßects a high-level overview of how to best use the tools provided inPro to build your embedded application. The outline below covers the developmentcycles of the three main components of an embedded Linux application � kerneldevelopment, application development, and system integration. For some projects, theLinux kernel and MontaVista provided applications can be used without modiÞcation,allowing you more time to focus on your custom applications. For other projects, youmay Þnd that you need to modify the kernel to support custom features for yourboard, or that your project requires additional applications which were not provided.For those projects, your development cycle is more involved.

Although you can build your system in a number of different ways, we recommendpursuing your project in the following order. The steps described below are explainedin greater detail later in this manual.

Prepare the Development Environment

Install Pro and boot your target

To get started using Pro, you Þrst need to install Pro for your reference board. Byinstalling the LSP for your reference board, you have a default environment that canbe booted on your reference board and a root Þle system NFS-mounted on your host.Your target�s root Þle system contains the appropriate applications for your referenceboard�s architecture and processor, and you have all of the cross-compilation toolsthat you need to compile custom applications for your target on the host.

The next step is to perform an initial boot and setup of your target. Assuming youfollowed the instructions in the quick start guide for your target provided byMontaVista, the target�s root Þle system is NFS-mounted on the host. Thedevelopment environment directory structure appears as follows:

Target System

Host System /opt/hardhat

/devkit /<architecture> /<processor>

/target /bin /etc /lib ...

/host

NFS root file system

MontaVista� Linux® Professional Edition 5

Page 14: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionDeveloping Embedded Applications With Pro

A complete description of the directory structure installed can be found in this manual.If you are using a local-compilation environment, the host system and the targetsystem are on the same machine, and there is no need for an NFS mount of the targetÞle system.

Once you have installed Pro and performed an initial boot of the target, you are readyto begin development. Included in the Pro distribution are over 280 applicationpackages. If you do not know how to use these applications, documentation in theform of man and info pages are available that can help.

Create your project directories

When working with Pro, we recommend that you not work directly in the /opt/hardhat/devkit tree. Rather, we recommend that you copy the Þles youneed to modify to a work directory elsewhere on your host. This way, you can easilyreturn to the default conÞgurations provided by MontaVista. In addition, it isimportant that you do not make changes to the /target directory. This directory isused by the MontaVista Target ConÞguration Tool (TCT) for Þle systemdevelopment. Changes can result in problems when creating your Þle system.

Assuming that you are doing kernel and application development, you could create awork directory structure such as the following:

The mykernel directory can be used for kernel development. Themyapplication directory can be used for application development. Themyfilesystem directory is where you can integrate your Þle system hierarchy andyour application. You can NFS-export the myfilesystem directory for testing.These directories will be referred to later in this overview.

Develop Your Kernel and/or Application

Once you have prepared your environment, you are ready to begin development.Application and kernel development cycles are very similar. Typically, kerneldevelopment work is done before application work; however, kernel work andapplication work can occur in parallel and be merged later for testing and Þnaldeployment.

my_work_directory

/mykernel/myapplication/myfilesystem

6 MontaVista� Linux® Professional Edition

Page 15: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionDeveloping Embedded Applications With Pro

The typical development cycle for building a kernel and/or application appears asfollows:

Whether you are working on kernel code or application code, we recommend makingonly a few changes to your target�s environment at a time. This method allows you totrack your progress and isolate bugs more easily. It will also help the MontaVistaSupport team answer your questions more quickly. Simply stated, by starting from anenvironment that works, you can control the incremental changes made to the system.

Kernel development

For kernel development, you may use Target ConÞguration Tool (TCT) � a GUI toolprovided by MontaVista used to manage kernel and Þle system development, or youmay use the compilers and kernel debuggers distributed with Pro. Whether you useTCT or another method, you should create a work directory (such as mykernel) forkernel development that contains a copy of the LSP kernel. If you use TCT, the LSPkernel and conÞguration Þles are copied automatically to a work directory when youcreate a TCT project. If you do not use TCT, you need to copy the LSP kernel byhand.

TCT stores kernel conÞguration information in a conÞguration Þle. One advantage ofusing TCT is that you can easily save multiple kernel (and Þle system) conÞgurationsfor a single project. However, if you use TCT, it is important to note that changesmade to the kernel using another tool, such as make menuconfig, will not bestored in your TCT conÞguration Þle and will not be built in the kernel by TCT.

Once you have copied the kernel to a work directory, how you proceed with yourdevelopment depends on whether you are customizing kernel code, adding a customdevice driver, or conÞguring the kernel.

If you are adding custom kernel code or adding a custom device driver, we recommendthat you use the copy of the kernel in your project directory.

Modify the kerneland/or applicationon the host

Compile the kernel and/orapplication on the host

Make the kerneland/or applicationavailable to thetarget

Run the target to testthe kernel and/or application

Success!

Begin development

MontaVista� Linux® Professional Edition 7

Page 16: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionDeveloping Embedded Applications With Pro

If you are conÞguring the kernel, we recommend that you use TCT. Before youconÞgure your kernel, you should make some decisions about the kernel options youneed to enable. Because rebuilding the kernel can take time, it is best to make yourkernel conÞguration selections all at once. Here are some things to think about whenyou are conÞguring your kernel:

� Will you be using kernel modules?

� Which standard devices do you wish to enable (keyboard, mouse,framebuffer, etc.)?

� Will you be including any custom device drivers?

� Will your application require any of the real-time performanceenhancements? (real-time scheduler or preemptible kernel)

� Which type of Þle system do you want to use in your deployedembedded project? (EXT2, ReiserFS, JFFS, etc.)

Once you have Þnished building the kernel, you can boot the target with the newkernel image.

Application development

Development of your application can be done on the host using KDevelop, a C/C++IDE. You may also use the command-line compilers and debuggers available withPro. Whether you use KDevelop or another tool, you should create a work directory(such as myapplication) for application development. After you have written andcompiled your application on the host, move the application to an NFS-mounted Þlesystem on the target to test the application.

There are a number of advantages to using a cross-development environment with anNFS-mounted Þle system when testing an application:

� The host contains the root Þle system for the target to NFS mount.The NFS root Þle system allows for fast prototyping and faultisolation.

� The NFS root Þle system provides a large selection of applicationsthat the typical embedded target would not be able to have locally asit would not, in most cases, have enough resources.

� In most environments, compiles more quickly on the host than onthe target, because the host is usually faster and has more resourcesthan the target.

� The host, with its graphic capability, swap space, and memory,allows for developing with user-friendly GUI tools.

Note: MontaVista provides the ability to compile the kernel or application on thetarget; however, in most cases, using the host�s environment makes more sense.

,

8 MontaVista� Linux® Professional Edition

Page 17: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionDeveloping Embedded Applications With Pro

Integrate Your System Components

Once you are satisÞed with your kernel and application, it is time to integrate yoursystem components and test your embedded environment.

Integrating the system components includes the following steps:

� Determine which libraries and applications are required to supportyour application, and then build a Þle system with thoseapplications and libraries. We recommend that you use TCT toselect the packages you wish to include in your Þle system.

� Boot the target with the your modiÞed kernel.

� Add your application to your Þle system. You should use a builddirectory (such as myfilesystem) as the location for integratingyour Þle system and application.

� Export the myfilesystem directory containing your Þle systemand application as NFS to the target system. By exporting the Þlesystem directory as NFS, you can test your environment on thetarget before spending the development time to reduce the Þlesystem size or burn the Þle system into ßash.

� ConÞgure the user environment. Doing this for your applicationcan include activities such as adding your application to start-upscripts (setting the run levels), creating required device nodes, orconÞguring the networking components used.

Once you have completed the tasks above, you should have a system that appears asfollows:

When you know you have an environment that works, you can proceed to reducing thesize of your Þle system. After reducing the size of your Þle system, you should useproÞling tools to evaluate the your project�s performance and to look for memory

Host

Local Network

Serial

.....................................

Target

Pro 3.0---------------Red Hat 7.3

Custom KernelNFS Root File System

Custom Apps

User-Space Configs

Target File System

MontaVista� Linux® Professional Edition 9

Page 18: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionDeveloping Embedded Applications With Pro

leaks, etc. You will want to use the same development cycle you used for initialkernel and application development to Þx and test problems uncovered with thesetools.

Deploy Your Embedded Application

When your kernel and application have been proven in a test environment, then it�stime to disconnect the target from its reliance on the host and make it self-sufÞcient.

A stand-alone target may appear as the diagram below:

Disconnecting the target from the host may require building a kernel and Þle-systemimage that can be booted from ßash, or it may require a system than can be booted viaLILO. Some general strategies are outlined later in this manual.

.....................................

Target

User-Space Configs

Custom Apps

Local Root File System

Custom Kernel

10 MontaVista� Linux® Professional Edition

Page 19: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionAbout This Manual

About This Manual

This manual describes how to install and use Pro to develop embedded systems basedon Pro. This manual covers all supported target architectures, and it is included oneach of the Pro CDs in PDF format. The host system in this manual is assumed to be aRed Hat® host. If you are using another host, we recommend that you read one of thePro host manuals for more information and requirements regarding the host OS youare using.

This manual assumes that you know how to use Linux. If you are unfamiliar withLinux, there are many books available to help you get started using and understandingLinux.

Note: MontaVista Software does not endorse the book listed below. The followingexample is provided for your convenience only:

� Running Linux, Matt Welsh, Matthias Kalle Dalheimer, and LarKaufman. Sebastopol, California: O'Reilly & Associates [1999].(ISBN: 156592469X)

Other Documentation

MontaVista Linux Professional Edition Quick Start Guides

For each supported target, MontaVista Software provides a Pro quick start guide. Thequick start guides contain step-by-step instructions for booting Pro on the target usinga Red Hat® Linux host. Copies of the quick start guides can be found on the �ProHost Binaries� CD-ROM in the /docs/quickstarts directory. In addition, asupdates are made, the latest versions will be available on MontaVista Zone.

MontaVista Linux Professional Edition Host Manuals

Pro quick start guides assume that you are using a Red Hat® host. If you wish to useone of the other supported hosts, MontaVista Software provides host manuals. Thesemanuals provide step-by-step instructions on how to conÞgure the host along withusage notes about using Pro with that host OS. Host manuals are available forSolaris�, SuSE®, YellowDog®, and Mandrake� as well as for using a local-compilation environment. Copies of the Pro host manuals can be found on the �ProHost Binaries� CD-ROM in the /docs/hostmanuals directory. In addition, asupdates are made, the latest versions will be available on MontaVista Zone.

MontaVista Zone

MontaVista Zone (http://support.mvista.com) is the MontaVista subscriber-onlysupport Web site. MontaVista Zone provides focused information to assist in gettingproducts to market faster. On MontaVista Zone, you will Þnd embedded Linuxinformation, access to MontaVista-developed software, and MontaVista FAQs.

MontaVista� Linux® Professional Edition 11

Page 20: Monta Vista Users Guide

Chapter 1: Welcome to MontaVista� Linux® Professional EditionSupport

SupportIn-depth technical engineering assistance is available for the distributed software thatMontaVista Software develops, for example, MontaVista Linux Professional Edition.Customers can request help with installation, conÞguration, usage, and otherquestions concerning Pro. Generally, this software is fully supported for developmentand deployment.

Unless otherwise stated on MontaVista Zone or in the quick start guide for your LSP,the LSP is supported for development and deployment. Some of the Linux SupportPackages (LSPs) may be deemed for �development only.� This means one or both ofthe following:

� MontaVista Software still considers this LSP to be underdevelopment and does not guarantee, support, or recommend its usefor deployment in end customer products.

� MontaVista Software considers this LSP to be useful and supportsthe use of this LSP for customers to develop on and with. TheseLSPs usually are updated regularly and the customer should visitMontaVista Zone (http://support.mvista.com) to look for updates.

The purpose of this classiÞcation is to get LSPs to customers asquickly as possible. The LSP may be as complete as it is plannedto be, and following a release or update, the LSP will be changedfrom �development only� to �development and deployment.�

General technical assistance only is provided for third-party products that MontaVistaSoftware recommends for use with Pro. This service may range from answeringquestions to providing work-arounds. Since MontaVista Software is not responsiblefor the development of these third party products, some issues may require input fromthe original applications vendor. Note that MontaVista only provides assistance forthese products when they are being used with Pro.

No assistance is provided for non-system software, e.g. games or I/O drivers for non-MontaVista Software certiÞed systems and boards.

MontaVista Software maintains a hardware support environment of supported boardsand systems to duplicate the reference hardware environment of the customer. If acustomer is having a problem on a custom board or customized enhancements thatthey�ve made to our standard products, MontaVista Software may request that thecustomer duplicate the problem on a reference board Þrst before troubleshooting theproblem.

MontaVista Software wants your input regarding how well MontaVista Software isperforming, as well as any suggestions or comments for improvement that you have.Suggestions can be e-mailed to [email protected].

12 MontaVista� Linux® Professional Edition

Page 21: Monta Vista Users Guide

Chapter 2: Installation

Overview

To use Pro 3.0, you Þrst need to install it on your host machine. Step-by-stepinstructions for installing Pro 3.0 for a cross-compilation development environmentcan also be found in the quick start guide for your target. For instructions on how toinstall Pro 3.0 on an IA-32/x86 target for a local-compilation developmentenvironment, see Using MontaVista Linux Professional Edition for LocalCompilation.

Pro 3.0 is distributed as a multiple CD-ROM set. The number and complement of CD-ROMs in your set depends on the product subscription you have purchased. Each Pro3.0 subscription CD-ROM set contains:

� A �Pro 3.0 Host Binaries� CD-ROM, containing the componentsfor all supported development host platforms

� One or more Pro 3.0 target architecture CD-ROMs, containing thetarget platform components

� A �Pro 3.0 Source� CD-ROM containing all of the source packages(SRPMS) corresponding to installable packages on the otherCD-ROMs

To install Pro 3.0 for cross-compilation, you need to use the hhl-host-installtool. This chapter contains the following sections:

� �Requirements� on page 15

� �The hhl-host-install Tool� on page 17

� �Displaying the Product Directory� on page 20

� �Installing or Upgrading Pro� on page 22

MontaVista� Linux® Professional Edition 13

Page 22: Monta Vista Users Guide

Chapter 2: InstallationOverview

� �Removing Pro� on page 30

� �Installing, Upgrading, or Removing Optional Packages� onpage 32

For more information about the Þle-system layout installed on the host and target, see�Pro File-System Layout� on page 189.

14 MontaVista� Linux® Professional Edition

Page 23: Monta Vista Users Guide

Chapter 2: InstallationRequirements

Requirements

Before you begin, make sure your host and target machines meet the requirementsprovided below.

Host Pro 3.0 supports a variety of different host environments for cross-compilationdevelopment. You may use any of the supported host systems with any of thesupported targets (with some exceptions). The supported host systems are:

� Mandrake® 8.1 (on x86)

� Red Hat® 7.2 and 7.3 (on x86)

� SuSE® 7.3 (on x86)

� YellowDog® 2.1 (on PowerPC)

� Solaris� 7 and 8 (on Sparc�)

Warning! Some of the host OS default installations do not include all of the softwarethat you need in order to install and use Pro. For Red Hat hosts, if you are using astandard Workstation installation (all versions) with X windows and Gnome or KDEand Software Development package groups (7.2 and 7.3) installed, you need to installdhcp (individual package) from the Red Hat installation CD-ROMs. For Red Hat 7.2and 7.3, you must also ensure that the Þrewall is set to allow NFS mounting.Information about the additional components required for a particular host, alongwith any restrictions and work-arounds for using a particular host, can be found in thehost manuals.

Regardless of which host system you are using, your system must meet the followingrequirements:

� For a basic installation of a single architecture and a single LSP, thehost system must have a minimum of 1100 MB disk spaceavailable.

Note: For each additional architecture, you need an additional 800MB of disk space. For each additional LSP, you need an additional150 MB of disk space.

Note: All disk space must be on a single Þle system.

� The host system must have a supported Ethernet interface.

� You need root access on the host machine.

� You need console access to the target. Console access can be eithera serial connection to the host, or a VGA display and keyboardconnected to the target. (Refer to the quick start guide for yourtarget to determine your connection type.)

MontaVista� Linux® Professional Edition 15

Page 24: Monta Vista Users Guide

Chapter 2: InstallationRequirements

Target Pro 3.0 can be used with six different target architectures: ARM, IA-32/x86, MIPS,PowerPC, StrongARM/XScale, and SuperH (SH), and with more than 78 differenttarget boards. For a complete list of the supported targets, please visit:

� http://support.mvista.com/content/Pro/Targets

Note: Some targets are supported for �development only.� For more informationabout support levels, see �Support� on page 12.

16 MontaVista� Linux® Professional Edition

Page 25: Monta Vista Users Guide

Chapter 2: InstallationThe hhl-host-install Tool

The hhl-host-install Tool

Install Pro 3.0 using the hhl-host-install tool.

Usage Use of the hhl-host-install tool is described below:

hhl-host-install--helphhl-host-install--versionhhl-host-install--install | --upgrade | --remove | --list [ --quiet | --verbose ] [ --confirm | --noconfirm ] [ --noprogress | --progress ] [ --media { /mnt/cdrom | <mediamountpoint> } ] [ --prefix { /opt | <install-dir> } ] [ --lsp ] { <lsp-name> | <lsp-name-pattern> } --package <package-name>

Options The following list contains a description of each option:

� --helpThis option produces an installer usage display similar to the above.

� --versionThis option displays the version of the installer.

� --installThis option speciÞes operation of the installer which results in aninstall of all packages on a fresh system, or to install an additionalLSP to an existing environment. If neither --install, --upgrade, --remove, or --list is speciÞed, --install is assumed.

� --upgradeThis option speciÞes an upgrade operation whereby existingpackages are upgraded from copies on the distribution.

� --removeThis option speciÞes a remove operation to remove all or part of aprevious MontaVista Linux installation from the host.

� --listThis option produces a listing of the LSPs on the distribution and/orpreviously installed on the host. By default, all LSPs are listed;optionally, the listing may be Þltered by the --lsp option.

The --install, --upgrade, --remove, and --listoptions are mutually exclusive.

� --verboseThis option speciÞes that installation steps are to produce verbose

MontaVista� Linux® Professional Edition 17

Page 26: Monta Vista Users Guide

Chapter 2: InstallationThe hhl-host-install Tool

output with respect to actions taken, such as complete lists ofinstalled Þles.

� --quietThis option speciÞes that installation steps produce compact outputfor each step. This is the default.

� --progressThis option displays progress bars ("#") during packageinstallation.

� --noprogressThis option does not display progress bars during packageinstallation. This is the default.

� --confirmThis option speciÞes that the user is prompted to make decisionsabout the progress of the installation process. This is the default.The instructions below assume that conÞrmation is in effect andshow the types of prompts received in this mode.

� --noconfirmThis option speciÞes that the installation is to run unattended anddefault responses are assumed for actions which would evoke aprompt in conÞrmation mode. In some cases where a media changeor password is required, operation cannot be completelyunattended.

� --mediaThis option speciÞes the location of the distribution media. Thedefault is the mount point of the distribution media, generally/mnt/cdrom, the default CD-ROM mount point. If anothermedium (such as NFS) or different CD-ROM mount point is used,specify the mount point for that distribution here.

� --prefixThis option speciÞes the installation location for the product. Thedefault is /opt/hardhat, the MontaVista Linux defaultinstallation directory. If an alternate install directory is desired,specify it here.

� --lsp <lsp-name>--lsp <lsp-name-pattern>This option speciÞes an Linux Support Package (LSP) for a giventarget platform to be listed, installed, upgraded, or removedaccording to the operation option selected. The keyword �--lsp�is optional. This option has no default. If an LSP is required for thecurrent operation and none is speciÞed in this option, the installerwill prompt for an LSP name. Legal values for <lsp-name> arelisted under the �LSP Name� column of the display produced by

18 MontaVista� Linux® Professional Edition

Page 27: Monta Vista Users Guide

Chapter 2: InstallationThe hhl-host-install Tool

the --list option. In addition, the remove operation accepts thespecial values �all� or �hhl� to denote all LSPs.

If <lsp-name-pattern> is speciÞed instead of <lsp-name>, itcontains one or more Linux Þlename pattern-matching characters.Such a value may need to be quoted to protect the value from shellexpansion. For install, upgrade, and remove operations, <lsp-name-pattern> must match at most one <lsp-name>; if an LSP is requiredfor the current operation and the pattern matches multiple <lsp-name>s, the installer will prompt for an LSP name. For listoperations, the installer will display all <lsp-name>s that match thepattern.

The --lsp and --package options are mutually exclusive.

� --package <package-name>This option speciÞes a single host, cross-development, or targetarchitecture package to be installed, upgraded, or removedaccording to the operation selected. The operation modiÞes theinstalled MontaVista Linux environment. Incorrect use of thisoption may render the cross-development environment or the targetboard unusable. This option has no default.

<package-name> is the MontaVista Linux RPM package namebeginning with �hhl-�. Installed MontaVista Linux packages maybe listed using RPM.

All package-oriented operations must take place using a singleinstallation location speciÞed by --prefix or using the default inthis and all previous hhl-host-install commands.

The --package and --lsp options are mutually exclusive.

The installation tool prompts for conÞrmation when performing an --upgrade or --remove with the --package option. AnafÞrmative reply is required to continue. An attempt to install apackage already installed, or remove a package not installed, resultsin an error. However, it is okay to upgrade a package that is alreadyinstalled.

MontaVista� Linux® Professional Edition 19

Page 28: Monta Vista Users Guide

Chapter 2: InstallationDisplaying the Product Directory

Displaying the Product Directory

To display a list of all the LSPs contained in the product along with the location ofthose LSPs on the product CD-ROMs, complete the following steps:

1. Log in as root.

2. Insert any Pro CD-ROM into the CD-ROM drive. The CD-ROM usedneed not contain the architecture or LSP of interest.

3. Mount the CD-ROM, if necessary. Use the command:

mount /mnt/cdrom

The mount point is assumed to be /mnt/cdrom in the steps below.

4. Use the --list option of the installation tool to display the productdirectory. To see the complete list of LSPs in the product, enter thefollowing command:

/mnt/cdrom/bin/hhl-host-install --list

To see an abbreviated list of LSPs that match a pattern, enter the patternusing Linux Þle-name pattern-matching characters.

/mnt/cdrom/bin/hhl-host-install --list <lsp-name-pattern>

For example:

/mnt/cdrom/bin/hhl-host-install --list motorola*

Note: You may need to quote the <lsp-name-pattern> value to protectpattern-matching characters from the shell.

The installation tool displays the following information:

LSP Name Target Board Location

Under �LSP Name� is the name by which you identify the LSP to the installation toolfor installation, upgrade, or removal; for example, as part of the --lsp <lsp-name>option.

Under �Target Board� is the manufacturer's name and the well-known product namefor the target hardware supported by the speciÞed LSP.

20 MontaVista� Linux® Professional Edition

Page 29: Monta Vista Users Guide

Chapter 2: InstallationDisplaying the Product Directory

Under �Location� is the text of the printed label for the CD-ROM on which the LSP isdistributed. It may be the same CD-ROM currently mounted for the --listoperation, or any other CD-ROM in the product set.

Note: You may not have subscribed to all architectures included in Pro; therefore, youmay not possess all the CD-ROMs listed in the �Location� column.

You can now unmount the CD-ROM. Use the command:

umount /mnt/cdrom

MontaVista� Linux® Professional Edition 21

Page 30: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading Pro

Installing or Upgrading Pro

This section contains information on how to install Pro 3.0 or upgrade to Pro 3.0.

� If this is your Þrst time installing Pro 3.0, follow the instructions in�Install� on page 22.

� If you have a previous version of a MontaVista Linux productinstalled and you would like to upgrade to Pro, follow theinstructions in �Upgrade� on page 24.

Note: Even if you are not installing the same LSP as in the previousversion, you need to upgrade to the Pro rather than perform a newinstallation because the required host packages must be upgraded.

� If you have already installed Pro 3.0 (or upgraded to Pro 3.0) andyou want to install or upgrade an additional LSP, follow theinstructions in �Installing or Upgrading an Additional LSP� onpage 28.

Warning! Some of the host OS default installations do not include all of the softwarethat you need to install and use Pro. Information about the additional components andsteps required for a particular host along with any restrictions and work-arounds forusing a particular host can be found in the host manuals. Host manuals are located onthe �Pro Host Binaries� CD-ROM in the /docs/hostmanuals directory. Hostmanuals are also available on MontaVista Zone.

Install The following steps are used to install the Pro product for the Þrst time. First-time Proinstallation requires two CD-ROMs:

� The �Pro Host Binaries� CD-ROM, which applies to allinstallations

� The target architecture CD-ROMs, containing the target LSP youwant to install

Note: You may identify the correct target architecture CD-ROMusing the tables in appendix A of the quick start guide for yourtarget or by using the --list option of the installation tool. Thelabel of the correct target architecture CD-ROM is displayed in the�Location� column.

You should identify and have available both CD-ROMs before starting installation.

During installation the Þrst CD-ROM is automatically ejected by the installation tool.If, for any reason, the CD-ROM device is �busy,� the tool will fail to eject the ÞrstCD-ROM and the installation will not proceed. For this reason, you should eitherprint out this documentation or make a local copy on your machine. Viewing thedocumentation from the CD-ROM will cause the CD-ROM device to be busy.

22 MontaVista� Linux® Professional Edition

Page 31: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading Pro

To install Pro for the Þrst time, complete the following steps:

1. Log in as root.

2. Insert the �Pro Host Binaries CD-ROM� into the CD-ROM drive.

3. Mount the CD-ROM, if necessary. Use the command:

mount /mnt/cdrom

The mount point is assumed to be /mnt/cdrom in the steps below.

4. Close any CD-ROM Þle-system browser windows that appear.

5. Run the installation tool. To install Pro to the default location, /opt/hardhat, use the command:

/mnt/cdrom/bin/hhl-host-install

Warning! Do NOT change directories to the CD-ROM mount point torun the tool, as this will cause the tool to be unable to unmount the ÞrstCD-ROM.

To install to an alternate location, include the --prefix <install-dir>option in the command. For example, use the command:

/mnt/cdrom/bin/hhl-host-install --prefix <install-dir>

<install-dir> is the selected installation location.

Note: All Pro base and optional products must be installed in the samelocation. Select a location that provides enough space both to completethe Þrst-time installation and to allow for expansion if you intend toinstall additional LSPs or optional products.

You�ll receive messages identifying the version of Pro being installed,and then the prompt:

hhl-host-install: Enter LSP name (or "?" to list LSP names):

6. Enter the name of the LSP that corresponds to the target platformhardware you wish to install. LSP names are listed in the quick startguide for your target. LSP names can also be listed by typing ? at theprompt. A list of LSP names will be displayed and the prompt abovewill be repeated.

The host platform packages will be installed into the location selected instep 5.

The installation tool ejects the �Pro Host Binaries� CD-ROM anddisplays the message:

MontaVista� Linux® Professional Edition 23

Page 32: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading Pro

hhl-host-install: Insert MontaVista Linux <CD label> CD and

press enter:

<CD label> speciÞes the label of the target architecture CD-ROMneeded to complete installation.

7. Insert the appropriately-labeled CD-ROM speciÞed in the message intothe CD-ROM drive and press Enter.

The appropriate target architecture and LSP packages are now installed.

8. Close any CD-ROM Þle-system browsers that appear.

The installation tool automatically ejects the target platform architectureCD-ROM.

If installation is successful, you receive a message indicating installation is complete.In the event of a failure, review the error message and correct the problem. For moreinformation, see �Trouble-Shooting� on page 34.

Upgrade Important: The Pro 3.0 installation tool allows you to use the --upgrade option toupgrade from Pro 2.1 to Pro 3.0.

The Pro 3.0 installation tool provides you with a simple way to upgrade from Pro 2.1.Upgrading from earlier versions is not supported and is not covered by this manual.Regardless of which LSP you are installing, you need to upgrade if you have Pro 2.1already installed on your host machine.

Should I upgrade?

While we generally recommend that you upgrade to Pro 3.0, there are some situationswhere we recommend not upgrading at this time. These include:

� If you are using a MontaVista add-on product (such as VisualAgeMicro Edition 1.4 for MontaVista� Linux®) that has not yet beenupdated for use with Pro 3.0. Upgrading to Pro version 3.0 willcause the add-on to no longer function correctly. If your projectrelies on having the add-on functionality available, we recommendnot upgrading at this time.

� If you decide to upgrade to Pro 3.0, you must upgrade all LSPs atonce. Failure to do so will �break� the LSPs that were notupgraded. If you are using multiple LSPs and your developmentcycle prohibits upgrading all LSPs, you may not want to upgrade atthis time.

Upgrade from Pro 2.1

If Pro 2.1 was previously installed, you may not perform a simple installation (--install option); you must perform an upgrade (--upgrade option).

24 MontaVista� Linux® Professional Edition

Page 33: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading Pro

Installations of Pro 3.0 and Pro 2.1 CANNOT coexist, because they use a sharedRPM database; therefore, the installation tool upgrades MontaVista-distributedpackages in place. For that reason, you must upgrade Pro 3.0 using the same directoryas was used to install Pro 2.1.

For step-by-step instructions on how to upgrade, see �How to upgrade� below.

How to upgrade

The following steps are used to upgrade to Pro 3.0 from Pro 2.1.

Pro 3.0 upgrade requires two CD-ROMs:

� The �Pro 3.0 Host Binaries� CD-ROM, which applies to allinstallations

� The Pro 3.0 target architecture CD-ROM, containing the target LSPyou want to install

Note: You may identify the correct target architecture CD-ROMusing the tables in appendix A of the quick start guide for yourtarget or by using the --list option of the installation tool. Thelabel of the correct target architecture CD-ROM is displayed in the�Location� column.

You should identify and have available both CD-ROMs before beginning the upgrade.

During installation the Þrst CD-ROM is automatically ejected by the installation tool.If, for any reason, the CD-ROM device is �busy,� the tool will fail to eject the ÞrstCD-ROM and the installation will not proceed. For this reason, you should eitherprint out this documentation or make a local copy on your machine. Viewing thedocumentation from the CD-ROM will cause the CD-ROM device to be busy.

To upgrade to Pro 3.0, complete the following steps:

1. Log in as root.

2. Insert the �Pro 3.0 Host Binaries CD-ROM� into the CD-ROM drive.

3. Mount the CD-ROM, if necessary. Use the command:

mount /mnt/cdrom

The mount point is assumed to be /mnt/cdrom in the steps below.

4. Close any CD-ROM Þle-system browser windows that appear.

5. Run the installation tool. To install Pro 3.0 at the default location, /opt/hardhat, use the command:

/mnt/cdrom/bin/hhl-host-install --upgrade

MontaVista� Linux® Professional Edition 25

Page 34: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading Pro

Warning! Do NOT change directories to the CD-ROM mount point torun the installation tool, as this will cause the tool to be unable tounmount the Þrst CD-ROM.

To install at an alternate location, include the --prefix <install-dir>option in the command. Use the command:

/mnt/cdrom/bin/hhl-host-install --upgrade --prefix <install-dir>

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

<install-dir> is the selected installation location.

Note: If you installed Pro 2.1 in an alternate directory you must specifythat directory using the --prefix <install-dir> option. Theinstallation tool does not permit you to have simultaneous installationsof MontaVista Linux products.

You�ll be prompted to conÞrm that you want to overwrite the existingLSP. You must reply afÞrmatively to continue.

6. Enter the name of the LSP that corresponds to the target hardware youwish to install. LSP names are listed in the quick start guide for yourtarget. LSP names can also be viewed by typing ? at the prompt. A listof LSP names will be displayed and the prompt above will be repeated.

The host platform packages will be installed into the location selected instep 5.

The installer ejects the �Pro 3.0 Host Binaries� CD-ROM and displaysthe message:

hhl-host-install: Insert the MontaVista Linux <CD label> CD

and press enter:

<CD label> speciÞes the label of the target architecture CD-ROMneeded to complete installation.

7. Insert the target architecture CD-ROM speciÞed in the message into theCD-ROM drive and press Enter.

The appropriate target platform architecture and LSP packages are nowinstalled.

8. Close any CD-ROM Þle-system browsers that appear.

The installation tool automatically ejects the target platform architectureCD-ROM.

26 MontaVista� Linux® Professional Edition

Page 35: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading Pro

If the upgrade is successful, you receive a message indicating upgrade is complete. Inthe event of a failure, review the error message and correct the problem. Foradditional information, see �Trouble-Shooting� on page 34.

MontaVista� Linux® Professional Edition 27

Page 36: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading an Additional LSP

Installing or Upgrading an Additional LSP

The following steps are used to install or upgrade an additional LSP.

Before you can install or upgrade an additional LSP, you must install or upgrade toPro version 3.0 for at least one LSP. To install Pro version 3.0 for the Þrst time, use thesteps under �Install� on page 22. To upgrade to Pro version 3.0, use the steps under�Upgrade� on page 24.

Installing an additional LSP from Pro 3.0 requires the target architecture CD-ROMcontaining the desired target platform LSP. The correct target architecture CD-ROMis listed in the quick start guide for your target. You may also use the --list optionof the installation tool. The label of the correct target architecture CD-ROM isdisplayed in the �Location� column.

To install or upgrade an additional LSP, complete the following steps:

1. Log in as root.

2. Insert the Pro target architecture CD-ROM containing the additionalLSP you desire into the CD-ROM drive.

3. Mount the CD-ROM, if necessary. Use the command:

mount /mnt/cdrom

The mount point is assumed to be /mnt/cdrom in the steps below.

4. Run the installation tool. To install the additional LSP to the defaultlocation, /opt/hardhat, use the command:

/mnt/cdrom/bin/hhl-host-install

Warning! Do NOT change directories to the CD-ROM mount point torun the installation tool, as this will cause the tool to be unable tounmount the Þrst CD-ROM.

If hhl-host-install is run while accessing the mounted CD-ROM, the installer will abort. If the CD-ROM is referenced fromanother window, it will not be detected and cause the unmount to fail.

To upgrade an LSP installed from a previous version, use the--upgrade option rather than doing a simple installation. Use thecommand:

/mnt/cdrom/bin/hhl-host-install --upgrade

To install (or upgrade) to an alternate location, include the --prefix<install-dir> option in the command. For example, to install to analternate location, use the command:

28 MontaVista� Linux® Professional Edition

Page 37: Monta Vista Users Guide

Chapter 2: InstallationInstalling or Upgrading an Additional LSP

/mnt/cdrom/bin/hhl-host-install --prefix <install-dir>

<install-dir> is the selected installation location.

Note: All Pro base and optional products must be installed (orupgraded) in the same location. Use the default location for the productinstallation if you previously used the default location to install Pro. Ifan alternate location was chosen for Pro, use that same location for thisinstallation.

You�ll be prompted to conÞrm that you want to overwrite the existingLSP. You must reply afÞrmatively to continue.

5. Enter the name of the LSP that corresponds to the target platformhardware you wish to install. LSP names are listed in the quick startguide for your target. LSP names can also be viewed by typing ? at theprompt. A list of LSP names will be displayed and the prompt above isrepeated.

All target platform packages related to the selected LSP are installed at the locationselected in step 4. Packages which were previously installed as part of another LSPare noted and not duplicated.

If installation is successful, you receive a message indicating installation is complete.In the event of a failure, review the error message and correct the problem.

You can now unmount the CD-ROM. Use the command:

umount /mnt/cdrom

MontaVista� Linux® Professional Edition 29

Page 38: Monta Vista Users Guide

Chapter 2: InstallationRemoving Pro

Removing Pro

If you installed the incorrect LSP or would like to remove your installation of Pro, usehhl-host-install.

Note: For removals, the Pro CD-ROM does NOT need to be available. Once Pro isinstalled, the hhl-host-install tool is available in the /opt/hardhat/host/bin and the installation tool can be run from that location. If you installed ina location other than the default, replace /opt in the path above and in the commandsbelow with the path that you used.

Remove a Single LSP

LSPs may be removed in any order, without regard to the order in which they wereoriginally installed. You may also remove the last remaining LSP. In this case, the hostplatform and target platform architecture packages remain installed.

To remove only the packages for a speciÞc LSP, complete the following steps:

1. Log in as root.

2. Run the command:

/opt/hardhat/host/bin/hhl-host-install --remove <lsp-name>

You receive a message conÞrming your intentions:

hhl-host-install: This operation will remove allinstalled <lsp-name> packages. Okay to proceed?

3. Enter yes to remove the LSP.

All packages for the speciÞed LSP are removed.

Note: If you conÞgured any host services (e.g., DHCP, TFTP, NFS) for use with Pro,you may want to reconÞgure and/or remove these services, as the Pro componentsthat these services may depend on, are no longer present on your system.

Remove All of Pro To remove all of Pro, complete the following steps:

1. Log in as root.

2. Run the command:

/opt/hardhat/host/bin/hhl-host-install --remove all

You receive a message conÞrming your intentions.

3. Enter yes to remove Pro.

All Pro packages are removed.

30 MontaVista� Linux® Professional Edition

Page 39: Monta Vista Users Guide

Chapter 2: InstallationRemoving Pro

Note: If you conÞgured any host services (e.g., DHCP, TFTP, NFS) for use with Pro,you may want to reconÞgure and/or remove these services, as the Pro componentsthat these services may depend on are no longer present on your system.

MontaVista� Linux® Professional Edition 31

Page 40: Monta Vista Users Guide

Chapter 2: InstallationInstalling, Upgrading, or Removing Optional Packages

Installing, Upgrading, or Removing Optional PackagesNot all packages shipped with Pro 3.0 are installed by the LSP installation procedure.This is because some packages are mutually exclusive and cause Þle conßicts ifinstalled simultaneously. See �Pro Applications� on page 197 for a list of applicationsappearing in Pro 3.0 and whether they are installed by default.

Install To install an optional package, complete the following steps:

1. Log in as root.

2. Insert the Pro 3.0 target architecture CD-ROM containing the LSP (andtherefore the optional target application) you need into the CD-ROMdrive.

3. Mount the CD-ROM, if necessary. Use the command:

mount /mnt/cdrom

The mount point is assumed to be /mnt/cdrom in the steps below.

4. Run the installation tool with the --package <package-name> optionto install the optional package. Use the command:

/mnt/cdrom/bin/hhl-host-install --install --package<package-name>

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

<package-name> is the name of the optional package. See �ProApplications� on page 197 for a list of applications appearing in Pro.For example:

/mnt/cdrom/bin/hhl-host-install --install --package hhl-x86_pentium2-dhcpcd

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

Note: Packages must be installed in the same installation path as waspreviously chosen for Pro installation.

To install a package in an alternate location, use the command:

/mnt/cdrom/bin/hhl-host-install --install --package<package-name> --prefix <install-dir>

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

For example, to install the optional dhcpcd package for a Pentium IItarget when the non-default installation directory /group1 was

32 MontaVista� Linux® Professional Edition

Page 41: Monta Vista Users Guide

Chapter 2: InstallationInstalling, Upgrading, or Removing Optional Packages

previously chosen for Pro installation, you would use the followingcommand:

/mnt/cdrom/bin/hhl-host-install --install --package hhl-x86_pentium2-dhcpcd --prefix /group1

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

Upgrade or Remove

You may upgrade or remove an optional package by combining the --upgrade or--remove options with the --package <package-name> option. In the case ofmutually exclusive packages you may, for example, remove a previously installedoptional package from a mutually exclusive set and install an alternative packagefrom that set.

The installation tool prompts for conÞrmation when performing an --upgrade or --remove with the --package option. An afÞrmative reply is required tocontinue. An attempt to install a package already installed, or remove a package notinstalled, results in an error. However, it is okay to upgrade a package that is alreadyinstalled.

MontaVista� Linux® Professional Edition 33

Page 42: Monta Vista Users Guide

Chapter 2: InstallationTrouble-Shooting

Trouble-Shooting

The following information provides solutions for common installation problems.

Could not run the installation tool

All installation tool operations must be run as root. However, with the automounterrunning, logging into a KDE or Gnome desktop and then using the su command tobecome root may cause the installation tool on the CD-ROM to be unexecutable.

To support the automounter, during Linux system installation, the CD-ROM entry in/etc/fstab is created with the user option and the automounter process runsunder a non-root userID. Under these conditions, the automounter will mount thedistribution CD-ROM using the noexec option (implied by user), rendering thehhl-host-install tool (and any other executables on the CD-ROM)unexecutable.

There are several work-arounds. One option is to run the host installer from a rootlogin desktop session rather than using the command su root from a non-rootdesktop session. Another option is to disable the automounter. To disable theautomounter, you need to edit the Þle /etc/fstab to either add the exec optionbefore the user option or simply remove the user option for the CD-ROM mount.

Unable to eject the Þrst CD-ROM

If, for any reason, the CD-ROM device is �busy,� the installation tool will fail to ejectthe Þrst CD-ROM and installation will not proceed. Three of the most typical reasonsare:

� For some desktop environments, when the automounter mounts aCD-ROM, a Þle-system browser window appears. You need toclose this window to allow the CD-ROM to be unmounted by theinstaller.

� If you changed directories to the CD-ROM mount point to run theinstallation tool, the installation tool will be unable to unmount theÞrst CD-ROM. The installer will detect this condition and abort.

� Viewing the documentation directly from the CD-ROM will causethe CD-ROM device to be busy. You should either print this manualor make a local copy on your machine.

Unable to burn CDs

Pro CD images can be downloaded via MontaVista Zone. MontaVista Softwarerecommends burning CDs and installing from those CDs. If you are unable to burnCDs, Pro can be installed from the CD images using the --media-host or

34 MontaVista� Linux® Professional Edition

Page 43: Monta Vista Users Guide

Chapter 2: InstallationTrouble-Shooting

--media-arch options of the installation tool. To install from the CD images,follow these steps:

1. Create mount point directories for the host and architecture CD images.Use the command:

mkdir /mnt/prof-host /mnt/prof-arch

2. Mount the �Pro Host Binaries� CD image you previously downloaded,using a loopback mount.

Loopback mounts are available only on Linux host systems. Use acommand such as:

mount -r -t iso9660 -o loop <prof-host-cdimage-file> /mnt/prof-host

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

3. Mount the �Pro Target Binaries� CD image associated with the LSP youwish to install that you previously downloaded, using a loopback mount.

Loopback mounts are available only on Linux host systems. Use acommand such as:

mount -r -t iso9660 -o loop <prof-target-cdimage-file> /mnt/prof-arch

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

4. Follow the LSP installation instructions in this guide, using the --media-host and --media-arch options to specify the locationof the two CD images:

/mnt/prof-host/bin/hhl-host-install --install --media-host <mounted-cdimage-dir> --media-arch <mounted-cdimage-dir> <lsp-name>

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

<mounted-cdimage-dir> is the CD image mounted on /mnt/prof-host or /mnt/prof-arch. You may run the hhl-host-install tool from either the CD image mounted on /mnt/prof-host or /mnt/prof-arch. The same installation tool is provided inboth CD images.

If the <prof-target-cdimage-Þle> you supply does not correspond to thecorrect architecture for <lsp-name>, the installer will unmount /mnt/prof-arch and request that you mount the correct CD image.You will be forced to abort the installation at that point and resume fromthe beginning with the correct image.

MontaVista� Linux® Professional Edition 35

Page 44: Monta Vista Users Guide

Chapter 2: InstallationTrouble-Shooting

5. Unmount the �Pro Host Binaries� and �Pro Target Binaries� CD images:

umount /mnt/prof-host

umount /mnt/prof-arch

36 MontaVista� Linux® Professional Edition

Page 45: Monta Vista Users Guide

Chapter 3: The Development Environment

Overview

Pro contains everything you need to build an embedded Linux kernel. Full source isprovided to allow for a custom kernel and for custom device drivers, as well as forapplication development. For more information about the Pro directory structureinstalled, see �Pro File-System Layout� on page 189.

Included in the Pro distribution are over 280 application packages. If you do not knowhow to use these applications, man and info pages are available that can help. Acomplete list of the applications, along with a brief description and pointers toreference books, can be found in �Pro Applications� on page 197.

Once you have installed Pro and performed an initial boot of the target, you are readyto begin development. This chapter provides step-by-step instructions on how toconÞgure your development environment to allow you to easily use the tools includedwith Pro. This chapter includes the following sections:

� �Project Directories� on page 38

� �Running Pro Applications and Tools� on page 40

� �Accessing man and info Pages� on page 44

� �Other Linux Documentation� on page 48

.

MontaVista� Linux® Professional Edition 37

Page 46: Monta Vista Users Guide

Chapter 3: The Development EnvironmentProject Directories

Project DirectoriesWhen working with Pro, we recommend that you NOT work directly in the /opt/hardhat/devkit tree. Rather, we recommend that you copy the Þles youneed to modify to a work directory elsewhere on your host. We make thisrecommendation for the following reasons:

� It allows you to easily return to the default conÞgurations providedby MontaVista Software.

� The /opt/hardhat/devkit/<architecture>/<processor>/target/ directory is used by the MontaVistaTarget ConÞguration Tool (TCT) for Þle-system development.Changes can result in problems when creating your Þle system.

To create a development environment, we recommend that you follow the stepsbelow:

1. Create project directories.

2. Populate your project directories with copies of the default Þles fromMontaVista Software.

3. NFS export your project directories to your target for testing.

Details on these steps are included in the sections below.

Create Project Directories

Assuming that you are doing kernel and application development, you could create awork directory structure such as the following:

The mykernel directory can be used for kernel development. Themyapplication directory can be used for application development. Themyfilesystem directory is where you can integrate your Þle system hierarchy andyour application. These directories will be referred to later in this manual.

Populate Project Directories

The next step in setting up your development environment is to populate your projectdirectories. The sections below describe what we recommend each project directorycontain.

mykernel

In this directory, you should place a copy of your development kernel. How you copythe development kernel over depends on whether you are using Target ConÞguration

my_work_directory

/mykernel/myapplication/myfilesystem

38 MontaVista� Linux® Professional Edition

Page 47: Monta Vista Users Guide

Chapter 3: The Development EnvironmentProject Directories

Tool (TCT) (recommended), or another utility, such as make menuconfig, for yourkernel development.

TCT. If you are using TCT, when you create your TCT project directory, select themykernel directory to save your project. TCT will automatically copy everythingyou need for kernel and Þle-system development to the mykernel directory.

make menuconÞg. If you are using another tool, such as make menuconfig, usethe following commands to copy everything in the appropriate linux directory inthe kernel source tree to your mykernel directory:

cd my_work_directory/mykernel

cp -a /opt/hardhat/devkit/lsp/<target>/linux-<version-number> .

Note: There is no Þnal / in the command above. This ensures that critical hidden Þles(such as .config) are copied along with the kernel software. If you choose anothermethod for copying the Þles over, be sure to include options for copying symboliclinking and permissions.

myapplication

Use this directory to build your application. At this time, there is nothing that needs tobe copied from the Pro distribution to your application work directory for you tobegin development.

If you are using KDevelop, you need to specify this directory when setting up yourproject.

myÞlesystem

In this directory, you will eventually want to create a sub-directory for each of yourtest Þle systems. The Þle system we recommend you start with is a copy of the target�sdefault root Þle system directory. Other Þle systems you will want to test are thosethat you create using TCT.

To copy the target root Þle system as root, use the commands:

cd my_work_directory/myfilesystem

mkdir mvdefault

cd mvdefault

cp -a /opt/hardhat/devkit/<architecture>/<processor>/target .

Note: There is no Þnal / in the command above. This ensures that critical hidden Þlesare copied as well as all other software. If you choose another method for copying theÞles over, be sure to include options for copying symbolic linking and permissions.

Once you boot the target, you can NFS export this directory to provide a convenientlocation for testing your application on the target.

MontaVista� Linux® Professional Edition 39

Page 48: Monta Vista Users Guide

Chapter 3: The Development EnvironmentRunning Pro Applications and Tools

Running Pro Applications and Tools

Pro includes over 280 application packages. Applications are classiÞed as �cross-development applications,� �host applications,� or �target applications.�

Cross-development applications are tools that are run on the host but produce outputintended to run on the target. In general, the cross-development applications arecompilers, linkers, or similar tools. For the list of cross-development applications, see�Cross-Development Application Packages� on page 198.

Host applications provide tools that are run on one of the supported host platforms:SuSE, Red Hat, Solaris, etc. These applications do not relate to the target in any way �they simply provide an environment on the host in which development can take place.An example would be the TFTP server for those hosts that don't have a compatibleversion of TFTP. For the list of host applications, see �Host Application Packages� onpage 200.

Target applications are intended to be used only on the corresponding architecturetarget. The Pro distribution contains pre-compiled and pre-packaged versions of theseapplication packages so that RPM can be used to install them on the target. Fordevelopment, we recommend that NFS be used to provide the target root. The Þlesystem served by NFS is considered part of the target system, and therefore containsonly target application packages (i.e., �host� and �cross-development� packages arenot installed into this NFS portion of the Þle system). For the list of targetapplications, see �Target Application Packages� on page 204.

40 MontaVista� Linux® Professional Edition

Page 49: Monta Vista Users Guide

Chapter 3: The Development EnvironmentRunning Pro Applications and Tools

The chart below shows the full installation paths for the Pro applications and tools. Ifyou installed Pro using relocation, replace /opt in the paths listed below with thepath you used.

To run any of Pro applications, update your executable search path to include the Proapplications.

For bash, use the command:

export PATH=$PATH:<path>

For sh or ksh, use the commands:

PATH=$PATH:<path>

export PATH

For csh or tcsh, use the command:

set path=($path <path>)

Once your path has been set, applications can be run simply by entering theapplication start command at the host or target system prompt. For help on any of theapplications, see the man or info page for that application. For more information, see�Accessing man and info Pages� on page 44.

Applications Path

Target On the host:/opt/hardhat/devkit/<architecture>/<processor>/target/bin/

/opt/hardhat/devkit/<architecture>/<processor>/target/usr bin/

/opt/hardhat/devkit/<architecture>/<processor>/target/sbin

/opt/hardhat/devkit/<architecture>/<processor>/target/usr/sbin/

/opt/hardhat/devkit/<architecture>/<processor>/target/usr/share/

On the target:/bin

/usr/bin

/sbin

/usr/sbin

/usr/share

Host /opt/hardhat/host/bin

Cross-development

/opt/hardhat/devkit/<architecture>/<processor>/bin

MontaVista� Linux® Professional Edition 41

Page 50: Monta Vista Users Guide

Chapter 3: The Development EnvironmentRunning Pro Applications and Tools

Note: Cross-development applications contain a preÞx indicating the targetarchitecture and processor. For a list of the preÞxes, see �Cross-DevelopmentApplication PreÞxes� on page 42.

For example, to update your executable search path to include the Pro hostapplications for bash, use the command:

export PATH=$PATH:/opt/hardhat/host/bin

For sh or ksh, use the commands:

PATH=/opt/hardhat/host/bin:$PATH

export PATH

For csh or tcsh, use the command:

set path=(/opt/hardhat/host/bin $path)

Cross-Development Application PreÞxes

Cross-development applications use a preÞx that indicates the architecture andprocessor in the application�s start command. For example, to run GCC to compilecode for a PowerPC 8xx target, you would use ppc_8xx-gcc as the start command.The chart below lists the application preÞxes for the supported target CPUarchitecture and processor types.

Architecture and Processor Prefix Example

ARM 720t Little Endian arm_720t_le- arm_720t_le-gcc

ARM 920t Little Endian arm_920t_le- arm_920t_le-gcc

IA-32/x86 486 x86_486- x86_486-gcc

IA-32/x86 586 x86_586- x86_586-gcc

IA-32/x86 Crusoe crusoe- crusoe-gcc

IA-32/x86 Pentium2 pentium2- pentium2-gcc

IA-32/x86 Pentium3 pentium3- pentium3-gcc

MIPS Floating Point and Little Endian

mips_fp_le- mips_fp_le-gcc

MIPS Floating Point and Big Endian

mips_fp_be- mips_fp_be-gcc

PowerPC 405 ppc_405- ppc_405-gcc

PowerPC 7xx ppc_7xx- ppc_7xx-gcc

PowerPC 74xx ppc_74xx- ppc_74xx-gcc

PowerPC 8xx ppc_8xx- ppc_8xx-gcc

PowerPC 82xx ppc_82xx- ppc_82xx-gcc

StrongARM/XScale StrongARM Little Endian

arm_sa_le- arm_sa_le-gcc

42 MontaVista� Linux® Professional Edition

Page 51: Monta Vista Users Guide

Chapter 3: The Development EnvironmentRunning Pro Applications and Tools

StrongARM/XScale XScale Little Endian

arm_xscale_le- arm_xscale_le-gcc

SuperH SH3 Little Endian sh_sh3_le- sh_sh3_le-gcc

SuperH SH3 Big Endian sh_sh3_be- sh_sh3_be-gcc

SuperH SH4 Little Endian sh_sh4_le- sh_sh4_le-gcc

SuperH SH4 Big Endian sh_sh4_be- sh_sh4_be-gcc

Architecture and Processor Prefix Example

MontaVista� Linux® Professional Edition 43

Page 52: Monta Vista Users Guide

Chapter 3: The Development EnvironmentAccessing man and info Pages

Accessing man and info PagesLinux has fairly extensive online documentation. Most of the applications includedwith Pro have man and/or info pages available. Info pages are online manuals for thegiven application. A typical man page provides a description of the application and itsoptions, examples, pointers to related documentation, and a list of known problems.

man Pages By default, man pages for Pro applications are installed in the directories listed in thechart below. If you installed Pro using relocation, replace /opt in the paths listedbelow with the path you used.

Note: Man pages for target applications are not available when using a Solaris host.

Viewing man pages

To view man pages for any of the Pro applications, update your executable searchpath to include the Pro man pages.

For bash, use the command:

export MANPATH=<path>:$MANPATH

For sh or ksh, use the commands:

MANPATH=<path>:$MANPATH

export MANPATH

For csh or tcsh, use the command:

set MANPATH=(<path> $MANPATH)

For example, to update your executable search path to include the Pro man pages forthe host applications for bash, use the command:

export MANPATH=/opt/hardhat/host/man:$MANPATH

Applications Path

Target /opt/hardhat/devkit/<architecture>/<processor>/target/usr/share/man

Host /opt/hardhat/host/man

Cross /opt/hardhat/devkit/<architecture>/<processor>/man

44 MontaVista� Linux® Professional Edition

Page 53: Monta Vista Users Guide

Chapter 3: The Development EnvironmentAccessing man and info Pages

For sh or ksh, use the commands:

MANPATH=/opt/hardhat/host/man:$MANPATH

export MANPATH

For csh or tcsh, use the command:

set MANPATH=(/opt/hardhat/host/man $MANPATH)

Once your path has been set, man pages can be viewed simply by entering thefollowing command at the host or target system prompt:

man <application>

For example, to view the man page for bash, enter the command:

man bash

Listing man pages

A single application may have multiple man pages. To see the order in which manpages are displayed, enter the command:

man -aw <application>

For example, to see all of the man pages for bash, enter the command:

man -aw bash

Additional information

Additional information about man pages can be obtained by reading the man page forman. To view the man page for man, enter the command:

man man

info Pages By default, info pages for Pro applications are installed in the directories listed in thechart below. If you installed Pro using relocation, replace /opt in the paths listedbelow with the path you used.

Applications Path

Target /opt/hardhat/devkit/<architecture>/<processor>/target/usr/share/info

Host /opt/hardhat/host/info

Cross /opt/hardhat/devkit/<architecture>/<processor>/info

MontaVista� Linux® Professional Edition 45

Page 54: Monta Vista Users Guide

Chapter 3: The Development EnvironmentAccessing man and info Pages

Viewing info pages

To view info pages for any of the Pro applications, update your executable search pathto include the Pro info pages.

For bash, use the command:

export INFOPATH=<path>:$INFOPATH

For sh or ksh, use the commands:

INFOPATH=/<path>:$INFOPATH

export INFOPATH

For csh or tcsh, use the command:

set INFOPATH=(<path> $INFOPATH)

For example to update your executable search path to include the Pro info pages forthe host applications, for bash, use the command:

export INFOPATH=/opt/hardhat/host/info:$INFOPATH

For sh or ksh, use the commands:

INFOPATH=/opt/hardhat/host/info:$INFOPATH

export INFOPATH

For csh or tcsh, use the command:

set INFOPATH=(/opt/hardhat/host/info $INFOPATH)

Once your path has been set, info pages can be viewed simply by entering thefollowing command at the host or target system prompt:

info <application>

For example, to view the info page for bash, enter the command:

info bash

46 MontaVista� Linux® Professional Edition

Page 55: Monta Vista Users Guide

Chapter 3: The Development EnvironmentAccessing man and info Pages

Additional information

Additional information about info pages can be obtained by reading the info page forinfo. To view the info page for info, enter the command:

info info

MontaVista� Linux® Professional Edition 47

Page 56: Monta Vista Users Guide

Chapter 3: The Development EnvironmentOther Linux Documentation

Other Linux Documentation

In addition to the man and info pages described in the previous sections, you can alsoÞnd Linux documentation and HOW-TOs in the following directories:

� /opt/hardhat/devkit/<architecture>/<processor>/doc

� /opt/hardhat/host/doc

� /opt/hardhat/devkit/lsp/<lsp-name>/linux-<kernel-version>/Documentation

48 MontaVista� Linux® Professional Edition

Page 57: Monta Vista Users Guide

Chapter 4: Target ConÞguration and Boot

OverviewOnce you have installed Pro on your host machine and conÞgured your developmentenvironment, the next thing you will want to do is an initial boot of Pro on the target.This chapter contains the following sections:

� �Booting the Target with the MontaVista Supplied Kernel� onpage 50

� �Booting the Target with a Custom Kernel� on page 52

� �Using Minicom� on page 54

MontaVista� Linux® Professional Edition 49

Page 58: Monta Vista Users Guide

Chapter 4: Target Configuration and BootBooting the Target with the MontaVista Supplied Kernel

Booting the Target with the MontaVista Supplied Kernel

How you boot the target depends on which target you are using and on the version ofÞrmware installed on the target. For each supported target, MontaVista Softwareprovides a quick start guide. The quick start guides contain step-by-step instructionsfor booting Pro on the target for a cross-compilation development environment. Forinstructions on how to install Pro for local-compilation development on an IA-32/x86target, see Using MontaVista Linux Professional Edition for Local Compilation.Copies of the Pro quick start guides and the local-compilation manual can be foundon the �Pro Host Binaries� CD-ROM in the /docs/quickstarts directory. Inaddition, as updates are made, the latest versions will be available on MontaVistaZone.

In general, booting the target for cross-compilation development consists of thefollowing steps:

Warning! These steps are generic. For step-by-step instructions for your target, seethe Pro quick start guide for your target.

1. Hardware setup. This involves connecting the target to the host using aserial connection and connecting the target to a LAN. Some targets alsorequire a speciÞc power supply setup or Abatron BDI setup. For others,hardware setup may also include changing DIP switches or installingEEPROMS.

2. Minicom (or other terminal emulation program) conÞguration. You needto use a terminal emulation program such as Minicom to communicatewith your target. For step-by-step instructions on using Minicom, see�Using Minicom� on page 54. The parameters for communicating withyour target are listed in the Pro quick start guide for your target.

3. Target conÞguration. For many targets, you need to interact with theÞrmware to set such conÞgurations as the target IP address and the hostIP address. Some targets also require you to set the connection speed.

4. Host conÞguration. Many of the targets use a network boot. All targetsmount their root Þle system via NFS. Depending on the Þrmware usedby your target, you�ll need to conÞgure all or some of the following hostservices: DHCP, TFTP, and NFS.

Note: The Pro quick start guides assume that you are using a Red Hat®host. If you wish to use one of the other supported hosts, MontaVistaSoftware provides host manuals. These manuals provide hostrequirements, step-by-step instruction on how to conÞgure the requiredhost services, and notes on using that host for development. Hostmanuals are available for Solaris, SuSE, and Mandrake. Copies of thePro host manuals can be found on the �Pro Host Binaries� CD in the /docs/hostmanuals directory. In addition, as updates are made, thelatest versions will be available on MontaVista Zone.

50 MontaVista� Linux® Professional Edition

Page 59: Monta Vista Users Guide

Chapter 4: Target Configuration and BootBooting the Target with the MontaVista Supplied Kernel

5. Booting the target. To boot the target, the Þrmware often requires acommand to begin the booting sequence. The commands are ÞrmwarespeciÞc.

6. Once Linux boots, you are placed at a login prompt:

<targetIPaddress or name> login:

7. At this point, you can login as root with no password. You are placed ata bash shell prompt.

Note: We recommend that you change the root password as soon aspossible.

The quick start guides includes information about how to NFS export the target�s rootÞle-system directory (/opt/hardhat/devkit/<architecture>/<processor>/target/). This Þle system has been tested and is known towork. Once you have proven that the target boots, you can begin development.

Note: In the chapter �The Development Environment� on page 37, we recommendedcreating a directory called �myfilesystem� as a location for doing Þle-systemdevelopment. We recommend that you NFS export this directory in addition to thedefault system created by MontaVista Software. By exporting the Þle-systemdirectory as NFS, you can test your environment on the target before spending thedevelopment time to reduce the Þle-system size or adding the Þle system to ßash. Ingeneral, you will want to continue using the NFS-mounted root Þle system until Þnaldeployment.

For more information about how to NFS export an additional directory, see �How toNFS export your Þle-system project directory� on page 53.

MontaVista� Linux® Professional Edition 51

Page 60: Monta Vista Users Guide

Chapter 4: Target Configuration and BootBooting the Target with a Custom Kernel

Booting the Target with a Custom Kernel

To boot the target with a custom kernel, complete the following steps:

1. Place a copy of your kernel image, binary version of the kernel and thesystem.map Þle in the top level of the Linux tree. For compressedimages, you should place a copy of the image in the directory /opt/hardhat/devkit/<architecture>/<processor>/boot/.For targets that boot via TFTP, you should create a symbolic link to thekernel image in /tftpboot to the new kernel image.The image nameand image path that you use here should be used in the next step.

2. If you added new modules to your kernel, complete the following steps:

� Create a directory for your modules in the root Þle system directoryof the local system for your target. Loadable module are typicallylocated in /lib/modules. If you don�t already have a directoryfor your modules, create one by using the command:

mkdir /<kernel_build_directory>/lib/modules

� Copy your modules to the directory you just created. Use thecommand:

cp -a /<module> <kernel_build_directory>/lib/

modules/<module>

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

<module> is the full path and name of the module you wish toinclude.

3. Add a line in the /etc/rc.sysinit Þle on the target to insmod themodule. See the man page for insmod for information about use andsyntax.

4. Complete the steps listed in the quick start guide for your target usingthe new kernel image and path, rather than the default kernel images andpaths listed in the manual.

Note: The quick start guide for your target includes information abouthow to NFS export the target�s default root Þle system directory(/opt/hardhat/devkit/<architecture>/<processor>/target/). In the chapter �The Development Environment� onpage 37, we recommended creating a directory called�myfilesystem� as the location for Þle-system development. Werecommend that you NFS export this directory in addition to the defaultsystem created by MontaVista Software. By exporting the Þle systemdirectory as NFS, you can test your environment on the target beforespending the development time to reduce the Þle-system size or adding

52 MontaVista� Linux® Professional Edition

Page 61: Monta Vista Users Guide

Chapter 4: Target Configuration and BootBooting the Target with a Custom Kernel

the Þle system to ßash. In general, you will want to continue using theNFS-mounted root Þle system until Þnal deployment.

How to NFS export your Þle-system project directory

To NFS export your project directory, follow the instructions in the quick start guide(or appropriate host manual, if you are not using a Red Hat host) to �ConÞgure NFS�and add a line to the /etc/exports Þle for the directory you wish to export.

You can export any number of directories via NFS; however, only one directory canbe exported as the root Þle system. In addition to conÞguring NFS, if you would liketo make a particular directory the target�s root Þle system directory, you also need toreconÞgure DHCP. To specify that a directory should be the root Þle system, followthe instructions in the quick start guide (or appropriate host manual, if you are notusing a Red Hat host) to conÞgure DHCP. Be sure to replace the line /opt/hardhat/devkit/<architecture>/<processor>/target/ in theDHCP conÞguration Þle with the path to the directory you want to use for the root Þlesystem.

MontaVista� Linux® Professional Edition 53

Page 62: Monta Vista Users Guide

Chapter 4: Target Configuration and BootUsing Minicom

Using MinicomMinicom is a terminal emulation and modem interface program included in mostLinux distributions. Minicom is used with Pro to communicate with target boards.

ConÞgure Minicom

To conÞgure Minicom, complete the following steps:

1. Log in as root and enter the command:

minicom -s

The Minicom conÞguration menu appears:

2. Select Serial port setup and set the options for your target. The quickstart guide for your target contains the parameters you need to set to beable to communicate with your target.

Note: The serial device values given are typical. They can changedepending on which port you have connected your device.

3. Press Enter to return to the main conÞguration menu.

4. Select Modem and dialing. Set the options as indicated below.

Note: Be sure to erase the values for A - Init string, B - Reset string,and K - Hang-up string.

Filenames and paths File transfer protocols Serial port setup Modem and dialing Screen and keyboardSave setup as dflSave setup as.. Exit Exit from Minicom

A - Init string ......... B - Reset string ........ C - Dialing prefix #1.... ATDT D - Dialing suffix #1.... ^M E - Dialing prefix #2.... ATDP F - Dialing suffix #2.... ^M G - Dialing prefix #3.... ATX1DT H - Dialing suffix #3.... ;X4D^M I - Connect string ...... CONNECT J - No connect strings .. NO CARRIER BUSY NO DIALTONE VOICE K - Hang-up string ...... L - Dial cancel string .. ^M M - Dial time ........... 45 Q - Auto bps detect ..... No N - Delay before redial . 2 R - Modem has DCD line .. Yes O - Number of tries ..... 10 S - Status line shows ... DTE speed T - Multi-line untag .... No P - DTR drop time (0=no). 1

Change which setting? (Return or Esc to exit)

54 MontaVista� Linux® Professional Edition

Page 63: Monta Vista Users Guide

Chapter 4: Target Configuration and BootUsing Minicom

5. Press Enter to return to the main conÞguration menu.

6. Select Save as dß to save these as the default settings.

7. Select Exit from Minicom.

Start Minicom When you enter Minicom again, you are able to communicate with your target byusing the command:

minicom

Note: You may need to initiate a board hardware reset after restarting Minicom tosuccessfully communicate with your target.

Exit Minicom To exit Minicom, complete the following steps:

1. Use the command:

control-A X

You are prompted to conÞrm that you want to exit Minicom.

2. Press Enter to exit.

Help For help using Minicom, complete the following step:

1. Use the following command:

control-A Z

MontaVista� Linux® Professional Edition 55

Page 64: Monta Vista Users Guide
Page 65: Monta Vista Users Guide

Chapter 5: Target ConÞguration Tool (TCT)

Overview

Now that you have Pro installed and your target booted, you are ready to begindevelopment of your embedded application. To help you right-size the Linux kerneland create an optimal Þle system, MontaVista Software provides Target ConÞgurationTool (TCT). This GUI-based utility enables you to select only needed modules anddrivers for inclusion in kernel builds, allowing bootable footprints scaled below 500K.Using TCT avoids the drudgery of hand-editing conÞguration and make Þles whilemanaging dependencies among components. TCT also lets you choose pre-builtpackages for inclusion in your Þle system, including system binaries and data.

As the base for kernel and Þle-system development, TCT uses the Þles andconÞgurations provided in the reference LSP selected for your project. By startingwith the default system provided in the LSP, you can greatly reduce your developmenttime, because you are starting with a system that works.

TCT also allows you to maintain multiple conÞguration Þles for a particular project.Each conÞguration Þle can contain different kernel conÞgurations and Þle systempackage selections. By allowing you to maintain multiple conÞgurations, TCT allowsyou to test multiple conÞgurations and to easily save previous versions.

This chapter contains the following information:

� �Starting TCT� on page 58

� �TCT Project Menus� on page 61

� �Using TCT� on page 68

� �Using the Tar Archive Created by TCT� on page 72

� �The targetpkg Utility� on page 73

MontaVista� Linux® Professional Edition 57

Page 66: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Starting TCT

Starting TCT

This section covers how to start TCT, how to open a current project, and how to createa new project.

Start TCT To start TCT, on the host, enter the following command:

targetconf

Note: To run TCT, you need to update your executable search path to include the Proapplications. Instructions on how to run Pro applications can be found in �RunningPro Applications and Tools� on page 40.

The Project Manager window appears:

Create a New Project

To create a new project, complete the following steps:

1. Click the New Project button in the right-hand pane of the ProjectManager window.

58 MontaVista� Linux® Professional Edition

Page 67: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Starting TCT

A New Project window appears:

2. In the New Project window, enter the following information:

� Project Name: This is the name of your project. Each project musthave a unique name.

� Directory... This is the directory where the project is stored. If youclick on the Directory... button, a Directory Selection dialog boxappears. From there, you can browse to and choose an emptydirectory you already created or click the New Directory button tocreate a new directory.

Note: The directory speciÞed here MUST be completely empty.

� Summary: This Þeld contains a short description of the project.This Þeld is optional.

� Select LSP: In this Þeld, highlight the LSP you want to use.

Note: Even if you intend to use a custom kernel, you should selectan LSP. Selecting an LSP ensures that the correct default targetdirectory and cross-compilers are used by TCT for your targetboard. In addition, by selecting an LSP, you have a kernel that isknown to boot on the reference board as a starting point for yourdevelopment.

� If you are using a custom kernel, make sure Use Custom Kernel isselected.

Note: If you do not select the Use Custom Kernel option, TCTassumes that you are using the default kernel and some menus(such as View -> Kernel ConÞgure) are not available to you.

3. Click the Create button.

MontaVista� Linux® Professional Edition 59

Page 68: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Starting TCT

A project directory is created, and if you are using a custom kernel, the kernel iscopied to the new directory. Copying the kernel can take some time (there is noprogress indicator).

Open a Project To open an existing project, you can perform one of two procedures:

� Highlight the project you want to open and then click the OpenProject button in the right-hand pane of the Project Managerwindow.

� Or simply double-click on the name of the project in the left-handpane of the Project Manager window that you want to open.

Remove a Project To remove an existing project, complete the following step:

1. Highlight the project you want to remove, then click the RemoveProject button in the right-hand pane of the Project Manager window.

The project name is removed from the list of available projects.

Note: The actual Þles associated with the project are NOT deleted. If you want toremove these Þles from your system, you must do so manually.

60 MontaVista� Linux® Professional Edition

Page 69: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

TCT Project Menus

This section describes the menus available to you after you have opened a project. Foreach project, TCT has three menus available. They are the File menu, the View menu,and the Info menu. The sections below describe each menu and their options.

The File Menu The following sections describe the File menu options.

New ConÞg...

Select this option if you want to create a new conÞguration Þle for your project. Youcan have multiple conÞgurations for each project.

Open ConÞg...

Select this option if you want to open an existing conÞguration Þle for your project.

MontaVista� Linux® Professional Edition 61

Page 70: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

Once selected, a conÞguration selection dialog box appears. Select the conÞgurationyou want to use, then click OK.

Save ConÞg

Select this option to save changes to the current open conÞguration. ConÞgurationÞles are saved to your project directory and are each named with a .cfg extension.You can save several different conÞgurations for each project.

Save ConÞg As...

Select this option to save the current open conÞguration under a new name.ConÞguration Þles are saved to your project directory and are named with a .cfgextension.

Close ConÞg

Select this option to close the conÞguration that you are viewing without savingchanges.

Build Target

Select this menu option to build the kernel and Þle system for your target.

62 MontaVista� Linux® Professional Edition

Page 71: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

Once Build Target is selected, a dialog box appears displaying the status of the build.Build messages normally reported on Standard Error are displayed in red text for easyidentiÞcation. The build log is also stored in the project directory.

If you click Abort during the build, the build stops immediately. Any Þles alreadycreated remain on the system.

When the build is complete, the Done button is highlighted. You can scroll throughthe status messages to Þnd out what happened. Click Done when you are Þnished.

MontaVista� Linux® Professional Edition 63

Page 72: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

The View Menu TCT allows you to conÞgure your kernel, select packages for your Þle system and setoptions for the Þnal build using the View menu.

Kernel ConÞgure

This view can be used to change kernel conÞguration parameters. The interface forediting the conÞguration is the same as when using make xconfig in the Linuxsource directory.

This view is only available if you are using a custom kernel.

Note: While many features are available for conÞguration, only features speciÞcallystated on the MontaVista Zone page for your target are supported.

64 MontaVista� Linux® Professional Edition

Page 73: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

Package Selector

Use this view to select the packages you want in your target Þle system.

Package groups are displayed in a hierarchical manner in the pane on the left. Thepackages in a selected group are displayed in a hierarchical manner in the pane on theright. When an arrow pointing to the right is displayed next to the name of a packageor group, the package or group has subcomponents. To display the subcomponents,click on the arrow icon. The icon changes to an arrow image pointing down. Click itagain to hide the subcomponents. For more information about how to list whichpackages are in which group, see �The targetpkg Utility� on page 73.

Warning! The checkboxes only show the packages you selected. If a package has adependency on another package, that package is automatically installed with theselected package; however, the check box for that package remains unchanged.

At the bottom of the Package Selector view are two values - Total size and Strippedsize.

� Total Size is the total size of the packages selected.

� Stripped Size is the total size of the packages selected once theyhave been �stripped� of all symbol information.

Using the Target Options view, you can decide if you want to strip the binaries beforethey are included in the Þle system.

Warning! If you have made any changes to the default contents of the /opt/hardhat/devkit/target directory, the package selector may report errors.

MontaVista� Linux® Professional Edition 65

Page 74: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

Target Options

Use this view to select the options you want to use when building your Þle system.

Target options include:

� Binary File OptionsThis category always includes the option to Strip Binary Files.

� Install Kernel FilesThis category is for custom kernels only. The options displayedhere are different for each kernel. For most LSPs, these optionsinclude the type of kernel images to build and place in the Þlesystem tar archive created when you build the target. You want tomake sure to select the kernel image type required for your target.The Kernel Modules option is almost always present, and it isselected by default � any modules that are conÞgured by the kernelconÞguration selections will be installed.

No options are available when using a pre-built kernel.

� Filesystem Image TAR Þle name:Use this Þeld to enter the Þle name that you would like the tararchive saved as. The default name is fsimage.tar. If you aresaving multiple conÞgurations, to prevent overwriting an olderconÞguration, make sure you change this Þle name.

66 MontaVista� Linux® Professional Edition

Page 75: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)TCT Project Menus

The Info Menu TCT allows you to enter and view information about each project using the Infomenu.

Project Info...

Select this option to enter or view information about the current project.

The Summary and Description Þelds can be edited.

ConÞguration Info...

Select this option to enter or view information about the conÞguration.

The Description Þeld can be edited.

MontaVista� Linux® Professional Edition 67

Page 76: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Using TCT

Using TCT

Once you have opened a project using TCT, you can begin using TCT for kernel andÞle-system development. The sections below provide step-by-step instructions for thefollowing TCT activities:

� �Create a ConÞguration File� on page 68

� �Create/Edit Kernel ConÞguration� on page 69

� �Create/Edit File System� on page 70

� �Build the Target Kernel and File System� on page 71

Create a ConÞguration File

You can use TCT to create a target conÞguration Þle. A target conÞguration Þlecontains the options you have selected for your target Þle system, the options selectedfor your custom kernel conÞguration, and options regarding how to build the targetkernel and Þle system. You can have multiple conÞguration Þles for single project.This allows you to easily save and test a different conÞguration for the same target.

Warning! Changes made to the kernel conÞguration using another tool such as makemenuconfig or by running make xconfig independent of TCT are NOT storedin your project�s conÞguration Þle.

Create a new conÞguration Þle

To create a new conÞguration Þle for your project, complete the following steps:

1. Open your project.(See �Starting TCT� on page 58.)

2. From the File menu, select New ConÞg.

Any changes you make to the kernel or Þle-system conÞguration orbuild options will be added to the new conÞguration Þle.

3. From the File menu, select Save ConÞg or Save ConÞg as....

A dialog box appears asking you to enter the name of the newconÞguration Þle.

4. Enter the name to use to save the conÞguration Þle and click OK.

ConÞguration Þles are saved to your project directory and are named with a .cfgextension.

68 MontaVista� Linux® Professional Edition

Page 77: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Using TCT

Open a saved conÞguration Þle

To open a saved conÞguration Þle for editing or building, complete the followingsteps:

1. Open your project.(See �Starting TCT� on page 58.)

2. From the File menu, select Open ConÞg.

A dialog box appears listing the current saved project conÞgurations.

3. Highlight the conÞguration Þle you want to open and click OK.

You can now edit the kernel and Þle-system conÞguration.

Create/Edit Kernel ConÞguration

This option is only available if you selected Custom Kernel when creating your TCTproject. (See �Starting TCT� on page 58.)

Warning! Changes made to the kernel conÞguration using another tool such as makemenuconfig or by running make xconfig independent of TCT are NOT storedin your project�s conÞguration Þle.

To create/edit a new kernel conÞguration for your project, complete the followingsteps:

1. Open your project and the conÞguration you want to edit. (See �StartingTCT� on page 58.)

2. From the View menu, select Kernel ConÞguration.

3. Click the ConÞgure Kernel button.

This action starts make xconfig.

4. Use make xconfig as you normally would to conÞgure the kernel.

For more information about options to select to enable real-timeenhancements, standard devices, or Þle-system types, see �Linux KernelDevelopment� on page 75.

Note: While many features are available for conÞguration, only featuresspeciÞcally stated on the MontaVista Zone page for your target aresupported.

5. When Þnished, click on Save & Exit inside of make xconfig.

6. Ignore the warning message that appears and click OK.

7. Select Save ConÞg from the File menu to save your changes.

MontaVista� Linux® Professional Edition 69

Page 78: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Using TCT

The kernel options are now saved in the open conÞguration Þle. TCT does not buildthe kernel until the Build Target option from the File menu is selected. For moreinformation, see �Build the Target Kernel and File System� on page 71.

Create/Edit File System

Warning! If you have made any changes to the contents of the /opt/hardhat/devkit/target directory the package selector may report errors.

Knowing which ßash, memory, and disk drive provided by the board in your productdetermines the size and type of Þle system, which in turn dictates how manyapplications can be included. You should be aware of the type of Þle system you wantto use in your deployed product before creating the Þle-system hierarchy, as differentÞle-system types have different constraints. The section �Select a Deployment File-System Type� on page 145 has some information about the features and limitations ofeach supported Þle system.

To select the packages you want in your Þle system, complete the following steps:

1. Open your project and the conÞguration you want to edit. (See �StartingTCT� on page 58.)

2. From the View menu, select Package Selector.

The package selector pane appears.

Package groups are displayed in a hierarchical manner in the pane onthe left. For more information about how to list which packages are ineach group, see �The targetpkg Utility� on page 73.

3. In the pane on the left, click the group that you wish to choose.

The packages in that group are displayed in the pane on the right. (Alsoin a hierarchical manner.)

4. In the pane on the right, select the packages you want to include in yourÞle system.

Selecting a package or package component at any level automaticallyselects a useful subset of its associated subcomponents. You may alsoselect or deselect any of the subcomponents if you wish to control theselections at a Þner level.

When you select a package, the Package Selector reports any conßictswith other packages already selected.

Warning! The checkboxes only show the packages you selected. If apackage has a dependency on another package, that package isautomatically installed with the selected package; however, the checkbox for that package remains unchanged.

Note: At the bottom of the Package Selector view are two values - Totalsize and Stripped size. As size is a major consideration for many

70 MontaVista� Linux® Professional Edition

Page 79: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Using TCT

embedded development projects, pay attention to these values as youbuild your Þle system.

5. Select Save ConÞg from the File menu to save your changes to thecurrent open conÞguration Þle.

The packages selected are saved as part of the conÞguration. TCT does not build theÞle system until the Build Target option from the File menu is selected. For moreinformation, see �Build the Target Kernel and File System.�

Build the Target Kernel and File System

To build the target kernel (if using a custom kernel) and Þle system for the currentopen conÞguration, complete the following steps:

1. From the View menu, select Target Options. The Target Optionswindow appears.

2. Select the build options you want to use. Be sure to change the name ofthe Þle-system image, or you may overwrite a previous image. For moreinformation about the options available, see �Target Options� onpage 66.

Note: You should select the kernel image format you need for yourtarget in this screen. If you do not, you will need to convert the kernelimage to the correct format before booting.

3. Select Save ConÞg from the File menu to save your changes to theproject conÞguration.

4. From the File menu, select Build Target.

The Build Target dialog box appears displaying the status of the build.Build messages normally reported on Standard Error are displayed inred text for easy identiÞcation. This build log is also stored in the projectdirectory.

Note: If you click Abort during the build, the build stops immediately.Any Þles already created remain on the system.

When the build is complete, the Done button is highlighted. At thispoint you can scroll through the status messages to Þnd out whathappened.

5. Click Done when you are Þnished.

The build process creates a tar archive of the Þle system (and kernel) in your projectdirectory. See �Using the Tar Archive Created by TCT� on page 72 for moreinformation about how to use the tar archive once it has been created.

Warning! Changes made to the kernel conÞguration using another tool such as makemenuconfig or by running make xconfig independent of TCT were NOT storedin your project�s conÞguration Þle, and therefore not built in the kernel.

MontaVista� Linux® Professional Edition 71

Page 80: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)Using the Tar Archive Created by TCT

Using the Tar Archive Created by TCT

The build process creates a tar archive of the Þle system and kernel in your projectdirectory. The tar archive contains:

� a Þle-system hierarchy with the applications and libraries youselected

� kernel images � depending on the selections you made in the TargetOptions screen, there may be multiple kernel images of differentformats

The tar archive must be extracted for use for kernel development or Þle-systemdevelopment. To untar the tar archive, complete the following steps:

1. Create a build directory for your kernel/Þle system. For example:

mkdir myfilesystem

2. Copy or move the resulting Þle-system tar archive to the directory youcreated for your Þle system.

3. Use GNU tar to untar the Þle-system tar archive into your Þle-systemdirectory. For example, to untar the Þle project1.tar into thedirectory myfilesystem, you would use the commands:

cd myfilesystem

tar xv --numeric-owner -f /<path>/project1.tar

For more information, see the man page for tar.

Note: When you untar the Þle system, to ensure that the correct user andgroup IDs for the target are used, be sure to use the GNU tar option,--numeric-owner.

For Þle-system development, you can now continue with system integration. See�System Integration� on page 143.

For kernel development:

� If you selected the correct kernel image format from the TargetOptions screen, you should have a kernel image of the correct typeto boot your target.

� If your CPU or board Þrmware uses an image type not available onthe Target Options screen, or you did not select the image type youneed, convert the binary kernel image to the format you need.

You can now boot the target with the new image. See �Booting the Target with aCustom Kernel� on page 52.

72 MontaVista� Linux® Professional Edition

Page 81: Monta Vista Users Guide

Chapter 5: Target Configuration Tool (TCT)The targetpkg Utility

The targetpkg Utility

Included with TCT is a command-line utility called targetpkg. This utility allowsyou to list the TCT groups with the packages and Þles in the groups. To usetargetpkg, you need to update your executable search path to include the Proapplications. Instructions on how to run Pro applications can be found in �RunningPro Applications and Tools� on page 40.

Usage Use of the targetpkg utility is described below.

targetpkg [-f] <architecture>_<processor>

targetpkg accepts the following option:

� -fList all Þles. By default, targetpkg only lists the packages.

Examples If you want to see all of the packages listed in TCT for a PowerPC 8xx target, youwould use the command:

targetpkg ppc_8xx

You would see output similar to the following:

admin adduseradmin anacronweb apachedevel apache-devdoc apache-html_manual...

In the example above, the Þrst column is the TCT group and the second column is thepackage.

If you want to see all of the packages and Þles listed in TCT for a PowerPC 8xxtarget, you would use:

targetpkg -f ppc_8xx

You would see output similar to the following:

admin adduser/base /etc/adduser.confadmin adduser/base /etc/deluser.confadmin adduser/base /usr/lib/perl5/AdduserCommon.pmadmin adduser/base /usr/sbin/adduseradmin adduser/base /usr/sbin/deluser...

In the example above, the Þrst column is the TCT group, the second column is thepackage, and the third column is the Þle.

MontaVista� Linux® Professional Edition 73

Page 82: Monta Vista Users Guide
Page 83: Monta Vista Users Guide

Chapter 6: Linux Kernel Development

OverviewThe kernel binary is at the core of every MontaVista Linux execution. It handlesscheduling, resource allocation, and use of programs. Pro provides you with twokernels: an LSP-speciÞc kernel and a generic kernel.

The LSP kernel (with MontaVista Software patches) is built speciÞcally for thesupported reference boards. MontaVista recommends that you use the LSP kernel forall development. The sources for this kernel are installed automatically when youinstall Pro and can be found in: /opt/hardhat/devkit/lsp/<target>/linux-<version-number>

The generic kernel (with MontaVista patches) can be used for building your own LSP.Installing the sources for this kernel is optional.The generic kernel sources are in thedirectory: /opt/hardhat/devkit/kernel/linux-<version-number>

Kernel development activities covered in this chapter include:

� �Building and ConÞguring the Kernel� on page 76

� �Enabling Loadable Kernel Modules� on page 80

� �Enabling Real-Time Performance Enhancements� on page 81

� �Enabling Standard Devices� on page 84

� �Building Custom Device Drivers� on page 88

� �Enabling File Systems� on page 103

� �Debugging the Kernel� on page 104

MontaVista� Linux® Professional Edition 75

Page 84: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding and Configuring the Kernel

Building and ConÞguring the Kernel

Build the Kernel With TCT

Included with the Pro is MontaVista Target ConÞguration Tool (TCT). TCT is a GUI-based tool that provides you with the ability to easily choose kernel options and selecttarget Þle system packages. You can also use TCT to manage kernel builds and tocontrol options such as whether target binaries are stripped. In addition, TCT supportsmultiple conÞgurations for a single target environment.

For more information about how to use this tool, see �Target ConÞguration Tool(TCT)� on page 57.

Warning! Changes made to the kernel conÞguration using another tool such as makemenuconfig or by running make xconfig independent of TCT are NOT storedin your project�s TCT conÞguration Þle, and therefore will not be built in the kernel.

Build the Kernel Without TCT

If you don�t want to use TCT, or if make xconfig cannot be used with your LSP,you need to build the kernel on your own. To build the kernel, complete the followingsteps:

1. Copy everything in the appropriate linux directory in the kernelsource tree to the directory where you wish to build the new kernel. Usethe command:

cp -a /opt/hardhat/devkit/lsp/<target>/linux-<version-number> /<build-directory>/

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

Note: Building the kernel in the /opt/hardhat/devkit/directory structure will cause problems when removing or upgradingPro. For that reason, we strongly recommend that you copy everythingto a build directory, such as mykernel. For example:

cp -a /opt/hardhat/devkit/lsp/<target>/linux-<version-number> /mykernel/

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

2. Change to the directory containing your copy of the kernel. Forexample:

cd /mykernel/

3. ConÞgure the kernel. Use one of the following commands:

make oldconfig

Recommended for initial installation; uses default conÞguration.

make config

Use this command to manually conÞgure all options.

76 MontaVista� Linux® Professional Edition

Page 85: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding and Configuring the Kernel

make menuconfig

Use this command to select conÞguration options from hierarchicalgroups. To enable an option using make menuconfig, place anasterisk (*) in the brackets in front of the option. For example:

[*] VESA Framebuffer

Note: If you are using a board that requires the selection of two CPUoptions, make menuconfig will not correctly conÞgure the kernel.

make xconfig

This is a mouse-driven conÞguration tool. To enable an option, click thecheck box for �yes� next to the option you wish to enable.

Note: To run any of the Pro tools, you need to update your executablesearch path to include the Pro applications and tools. Instructions onhow to run Pro tools, can be found in �Running Pro Applications andTools� on page 40.

Note: While many features are available for conÞguration, only featuresspeciÞcally stated on the MontaVista Zone page for your target aresupported.

Note: If you intend to use loadable kernel modules, you must ensurethat Loadable module support is enabled in your conÞguration. Formore information about kernel modules, see �Enabling Loadable KernelModules� on page 80.

4. Remove old kernel images, dependency Þles, or other old Þles that maydisrupt a kernel build. Use the command:

make clean

5. Set up all of the dependencies. Use the command:

make dep

6. Create a kernel image. Use one of the following commands:

make zImage

Creates a zipped image. (Typically, you will use this command.)

make bzImage

Creates a b2z zipped image.

make vmlinux

Creates a non-compressed image.

7. Convert the kernel image to a format that can be used by your target�sÞrmware. If your CPU or board Þrmware can use a binary image, youdo not need to do anything.

MontaVista� Linux® Professional Edition 77

Page 86: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding and Configuring the Kernel

If your CPU or board Þrmware requires a Motorola S-Records image,create a bootable image by using the objcopy command to copy thenew kernel image to the appropriate location for your target to replacethe default kernel image.

For example, if you were to use a PowerPC 8xx target, you would usethe command:

ppc_8xx-objcopy -O srec vmlinux vmlinux.srec

For example, if you were to use a MIPS ßoating point little-endiantarget, you would use the command:

mips_fp_le-objcopy -O srec vmlinux vmlinux.srec

For example, if you were to use an ARM Integrator 920T or 720T little-endian target, you would use the command:

arm_920t_le-objcopy -S -O srec -R .stack arch/arm/boot/compressed/vmlinux vmlinuz.srec

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

or

arm_720t_le-objcopy -S -O srec -R .stack arch/arm/boot/compressed/vmlinux vmlinuz.srec

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

8. If you conÞgured any of the parts of the kernel as a module and enabledLoadable module support in step 3, you need to compile the modules.Use the commands:

make modules

make modules_install

Note: Loadable module are located in /lib/modules. This step isrequired if you enabled or disabled any modules. If you do notrecompile the modules, you will receive �unresolved symbols� errorsduring or after kernel boot.

9. Boot the target. For instructions on how to boot the target with your newkernel, see �Booting the Target with a Custom Kernel� on page 52.

For more information about conÞguring and building the kernel, see the README Þleand the Þles in the Documentation subdirectory in the kernel source directory.

Warning! Changes made to the kernel conÞguration using tools such as makemenuconfig or by running make xconfig independent of TCT are NOT storedin your TCT project�s conÞguration Þle, and therefore will not be built in the kernel

78 MontaVista� Linux® Professional Edition

Page 87: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding and Configuring the Kernel

created by TCT. If you did not use TCT for your kernel development but did use TCTfor your Þle-system development, ignore the kernel generated by TCT.

MontaVista� Linux® Professional Edition 79

Page 88: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Loadable Kernel Modules

Enabling Loadable Kernel Modules

Rather than having all device drivers built into the kernel, the Linux kernel supportsloadable modules � that is, modules that can be inserted or removed from memory atruntime. The advantage of loadable kernel modules is that you do not need to rebuildthe kernel to test or enable a new device.

When building your own custom device driver, we recommend that you Þrst write andtest your device driver as a loadable kernel module (see �Building Custom DeviceDrivers� on page 88). For that to work, you need to ensure that support for loadablemodules has been enabled in the kernel.

Loadable kernel modules is on by default in most LSPs. To enable loadable kernelmodules, complete the following steps:

1. Start make menuconfig or make xconfig. The latter can be runon its own or through TCT.

2. Select Loadable module support.

3. Enable Enable Loadable Module support.

4. Save your changes.

5. Rebuild the kernel using TCT, or the procedure in �Building andConÞguring the Kernel� on page 76.

You can now use insmod and rmmod commands to load and unload kernel modules.For more information about insmod and rmmod, see the man pages for thoseapplications.

80 MontaVista� Linux® Professional Edition

Page 89: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Real-Time Performance Enhancements

Enabling Real-Time Performance Enhancements

For many embedded-system developers, real-time performance is a top requirement.To address this requirement, MontaVista Software has invested signiÞcant effort inimproving the real-time performance characteristics of the Linux kernel. Thisapproach to real-time Linux doesn't alter the APIs of the programming model. Byleveraging the inherent capabilities of the kernel, changes required of applicationsthat utilize these real-time performance improvements are minimized.

MontaVista Software engineering efforts into benchmarking and improving the real-time performance of the Linux kernel have resulted in the following improvements tothe kernel:

� �MontaVista Real-Time Scheduler� on page 81

� �Preemptible Kernel� on page 82

MontaVista Real-Time Scheduler

The MontaVista Real-Time Scheduler (RTS) is a supplemental scheduler for theLinux kernel that takes scheduling custody of real-time processes. The MontaVistaReal-Time Scheduler separates the ready real-time tasks into priority lists(MAX_PRI), allowing for very fast insertion. It also allows for very fast, ßat dispatchtimes of real-time tasks. Non-real-time (SCHED_OTHER) tasks are handled in afashion similar to the standard scheduler; however, the management of the time slicecalculation is modiÞed to be much faster while having the same end result.

Support

The scheduler is available on all supported architectures; including SymmetricMultiprocessing (SMP) Systems. Check the MontaVista Zone page for your target forinformation about support for this feature on your target.

Enabling the MontaVista Real-Time Scheduler

The MontaVista LSPs include the Real-Time Scheduler, however it is not enabled bydefault. To enable the MontaVista Real-Time Scheduler, complete the followingsteps:

1. Start make menuconfig or make xconfig. The latter can be runon its own or through TCT.

2. Depending on the target architecture, select Processor type andfeatures or Platform support.

3. Enable Real Time Scheduler.

4. Enter a value for the Maximum Priority? option. This option allowsyou to specify the number of priorities available to real-time tasks.Priorities 1 through the value of the Maximum Priority option are real-

MontaVista� Linux® Professional Edition 81

Page 90: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Real-Time Performance Enhancements

time tasks. The available range for Maximum Priority is 99 to 2047.Values smaller than 99 are changed to 99 and values greater than 2047are changed to 2047. The default is set to 127, and in most cases, this iswhat you would use.

5. Save your changes.

6. Rebuild the kernel, using TCT or the procedure in �Building andConÞguring the Kernel� on page 76.

The MontaVista Real-Time scheduler is now enabled.

Warning: The MontaVista Real-Time Scheduler does not honor theallowed_cpus member of the task_struct; thus, it will not honor any attemptto deÞne CPU afÞnity. At this time, the only known use of allowed CPUs is in TUX �a kernel-resident Web server for Linux � where ignoring this option may causeperformance degradation.

Additional information

The MontaVista Real-Time Scheduler is an open-source project and it is hosted at:

� http://rtsched.sourceforge.net/

Preemptible Kernel

The Preemptible Kernel (CONFIG_PREEMPT) option reduces the latency of thekernel when reacting to real-time or interactive events by allowing a low-priorityprocess to be preempted, even if it is in kernel mode executing a system call. Thisfeature allows applications that need real-time response � such as audio and othermultimedia applications � to run more reliably, even when the system is under anincreased load due to other lower-priority processes.

Features

The new preemption model allows the kernel to be preempted any time it is notlocked, which is very different from the model where preemption is actively requestedby the currently executing code. Using the new model, when an event occurs causinga higher priority task to be executable, the system will preempt the current task andrun the higher priority task. In the following instances, preemption should not occur,and the Preemptible Kernel option does not allow it:

� while handling interrupts

� while doing �bottom half� processing -- bottom half processing iswork that an interrupt routine needs to do, but that can be done at amore relaxed pace

� while holding a spinlock, writelock, or readlock

82 MontaVista� Linux® Professional Edition

Page 91: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Real-Time Performance Enhancements

These locks exist in the kernel to protect it from other processors inSymmetric Multiprocessing (SMP) Systems. While these locks areheld, the kernel is not preemptible for re-entrancy or data protectionreasons (just as in the SMP case).

� while the kernel is executing the scheduler itself -- the scheduler ischarged with executing the �best� task, and if it is engaged inmaking that decision, it should not be confused by asking it to giveup the processor

At all other times, the MontaVista algorithm allows preemption. Also, whenever thesystem exits from one of the above states, it tests to see if preemption is called for. Ifso, the current task is preempted.

Support

Check the MontaVista Zone page for your target for information about support forthis feature on your target.

Enabling the MontaVista Preemptible Kernel

To enable the MontaVista Preemptible Kernel, complete the following steps:

1. Start make menuconfig or make xconfig. make The latter canbe run on its own or through TCT.

2. Select General setup.

3. Enable Preemptible kernel support.

4. Enable Break selected locks.

5. Rebuild the kernel using TCT, or the procedure in �Building andConÞguring the Kernel� on page 76.

The MontaVista Preemptible Kernel is now enabled.

Limitations When used in conjunction with Symmetric Multiprocessing (SMP) Systems support,this feature is currently experimental.

At this time, using the preemptible kernel patch on ARM architecture targets isexperimental.

MontaVista� Linux® Professional Edition 83

Page 92: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Standard Devices

Enabling Standard DevicesPro provides drivers to enable a variety of devices. For a list of the available drivers,see the Þle:

/opt/hardhat/devkit/<architecture>/<processor>/kernel/linux-<version-number>/linux/Documentation/devices.txt.

The Þle above contains a list of devices and device numbers. While these drivers areavailable for you to use, MontaVista Software does NOT support all listed drivers.Only features speciÞcally stated on the MontaVista Zone page for your target aresupported.

The sections below describe how to enable some of the more standard features.

Framebuffer Support

Framebuffer provides bitmap graphics for running a windowing system.

Support

Check the MontaVista Zone page for your target for information about support forthis feature on your target.

Enabling framebuffer support

To enable framebuffer support, complete the following steps:

1. Edit the makefile under kernel/ in your project directory to set theSVGA_MODE variable. To set the SVGA_MODE variable, change theSVGA_MODE variable setting from NORMAL to what is appropriate foryour setup. Read /opt/hardhat/devkit/lsp/<target>/linux-<version-number>/Documentation/fb/vesafb.txt to determine the value you should use. For example, toset the SVGA_MODE variable for 640x480 resolution at 256 colors, usethe following line in your makefile:

export SVGA_MODE= -DSVGA_MODE=0x301

2. Start make menuconfig or make xconfig. The latter can berun on its own or through TCT.

3. Select Console drivers.

4. Select Framebuffer Drivers.

5. Make sure VESA Framebuffer is enabled.

6. Save your changes.

84 MontaVista� Linux® Professional Edition

Page 93: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Standard Devices

7. Rebuild the kernel, using TCT or the procedure in �Building andConÞguring the Kernel� on page 76.

Framebuffer support is now enabled.

Videocard Support Support

Check the MontaVista Zone page for your target for information about support forthis feature on your target.

Enabling videocard support

To enable videocard support, complete the following steps:

1. Start make menuconfig or make xconfig. The latter can be runon its own or through TCT.

2. Select Console drivers.

3. Select Framebuffer support.

4. Enable the videocard you are using, such as a Media Q 200.

5. Enable the following:

� Advanced low level driver options

� 4 bpp packed pixels support

� 8 bpp packed pixels support

� 16 bpp packed pixels support

6. Return to the main menu.

7. Select Character devices.

8. Enable Support for console on virtual terminal.

9. Save your changes.

10. Rebuild the kernel, using TCT or the procedure in �Building andConÞguring the Kernel� on page 76.

To verify that videocard support has been enabled, load and boot the new kernel onthe target. If you see a penguin in the upper left-hand corner of your target screen, youhave succeeded.

MontaVista� Linux® Professional Edition 85

Page 94: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Standard Devices

PS/2 Keyboard and Mouse Support

Support

Check the MontaVista Zone page for your target for information about support forthis feature on your target.

Enabling PS/2 keyboard and mouse support

To enable PS/2 keyboard and mouse support, complete the following steps:

1. Start make menuconfig or make xconfig. The latter can be runon its own or through TCT.

2. Select Character devices.

3. Select Mice.

4. Enable the following options:

� Mouse Support (not serial and bus mice)

� PS/2 mouse (aka �auxiliary device�) support

5. Save your changes.

6. Rebuild the kernel, using TCT or the procedure in �Building andConÞguring the Kernel� on page 76.

7. On the target, ensure that you have a psaux device. Use the followingcommand to list the devices:

ls /dev/psaux

If you do not have a psaux device, use the following command tocreate one:

mknod /dev/psaux c 10 1

For more information about creating standard device nodes, see �Create StandardDevice Nodes� on page 158.

8. Start the gpm daemon. Use the following command:

gpm -t ps2 -m /dev/psaux

Note: Startup/kill scripts can be used in place of the gpm daemon.Samples are on the following page.

PS2 keyboard and mouse support is now enabled.

For information about USB mouse support, see MontaVista Zone.

86 MontaVista� Linux® Professional Edition

Page 95: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling Standard Devices

Sample Startup/Kill Scripts. Startup and kill scripts can be used rather than the gpmdaemon. For startup/kill scripts you need to create the following Þles: /etc/gpm.conf, a startup script ( /etc/rc.d/rc1.d/S85gpm) and a kill script(/etc/rc.d/rc1.d/K85gpm). Sample scripts are provided below:

Sample /etc/gpm.conf

type=ps2device=/dev/psaux

Sample startup and kill scripts

#!/bin/sh## Start Mouse event server# chkconfig: 2345 20 20#PATH=/bin:/usr/bin:/sbin:/usr/sbin

PIDFILE=/var/run/gpm.pidGPM=/usr/sbin/gpmCFG=/etc/gpm.conf

test -x $GPM || exit 0if [ "$(id -u)" != "0" ]then echo "You must be root to start, stop or restart gpm." exit 1ficmdln=if [ -f $CFG ]; then . $CFG if [ -n "$device" ]; then cmdln="$cmdln -m $device"; fi if [ -n "$type" ]; then cmdln="$cmdln -t $type"; fi if [ -n "$responsiveness" ]; then cmdln="$cmdln -r $responsiveness";fi if [ -n "$sample_rate" ]; then cmdln="$cmdln -s $sample_rate"; fi if [ -n "$repeat_type" ]; then cmdln="$cmdln -R$repeat_type"; fi # Yes, this /IS/ correct! There is no space after -R!!!!!! # I reserve the right to throw manpages at anyone who disagrees. if [ -n "$append" ]; then cmdln="$cmdln $append"; fifigpm_start () { echo -n "Starting mouse interface server: gpm" start-stop-daemon --start --quiet --exec $GPM -- $cmdln echo "." return 0}gpm_stop () { echo -n "Stopping mouse interface server: gpm" /usr/sbin/gpm -k echo "."}case "$1" in start) gpm_start ;; stop) gpm_stop ;; force-reload|restart) gpm_stop sleep 3 gpm_start ;; *) echo "Usage: /etc/init.d/gpm {start|stop|restart|force-reload}" exit 1esacexit 0

MontaVista� Linux® Professional Edition 87

Page 96: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

Building Custom Device DriversWhile there are hundreds of drivers available for Linux, you may Þnd that the exactdriver you need does not exist for your device. In this case, you need to either writeyour own driver or simply modify a similar driver.

Whether you are writing a new driver or modifying an existing driver, you shouldwrite and test your driver in an incremental fashion. By working in increments, youcan easily track your progress and isolate bugs. A test program, developed in lock-step with the coding of the driver, can be used to test each piece as you progress.

We also recommend that you write and test the driver as a module. In the sampledriver outlined in this section, the Þrst steps to developing the driver are to write andtest install and remove scripts and to write and test the driver�s kernel module�carrier.� Being able to quickly unload and load the driver module makes it mucheasier to test each section of driver code as you write it. While it is easiest to write andtest a device driver as a loadable kernel module, it is not necessary for the device to bea loadable module. Once you are conÞdent the driver works, you can compile thedriver as you desire � as a loadable module or as part of the kernel.

When writing your device driver, it is important to note that while many of theparticulars for building a device driver are dependent on the device, Linux devicedrivers have many common features. There are hundreds of examples available in/opt/hardhat/devkit/lsp/<lsp-name>/linux-<version-number>/drivers. It is advisable to review the code in these examples, and,when applicable, to simply copy and paste the code needed into your driver.

This section contains details on the steps above. The sections included are:

� �Load and Unload the Driver (Kernel Module)� on page 89

� �Code the Kernel Portions of the Driver� on page 90

� �Initial Coding of the Driver� on page 91

� �Additional Information� on page 102

Note: The driver sketched out here is not a PCI-device driver. However, almosteverything shown in the example driver is required in a PCI-device driver as well.

88 MontaVista� Linux® Professional Edition

Page 97: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

Load and Unload the Driver (Kernel Module)

Below is a brief example of the operations needed to load a device driver (written as akernel module), create the /dev node, and launch a test program. The test programshould be written as you write your driver to test each new piece of functionality. Yourkernel must have loadable kernel module support enabled. See �Enabling LoadableKernel Modules� on page 80 for more information.

Refer to the appropriate man and info pages for details on each of these operations.

First, the mknod command creates a character (c) device entry in the /dev Þlesystem. The driver will use major device 120, one of the numbers reserved forexperimental use. The minor device number, 0 in the above example, will be passed tothe driver each time the driver is used, and has no meaning other than what the drivermakes of it.

Note: If the driver (kernel module) is going to allow Linux to assign the major devicenumber, insmod must be executed before mknod, and some additional shellprogramming will be needed to extract the answer from /proc/devices beforemknod can be executed. (Finally, it is possible to do the mknod(2) operation in thedriver itself.)

Next, assuming the driver (kernel module) has been compiled as mydriver.o, theinsmod command inserts (loads) the driver into the running system. Within thedriver (kernel module), a special �initialize the module� function will be executed.This entry point is identiÞed in the driver's source code with the module_init()wrapper.

Finally, a test program named test_driver is executed. Residing in the currentdirectory � hence the �./� preÞx � this program tests the driver by issuing typical I/Ocalls and checking the results. The test program should also test boundary conditionsas well as verify the error-checking in the driver itself. For example, device driversmust validate user-space addresses. Failure to do so could result in a system panic.The test program should, therefore, attempt some operations using invalid addressesand verify that the driver returns the proper error status. It is not uncommon for a testprogram to be several times larger than the driver being tested.

Sample load module and test program script

#!/bin/sh# Insert mydriver and run the test program#mknod /dev/mydriver c 120 0insmod mydriver.o./test_mydriver

MontaVista� Linux® Professional Edition 89

Page 98: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

When a problem is detected in the driver source code, the driver must be removedfrom the system, the error must be corrected, and the driver must then be recompiledand reloaded. For consistent results, a removal script, such as the following, should beused:

First, the removal script undoes the insertion. Note that the driver's name no longercarries the �.o� Þlename extension. This is common.

Next, a �-f� option is used with the rm command to forcibly remove the /dev entry.

On rare occasions, a problem in the driver causes the system to panic and a reboot willbe needed. In those cases, the removal script will not have been executed. Run it Þrst(and ignore the error from the rmmod command). Alternatively, when the driver isready to be tested again, expect an error message when the mknod command isexecuted because the /dev/mydriver node is still present from the previous life ofthe system.

Code the Kernel Portions of the Driver

While writing and testing the driver, the kernel module provides a carrier for loadingand unloading the device driver. As such, the kernel module should be written anddebugged Þrst. Once it can be inserted and removed at will, coding of the driver canbegin. For this to work, your kernel must have loadable kernel module supportenabled. See �Enabling Loadable Kernel Modules� on page 80 for more information.

Note: While it is easiest to write and test a device driver as a loadable kernel module,it is not necessary for the device to be a loadable module. Once you are conÞdent thedriver works, you can compile the driver as you desire � as a loadable module or aspart of the kernel.

Below is a very simple kernel module example:

Sample remove module script

#!/bin/sh# Remove mydriver#rmmod mydriverrm -f /dev/mydriver

Sample kernel module

#include <linux/module.h>#include <linux/init.h>#include <linux/kernel.h>

static int __initinit_myself(void) { printk("myself is loaded\n"); return 0;}

static void __exitremove_myself(void) { printk("myself is being removed now\n");}

module_init(init_myself);module_exit(remove_myself);

90 MontaVista� Linux® Professional Edition

Page 99: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

The three #include statements are all required. The linux/init.h header Þlecontains, among other things, the deÞnitions for the __init and __exit keywords.For a kernel module, they have little practical effect. However, if the driver is laterbuilt in with the kernel image, that will help minimize the overall size of the system.

To compile the driver (kernel module), use a command such as the following:

ppc_8xx-gcc -c -DMODULE -D__KERNEL__ -D_REENTRANT -Wall -O mydriver.c

In this example, ppc_8xx-gcc is the name of the cross-compiler. For moreinformation about running the cross-compiler for your target, see �Running ProApplications and Tools� on page 40. The following describes the other options used:

� The -c option tells the compiler to generate the object Þle frommydriver.c, but to proceed no farther.

� The -DMODULE option is needed when compiling a kernel moduleSome compilers do not, by default, generate reentrant code. Fordevice drivers, this is a necessity.

Note: If you are compiling your driver as part of the kernel ratherthan as a module, you would use the -DKERNEL option in place ofthe -DMODULE option.

� The -I <path-to-kernel>/include instructs the compilerto use the kernel include Þles (rather than user-space Þles.) Replace<path-to-kernel> with the proper path where the kernelsource code used to build the kernel image used on the target board.

� The -nostdinc option ensures that the compiler does not pick upany user-space paths.

� The -Wall option instructs the compiler to issue all relevantwarnings. Tracking down the source of these and carefullyimplementing the proper correction is very important whenworking in the kernel, much more so than in user-space programs.

� The -O option turns on compiler optimizations. For user-spaceprograms, this is a good idea. For code that will execute in thekernel, however, it is required.

At this point, the kernel module should be compiled and the load and unload scriptstested.

Note: The output from the printk() statements appear only on the /dev/console device. If you are connected to the target through some other mechanism,the dmesg program can be used to see the entire console log.

Initial Coding of the Driver

Character device drivers typically have at least eight (8) primary functions. These are:

� initialize the driver

MontaVista� Linux® Professional Edition 91

Page 100: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

� uninitialize (remove) the driver

� open a device

� release a device

� write to a device

� read from a device

� handle an interrupt

� post process an interrupt

Generally speaking, this is also the sequence in which the driver might be written andtested.

Incidentally, you may have noticed that write is listed before read. This is intentional:coding and testing the write routine may be easier in many drivers than thecorresponding read routine. Once write is Þnished, it can often be copied and pastedinto the read routine and, after some minor changes, read will also be Þnished.

Initialize the driver and uninitialize (remove) the driver

These two functions are opposites. What one does, the other must undo.

The initialize routine has only one thing it must do: register_chrdev(). Thissystem operation registers the fact that a new driver is present in the system, whichshould be done when the driver (kernel module) is loaded. The driver's initializationroutine should, therefore, be called by the kernel module's initialization routine(init_myself() in the example on page 89).

To code the register_chrdev() request, Linux sources must be consulted. Thisparticular operation is used in practically every driver in Linux. There are hundreds ofexamples beneath the drivers directory. Look for a directory named drivers in/opt/hardhat/devkit/lsp/<lsp-name>/linux-<version-number>/drivers. For example:

find /opt/hardhat/devkit/lsp/ibm-walnut/linux-<version-numner>/drivers -name drivers -print

From the results, pick a directory and grep for the �register_chrdev� string.

There are two basic ways of using register_chrdev(): assigning a majordevice number, or letting Linux assign one. The Þrst argument inregister_chrdev() may contain either a non-zero number, or zero. A non-zeronumber tells Linux what major device number to use. Linux will return success (0) orfailure (non-zero).

Conversely, coding a zero as the Þrst argument to register_chrdev() asksLinux to automatically assign an unused major device number to the driver. In that

92 MontaVista� Linux® Professional Edition

Page 101: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

case a return value of non-zero means success and the returned value is the assignedmajor device number. Should Linux return a zero, however, there are no major devicenumbers available, and the register_chrdev() operation has failed.

The second argument to register_chrdev() is the driver's name. Although itcould be anything, for consistency, it is a good idea to make this name the same as thename used in the /dev Þle system.

The Þnal argument is the name of a structure containing pointers to the driver entrypoints. Some ordering of functions and deÞnitions in the source Þle may be helpful.For example, the driver initialization routine refers to this structure, so the structuredeÞnition should be positioned in the source Þle ahead of the initialization routine.Similarly, the driver entry points themselves will be mentioned in the structure so theywill, in turn, be positioned ahead of the structure deÞnition in the source Þle.

The register_chrdev() call is the only required function in the driverinitialization routine, and, conversely, the unregister_chrdev() call is the onlyfunction required to be in the driver remove routine.

There are other system operations commonly found in the initialization code ofdevice drivers. These are ioremap(), tasklet_init() and, quite often, theoperations needed to reset the hardware device being controlled.

ioremap() programs the processor's address translation unit (or discovers thepreviously programmed address) for the hardware device the driver is controlling. Forportability, it is important to recognize that the return from ioremap() is an �I/OSpace Address,� which is not necessarily accessible by a direct memory reference.Special functions are provided for all I/O space address references. Drivers thatdereference these pointers directly will not be portable and may also suffer byte-orderproblems.

tasklet_init() initializes the structure used to trigger a tasklet which, in mostdrivers, is used for the post-processing of an interrupt. (Earlier Linux implementationsprovided �tasks,� or, earlier still, �bottom halves.� Although bottom halves still exist,they should be avoided. �Tasks� were renamed �tasklets� and, at the same time,something called a �soft IRQ� was added. New device drivers should avoid bottom-halves and soft IRQs and should use tasklets.)

For both ioremap() and tasklet_init(), refer to examples in the Linuxdriver source Þles.

Finally, if an ioremap() is coded in the driver initialization routine, aniounmap() should probably be written into the remove routine. There is nocounterpart to tasklet_init().

Testing the initialization and remove routines. With the initialization and remove routines coded, this is a good point to test thedriver again. When the driver (kernel module) is loaded, the register_chrdev()call should cause the driver name and major device number to appear in the /proc/devices entry. To view the entries in /proc/devices, use the command:

cat /proc/devices

MontaVista� Linux® Professional Edition 93

Page 102: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

The above command displays the current registry of major device numbers and namesknown to Linux. If run after loading the driver, by Þnding the driver's name in theoutput from this command, the assigned major device number can be determined.

Conversely, when the driver (kernel module) is removed, the driver's entry in/proc/devices should disappear.

Open and Release

From here on, answers in this description will be less speciÞc, because of the numberof different types of devices, and the different ways in which they may be installedand used with Linux. Therefore, it may be useful to examine several drivers andcompare the approaches implemented in them with the suggestions herein.

The Open routine in a device driver often associates an external hardware interruptwith a piece of code in the driver, the ISR or Interrupt Service Routine. Therequest_irq() function provides this service. Before it can be used, however, thedriver must determine which IRQ (Interrupt ReQest number) it should use.Depending on the hardware design and the device's capabilities, there are severaltechniques to choose from.

First, the device may simply be hard-wired with a particular IRQ number. This isoften true of on-board devices that are soldered in place. For these devices, thehardware designer may have made the selection of IRQ number and documented theanswer in the hardware reference materials.

If the device is PCI-based, however, the device will have been programmed in the PCIsubsystem or possibly earlier, in BIOS if present, or in a comparable part of thesystem�s initialization code. For PCI-based devices, the PCI subsystem will know theIRQ number. Again, refer to the Linux sources for the most reliable answer. Locate adevice driver containing both a call to request_irq() and also a call to, forexample, pci_enable_device().

Another technique is probing for an IRQ number. The kernel routinesprobe_irq_on() and probe_irq_off() are used, in sequence, to determinewhat IRQ number a particular device is using. In between those two operations, thedevice driver is expected to do something to the device to provoke an interrupt. Linuxmonitors the unused IRQ lines and returns the IRQ number whenprobe_irq_off() is called. Although useful in some environments, probing mayexhibit some undesirable behavior in some systems. It should, therefore, be avoided ifpossible.

Note: Examination of the sources for Linux drivers will reveal a dozen or moreadditional techniques. Choose one appropriate for the hardware you are using.

The IRQ number is the Þrst argument to request_irq(). The second argument isthe name of the function to be executed in the interrupt context. This is the driver'sISR.

Note: It is important to note, throughout the driver, the context of execution of aparticular function. Interrupt Service Routines execute in the interrupt context. Most

94 MontaVista� Linux® Professional Edition

Page 103: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

other portions of a driver, however, execute in a process (some would say �thread�)context. Additionally, tasklets (and bottom halves and Soft IRQs) should beconsidered a third type of context. Of these, the portions of a driver that execute in theprocess context can be interrupted by tasklets and interrupts, tasklets themselves canbe interrupted by interrupts, and in some cases, interrupts can even be interrupted byother interrupts. This is what the -D_REENTRANT ßag is for when compiling adriver. And, this is what things like kernel MUTEXes, spin locks and interruptmasking are designed to help a driver handle. If these are new concepts, a careful andthorough study of these topics is recommended and, unfortunately, is much more thancan be dealt with here.

The third argument to request_irq() is a group of ßags that may be OR'dtogether. These include whether or not the driver is a �fast� or �slow� interrupthandler, is willing to share the IRQ with other drivers, and whether or not interruptsfrom the device tend to occur at random times. The relevant ßags areSA_INTERRUPT (a �Fast� handler), SA_SHIRQ (the driver will �share� the IRQline), and SA_SAMPLE_RANDOM (interrupts occur at random times). The converse ofeach ßag is 0 (there is no deÞned symbol).

Generally speaking, most interrupt handlers should be of the �slow� and �share�variety. These would be the most communally responsible choices. Depending on thecapabilities of the hardware, �slow� interrupt handlers execute with interrupts otherthan their own re-enabled. This allows for the nesting of other (often �higherpriority�) interrupts. Drivers that can �share� IRQs with other drivers lead to a moreßexible design, one that gives system designers more options.

The request_irq() call also needs to know the name of the interrupt source.Again, the name of the driver used in the /dev Þle system is the most probablechoice. The name used with request_irq() will be displayed through the/proc/interrupts interface that shows how many interrupts have occurred ateach IRQ number.

And the Þnal argument to request_irq() is any value of use to the driver. Thisvalue will be passed to the driver's interrupt service routine whenever an interruptoccurs. It is often used to pass a pointer to some driver control structure needed atinterrupt time.

The Þnal item needed in the driver's open routine is the MOD_INC_USE_COUNTmacro. This increments a counter and is used to determine when a module may beunloaded.

A corresponding MOD_DEC_USE_COUNT should, therefore, appear in the releaseroutine, which should also include a free_irq() call to release the IRQ number. Itmay also be a good idea to disable the device or otherwise prevent it from generatinginterrupts in the future.

With the open and release handlers coded and compiled, the test program can beenhanced to test the new entry points. In the test program, open(�/dev/mydriver�,...) will return a Þle descriptor. Prior to that, however, the driverentry point will be executed. The driver must, therefore, return success (0) ifeverything is working. On the other hand, if the request_irq() or other operation

MontaVista� Linux® Professional Edition 95

Page 104: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

fails, the driver�s open routine should return an appropriate error number. Examinevarious driver sources and note the methods used. They are relatively straightforwardand common across many drivers.

At this point, all the test program can do is open() and close() the driver. Butthese should cause the driver's corresponding entry points to execute. If desired, a fewprintk()s could be placed throughout these routines in the driver to verifyoperation.

Write to a device

The write and read portions of the driver will be handled and tested separately, andthey should probably be coded and debugged in that order: write before read. This issimply because it is easier to code a test program that makes up random data to bewritten to a device than it is to cause a device to make readable data available. Testingis easier if the write handler in a driver is completed Þrst.

When a user program asks for data to be written, it speciÞes the address of theexisting data and the number of bytes therein. The address the program speciÞes, andwhich is passed to the driver, is a user-space address. That area of memory, includingvarious portions or all of it, might not be resident in RAM at the time the I/O call isissued. The driver, therefore, must not attempt to touch the user-speciÞed datadirectly. A page fault might occur and, when unprotected as in the driver, an �oops�(kernel memory fault) would occur.

Instead, many drivers allocate a kernel-space buffer, via kmalloc(), for thispurpose. The buffer must be large enough to hold the maximum size write (or read) tobe handled by the driver. In many cases this means very large writes (and reads) willactually be handled by the driver in segmented fashion. The kmalloc() call will,most likely, be coded in the driver's open handler. In some cases, the driver'sinitialization routine may be selected for this operation. The difference between thesetwo depends on how many kernel-space buffers will be needed by the driver. Thedriver initialization routine is executed once. The open routine, on the other hand, isexecuted once for each minor device that is opened. Drivers supporting multipleminor devices and needing a kernel-space buffer for each such device may do thekmalloc() operation in the open routine, and the corresponding kfree() in therelease routine.

When a user program issues a write operation, the device driver's write handler mustcopy the data from user space to kernel space. The copy_from_user() functionprovides this operation, and does it in a manner that will properly handle page faults.That is, if the user-speciÞed address is associated with memory that is currently pagedout, the copy_from_user() function will initiate a page-in operation and put thecurrent operation to sleep until it completes. This means that the driver's write routinemay be put to sleep during the copy_from_user() operation.

Note: Sleeping is perfectly acceptable in a process (or thread) context. It is notallowed; however, in an interrupt or tasklet context. Since different portions of thedevice driver will execute in different contexts, it will be important to remember whatis and is not allowed in each part of the driver.

96 MontaVista� Linux® Professional Edition

Page 105: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

In addition to coping with page faults, copy_from_user() will also validate theuser-space addresses over the entire range of indicated addresses. If the user programspeciÞes an invalid address, or if the user-space buffer beginning address is valid butthe length extends into forbidden space, copy_from_user() will return a non-zero value to the driver. The driver is then obligated to return -EFAULT to the userprogram. This will probably result in a segment violation signal to the requestingprocess, typically a fatal event.

Arguments to copy_from_user() are straightforward: kernel-space destinationaddress, user-space source address, and number of bytes. Two of these values, user-space address and byte count, are passed directly to the driver via the write interface.

Depending on the requirements of the hardware, the data, now sitting in a kernel-space buffer, is then transferred to the I/O device. Sometimes this is a copy fromkernel-space to I/O-space, memcpy_toio(), or, in the case of a device that handlesonly a single byte, �word� (two bytes) or �longword� (four bytes) at a time,writeb(), writew(), and writel(). In cases where the device is capable offetching the contents of system memory, the appropriate memory address must beprogrammed into the device. Because devices are assumed to exist in I/O space whichmay be different from the processor's memory space, the kernel-space address mustbe translated to an I/O space address. This is done via the virt_to_bus() call.(The Linux kernel and device drivers all execute using virtual addresses. Physicaladdresses are rarely used in Linux.)

Once the device is prepared with the data or its address, one or more writeb(),writew() and/or writel() operations to the device are used to start the datatransfer. These calls access the system's I/O space: the pointers to the I/O deviceshould be the value returned by the ioremap() call in the driver's initializationroutine, or some offset.

If a delay occurs between starting the data transfer and when it completes, the processis typically put to sleep by having the driver callinterruptible_sleep_on(). Later, if an interrupt occurs at the end of the datatransfer, the driver's ISR or tasklet can issue the correspondingwake_up_interruptible() operation. When that occurs, the driver will re-awaken at the line of code immediately after the interruptible_sleep_on().

Some drivers provide one or two common variants; however, instead of waiting forthe operation to complete, some drivers may support O_NONBLOCK operation. Whenan application program requests an O_NONBLOCK operation, it is asking for thedriver to complete the transfer of data from user space immediately and to allow theprogram to continue running without possibility of sleep. In other words, the drivershould copy the data from user space, start the data transfer with the I/O device, butthen immediately return from the write routine. Later, when the I/O completioninterrupt occurs, the ISR (or tasklet) must be smart enough to know if it should not dothe wake_up_interruptible() call, since no one is sleeping. In addition, thedriver must also know that the device is busy. If an additional O_NONBLOCKoperation is requested while the device is busy, the -EBUSY status should bereturned. The -EBUSY status tells the application program that the non-blockingoperation was not possible.

MontaVista� Linux® Professional Edition 97

Page 106: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

The second alternative is the FASYNC operation. This is similar to O_NONBLOCKexcept that in the former case, the application program cannot know when the datatransfer to the external device has been completed. FASYNC operation, on the otherhand, asks the driver to send a signal to the process. Driver support of FASYNC isusually implemented by using the fasync_helper() function in the kernel.Examination of existing driver sources will show how this is done.

Interrupt handling and tasklet operation

The Þrst thing the driver's ISR (Interrupt Service Routine) must do is determine if itshardware device is causing an interrupt. Drivers for devices that �share� IRQ linesmay be called with a different device on the same IRQ line that is requesting aninterrupt. Therefore, drivers must check to see if their device is generating aninterrupt. If not, the ISR should simply return to Linux.

If the driver's device is causing an interrupt, then the question becomes, why? Andonce that is answered, the next question is, what should the ISR do about it?

The details are device-speciÞc, but, in general, the answer is to:

� collect whatever information in the device that may be lost if wewait too long

� defer as much work as possible into a tasklet probably by addingentries to a queue of work to be done (the kernel's list_headmanipulating routines may be particularly useful)

� use tasklet_schedule() to cause the tasklet to execute atsome later time

When should everything be done in the ISR and when should a tasklet be used aregood questions with no clear answers. It is probably safe to say that if deferring thework takes longer than doing it, then a tasklet is not warranted. On the other hand, ifthe work is complex and may involve a backlog or transactions, then a tasklet is agood design choice.

Assuming that the ISR defers work and schedules a tasklet, the tasklet should be run�real soon.� Tasklets run after all interrupts have been processed but before Linuxreturns to the execution of any process. Tasklets are, therefore, a third type of �thingsthat can execute code� and, in importance, they fall between hardware interrupts andprocesses.

The content of the ISR and tasklet, if any, depends on the I/O device and the type ofexecution (O_NONBLOCK, FASYNC, etc.) desired by the application program, and bythe designer. SufÞce it to say that these considerations and the discussion in thesection �Write to a device� on page 96 should indicate nearly all of the processing.

Meanwhile, back in the write routine. The last thing the driver's write routine needs to do is determine how many bytes weretransferred, and return that count.

98 MontaVista� Linux® Professional Edition

Page 107: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

With the driver write routine coded and ready to be tested, the test program must bemodiÞed. Here's where things start to get involved in the test program. There areseveral questions to be answered. First, what types of data are acceptable to thedevice? What lengths of data are allowed? Does the driver support O_NONBLOCKoperation? Does it support the FASYNC style of transfer? Of course, all the permittedcombinations must be tested.

Additionally, various combinations of illegal and nonsensical operations must also beattempted. In all cases, the value returned from the driver must be compared to see ifthe driver is giving the correct response. This is also the time to begin stressing thedriver to see if it continues to behave well under load.

Depending on the driver, the use of a kernel MUTEX may be required. These areinitialized with init_MUTEX() and then manipulated withdown_interruptible() and up(), and occasionally with plain down(). Akernel MUTEX is used in a driver to prevent multiple processes (or threads) fromusing critical portions of the driver at the same time. When one process successfullyexecutes the down_interruptible() operation, any subsequent processreaching that same point will be put to sleep until the Þrst process executes thecorresponding up() operation. Note that as before, ISRs and tasklets are not allowedto sleep. They must not, therefore, use the down_interruptible() operation.

Interruptible sleep follow-up. Anywhere in a driver where an interruptible sleep is being used, includingdown_interruptible() as well as interruptible_sleep_on() and itsvariants, special handling is needed immediately thereafter. These kernel operationsare �interruptible� in the sense that a signal could be sent to the process while it issleeping, and the signal will cause the process to re-awaken. The sleep is, therefore,�interruptible.� Look at several other drivers to see how sleep interrupts are handled.Typically there is a call to signal_pending() and, if true, a return of -EINTR or-ERESTARTSYS. The choice can be made by reading the descriptions of these twosignals and noting their precise meaning.

Also note that when a data transfer is initiated and the process is put to sleep, in mostdevices there will be an interrupt to let the driver know the I/O has been completed. Ifthe process has already been awakened as a result of a signal, the ISR (or tasklet)should not issue the wake_up_interruptible(). Many drivers ignore this caseas the �sleep queue� is presumed to be empty. Depending on the driver and theapplication, this behavior and its consequence should be carefully considered.

And Þnally, there is another potentially larger problem. If an application program asksa driver to transfer data to a device, and then a signal causes that application programto be terminated, should the driver Þnish transferring the data? And what about whena read operation is in progress?

In some cases, the answer is that the previously started data transfer must be aborted.Depending on the hardware device, this may be difÞcult. There is also the case wherethe data transfer completion and the signal both occur at essentially the same time.Which one should the driver honor? Can it do both? The answer to this question isdriver-speciÞc and application-speciÞc. You need to decide based on your driver andapplication needs.

MontaVista� Linux® Professional Edition 99

Page 108: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

Read from a device

At this point, the driver's write routine should be 100% functional. It should be fairlywell tested under normal, stress, and abusive conditions. It should handle bad pointersfrom users, deal with reentrancy issues using MUTEXes, and be fully coordinatedwith the driver's ISR and tasklet. As needed, it should handle normal, non-blockingand asynchronous writes.

To code the read routine, copy the core of the write routine and paste it into the readfunction. Once there, review the sequence of events and make any necessaryadjustments. For example, instead of copy_from_user(), the read routine usesthe copy_to_user() function. Since the data to be read won't be available untilnear the end of the read routine, the call should probably move to the end of the readhandler. In the case of a normal (sleeping) data transfer, the copy_to_user()function would belong shortly after the interruptible_sleep_on(). In thatcase, the device interrupt would essentially mean �the data is now ready in the kernelbuffer.�

Other details of the read handler in the device driver should be relatively obvious. Aswith all other routines, study of existing drivers may be very helpful.

As with the testing of the write routine, similar techniques should be added to the testprogram for the read routine. Other issues to be tested may involve the concurrency ofreads and writes to the same device at the same time. There is no absolute rule here. Itdepends on what your driver is supposed to be capable of supporting. With somehardware devices, only one read or one write can be performed at any instant. Thedriver should take this into account, therefore, and serialize use of the deviceaccordingly. But if the device supports reading and writing at the same time, thedriver read and write routines will be largely independent but the ISR and tasklet(s)will have to deal with varying order of completions: just because a write starts Þrstdoesn't mean it will end Þrst.

Disabling interrupts. Key portions of a device driver may be designated as �critical regions.� In particular,any sequence of instructions executed in a process context that manipulates datavariables or device control registers that might also be accessed or manipulated in theinterrupt or tasklet context should be considered a critical region.

The classic method of ensuring integrity of the data is to simply preclude a change ofcontext. This is most easily done by disabling (blocking) all hardware interrupts.

Use the save_flags(); cli(); sequence to Þrst save the current state of theinterrupt mask and then set it into the disabled state and, later, userestore_flags() to restore the former setting. Using this sequence is �safe� nomatter what the interrupt state is at the beginning. It will always set it back to thecorrect value.

Testing for reentrancy problems is difÞcult. Although it is theoretically possible to testa driver for all possible cases, in practice, the hardware is usually not available to tryall combinations. Instead, most drivers are subjected to long-running stress tests withrandomized data and timings. The hope is that, given enough time and enoughrandom variation, all the bugs will eventually be found.

100 MontaVista� Linux® Professional Edition

Page 109: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

For the test program, this means that all of the foregoing tests must be repeatedthousands and thousands of times, meticulously checking each and every operationfor proper behavior. Multi-threading in the test program is a common way ofachieving a high degree of parallelism but, if overdone, can drive the system so hardthat it ends up operating in a highly serialized fashion again. Testing of kernel code,including device drivers, is difÞcult.

SMP and preemptible kernel handling. Systems having SMP (Symmetric Multi-Processing) capabilities allow multipleapplication programs to execute in true concurrent fashion. In those systems, oneapplication program may call a device driver at exactly the same time as a differentapplication program on another processor calls the exact same driver. The previouslydescribed MUTEX will adequately handle this case, but what if one processor isinitiating a data transfer and, nanoseconds later, the device causes an interrupt and thehardware decides to allow a different processor handle the interrupt? In that case, thedriver's ISR and read/write handler will both be executing, literally at the exact sametime. If they both access a common data structure at the same time, the data couldeasily be corrupted.

The situation above demonstrates the need for spin locks. A spin lock is a bit that iseither on (locked) or off (unlocked). The processor provides some basic mechanismfor testing and setting these bits, and Linux provides well-documented and portableinterfaces for performing those processor-speciÞc operations.

The spin_lock() family of calls will protect drivers in SMP conÞgurations and,since a preemptible kernel behaves essentially the same as a second processor, adriver that is SMP-safe will also behave correctly with a fully preemptible kernel.

Of particular note is the spin_lock_irqsave() routine, which not only acquiresa spin_lock but also disables interrupts on the local processor. The correspondingspin_unlock_irqrestore() is then used later to undo both the spin lock andthe processor's interrupt mask.

Finally, because spin locks may cause other processors to �spin in their tracks,� theiruse should be as rare and for as brief a period of time as possible. Study of the sourcecode to other drivers will show that, in most cases, spin locks are rarely held forlonger than one or two lines of C source code, and never across a sleep!

Wrap Up Device drivers for Linux should be written and tested in an incremental fashion. A testprogram, developed in lock-step with the coding of the driver, can be used to test eachpiece. As the driver gains in capability, the test program is similarly enhanced tothoroughly probe the driver and verify proper operation. This includes giving theappropriate errors when the program (intentionally, in the case of the test program)attempts something illegal.

Development begins with the writing and testing of an install and a remove script andthe driver's kernel module �carrier.� The associated kernel module initialization andremoval routines are tested at this initial stage.

MontaVista� Linux® Professional Edition 101

Page 110: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentBuilding Custom Device Drivers

Then, the driver's initialization and prepare to be removed functions are coded andtested. These include the Þrst use of the kernel via the register_chrdev() andunregister_chrdev() functions.

Next, open and release are coded and the test program modiÞed accordingly.

A big step is involved in the next section � coding the write routine, the interrupthandler and, if necessary, the driver's tasklet. To test the new code, the test program isenhanced to include normal (legal) writes as well as writes specifying invalidaddresses and other illegal operations the driver is supposed to catch. The testprogram veriÞes that the driver not only catches the errors, but also returns the properindication.

When the write handler is Þnished, it is copied into the read handler and, after somefairly minor adjustments, it is ready to be tested. The test program is modiÞedaccordingly and run.

Issues of reentrancy abound. Kernel MUTEXes, spin locks and interrupt maskingmust all be used in various places and combinations. Testing becomes less certain ofÞnding all problems and �long duration stressing� is often used in partialcompensation.

The main driver entry points have been sketched out here. The driver's handlers foropen(), close(), read() and write() are almost complete. However, mostdrivers will also include handlers for ioctl() and others. Many will also provideinterfaces for poll(), mmap(), media_change(), revalidate() andseveral others. And, practically every one of these will have only a passing similarityfrom one driver to the next.

Additional Information

The best information on Linux device drivers are the hundreds of Linux devicedrivers, all of which are provided in source form in:

� /opt/hardhat/devkit/lsp/<lsp-name>/linux-<version-number>/drivers

In addition, there are many good books that provide details on building Linux devicedrivers.

Note: MontaVista Software does not endorse the book listed below. The followingexample is provided for your convenience only.

Linux Device Drivers (Nutshell Handbook), Second Edition, Alessandro Rubini, AndyOram (Editor). Sebastopol, California: O'Reilly & AssociatesISBN: 1565922921

102 MontaVista� Linux® Professional Edition

Page 111: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentEnabling File Systems

Enabling File Systems

The Linux kernel supplies Þle-system services for a of variety Þle-system types. Filesystems are included for use with rotating media, network, ßash, and RAM devices.Pro supports EXT2, EXT3, ReiserFS, CramFS, JFFS and JFFS2 Þle systems,although not all Þle systems are supported on all platforms.

Check the MontaVista Zone page for your target for information about Þle systemsupport on your target.

As part of deployment (see �Deployment� on page 171), you need to build a Þlesystem for your embedded system. Building a Þle system requires, among otherthings, that the Þle system you want to use is enabled in the kernel.

For information about how to choose a Þle system, see:

� �Select a Deployment File-System Type� on page 145

For information about how to enable your Þle system for deployment (in other words,which options you need to enable in the kernel � for example, MTD and JFFS forJFFS), see:

� �ConÞguring the Kernel to Be Stand-Alone and to Enable aDeployable Root File System� on page 173

MontaVista� Linux® Professional Edition 103

Page 112: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

Debugging the Kernel

Pro provides a number of tools and conÞguration Þles that can be used to debug thekernel. The tools and conÞguration Þles are:

� KGDB

� Linux Trace Toolkit (LTT)

� Abatron BDI2000 ConÞguration Files

KGDB KGDB is a debugging tool that can be used to debug the Linux kernel. Using KGDB ismost practical when you are implementing kernel device drivers and other similarfunctions. By using KGDB, you can:

� set and unset breakpoints

� step through code

� examine memory

� set memory

To use KGDB, you need to reconÞgure and rebuild the target kernel. In Pro, KGDB isnot on by default in the kernel; however, the ability to turn on KGDB is there for eachkernel. For Pro, you need to complete the following steps:

1. ConÞgure the kernel to use KGDB.

2. Boot the target with the new kernel image.

3. Set up GDB to debug the kernel.

Details on these steps are provided in the sections below.

ConÞgure the kernel to use KGDB

To use KGDB, it is necessary to conÞgure the kernel to enable kernel debugging. Toenable kernel debugging, complete the following steps:

1. Start make menuconfig or make xconfig. The latter can be runon its own or through TCT.

2. Depending on the target architecture, select Kernel Hacking or KernelDebugging.

104 MontaVista� Linux® Professional Edition

Page 113: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

3. Enable GDB stub kernel debug or KGDB.

4. The makefile in the same directory where .config for the kernelresides must be checked for the following change. The following line:

CFLAGS = -Wall �Wstrict-prototypes �O2 �fomit-frame-pointer

must be changed to:

CFLAGS = -Wall �Wstrict-prototypes -O2 �g -ggdb

This change inserts debug data into the kernel allowing the use of GDBfor symbolic debugging. Removing the �fomit-frame-pointerallows the capability to do stack traces and walkbacks.

5. Rebuild the kernel, using TCT or the procedure in �Building andConÞguring the Kernel� on page 76.

Once the kernel is re-built, it contains all the data needed to use the KGDB interface.

Boot the target with the new kernel image

Boot the target using the new kernel. For more information about how to boot thetarget with the new kernel, see �Booting the Target with a Custom Kernel� onpage 52.

Set up GDB to debug the kernel

Now that everything is set to debug the kernel, it is necessary to connect to it usingGDB. To connect to the target using GDB, complete the following steps:

1. Terminate the Minicom (or other terminal emulator) connection totarget.

2. Change to the directory on the target where the kernel image is stored.

3. Start GDB. For example, run the command:

ppc_8xx-gdb

Note: For more information about GDB, see the GNU GDB manual. Acopy of the GDB manual is available on the GNU Web site at: http://www.gnu.org/manual/gdb-4.17/gdb.html

4. Enter the following command:

file <kernel-binary-image>

The file command loads the symbols for the kernel into GDB toenable symbolic debugging. By being in the correct directory, the fullsource is also available for display.

MontaVista� Linux® Professional Edition 105

Page 114: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

Note: The kernel binary image Þle to download into GDB is located inthe top-level directory of the tree used to build the kernel, and it isusually called vmlinux.

5. On the host, enter the following to connect to the target:

target remote /dev/ttyS0

This connects GDB to the target, which is waiting for the debugger.

6. Enter a breakpoint command at the address or function wheredebugging should begin. There are two convenient places to setbreakpoints. They are:

� b panic This is the entry point to panic routines. This traps all panics toGDB.

� b sys_sync By entering a sync command, the system will go to the breakpointfor sys_sync.

7. Enter continue to start the kernel running again.

GDB is now running and in control of the kernel. It will stop at the breakpoint enteredabove. This allows for examining variables and watching how the code ßows.

Additional information

For more information about using KGDB and kernel debugging, see the followinghelp document on MontaVista Zone (http://support.mvista.com/content/Kernel).

106 MontaVista� Linux® Professional Edition

Page 115: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

Linux Trace Toolkit (LTT)

LTT provides a general-purpose event logging and analysis system, with many usefulpre-deÞned events. The pre-deÞned events are in the areas of:

Some examples of questions that can be answered using LTT include:

� Why do certain synchronization problems occur?

� What exactly happens to an application when a packet is receivedfor it?

� Overall, where do all the applications that I use pass their time?

� Where are the I/O latencies in a given application?

Limitations

LTT has been ported to work with ARM, x86, MIPS, PowerPC, StrongARM/XScale,and SuperH targets, and it is part of the Pro distribution.

The �graphic mode� of the tracevisualizer program is not implemented forSolaris.

For all hosts, the LTT tracevisualizer data analysis tool is linked in statically to avoidan install-time dependency on some graphics packages, such as glib, XFree86-libs,and gtk+. This results in problem using some GTK themes. These problems dependon the theme and can include Segmentation fault, X error, or many GTK warnings.

If you see any of these problems, you can use one of the following solutions:

� On most systems, change the GTK theme to one of the following:Blue-n-Gray, BrushedMetalClean, Cheese, Default, Notif, Notif2,or Quiet.

� system calls

� traps

� interrupts

� scheduler

� kernel timer

� soft IRQ management

� processmanagement

� Þle-system management

� timer management

� memory management

� socket communications

� SystemV IPC

� communications

� network devicemanagement

MontaVista� Linux® Professional Edition 107

Page 116: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

� Remove ~/.gtkrc (you might want to save a copy).

� The hhl-host-ltt-dynamic package contains a version ofthe tracevisualizer data analysis tool that is linked withshared libraries. Remove the hhl-host-ltt-0.9.5a packageand install the hhl-host-ltt-dynamic-0.9.5a packageavailable on the Pro distribution CD-ROMS.

To remove the hhl-host-ltt-0.9.5a package, use thecommand:

rpm -e hhl-host-ltt-0.9.5q-mvl3.0.5<host>.rpm

To install the hhl-host-ltt-dynamic-0.9.5a package, usethe command:

rpm -Uhv --ignorearch hhl-host-ltt-dynamic-0.9.5q-mvl3.0.5<host>.rpm

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

Note: <host> is i386, ppc or solaris2.7-sparc64 depending on thehost you are using.

Additional information

For more information about what LTT does and how to use it, see the LTT referencemanual distributed with the LTT package. It can be found in /opt/hardhat/host/doc/hll-host-ltt-0.9.5a/index.html.

Abatron BDI2000 BDI2000 is a hardware instruction-level debugging system distributed by Abatron,AG (http://www.abatron.ch/) that allows source-level debugging of kernel, drivers,and boot code using GDB via a BDM(Background Debug Mode) or JTAG interface.With a BDM or JTAG debug port, you control and monitor the microcontroller solelythrough the stable on-chip debugging services. This debugging mode runs even whenthe target system crashes, and it enables you to continue investigating the cause of thecrash.

Host-to-BDI communication uses the standard GDB remote protocol, as in thediagram below:

Host Target

AbatronBDI2000(Functions asa GDB server)

BDM/JTAGLAN

Serial Connection

(Optional for console)

108 MontaVista� Linux® Professional Edition

Page 117: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

Features

The Abatron BDI2000:

� provides the ability to step through system interrupts

� provides a turnkey solution to using JTAG

� supports Linux kernel debugging even when MMU is enabled

� allows Ethernet debugging with target systems without networkcapability

� supports built-in on-board programming of ßash memories

� supports internal break register (allows debugging of code runningout of a read-only memory)

� supports fast download speed, up to 150Kbytes/s

� requires no target communication channel (for example, serial line)for debugging purposes

� connects on target, eliminating typical ICE cabling problems

Supported Targets

MontaVista Software provides an Abatron BDI2000 conÞguration Þle for the LSPsfor which we support the use of the Abatron BDI2000 debugger.

Check the MontaVista Zone page for your target for information about support forthis feature on your target.

MontaVista� Linux® Professional Edition 109

Page 118: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

Using Abatron BDI 2000 with Pro

The primary reference for the BDI2000 is the documentation distributed by Abatron.The following step-by-step guide is intended as an overview of the steps you need tofollow to get your BDI2000 operational.

1. Ensure that TFTP is installed on the host, conÞgured and running.

2. Mount the ßoppy disk that came with the Abatron BDI2000 thatcontains bdisetup.zip.

3. Copy the .cnf and .def Þles that came with the BDI2000 into thedirectory that your TFTP server gives access to. If a .cnf Þle camewith your target's LSP, that Þle should also be placed in that directory.You should select the .cnf Þle that is appropriate for your target andthen make a copy of the Þle. Edit the copy to change the conÞgurationvalues to Þt your particular environment. You will want to refer to theBDI2000 documentation for more details. You will need the name ofthis Þle in Step 8.

4. Connect your BDI2000 to your host with a serial cable, the networkwith a LAN cable and then connect its power. Do NOT connect theBDI2000 to your target yet.

5. Compile the bdisetup sources that came with the BDI2000.

6. Run the bdisetup program. It will print out an overview of its usage.

7. Update the BDI2000's Þrmware by running bdisetup with the -uoption. The defaults for the options can be determined by looking in thesource, but it is probably easier to just specify all options. Theapplication type should be speciÞed as GDB. For example:

bdisetup -u -p/dev/ttyS1 -b38 -aGDB -tPPC400 -d.

The command above updates the Þrmware and logic in the BDI2000from the Þles in the current directory using the serial port /dev/ttyS1running at 38400 baud. The Þrmware and logic that is loaded is for aPPC400 target using GDB as the debugging interface.

8. ConÞgure the BDI2000's networking by running bdisetup with the-c option. You need to obtain a free IP address to give to the BDI2000.You also need to know the IP address of your host, the subnet mask, andthe IP address of your gateway. The conÞguration Þle should be thename of the .cnf Þle from step 3. For example:

bdisetup -c -p/dev/ttyS1 -b38 -i10.0.0.3 -h10.0.0.2 -m255.255.255.0 -g10.0.0.1 -fevb405gp.cnf

(ENTER THE PRECEDING STRING AS A SINGLE LINE.)

110 MontaVista� Linux® Professional Edition

Page 119: Monta Vista Users Guide

Chapter 6: Linux Kernel DevelopmentDebugging the Kernel

9. Make sure that the Þrmware is programmed correctly and then tell theBDI2000 to exit the loader and run the Þrmware. Use the command:

bdisetup -v -p/dev/ttyS1 -b38 -s

If you have successfully done the above steps, the red MODE LEDshould no longer be blinking on the BDI2000 and you should be able totelnet to it. When you telnet to the BDI2000, it will show a help screenand then report that it is waiting for the target Vcc.

10. Make sure that your target's power is turned off. You can then connectthe JTAG or BDM ribbon cable between your target and the BDI2000.Turn on the target's power. If all is well, the BDI2000 resets andinitializes the target with no errors.

You are now ready to start using the BDI2000. Using the telnet interface, you can dosuch things as:

� display and modify the targets memory and registers

� set instruction and data breakpoints

� step through code

� download code from your TFTP server to RAM or FLASH

Note: Not all of the above features are present on all targets.

The telnet interface is very useful, but the real power of the BDI2000 is apparentwhen you start using it as a gdbserver. You will be able to debug boot code, thekernel, drivers, and modules. If you compile your code with -ggdb and use ddd, youwill even be able to display structures such as linked lists.

Additional information

Additional information about the Abatron BDI2000 is available at:

� http://www.abatron.ch/BDI/bdihw.html

� The Abatron BDI2000 FAQ on MontaVista Zone(http://support.mvista.com/content/DevEnv/AbatronFAQ.html)

MontaVista� Linux® Professional Edition 111

Page 120: Monta Vista Users Guide
Page 121: Monta Vista Users Guide

Chapter 7: Application Development

OverviewThere are a variety of ways to build your application using Pro. You can build theapplication on the host using KDevelop (a C/C++ IDE) or the command-line cross-compilers included with Pro. Whether you use KDevelop or the command-line tools,we recommend that you do NOT work directly in the /opt/hardhat/devkittree. Rather, you should create a build directory for your work (for example,myapplication) Once you have written and compiled your program, you shouldcopy the program to the target and test it (recommended). By having the target�s rootÞle system NFS exported from the host, you can easily copy your application to thetarget for testing.

When choosing a location for your application in the target Þle system, werecommend following the Filesystem Hierarchy Standard (FHS). For moreinformation, see http://www.pathname.com/fhs/.

Note: You can also write and debug programs directly on the target using the target-speciÞc command-line compilers.

This chapter provides examples of writing simple programs and information on howto use the debuggers. This chapter contains the following sections:

� �Building Programs Using KDevelop� on page 114

� �Building Programs Using GCC and G++� on page 128

� �Using Threads� on page 131

� �Debugging Programs Using GDB and DDD� on page 132

� �Debugging Multi-Threaded Applications� on page 136

� �Additional Tools for Programming and Debugging� on page 137

� �Using AltiVec� Technology by Motorola� on page 140

MontaVista� Linux® Professional Edition 113

Page 122: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

Building Programs Using KDevelop

KDevelop is an easy-to-use C/C++ Integrated Development Environment (IDE)provided with Pro for application development. Among other features, KDevelopprovides:

� GUI-based development

� a syntax-aware text editor

� Þle, class, and function hierarchy browsers

� organizational paradigm structured around development �projects�

� a built-in GDB-based debugger

� implicit invocation of the GNU tool set for compiles, links, etc.

� projects oriented to speciÞc types of development � for the selectedproject type, Þle templates and appropriate includes and librariesare pre-deÞned

� a built-in document (HTML) browser

� compatibility with CVS version control

KDevelop manages the development tools needed for C/C++ programming such asCompiler, Linker, automake and autoconf. MontaVista Software has customizedKDevelop for use in the cross-development environment. See �MontaVistaCustomizations� on page 115 for more information.

The KDevelop documentation set includes The User Manual to KDevelop and TheKDevelop Programming Handbook. Both of these manuals are part of the KDevelopdistribution and are also available via MontaVista Zone.

While fairly complete, the KDevelop documentation does not cover using KDevelopin a cross-development environment. The sections below provide information aboutthe customizations MontaVista Software made to KDevelop, as well as informationabout how to use KDevelop in the cross-development environment.

114 MontaVista� Linux® Professional Edition

Page 123: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

MontaVista Customizations

KDevelop 2.0.1 was used as the base for the Pro distribution. MontaVistacustomizations include:

� Menu Bar changes:

� Project-> New (New Project Wizard). Provides a �TargetNon-Graphic� major project type as a starting point for targetcross-development. �Non-graphic� means that support is notprovided for a graphical environment (X11, Qt/Embedded,KDE, or Gnome) on the target.

� Tools: Provides DDD (debugger) and TCT (TargetConÞguration Tool) entries if those components are installed aspart of Pro. (TCT and DDD are installed by default with Pro.)

� Options->Tools... Includes DDD and TCT entries.

� Help->MontaVista Support: Provides direct access toMontaVista Zone via a Web browser.

� KDevelop senses which cross-development environments areinstalled in /opt/hardhat/devkit. This allows projects to bedeÞned either for the development host (normal, natively hosteddevelopment) or for any of the cross-development targets. Variousmenus and options throughout KDevelop were adjusted for thisoption.

� The second pane of the Application Wizard presents a Target pull-down menu that allows you to select either Development Host fornatively-hosted development (using the host system's owntoolchain) or one of the MontaVista architecture/processor stringsfor cross-development using the appropriate toolchain for yourtarget.

� The Compiler Options pane has been changed to include a TargetArch/Proc pull-down. This initially shows the target chosen duringproject creation. Clicking this pull-down and changing the selectionredeÞnes the project for a new target. Selecting Development Hostconverts the project from cross-development to natively-hosteddevelopment.

� The Þeld Pro Development Kit shows the root of the Pro cross-development tree. This value is set based on the installed location ofPro (typically /opt/hardhat/devkit.) Replace the value ofthis Þeld if the development kit has been moved. (Warning: Procannot be relocated after installation and any attempts to do so willbreak the development environment; however, this option may beuseful for customers who have multiple products installed.)

� Under the Build menu, the options Execute and Execute withArguments can only be used for natively hosted projects. Because

MontaVista� Linux® Professional Edition 115

Page 124: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

these menu items run the application on the local host system, whena cross-development project is deÞned, these menu items aredisabled. Cross-development binaries must be moved to the targetsystem and run and debugged remotely.

� Under the Debug menu, the options Start and Start (other)... startthe debugger. If DDD is installed for cross-development, thedebugger is conÞgured to be DDD for the current target. Forexample, if the project target is set to arm_sa_le, by default, thedebugger is deÞned to be:

ddd --debugger arm_sa_le-gdb

The default value can be overridden by selecting KDevelop Setupfrom the Options menu.

Note: DDD can also be run by selecting DDD from the Tools menu.When run from the Tools menu, DDD does not automatically use thearchitecture-speciÞc debugger; instead, it uses the options speciÞedin the Options->Tools... conÞguration. If you intend to use DDD viathe Tools menu for cross-development, you must specify the--debugger option in the Options->Tools... conÞguration.

Install KDevelop KDevelop is included with Pro and was installed automatically during the installationof Pro.

Note: Many host distributions have a version of KDevelop already installed. Theversion of KDevelop installed with Pro does NOT overwrite the version on the host �both versions coexist on the system. Because the base system is not replaced, youmay see some look-and-feel and desktop interaction differences when running theMontaVista provided KDevelop. These differences are most noticeable when runningin a non-KDE desktop (Gnome, CDE, OpenWindows, Motif). For a KDE desktopolder than KDE 2, there are some stylistic differences in the decoration of windows,etc. For the most part, these differences are benign; however, you should be aware thatwhen KDE 2 is the desktop (this will be true on Red Hat 7.x and SuSE 7.3 systems),customizations of the desktop environment will not be reßected in the MontaVistaprovided KDevelop. For example, if the �File Browsing Preferences� were changedvia the control panel, those changes would not affect the MontaVista providedKDevelop. In general, the MontaVista provided KDevelop is isolated from thedesktop, since its main purpose is to build tools for the target.

116 MontaVista� Linux® Professional Edition

Page 125: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

Start KDevelop To start KDevelop, at the system prompt, enter the command:

/opt/hardhat/host/bin/kdevelop

Note: Because the MontaVista provided KDevelop does not overwrite any hostversions of KDevelop, it is possible to have two copies of KDevelop on your system.To ensure that you are running the version you want to use, we recommend using thefull path when starting the MontaVista provided KDevelop. Alternatively, the PATHvariable must be set to give priority to the Pro host tools. The base system installsKDevelop into /usr/bin or /opt/kde2/bin while Pro installs by default into /opt/hardhat/host/bin.

Use KDevelop for Cross-Development

The sections below provide an example of how to use KDevelop in the cross-development environment.

Using KDevelop for the Þrst time

The Þrst time you run KDevelop, a series of setup screens appear. These screens:

� allow you to adjust some of the settings for the editor and user-interface

� check your system for helper programs needed by KDevelop

� set up your documentation

Follow the instructions on-screen to navigate the set-up process.

After the initial setup, the setup screens can be viewed and edited by startingKDevelop with the --setup option. Use the command:

/opt/hardhat/host/bin/kdevelop --setup

Rerunning setup replaces all options previously conÞgured in setup mode and erasesthe �recently opened project� list. KDevelop project deÞnitions and directories are notdisturbed. Following setup, you need to open existing projects by explicitly selectingOpen... from the Projects menu. You may also change some (but not all) settingsestablished without re-starting in setup mode by selecting KDevelop Setup... fromthe Options menu.

MontaVista� Linux® Professional Edition 117

Page 126: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

Creating a new cross-development project

To create a new project that will use the cross-compilers for your target, complete thefollowing steps:

1. From the Project menu, select New.

The Application Wizard appears. This wizard is used to deÞne the type,name, and other properties of your project.

2. For the project type, under the Target Non-Graphic major project type,select either C or C++.

The Target Non-Graphic major project type is a starting point fortarget cross-development. The target is assumed to only contain the Prodevelopment environment, and support is not provided for a graphicalenvironment (X11, Qt/Embedded, KDE, or Gnome).

3. After selecting the project type, select Next to move to the next screen.

A preview of the generated project appears.

4. Select Next to move to the next screen.

118 MontaVista� Linux® Professional Edition

Page 127: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

5. Fill in the Þelds in the Generate settings panel. The examples in thismanual use mynewproject as the application project directory name.

6. From the Target pull-down menu, select the architecture/processor typeof your target board.

Note: KDevelop automatically detects which architecture/processortypes have been installed as part of previous Pro installations. Only thearchitecture/processor types installed, along with the native host option,are available.

Note: Only one architecture/processor type can be selected at a time, soa single project cannot simultaneously be built for multiple architecture/processor types. For team development, all developers share the sameproject metadata and therefore must use the same architecture/processortype.

7. Select any additional features that you need for your project, such asAPI-Documentation or GNU-Standard-Files.

MontaVista� Linux® Professional Edition 119

Page 128: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

8. Select Next to move to the next screen.

9. If you intend to use a local CVS repository for your version controlsystem, select CVS from the pull-down menu and enter the informationabout your repository in the VCS Support Þelds. If you are using a non-local CVS server, you may need to do a separate import.

10. Select Next to move to the next screen.

A preview of the project Þles is displayed.

11. Click Next until it is no longer an available option.

12. When the project deÞnition is complete, click the Create button tocreate the new project using the chosen development environment.

13. Once the project has been created, click Exit.

KDevelop runs autoconf, automake, and configure to create the requiredmakeÞles. You can now write your application.

Note: Following initial deÞnition of a project, the target may be changed at any timeby selecting Options from the Project menu. If any project options are changed, theproject will be reconÞgured upon closing the Project->Options menu. If thedevelopment target was changed, the project will be reconÞgured to use the newdevelopment toolchain; however, the project is not rebuilt for the new architecture

120 MontaVista� Linux® Professional Edition

Page 129: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

until you select Rebuild from the Build menu. Source code that is not written in anarchitecture-independent manner remains unchanged, and if the target is changed, thecode may not compile in the new environment.

Import a pre-existing application into KDevelop

To import a pre-existing application with a makeÞle and source code into KDevelop,complete the following steps:

1. From the Project menu, select New.

The Application Wizard appears. This wizard is used to deÞne the type,name, and other properties of your project.

2. For the project type, under the Others major project type, selectCustom project.

3. Continue to use the Application Wizard just as you would for any newproject. (See �Creating a new cross-development project� on page 118).

4. Once you have completed the project deÞnition, click Exit.

A message appears indicating that no makeÞle exists.

5. Click OK.

6. From the Project menu, select Add Existing Files.

7. Click the Þle folder icon to open a Þle search window, then browsethrough the Þle system and select the source code and makeÞle youwant to include.

8. Click OK.

The Þles selected are now copied to the new KDevelop project directory.

9. From the Project menu, select Options.

The Project Options dialog box appears.

10. From the column on the left, select Make Options.

11. Click the Þle folder icon for the Run Make in Þeld.

12. Select your custom project directory.

Selecting the project directory deÞnes which makeÞle the build processwill use (that is, the one you imported).

MontaVista� Linux® Professional Edition 121

Page 130: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

13. Click OK.

14. From the File menu, select Save all.

Now you are ready to use your imported makeÞle and source code in KDevelop.

Write and build your application

The next step is to write your application. KDevelop provides you with theClassbrowser, Classtools, and Þle views to help you easily view and edit your projectsource Þles. For typical application development you might see a screen similar to theone below:

Once you have written your application, you can build your application by selectingRebuild from the Build menu.

Note: The Build menu commands Execute and Execute with Arguments can onlybe used for natively-hosted projects. Because these menu items run the application onthe local host system, when a cross-development project is deÞned, these menu itemsare disabled. Cross-development binaries must be moved to the target system andmust be run and debugged remotely.

122 MontaVista� Linux® Professional Edition

Page 131: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

Moving the application to the target

Cross-development binaries must be moved to the target system and then run ordebugged remotely. If you followed the steps listed in the quick start guide for yourtarget, you will have NFS exported the default root Þle system (/opt/hardhat/devkit/<architecture>/<processor>/target). We recommend thatyou NOT work directly in the /opt/hardhat/devkit tree. Rather, you shouldcreate a directory for your Þle system (for example,my_work_directory/myfilesystem) that contains a copy of the defaulttarget Þle system or the Þle-system you are developing. You should then NFS exportyour custom Þle system directory as the root Þle system on your target. See �How toNFS export your Þle-system project directory� on page 53 for more information.

Once you have written and compiled your program, you need to copy the program tothe target�s Þle system (/my_work_directory/myfilesystem), where it canbe run and debugged (recommended). When choosing a location for your applicationin the target Þle system, we recommend following the Filesystem Hierarchy Standard(FHS). For more information, see http://www.pathname.com/fhs/.

KDevelop can be used to run make install to move your executable and anyassociated data Þles to the cross-development Þle-system tree. To use KDevelop forthis purpose, complete the following steps:

1. In your project�s makeÞle, specify the location where you wish to movethe executable. For example, you could move the application to a workdirectory that is NFS mounted as the target root Þle system:

/my_work_directory/myfilesystem/target-1/usr/bin

Note: The login under which KDevelop is running must have writeaccess to the directory (or to the target subtree in general) speciÞed.

2. From the Build menu, select Install. KDevelop performs a makeinstall which moves the executable and any associated data Þles tothe cross-development Þle-system tree that you speciÞed in the projectmakeÞle.

Your application can now be run and debugged on the target.

MontaVista� Linux® Professional Edition 123

Page 132: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

Debugging an application

For cross-development, the debugger is conÞgured to be DDD for the current projecttarget, provided that DDD was installed. (DDD is a graphical front-end for Linux/UNIX debuggers, including the GDB debugger.)

For example, if the project target is set to arm_sa_le, by default, the debugger isdeÞned to be:

ddd --debugger arm_sa_le-gdb

Note: This default can be overridden by selecting KDevelop Setup from the Optionsmenu.

To debug the current open application, complete the following steps:

1. From the Options menu, select KDevelop Setup to set the options usedby the debugger.

2. In the panel on the right, click on Debugger.

3. Ensure that the box for Use external debugger is checked.

KDevelop provides an internal debugger (Use external debuggercheckbox is not checked) that is not useful for remote debugging and isnot supported by MontaVista Software. Since DDD was installed as partof Pro, KDevelop detects it and automatically selects Use externaldebugger and predeÞnes the Select debug command Þeld to ddd.

Note: Although the command line is shown as ddd, the actual commandline used is the following:

124 MontaVista� Linux® Professional Edition

Page 133: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

ddd --debugger gdb <options>

for native host development deÞned projects

<options> can be speciÞed in the Select debug command Þeldfollowing ddd.

4. In the cross-development environment, DDD establishes a connectionto a remote debugging stub, usually gdbserver, via a serial or TCPconnection. Since the location and type of connection to the target is notknown, you must set those options. One of the options related to remotedebugging over a serial line is:

� -b <speed>

to set the line speed for a serial connection from GDB togdbserver

To add user options, enter the options into the Select debug commandÞeld following ddd. For example, to set the line speed for remotedebugging to 9600bps, enter the following:

ddd -b 9600

5. Click OK to save your changes and close the KDevelop Setup window.

6. On your target, start the remote debugging stub. For a TCP connection,use the command:

gdbserver <targetIPaddress or name>:<port> <program>

<targetIPaddress or name> is the target system's domain name or IPaddress, <port> is the TCP port number on which the debugging stub islistening, and <program> is the full path to the program to bedebugged. For example, to debug a program called hello using thegdbserver debugging stub, on the target, enter the command:

gdbserver 10.0.1.17:2345 /usr/bin/hello

You should see output similar to the following:

Process dispbmp created; pid = 18

More information about DDD and GDB can be found in �DebuggingPrograms Using GDB and DDD� on page 132.

7. In KDevelop, run the debugger. From the Debug menu, select Start orStart (other)...

This launches DDD using the options speciÞed.

8. DDD creates a window with two panes. The lower, smaller paneprovides a work space for direct entry of GDB commands and viewingGDB responses.

MontaVista� Linux® Professional Edition 125

Page 134: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

� To connect to the remote debugging stub using a TCP connection,enter:

target remote <targetIPaddress or name>:<port>

where <targetIPaddress or name> is the target system's domainname or IP address and <port> is the TCP port number on whichthe debugging stub is listening (both values are parameters to thedebugging stub when the latter is started). For the exampledebugging stub started in step 6, the DDD connection establishedfrom the GDB command entry pane would be the following:

target remote 10.0.1.17:2345

� To connect to the remote debugging stub using a serial connection,enter:

target remote /dev/ttySn

where /dev/ttySn is the serial port on the development host(running KDevelop and DDD) that connects to the target systembeing debugged. This connection will run at the serial-line speedspeciÞed by the -b <speed> option (see the steps above).

Note: DDD may be run from the Tools menu. You may customize this menu entry torun the debugger remotely on your target system. To customize the DDD menu entry,complete the following steps:

1. From the Options menu, select Tools....

2. Click on the &DDD entry in the tools listing.

The detail Þelds at the bottom of the window are displayed. Executableand Menu Text should contain the correct information by default.

3. In the Arguments Þeld, enter:

--host <targetIPaddress or name> --login <userID> <program>

where <targetIPaddress or name> is the name of your target system,<userID> is the login user name on that system, and <program> is thefull path to a copy of your debug executable, previously moved or NFS-exported to the target system. For example, if your KDevelop project�testproject� compiled and linked an executable named �testproject�which you placed on the target system as /usr/bin/testproject,you could use as arguments:

--host targetsystem --login root /usr/bin/testproject

4. Ensure that the box Capture output is checked.

5. Click the Replace button.

126 MontaVista� Linux® Professional Edition

Page 135: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using KDevelop

6. Click the OK button.

You may now run DDD with remote debugging on your executable by selecting DDDfrom the Tools menu.

Help You can access MontaVista Zone from inside KDevelop by selecting MontaVistaSupport from the Help menu. For more information about MontaVista Zone, see�MontaVista Zone� on page 11. A supported Web browser must be available in thedesktop execution environment to view the content. For Linux systems, supportedbrowsers include Konqueror (KDE 2), Netscape (netscape-communicator), andMozilla.

For additional information about using GDB and DDD, see the GNU manuals forthose applications. The GNU GDB and DDD manuals are available on MontaVistaZone.

MontaVista� Linux® Professional Edition 127

Page 136: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using GCC and G++

Building Programs Using GCC and G++

Pro gives you the option of using the command-line cross-compilers to build yourprograms rather than the KDevelop IDE. When using the command-line compilers tobuild your program, you should work in a project directory created to Þt your needs.In the section �Project Directories� on page 38, we recommend creating amy_work_directory/myapplication directory for your applicationdevelopment and a my_work_directory/myfilesystem directory for yourÞle-system development. These directories will be used in all examples below. Wealso recommended that you NFS mount the myfilesystem directory on the targetfor testing. It is assumed in the examples below that the myfilesystem directorycontains your target Þle system and that it is NFS-mounted as the target�s root Þlesystem.

For all of these examples, the user�s executable search path has been updated toinclude the Pro applications. For information on how to update your path, see�Running Pro Applications and Tools� on page 40.

Example of a C Program

The following is an example of a simple C program for a PowerPC 8xx target. Bold isused to indicate user input. The target is assumed to be booted and the target root Þlesystem NFS-mounted.

1. On the host in the my_work_directory/myapplication, writeyour program. For this example, we�ll use the simple �hello world�program saved as hello.c.

2. Using the cross-development tools included with Pro, on the host, buildthe executable. Use the following command:

ppc_8xx-gcc -o hello hello.c

Note: A list of preÞxes for the cross-development tools can be found in�Cross-Development Application PreÞxes� on page 42. For help usinggcc, see the gcc man and info pages.

3. Copy the executable to an NFS-mounted directory on the target.

cp hello /my_work_directory/myfilesystem/testprgrams/

#include <stdio.h>main(int argc, char **argv){ printf("hello world\n");}

128 MontaVista� Linux® Professional Edition

Page 137: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using GCC and G++

4. On the target, change to the directory where your program is located.

cd testprograms

5. Run your program on the target. For example:

./hellohello world

Example of a C++ Program

The following is an example of a simple C++ program on a PowerPC 8xx target. Boldis used to indicate user input. The target is assumed to be booted and the target rootÞle system NFS-mounted.

1. On the host, in the my_work_directory/myapplication, writeyour program. For this example, we�ll use a simple �hello� programsaved as hello.cc.

2. Using the cross-development tools included with Pro, on the host, buildthe executable. Use the following command:

ppc_8xx-g++ -o hello hello.cc

Note: A list of preÞxes for the cross-development tools can be found in�Cross-Development Application PreÞxes� on page 42. For help usingg++, see the g++ man and info pages.

3. Copy the executable to an NFS-mounted directory on the target.

cp hello /my_work_directory/myfilesystem/testprograms/

4. On the target, change to the directory where your program is located.

cd testprograms

5. You can now run your program on the target. For example:

./hellohello from C++

Additional Information

For additional information about GCC and G++, see the following Web sites:

� Command-Line Development Tools on MontaVista Zone:http://support.mvista.com/content/DevEnv/index.html#Dev

#include <iostream>using namespace std;main(){ cout << "hello from C++\n";}

MontaVista� Linux® Professional Edition 129

Page 138: Monta Vista Users Guide

Chapter 7: Application DevelopmentBuilding Programs Using GCC and G++

� GCC/G++ User�s manuals:http://www.gnu.org/software/gcc/onlinedocs/

� Frequently Reported Bugs in GCC:http://www.gnu.org/software/gcc/bugs.html#known

130 MontaVista� Linux® Professional Edition

Page 139: Monta Vista Users Guide

Chapter 7: Application DevelopmentUsing Threads

Using ThreadsFor building multi-threaded applications, Pro provides LinuxThreads. LinuxThreadsis an implementation of the POSIX threading library speciÞcation IEEE 1003.1c.LinuxThreads implements a 1:1 threading model, allocating one kernel thread foreach user-space thread created by the program. LinuxThreads is the standard Linuxthreading library.

To use LinuxThreads in your application, you need to do the following:

� Use #include <pthread.h> in your source code.

� Add -lpthread to your application's compilation options to linkagainst libpthread.

� Add -D_REENTRANT to your application's compilation options.

More information about LinuxThreads is available at:

� http://pauillac.inria.fr/~xleroy/linuxthreads/

MontaVista� Linux® Professional Edition 131

Page 140: Monta Vista Users Guide

Chapter 7: Application DevelopmentDebugging Programs Using GDB and DDD

Debugging Programs Using GDB and DDDPro provides a number of tools for debugging code; however, the main trouble-shooting tool available for debugging application code is currently GDB. GDB is acommand-line debugger that allows you to step through code, set break points, andprint values to isolate problems in code.

In the cross-development environment, GDB runs in two parts:

� a server (gdbserver) that runs on the target and controls theexecution of the program being debugged

� a client that runs on the host and provides a command interface andaccess to symbol information and source code

The gdbserver is very small and requires minimal resources on the target. Also,since symbols are accessed by the GDB client through a copy of the program beingdebugged on the host, the program on the target can be stripped to further save space.

When used in this fashion, GDB can perform three main functions to help you catchbugs:

� stop your program on speciÞed conditions

� examine the state of your program, when your program stops

� change states and values in your program, allowing you toexperiment with the effects of a change

Pro also includes the program DDD. DDD is a graphical front-end for Linuxdebuggers, including the GDB debugger. Using DDD with GDB, it is possible topoint and click through debugging an application program.

You can use GDB to debug programs written in C, C++, and assembly. Examplesfollow on how to use GDB as a command-line tool and how to use GDB with DDD.

Note: For all of these examples, the user�s executable search path has been updated toinclude the Pro applications. For information on how to update your path, see�Running Pro Applications and Tools� on page 40.

Additional Documentation

For additional information about using GDB and DDD, see the GNU manuals forthose applications. The GNU GDB and DDD manuals are available via MontaVistaZone.

132 MontaVista� Linux® Professional Edition

Page 141: Monta Vista Users Guide

Chapter 7: Application DevelopmentDebugging Programs Using GDB and DDD

Example of Using GDB

Following is an example of using GDB to debug a Pentium III target system. In thedefault conÞguration for Pro, the target Þle system is NFS-mounted from the host,and the host and target see the same Þles. In this conÞguration, there is no need tostrip programs to save space on the target, and doing so prevents the GDB client fromaccessing symbol information.

Note: When working with a stripped binary on the target, the host requires a non-stripped version of the binary to facilitate symbolic-debugging. To debug programs,you need to set up debugging on the target environment and on the host environment.

Set up debugging in the target environment

In a shell on the target, with an example program called hello located in the target�susr/bin directory, you can begin debugging in the target environment, as in theexample below. Bold indicates user input.

<targetIPaddress or name>: cd /usr/bin<targetIPaddress or name>: gdbserver host:2345 helloProcess hello created; pid = 18

On the GDB server command line, 2345 is the network port number on which theserver waits for a connection from the client. This can be any available port numberon the target. Following this argument is the name of the program to be debugged(hello).

Set up debugging in the host environment

To connect to a server on a Pentium III target where Voyager is the machine nameand the port is 2345, you can begin debugging in the host environment as shown inthe example below. Bold indicates user input.

$ cd /my_work_directory/myfilesystem/target/usr/bin

$ pentium3-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 youare welcome to change it and/or distribute copies of it under certainconditions.

Type "show copying" to see the conditions.

There is absolutely no warranty for GDB. Type "show warranty" fordetails.

This GDB was configured as "--host=i686-pc-linux-gnu --target=i686- linux".

(gdb) target remote Voyager:2345

Remote debugging using Voyager:2345

0x3000ffbc in ?? ()

(gdb)

MontaVista� Linux® Professional Edition 133

Page 142: Monta Vista Users Guide

Chapter 7: Application DevelopmentDebugging Programs Using GDB and DDD

Example of Using GDB and DDD Together

Following is an example of using GDB and DDD together to debug a Pentium IIItarget system. In the default conÞguration for Pro for Pentium III, the target Þlesystem is NFS-mounted from the host, and the host and target see the same Þles. Inthis conÞguration, there is no need to strip programs to save space on the target, anddoing so prevents the GDB client from accessing symbol information. Bold indicatesuser input.

Note: When working with a stripped binary on the target, the host requires a non-stripped version of the binary to facilitate symbolic debugging.

1. On the target, to debug a program called disbmp, use the command:

gdbserver host:1000 disbmp penguin1.bmp

1000 is the network port number on which the server waits for aconnection from the client. This can be any available port number on thetarget. Following this are the name of the program to be debugged(dispbmp) and any arguments to that program (penguin1.bmp).Something similar to the following will be output to the console:

Process disbmp created; pid = 38

2. On the host, change directories to where you disbmp is located. Usethe command:

cd /my_work_directory/myfilesystem/testprograms

3. Enter the following command:

ddd --debugger pentium3-gdb --gdb disbmp

4. At the GDB command prompt in DDD, enter the following command:

target remote Voyager:1000

This command causes another line of output on the target consolesimilar to the following:

Remote debugging using Voyager:1000

Voyager is the machine name and the port is 1000. You can nowbegin debugging in the host environment using the interface provided byDDD.

5. Set a breakpoint on main by double clicking or entering on thecommand line: b main

6. Click the cont button.

134 MontaVista� Linux® Professional Edition

Page 143: Monta Vista Users Guide

Chapter 7: Application DevelopmentDebugging Programs Which Call fork(), vfork(), and execve()

Debugging Programs Which Call fork(), vfork(), and execve()

The version of GDB included with Pro allows you to debug programs which callfork(), vfork(), and execve().

To stop execution when the debugged program calls fork, vfork, or execrespectively, use one of the following commands:

catch fork

catch vfork

catch exec

To continue debugging the parent process after a fork or vfork event (this is thedefault), use the command:

set follow-fork-mode parent

To debug the child process after a fork or vfork event, use the command:

set follow-fork-mode child

MontaVista� Linux® Professional Edition 135

Page 144: Monta Vista Users Guide

Chapter 7: Application DevelopmentDebugging Multi-Threaded Applications

Debugging Multi-Threaded ApplicationsWith the current version of GDB, threads now be debugged in a cross environment.Just use gdbserver as normal. Some additional things to keep in mind aboutthreads:

� Threads in Linux are not child processes of the creator thread � allthreads are peers.

� The Þrst pthread_create call actually creates two threads;one is the thread manager and one is the thread called for.

DDD provides a threads status window which can be used to switch to a particularthread and to set a break point. There are two ways to set a break point with threadsusing DDD:

� You can specify the address of the break point and the threadnumber.

� Or you can attach to the thread and then set the break point.

Additional Information

There are several good sources of information about threads available.

Note: MontaVista Software does not endorse any of the books or Web sites (otherthan our own) listed in this section. Examples are provided for your convenience only.

Books

Pthreads Programming. by Bradford Nichols, Dick Buttlar and Jacqueline ProulxFarrell. O'Reilly & Associates, 1996ISBN: 1565921151 POSIX

Web Sites

The Linux Threads FAQ on MontaVista Zonehttp://support.mvista.com//content/AppInfo/LinuxThreadsFAQ.html

Links to additional thread FAQs are available on MontaVista Zone:http://support.mvista.com//content/AppInfo/index.html#Threads

136 MontaVista� Linux® Professional Edition

Page 145: Monta Vista Users Guide

Chapter 7: Application DevelopmentAdditional Tools for Programming and Debugging

Additional Tools for Programming and DebuggingThe following tools have been found to be valuable time-savers in developing anddebugging Linux applications. Many of these applications are free-source andavailable from the sites listed below and through MontaVista Zone at:

http://support.mvista.com/content/DevEnv/

MontaVista Software provides no support for these tools; however, we will answerquestions about use of the tools to the best of our abilities.

The tools are: cbrowser, cflow, cscope, dmalloc, ltrace, mtrace,strace, and showasm.

cbrowser cbrowser is a C/C++ source-code indexing, querying and browsing tool.cbrowser is composed of a small number of Tcl source code Þles.

cbrowser can be downloaded from:

� http://www.ziplink.net/~felaco/cbrowser/

cßow cflow reads a list of source Þles and prints a graph of the program's function callhierarchy. Called functions are indented with respect to their calling functions.

cflow can be downloaded from:

� http://metalab.unc.edu/pub/Linux/devel/lang/c/!INDEX.short.html

cscope cscope is an interactive screen-oriented tool that helps answer questions such as:

� Where is this symbol used?

� Where is the symbol deÞned?

� Where did this variable get its value?

� What is the value of this global symbol?

� Where is a function in the source Þles?

� What other functions call a function?

� What functions are called by a function?

� Where does the message �<some string>� come from?

� Where is a source Þle in the directory structure?

� What Þles include a header Þle?

MontaVista� Linux® Professional Edition 137

Page 146: Monta Vista Users Guide

Chapter 7: Application DevelopmentAdditional Tools for Programming and Debugging

cscope builds a symbol database that can be searched for the answers to thosequestions. It searches the database and displays a window of the Þles, which can thenbe opened in your favorite editor.

cscope can be downloaded from:

� http://cscope.sourceforge.net

dmalloc dmalloc is a memory allocation debugger that supports both C++ and threading.

dmalloc is part of the Pro distribution. More information about how to usedmalloc can be found by reading the man page for dmalloc.

ltrace ltrace is used to intercept and record dynamic library calls that are called by theexecuted process and the signals that are received by that process.

ltrace is part of the Pro distribution. More information about how to use ltracecan be found by reading the man page for ltrace.

mtrace There is a feature of the GNU C Library called mtrace. Using this feature allowsyou to detect memory leaks caused by unbalanced malloc and free calls. mtraceis implemented as a function call to turn on tracing. When implemented, mtracecreates a log Þle of addresses malloc'd and free'd. A perl script is used todisplay the log Þle listing only the unbalanced combinations and, if the source Þle isavailable, the line number of the source where the malloc occurred.

The key to using the mtrace feature is using these two items from the GNU CLibrary:

� the mcheck.h Þle

� the MALLOC_TRACE environment variable

If the MALLOC_TRACE variable is not set, then the effect of mtrace is disregarded.

For further information on the mtrace feature, read the libc info page andview the Memory Allocation section. In particular, within the MemoryAllocation section, see the section on Allocation Debugging.

Information on mtrace was the April 2001 Tip and Trick article on MontaVistaZone (http://support.mvista.com/content/TipArchive/april2001.html), which includedsample programs and scripts.

138 MontaVista� Linux® Professional Edition

Page 147: Monta Vista Users Guide

Chapter 7: Application DevelopmentAdditional Tools for Programming and Debugging

strace strace is a focused debugging tool for tracing system calls and signals byintercepting and recording system calls called and received by a process.

strace is part of the Pro distribution. More information about how to use stracecan be found by reading the man page for strace.

showasm showasm displays a C/C++ Þle and the assembly code produced from it in a way thatis easy to read. It is easy to Þgure out which assembly code each C-source linegenerated. Color is used to make the output easier to read.

showasm can be downloaded from MontaVista Zone.

MontaVista� Linux® Professional Edition 139

Page 148: Monta Vista Users Guide

Chapter 7: Application DevelopmentUsing AltiVec� Technology by Motorola

Using AltiVec� Technology by Motorola

AltiVec� technology provides general-purpose processing for PowerPCmicroprocessors while concurrently addressing high-bandwidth data processing andalgorithmic-intensive computations in a single-chip solution.

Using AltiVec technology can:

� provide multichannel modems, echo cancellation equipment, andbase-station processing

� enable encryption methods optimized for the SIMD processingmodel

� enhance performance for multimedia-oriented desktop computers,desktop publishing, and digital video processing

� enable real-time processing of data streams (MPEG-2 encode,continuous speech recognition, real-time high-resolution 3Dgraphics, etc.)

Features When using Motorola's AltiVec technology with Pro:

� assembler supports AltiVec instructions -- allows user applicationsto be written with in-line assembly AltiVec code

� the Kernel and C Library support saving and restoring AltiVecregisters

� the C library supports the use of setjmp and longjmp incombination with AltiVec code

Limitations No direct support is available for AltiVec C extensions. MontaVista Software isevaluating these extensions.

The kernel currently ignores VRSAVE and saves all registers when switchingbetween two user tasks running AltiVec code. These actions:

� may hide errors when using VRSAVE in user code

� may cause problems in the future if optimizations to use VRSAVEto determine which registers to save and restore are implemented inthe kernel

140 MontaVista� Linux® Professional Edition

Page 149: Monta Vista Users Guide

Chapter 7: Application DevelopmentUsing AltiVec� Technology by Motorola

Additional Information

Additional information about AltiVec is available at:

� http://altivec.org

� Motorola's AltiVec Programming Environments Manual:http://e-www.motorola.com/collateral/CT_ALTIVECPEM_R1.pdf

� AltiVec Programmers's Interface Manual:http://e-www.motorola.com/brdata/PDFDB/MICROPROCESSORS/32_BIT/POWERPC/ALTIVEC/ALTIVECPIM.pdf

MontaVista� Linux® Professional Edition 141

Page 150: Monta Vista Users Guide
Page 151: Monta Vista Users Guide

Chapter 8: System Integration

Overview

Once you have Þnished developing your kernel and application, you are ready tobegin deployment of your embedded application. The Þrst thing you need to do isintegrate your system components (the kernel and the application) in a testenvironment.

The steps listed below are guidelines. You may need to change the order ofintegration, depending on the type of Þle system you have or other developmentneeds. To integrate your system components, complete the following steps:

1. Create your Þle-system hierarchy and add your custom applications.

2. Boot the target and NFS-mount your Þle system.

3. ConÞgure the user-space environment.

4. Test your environment.

5. Reduce the size of your Þle system.

6. ProÞle your embedded application.

Additional information about these steps is provided in the following sections.

MontaVista� Linux® Professional Edition 143

Page 152: Monta Vista Users Guide

Chapter 8: System IntegrationOverview

Once you have completed the steps above, you should have a system that appears asfollows:

Host

Local Network

Serial

.....................................

Target

Pro ---------------Red Hat 7.3

Custom KernelNFS Root File System

Custom Apps

User-Space Configs

Target File System

144 MontaVista� Linux® Professional Edition

Page 153: Monta Vista Users Guide

Chapter 8: System IntegrationCreating Your File-System Hierarchy

Creating Your File-System HierarchyOnce you are satisÞed with your kernel and application, you need to determine whichadditional libraries and applications are required to support your application so thatyou can build a Þle system.

Typically, creating your Þle-system hierarchy consists of the following steps:

1. Select the type of Þle system you want to use for deployment.

2. Use TCT to select the applications and packages provided byMontaVista that you need in your embedded system.

3. Add your custom applications to the Þle system hierarchy created byTCT.

Guidelines on how to complete the above steps are included in the sections below.

Select a Deployment File-System Type

Knowing which ßash, memory, and disk drive provided by the board in your productwill determine the size and type of your Þle system, which in turn will dictate howmany applications can be included. You should know the type of Þle system you wantto use in your deployed product before creating the Þle-system hierarchy. DifferentÞle systems have different constraints.

For many embedded systems, Þle-system size is a major consideration, as many targetboards do not have the storage-device capacity for a large Þle system. For that reason,you may wish to use a ßash Þle system such as JFFS or a compressed Þle system suchas CramFS. In addition, MontaVista Software also provides a tool for reducing thesize of your Þle system by removing unused applications and code.

If storage space is not a limiting factor for your Þle system, you have a much widerrange of choices. One choice is ReiserFS, a journaling Þle system, which can be agood choice if your embedded application will need to be turned on and off on aregular basis. Another option is EXT2 (or the update EXT3), a fairly common,reliable, and well-tested Þle system. XFS is yet another option. The main features ofXFS include quick journaling recovery, fast transactions, high scalability, andexcellent bandwidth.

MontaVista Software supports the following Þle system types:

� CramFS

� EXT2 and EXT3

� Journaling FLASH Filesystem (JFFS)

� ReiserFS

� XFS

MontaVista� Linux® Professional Edition 145

Page 154: Monta Vista Users Guide

Chapter 8: System IntegrationCreating Your File-System Hierarchy

Not all of the Þle systems listed in this section can be used with all target boards. Tohelp you decide which Þle system you want to use, here are some notes about thefeatures and limitations for each Þle-system type. In addition, check the MontaVistaZone page for your target to obtain additional information about Þle system support.

CramFS

CramFS is a Þle system that was designed to be simple and small and is used to storeÞle systems in silicon ROMs and CDs. With CramFS, Þle sizes are limited to less than16MB, and the maximum Þle system size is a little over 256MB.

CramFS is a read-only Þle system, so unlike other Þle systems it must be createdalong with its contents. Once the image has been constructed, it can be written toßash/ROM and mounted.

CramFS is currently supported on all Pro architectures. CramFS can be used inconjunction with another Þle system and can be used with MTD (MemoryTechnology Device). Check the MontaVista Zone page for your target for informationabout the support for this feature on your target.

More information about CramFS can be found at:

� http://www.linuxhq.com/kernel/v2.3/doc/Þlesystems/cramfs.txt.html

CramFS is often used with handhelds. Some additional information about usingCramFS with handhelds can be found on the following Web site:

� http://www.handhelds.org

EXT2 and EXT3

The EXT2 Þle system is a very common Þle system (perhaps the most common).EXT2 was developed for Linux and operates on block devices such as hard disks andCD-ROM drives. EXT2 supports up to 4 Terabyte Þle system sizes and Þle namesizes of up to 255 characters. EXT3 is the latest version of the EXT Þle system. Twobig improvements included in EXT3 are support for access control lists (ACLs)conforming to Posix Semantics (IEEE 1992), and journaling (automatic recoverywhen the Þle system is remounted).

EXT2 is supported on all Pro architectures. EXT3 is experimental; however, it isavailable for all Pro architectures. Check the MontaVista Zone page for your targetfor information about the support for this feature on your target.

Additional information about EXT2 and EXT3 can be found on MontaVista Zone.

146 MontaVista� Linux® Professional Edition

Page 155: Monta Vista Users Guide

Chapter 8: System IntegrationCreating Your File-System Hierarchy

Journaling FLASH File System (JFFS)

The Journaling Flash Filesystem (JFFS) was developed by Axis Communications inSweden. JFFS:

� provides a Þle system directly on ßash, rather than emulating ablock device

� is designed for use on ßash-ROM chips and it recognizes ßash-ROM chips� special write requirements

� does wear-leveling to extend ßash life

� keeps the ßash directory structure in RAM at all times

� implements a log-structured Þle system which is always consistent,even if the system encounters crashes or improper power-downs --it does not require fsck upon boot

For JFFS and JFFS2, the minimum ßash size must be more than two timeserase_sector_size times the number of ßash chips that is required for garbagecollection.

JFFS has some limitations. It doesn�t do garbage collection incrementally, and itblocks read during the garbage collection erase sectors, which may last for severalseconds. In some cases, JFFS has failed after consecutive power cycles during writesto the ßash.

JFFS2 is the next version of JFFS. JFFS2 provides improved wear-levelling andgarbage-collection performance; improved RAM footprint and response to system-memory pressure, improved concurrency and support for suspending flash erases;marking of bad sectors with continued use of the remaining good sectors, thusenhancing the write-life of the devices; native data compression inside the file systemdesign; and support for hard links.

Check the MontaVista Zone page for your target for information about support forthis feature on your target.

Additional information about JFFS is available at:

� http://support.mvista.com/content/IntDep/Þlesystems/Þlesystems-ßash.html

Includes information about how to put JFFS on Flash Devices, thesupplied MTD Utilities (in /usr/sbin), and some frequentlyasked questions about JFFS and MTD.

� http://developer.axis.com/software/jffs/

� http://www.linux-mtd.infradead.org/

MontaVista� Linux® Professional Edition 147

Page 156: Monta Vista Users Guide

Chapter 8: System IntegrationCreating Your File-System Hierarchy

� ftp://ftp.uk.linux.org/pub/people/dwmw2/mtd/cvs/mtd/mtd-jffs-HOWTO.txt

ReiserFS

ReiserFS is a journaling Þle system. The main beneÞt of ReiserFS is that there is noneed for a lengthy Þle-system check (fsck) when the system is rebooted. Duringnormal operation, ReiserFS logs all changes to Þle-system structure (metadata) to aspecial journal area on the disk. Upon reboot, this journal area is consulted to restoreÞle-system consistency without examining the entire Þle system, as is required fornon-journaling Þle systems.

The ReiserFS journal area is currently Þxed in size at 30 megabytes. This makesReiserFS unsuitable for Þle systems that are less than about 100 megabytes in size.

ReiserFS is currently supported on all Pro architectures. Check the MontaVista Zonepage for your target for information about the support for this feature on your target.

Additional information about ReiserFS is available at:

� http://www.reiserfs.com

� http://support.mvista.com/content/IntDep/Þlesystems/Þlesystems-block.html

XFS

XFS is a journaling Þle system developed by SGI and used in IRIX operating systemfrom SGI. XFS combines advanced journaling technology with full 64-bit addressingand scalable structures and algorithms. The main features of XFS include quickjournaling recovery, fast transactions, high scalability, and excellent bandwidth.

XFS provides the following beneÞts:

� sub-second Þle system recovery after crashes, which means no longfscks or worrying about metadata corruption

� 64-bit scalability

� support for extremely large disk farms -- no more 2GB limits(millions of terabytes, millions of Þles and a million Þles perdirectory)

� two terabyte Þle system limit is due to the Linux block device I/Olayer

� extremely scalable using Btrees extensively to support large and/orsparse Þles and extremely large directories

� resizing

148 MontaVista� Linux® Professional Edition

Page 157: Monta Vista Users Guide

Chapter 8: System IntegrationCreating Your File-System Hierarchy

� Four GB memory limit

XFS limitations include:

� does not support LILO

� does not support GRUB

� the IDE driver available in the Pro release has a 137 GB blockaddressing limitation effectively limiting the maximum Þle systemsize to 137 GB

SGI XFS is currently supported on all Pro architectures. Check the MontaVista Zonepage for your target for information about support for this feature on your target.

Additional information about SGI XFS is available at:

� XFS FAQhttp://oss.sgi.com/projects/xfs/faq.html

� Complete information and source tree http://oss.sgi.com/projects/xfs/

Additional information

More information about the Þle systems supported by Pro can be found onMontaVista Zone at:

� http://support.mvista.com/content/IntDep/Þlesystems/index.html

Information about how to enable the Þle system for deployment can be found in�Deployment� on page 171.

Use TCT to Select Applications

We recommend that you use TCT to select the packages you wish to include in yourÞle system. As you select packages for your Þle system, if the package has adependency on another package, that package is automatically installed with theselected package. TCT will also tell you the size of your Þle system. Once you haveselected your packages, you can use TCT to generate a tar-archive of the Þle system.

Warning! The check boxes only show the packages you selected. If a package has adependency on another package, that package is automatically installed with theselected package; however, the check box for that package remains unchanged.

To create your Þle system hierarchy, complete the following steps:

1. Use TCT to select the libraries and applications that you want to includein your Þle system.

2. Use TCT to build the Þle system. TCT creates a tar-archive of the Þlesystem.

MontaVista� Linux® Professional Edition 149

Page 158: Monta Vista Users Guide

Chapter 8: System IntegrationCreating Your File-System Hierarchy

3. Extract the Þle system into a build directory (for example,myfilesystem).

For more information about each of the above steps see �Using TCT� on page 68 and�Using the Tar Archive Created by TCT� on page 72.

Add Your Custom Application

After using TCT to create your Þle system and extracting the Þle system tar-archive toa build directory (for example, myfilesystem), the next step is to add youapplication. Copy your application to where you want it to reside in the target Þlesystem.

The default Þle system layout of the target follows the Filesystem Hierarchy Standard(FHS). When deciding where to place your application, we recommend that youfollow the FHS guidelines. For more information, see:

� http://www.pathname.com/fhs/

150 MontaVista� Linux® Professional Edition

Page 159: Monta Vista Users Guide

Chapter 8: System IntegrationBooting the Target and NFS-Mounting Your File System

Booting the Target and NFS-Mounting Your File System

Once your Þle-system hierarchy and your kernel are ready to test, you need to bootthe target with the new kernel and NFS-mount your Þle system. The kernel is eitherthe one you modiÞed for your embedded application, or, if you chose not to modifythe kernel, it is the default kernel supplied by MontaVista Software. If you used TCTto develop your kernel, your kernel image is included in the tar archive created byTCT. For more information, see �Using the Tar Archive Created by TCT� on page 72.

To boot the target with the new kernel, complete the steps listed in �Booting theTarget with a Custom Kernel� on page 52.

Note: The instructions include NFS mounting the target�s root Þle system. Byexporting the Þle system directory as NFS, you can test your environment on thetarget before spending the development time to reduce the size of the Þle system oradding the Þle system to ßash.

MontaVista� Linux® Professional Edition 151

Page 160: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

ConÞguring the User-Space EnvironmentOnce you have installed Pro and completed your kernel, application and Þle-systemdevelopment, and you have exported the Þle-system directory as NFS, the next step insystem integration is to tailor your target�s user-space environment to yourapplication. While we cannot anticipate the particulars of every situation, someexamples of common setups are provided below. This section contains informationabout the following conÞguration settings and tools:

� �Enable Run-Level Services (Startup Scripts)� on page 152

� �ConÞgure the Target for Serial Console or Virtual Terminal� onpage 156

� �Create Standard Device Nodes� on page 158

� �Add Shells� on page 158

� �Start PCMCIA� on page 160

� �ConÞgure Networking� on page 160

Enable Run-Level Services (Startup Scripts)

initdconfig is used to enable run-level services for initscripts. For moreinformation about initscripts, see �Initscript overview� on page 154.

initdconfig is part of the Pro distribution and can be used either on the target(initdconfig) or on the host. as a cross-development application(<architecture-prefix>-initdconfig). See �Running Pro Applicationsand Tools� on page 40 for more information about how to update your executablepath to easily run this script and how to access man and info pages.

The following is the command line help for initdconfig:

Usage: initdconfig --add <name> ... initdconfig --del <name> ... initdconfig --list [name ...] initdconfig [--level <levels>] <name> <on|off|reset> initdconfig --help initdconfig --version

Levels - S Startup 0 halt 1 Single User 2 Multiuser (No networking) 3 Normal/Multiuser (w/ networking) 4 reserved for local use (same as 3) 5 xdm or equiv graphic login 6 reboot

Note: The levels indicated in the help are guidelines. They are not hard and fast rules.

152 MontaVista� Linux® Professional Edition

Page 161: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Listing the run levels of initscripts

To list the run levels of your initscripts, use the command:

initdconfig --list [name ...]

For example, if you ran initdconfig --list, the output would appear similarto this:

In the above example:

� The initscripts, umountfs and umountnfs.sh execute in runlevels 0 and 6. They are both enabled in those run levels.

� urandom may be enabled in the start run level, but is not enabled.

� ifupdown may be enabled in the start run level and is enabled.

� cron and anacron both may be enabled in run levels 2, 3, 4, and5. They are not enabled in any of the run levels.

Enabling an initscript

To enable an initscript in all run levels (speciÞed by the initscript), use the--add option followed by the initscript name.

initdconfig --add <name> ...

For example, if you want to enable cron in all levels, use the command:

initdconfig --add cron

To enable an initscript in only some run levels, use the --level option. Use thecommand:

initdconfig [--level <levels>] <name> <on|off|reset>

For example, if you want cron to only run in levels 3 and 4, use the command:

initdconfig --level 34 cron on

mountfs 0:on 6:onumountnfs.sh 0:on 6:onurandom S:offifupdown S:oncron 2:off 3:off 4:off 5:offanacron 2:off 3:off 4:off 5:off

MontaVista� Linux® Professional Edition 153

Page 162: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Disabling an initscript

To disable an initscript in all run levels (speciÞed by the initscript) use the --deloption, followed by the initscript name. Use the command:

initdconfig --del <name> ...

For example, if you want to disable cron in all levels, use the command:

initdconfig --del cron

To disable an initscript in only some run levels, use the --level option. Use thecommand:

initdconfig [--level <levels>] <name> <on|off|reset>

For example, if you want to disable the run levels 3 and 4 for cron, use thecommand:

initdconfig --level 34 cron off

Note: The reset option (in place of on/off) Þrst turns the run levels off and then turnsthem back on. In general, this option is not needed for normal operation.

Initscript overview

The initscripts are located in /etc/init.d on the target, and they are run from the/etc/rc.d/rc{S,0,1,2,3,4,5,6}.d directories. Symbolic links are createdby the initdconfig program (see �Enable Run-Level Services (Startup Scripts)�on page 152) in the rc?.d directory pointing to the Þles in the /etc/init.ddirectory. The symbolic links are named SXXname or KXXname. Here is what eachcomponent of those names means:

� S indicates the scripts should be started in that run level.

� K indicates scripts should be stopped when that run level is entered.

� XX is used to give the initscripts a numerical order to allow theinitscripts to run in a given order.

� The name is identical to the name of the script in /etc/init.d.

When the system boots, the /etc/inittab Þle Þrst runs the script /etc/init.d/rcS. The/etc/init.d/rcS script is responsible for starting all of thescripts in /etc/rc.d/rcS.d. Once those scripts have been started, control isreturned to sysvinit.

When run levels change, /etc/init.d/rc is run with the argument of the newrun level. This script is responsible for stopping all of the services beginning with a Kat the speciÞed run-level and higher-numbered run levels and starting all of theservices beginning with an S at the speciÞed run level and lower-numbered run levels.

154 MontaVista� Linux® Professional Edition

Page 163: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Initscript example. The initscripts are located in /etc/init.d on the target. The script /etc/init.d/skeleton is a sample script. Similar to most initscripts, it contains thefollowing line:

# chkconfig: 2345 20 20

In this line:

� The keyword is: chkconfig:

� The starting run levels are: 2345

� The starting priority is: 20

� The stopping priority is: 20

Note: The # indicates that it is a comment in the shell script; this line is interpreted bythe initdconfig program.

Starting run levels may be any combination of S, 0, 1, 2, 3, 4, 5, and 6. The startingrun level implies the stopping run level. If you specify S as the starting run level thenthe stopping run levels are automatically 0 and 6. If you specify 0, 1, 2, 3, 4, 5, or 6then the non-speciÞed run levels are automatically the stopping run levels.

For example:

chkconfig: 2345 x y

starts in run levels 2, 3, 4, 5 and stops in run levels 0, 1, and 6.

The starting and stopping priority numbers are used to help order the start and stopprocesses. If there are two items with the same start/stop priority there is no guaranteeto the order in which they will run/stop.

If either the start or stop priorities are 0 then the script does not start or stop. Forexample, chkconfig: S 20 0 indicates that it starts as priority 20 in run level S.But it is never stopped. Conversely chkconfig: S 0 20 would indicate that it isnever started, but stops in run levels 0 and 6.

The /etc/init.d/skeleton example also shows the parameters mostinitscripts contain:

� start starts the item

� stop stops the item

� reload reloads the item if possible (usually by sending aSIGHUP)

MontaVista� Linux® Professional Edition 155

Page 164: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

� restart and force-reload should stop and then restart thedaemon (force-reload is only implemented if reload isimplemented.)

ConÞgure the Target for Serial Console or Virtual Terminal

The /etc/inittab Þle on your target is used to conÞgure the target for use with aserial console or virtual terminal.

Once the target has been booted, edit the /etc/inittab Þle to reßect the setup youare using (serial console or virtual terminal.)

Example Þles are included in the Pro distribution for both virtual terminals (videoconsoles) and serial consoles. Comments are included in the example Þles to help youdetermine which conÞguration is right for you.

On the next page is an example /etc/inittab Þle.

To conÞgure the target:

1. Open the /etc/inittab Þle for editing.

2. Disable any console login prompts. Comment out the following line byadding a �#� at the beginning:

con:2345:respawn:/sbin/getty console

3. Enable the correct console for your system by uncommenting the linefor your console (removing the �#� at the beginning.)

4. Save your changes.

Examples

If you want only one �virtual terminal,� uncomment the following line:

#1:2345:respawn:/sbin/getty 38400 tty1

If your device has a serial port, and you want a login prompt to come over the serialport, you need to uncomment one of the following lines (depending on which serialport you are using):

#T0:23:respawn:/sbin/getty -L ttyS0 9600 vt100#T1:23:respawn:/sbin/getty -L ttyS1 9600 vt100

Note: For some boards you may need to edit this line because the serial port is onttySA0 instead of ttyS0 (StrongARM boards are like this.)

Note: By default a serial console is only available in run levels 2 and 3. You may alsowish to change 23 to 2345 to ensure that a login prompt is available in run levels 2, 3,4 and 5.

156 MontaVista� Linux® Professional Edition

Page 165: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Here is an sample /etc/inittab Þle:

Sample /etc/inittab file

# /etc/inittab: init(8) configuration.# $Id: inittab,v 1.8 1998/05/10 10:37:50 miquels Exp $

# The default runlevel.id:2:initdefault:

# Boot-time system configuration/initialization script.# This is run first except when booting in emergency (-b) mode.si::sysinit:/etc/init.d/rcS

# What to do in single-user mode.~~:S:wait:/sbin/sulogin

# /etc/init.d executes the S and K scripts upon change# of runlevel.## Runlevel 0 is halt.# Runlevel 1 is single-user.# Runlevels 2-5 are multi-user.# Runlevel 6 is reboot.

l0:0:wait:/etc/init.d/rc 0l1:1:wait:/etc/init.d/rc 1l2:2:wait:/etc/init.d/rc 2l3:3:wait:/etc/init.d/rc 3l4:4:wait:/etc/init.d/rc 4l5:5:wait:/etc/init.d/rc 5l6:6:wait:/etc/init.d/rc 6# Normally not reached, but fallthrough in case of emergency.z6:6:respawn:/sbin/sulogin

# What to do when CTRL-ALT-DEL is pressed.ca:12345:ctrlaltdel:/sbin/shutdown -t1 -a -r now

# Action on special keypress (ALT-UpArrow).kb::kbrequest:/bin/echo "Keyboard Request--edit /etc/inittab to let this work."

# What to do when the power fails/returns.pf::powerwait:/etc/init.d/powerfail startpn::powerfailnow:/etc/init.d/powerfail nowpo::powerokwait:/etc/init.d/powerfail stop

# This line is provided to give that out of box experience. # In reality you should uncomment the proper devices.con:2345:respawn:/sbin/getty console# /sbin/getty invocations for the runlevels.## The "id" field MUST be the same as the last# characters of the device (after "tty").## Format:# <id>:<runlevels>:<action>:<process>#1:2345:respawn:/sbin/getty 38400 tty1#2:23:respawn:/sbin/getty 38400 tty2#3:23:respawn:/sbin/getty 38400 tty3#4:23:respawn:/sbin/getty 38400 tty4#5:23:respawn:/sbin/getty 38400 tty5#6:23:respawn:/sbin/getty 38400 tty6

# Example how to put a getty on a serial line (for a terminal)##T0:23:respawn:/sbin/getty -L ttyS0 9600 vt100#T1:23:respawn:/sbin/getty -L ttyS1 9600 vt100

# Example how to put a getty on a modem line.##T3:23:respawn:/sbin/mgetty -x0 -s 57600 ttyS3

MontaVista� Linux® Professional Edition 157

Page 166: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Create Standard Device Nodes

The MAKEDEV script can be used to create any standard device node. In most cases,you will run MAKEDEV from the /dev directory on the target as MAKEDEV createsdevice nodes in the current directory.

The MAKEDEV script is a target application available as part of the Pro distribution.See �Running Pro Applications and Tools� on page 40 for more information about thehow to update your executable path to easily run this script.

Examples

To create the device nodes /dev/hda[1-20] and /dev/hdb[1-20], on thetarget, enter the following commands:

cd /dev./MAKEDEV ide0

To create the framebuffer device nodes (/dev/fbX and /dev/fbXautodetect,and /dev/fbXcurrent where x=0-7) on the target, enter the followingcommands:

cd /dev./MAKEDEV fb

To create all of the normal audio device nodes, on the target, enter the followingcommands:

cd /dev./MAKEDEV audio

Add Shells shellconfig is used to add shells to the /etc/shells Þle and to set thesymbolic link that sets /bin/sh on the target.

shellconfig is part of the Pro distribution and can be used either on the target(shellconfig) or the host as a cross-development application(<architecture-prefix>-shellconfig). See �Running Pro Applicationsand Tools� on page 40 for more information about the how to update your executablepath to easily run this script and how to access the man and info pages for thisapplication.

The following is the command line help for shellconfig:

Usage: shellconfig --add <name> <priority> shellconfig --del <name> ... shellconfig --list [name ...] shellconfig --help shellconfig --version

If you are using shellconfig as a cross-development application, you need to usethe architecture and processor preÞx in the commands in the following sections(<architecture-prefix>-shellconfig).

158 MontaVista� Linux® Professional Edition

Page 167: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Listing the shells installed

To list the shells installed, use the command:

shellconfig --list [name...]

For example, if you ran shellconfig --list, you would receive output similarto the following:

Name Priority POSIX Shell (sh)/bin/ash: 10 yes/bin/ash.static: 11 yes/bin/bash: 1 yes/usr/bin/sash: 50 yes/bin/sh is linked to /bin/bash.

This output indicates that the following four shells are installed:

� ash

� ash.static

� bash

� sash

The lower the priority number, the more likely that the application is the target of the/bin/sh symbolic link. If the priority is negative, then the shell is not POSIX, andis therefore not capable of being the target of the /bin/sh symbolic link.

Adding a shell

You can add a shell from the conÞguration Þles with the --add option. When addinga shell with --add, the <name> Þeld is the full path (as seen by the target) to theshell and then the priority number.

For example, to add the shell /bin/something with priority level 5, use thecommand:

shellconfig --add /bin/something 5

Removing a shell

You can remove a shell from the conÞguration Þles with the --del option. You maylist as many shells on the command line as you want and each of them will beremoved from the list. When deleting a shell, the <name> Þeld is the full path (asseen by the target).

For example, to remove the shells /bin/something and /bin/otherthing,use the command:

shellconfig --del /bin/something /bin/otherthing

MontaVista� Linux® Professional Edition 159

Page 168: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

Start PCMCIA Pro provides pre-built PCMCIA. Check the MontaVista Zone page for your target forinformation about support for this feature, along with information about the cardstested and enabled with your LSP.

Note: If your application requires a type of card not tested or enabled by MontaVistaSoftware, you need to enable the PCMCIA driver in the kernel conÞguration andrebuild the kernel. For more information about rebuilding the kernel, see �Buildingand ConÞguring the Kernel� on page 76.

Once PCMCIA is enabled in the kernel, to start PCMCIA, on the target, enter thefollowing command:

/etc/init.d/pcmcia start

The above command loads the card services modules and starts the cardmgrdaemon.

To start PCMCIA at boot, use the utility initdconfig either on the host or thetarget. (See �Enable Run-Level Services (Startup Scripts)� on page 152.)

ConÞgure Networking

For networking, DHCP is conÞgured by default in Pro LSPs. Pro also enables theloopback device by default. An entry for eth0 is not necessary, because the LSPsenable the auto IP option in the kernel. When you are ready to build a stand-alonesystem for deployment, you may wish to use a different conÞguration.

Pro includes Internet Protocol Version 6 (IPv6). The sections below provideinformation about IPv6, an example to show how to set-up a minimal network usingeither IPv4 or IPv6, and information about MontaVista Net (a PCI-based back-panelcommunication product).

IPv6

Internet Protocol Version 6 (IPv6) is the next generation of the internal protocol and isbeginning to replace the more standard IPv4. IPv6 adds many improvements overIPv4 in areas such as routing, network autoconÞguration, security, and scalability. Themost signiÞcant change is that IPv6 uses 128bit address space (4 times longer thanIPv4) allowing for more available addresses.

Note: Some IPv6 speciÞcations are NOT supported. For more information, seeMontaVista Zone.

Enabling IPv6

IPv6 is enabled as a module by default.

160 MontaVista� Linux® Professional Edition

Page 169: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

If you have turned off IPv6 or if you want to build IPv6 statically into the kernel,complete the following steps:

1. Start make menuconfig or make xconfig. The latter can be runon its own or through TCT.

2. Select Networking.

3. Enable The IPv6 protocol.

4. Save your changes.

5. Rebuild the kernel using TCT, or the procedure in �Building andConÞguring the Kernel� on page 76.

IPv6 is now built into the kernel.

Which utilities can be used with IPv6?

To use IPv6, the utilities used must be IPv6 aware. If they are not, IPv6 requests willnot be served. The following list contains the target utilities included with Pro that canbe used with IPv6:

� apache

� atm

� bsd-Þnger

� inetd

� iproute

� libinet6

� linux-ftpd

� netkit-base

� netkit-ftp

� netkit-telnet

� net-tools

� netkit-rsh

� ping

� proftp

� radvd

� sendmail

� sysklogd

� tcpdump

� tcp-wappers

� ucd-snmp

� xinetd

MontaVista� Linux® Professional Edition 161

Page 170: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

More information

More information about IPv6 can be found on the following Web sites:

� http://www.ipv6.org/Includes links to the speciÞcation, RFCs, and HOW-To

� http://people.debian.org/~csmall/ipv6/index.html

� http://people.debian.org/~csmall/ipv6/setup.html

Minimal Network Example

The following example sets up a minimal network on the target that does loopback,FTP, and Telnet.

The root Þle system needs to have networking conÞgured just as a Linux PC/Workstation would. This example assumes that you have networking enabled in the kerneland that you have loaded the appropriate packages. As an incomplete list, thesepackages include FTP, Telnet, libtermcap, and inetd.

The following parameters are used in the example below:

� Host name = test

� IPv4 IP address = 192.168.2.202

� IPv6 IP address = 3ffe:305:1002:8010::1

� NFS Þle system server with an IP = 192.168.2.190

� root Þle system = /tftpboot/nfsroot

The following Þles are also required to exist on the target:

� /etc/hostname

� /etc/hosts/

� /etc/services

� /etc/inetd.conf

� /etc/nsswitch.conf

� /etc/resolv.conf

� /etc/network/interfaces

162 MontaVista� Linux® Professional Edition

Page 171: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

The above Þles have the following format:

/etc/hostname

/etc/hosts

/etc/nsswitch.conf

/etc/resolv.conf If you want to add the target into a DNS environment, then you need to conÞgure thisÞle. You also need to add dns [!UNAVAIL=return] before the Þles in thehosts: entry in the /etc/nsswitch.conf Þle above.

/etc/network/interfacesUse the examples provided in the /etc/network/interfaces Þle to create anentry like the following to set up each Ethernet interface:

test.mvista.com

#IPv4 Address127.0.0.1 localhost localhost.localdomain192.168.2.202 test.mvista.com test 192.168.2.190 rootnfs.mvista.com rootnfs

#IPv6 addresses::1 ipv6-localhost ipv6-loopback3ffe:305:1002:8010::1 test.mvista.com test

passwd: files group: files hosts: files networks: files ethers: files protocols:files rpc: files services: files

domain mvista.com search mvista.com nameserver 192.168.14.10 nameserver 192.168.14.38

#IPv4 Addressesauto eth0iface eth0 inet static address 10.23.3.32 network 10.23.3.0 netmask 255.255.255.0 broadcast 10.23.255.255 gateway 10.23.3.1

#ipv6 addressesauto eth0iface eth0 inet6 static address 3ffe:305:1002:8010::1 netmask 64

MontaVista� Linux® Professional Edition 163

Page 172: Monta Vista Users Guide

Chapter 8: System IntegrationConfiguring the User-Space Environment

MontaVista Net

MontaVista Net is a PCI-based back-panel communication product. MontaVista Netcan be used in one of two ways:

� to off load conventional Ethernet interfaces for transactionsbetween processors in the same chassis

� as a complete replacement for Ethernet � this option allowsPeripheral Processors to boot from ßash and remote mount the rootÞle system via NFS, through the MontaVista Net back-panelinterface

Instructions for conÞguring and using MontaVista Net can be found on MontaVistaZone.

164 MontaVista� Linux® Professional Edition

Page 173: Monta Vista Users Guide

Chapter 8: System IntegrationTesting Your Environment

Testing Your Environment

At this stage in your application�s development, you should fully test yourapplication. Because every project is different and has different requirements on thesystem, how you test your project is up to you. We do, however, recommend that youdo incremental tests. By starting with a system that works, when you reduce the Þle-system size you can more easily determine which libraries and applications are stillneeded by your application. We also highly recommend doing complete testing beforeyou reduce the size of your Þle system, as in many cases, doing so will remove thesymbol information required for proper debugging.

MontaVista� Linux® Professional Edition 165

Page 174: Monta Vista Users Guide

Chapter 8: System IntegrationReducing the Size of Your File System

Reducing the Size of Your File System As many embedded applications require a small Þle system, you may need to reducethe size of your Þle system. MontaVista Software provides Library Optimizer Tool(LOT), a command line tool that is used to analyze a target Þle-system hierarchy todetermine which components of supported shared libraries are required by theincluded executables and shared libraries. LOT then rebuilds the supported sharedlibraries so they contain only the required code, which often results in a signiÞcantsize reduction.

Because LOT removes symbols used for debugging, it is important that you test anddebug your environment before reducing the size of your Þle system.

Library Optimizer Tool (LOT)

Requirements

LOT requires detailed information about the contents of the shared library. For ashared library to be supported for use with LOT, the library packages containingdetailed information about the contents of the library must be installed on the hostmachine.

Currently, two libraries distributed with Pro have the detailed optimizationinformation. They are:

� glibc

� ncurses

The library packages containing the detailed optimization information for glibcand ncurses were installed by default when you installed Pro.

Usage

LOT is a command-line tool. To run LOT, update your executable search PATH toinclude the Pro applications. Instructions on how to run Pro applications can be foundin �Running Pro Applications and Tools� on page 40.

Use of the LOT command is described below:

<architecture-prefix>-libopt [-s] [-d <destree>] <srctree>

LOT accepts the following options:

� -sStrips the optimized libraries of all debugging information.Libraries or executables in the speciÞed tree that do not have therequired optimization information are not stripped.

� -d <destree>SpeciÞes the base of the Þle hierarchy where the resulting

166 MontaVista� Linux® Professional Edition

Page 175: Monta Vista Users Guide

Chapter 8: System IntegrationReducing the Size of Your File System

optimized libraries will be placed. This directory must be adirectory that already exists.

If this option is not speciÞed, the <srctree> directory is used,and the modiÞed libraries will overwrite the existing libraries.

� <srctree>This is the name of the root of the Þle hierarchy representing theÞle-system environment that is to be optimized. This option isrequired.

We recommend that the target directory be a separate tree that you have built. Whenusing LOT, you should work in a project directory created for building your Þlesystem. In the section �Project Directories� on page 38, we recommend creating amy_work_directory/myfilesystem directory for your Þle-systemdevelopment. We also recommended that you NFS-mount the myfilesystemdirectory on the target for testing. It is assumed in the example below that themyfilesystem directory contains your target Þle system, and that it is NFS-mounted as the target�s root Þle system.

One good way to build the target directory is to untar the Þle-system tar archivecreated by TCT and then add your applications. For information about TCT, see�Target ConÞguration Tool (TCT)� on page 57.

Warning! We strongly recommend that <srctree> NOT be in the /opt/hardhat tree. We also recommend that <srctree> only contain the Þles that willbe on the target (this includes your applications). We make this recommendationbecause if a destination tree is not speciÞed, the optimizer writes over the full versionsof the libraries. If your <srctree> is in the /opt/hardhat tree, the librarypackages will have to be reinstalled to restore the full versions.

Example For this example, the target used is a PowerPC 8xx target. The base of the directoryhierarchy to be optimized is my_work_directory/myfilesystem/fs-1.The directory mylib contains the bash shell executable. The directory fs-1/libcontains the libraries for glibc that have the required detailed optimizationinformation and the libraries for myprogram that do not. The directory fs-2 iswhere the resulting modiÞed Þles are to be built.

To run LOT for this example, you would use the following procedure:

1. Change to the directory where fs-1 is located. For example:

cd my_work_directory/myfilesystem/

2. Run LOT. Use the following command:

ppc_8xx-libopt -s -d fs-2 fs-1

When LOT runs, the following occurs:

MontaVista� Linux® Professional Edition 167

Page 176: Monta Vista Users Guide

Chapter 8: System IntegrationReducing the Size of Your File System

� The Þle tree under fs-1 is scanned for executables and sharedlibraries. Standard library search rules are used, so shared librariesshould be located in the same relative directory as they will be onthe target.

� For each shared library that contains the detailed optimizationinformation (glibc in this example), LOT:

� determines which symbols and code are required

� removes the symbols not required (along with the associatedcode)

� strips the Þles of all debugging information (does not happen if-s is not speciÞed)

� rebuilds the Þles under fs-2

� For shared libraries and executables that don�t contain the requiredoptimization information (myprogram and bash shell, inthis example) LOT simply determines which symbols are required.These Þles are left in myfs unchanged (that is, not stripped and notcopied to fs-2).

� The same directory structure used in fs-1 is used in fs-2

168 MontaVista� Linux® Professional Edition

Page 177: Monta Vista Users Guide

Chapter 8: System IntegrationProfiling Your Embedded Application

ProÞling Your Embedded ApplicationOnce you have completed development of your environment, you should use proÞlingtools to evaluate the project performance and to look for memory leaks, etc. Toolssuch as Linux Trace Toolkit (LTT) and mtrace, among others, are provided with Proto help with proÞling your application. In addition, other tools that could not bedistributed with Pro, such as netperf, are available via MontaVista Zone.

MontaVista� Linux® Professional Edition 169

Page 178: Monta Vista Users Guide
Page 179: Monta Vista Users Guide

Chapter 9: Deployment

OverviewOnce you have completed development of your embedded project, you will want todisconnect the target from its reliance on the host and create a stand-aloneenvironment suitable for product deployment.

How you create a stand-alone environment for your target depends on the target.Typically, for deployment, targets are booted from ßash or from an IDE device. OtherconÞgurations that have been used involve using Compact Flash, RAW ßash or SCSIconÞgurations. Because on-board ßash and IDE solutions are most common, thismanual provides information about deployment in those conÞgurations. When you areready to create a deployment candidate, you may wish to discuss your deploymentstrategy with the MontaVista representative assigned to your account.

A stand-alone target may appear as in the diagram below:

.....................................

Target

User-Space Configs

Custom Apps

Local Root File System

Custom Kernel

MontaVista� Linux® Professional Edition 171

Page 180: Monta Vista Users Guide

Chapter 9: DeploymentOverview

In general, to make the target stand-alone, you need to complete the following tasks:

1. �ConÞguring the Kernel to Be Stand-Alone and to Enable a DeployableRoot File System� on page 173

2. �Creating a File-System Image� on page 179

3. �Setting Up Your File Systems (/etc/fstab)� on page 185

4. �Booting the New Kernel� on page 186

Additional information about these steps is included in the following sections. Oncecompleted, you should have a suitable candidate for deployment.

Note: Because there are so many differences between the supported targets andembedded projects, these steps are generic. Your target may not follow these stepsexactly as listed and you may need to perform additional steps to enable otherfunctionality. For some hints on trouble-shooting, see �Trouble-ShootingDeployment� on page 187.

172 MontaVista� Linux® Professional Edition

Page 181: Monta Vista Users Guide

Chapter 9: DeploymentConfiguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

ConÞguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

To create a deployable system, you need to conÞgure the kernel to be stand-alone andto enable a deployable root Þle system.

The kernel supplied by MontaVista Software sends BOOTP queries and NFS mountsthe root Þle system. In this conÞguration, the kernel cannot be run as a system that isstand-alone (that is, without a host or network connection). For deployment, you needto rebuild the kernel to be stand-alone.

To rebuild the kernel for a stand-alone conÞguration and to enable a deployable Þlesystem, complete the following steps:

1. Start make menuconfig or make xconfig. The latter can berun on its own or through TCT.

2. Select General setup.

3. Enable Default bootloader kernel arguments.

4. Modify the Initial kernel command string line so that the section"root=/dev/nfs rw ip=bootp" is removed or reßects thedesired stand-alone conÞguration. Some examples are below.

For a system booting from an IDE mounted on the block device hda1,the default kernel command line is:

"noinitrd root=/dev/hda1 rw"

For a system booting from ßash with the Þle system mounted usingMTD at mtdblock0, the default kernel command line is:

"noinitrd root=/dev/mtdblock0 rw"

5. Select Networking options.

6. Ensure that the IP: BOOTP support option has been disabled.

7. Return to the main menu.

8. Select File systems.

9. Select Network File Systems.

10. Ensure that the Root Þle system on NFS option has been disabled.

11. Return to the main menu.

MontaVista� Linux® Professional Edition 173

Page 182: Monta Vista Users Guide

Chapter 9: DeploymentConfiguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

12. If you are using a ßash Þle system such as JFFS/JFFS2 or CramFS andyou need to use MTD (Memory Technology Device), ensure that MTDhas been enabled in the kernel.

For targets that support MTD, MTD should be enabled by default in thekernel supplied by MontaVista Software. If you are using a customkernel or a target for which MontaVista Software does not yet supportMTD, information about how to enable MTD is included in this manual.See �MTD� on page 176.

13. Enable the root Þle system that you want to use in your embeddedsystem. For more information about the options to select for each of thesupported Þle systems, see the sections listed below:

� �CramFS� on page 175

� �EXT2 and EXT3� on page 175

� �Journaling FLASH Filesystem (JFFS)� on page 175

� �ReiserFS� on page 175

� �XFS� on page 148

Note: If you are using the default kernel, all of the above Þle systems(with the exception of EXT2) are conÞgured as modules. If you areusing the default kernel or you�ve enabled the Þle system as a module,add a line in the /etc/rc.sysinit Þle on the target to insmod themodule. See the man page for insmod for information about use andsyntax. Another option is to use modprobe rather than insmod. Seethe man page for modprobe for information about use and syntax.

14. Rebuild the kernel, using TCT or the procedure in �Building andConÞguring the Kernel� on page 76.

You now have a kernel that can be run stand-alone (that is, without a network.)

Note: Most of the supported Þle systems can be used in conjunction with another Þlesystem. This manual only covers creating a root Þle system for your target. AdditionalconÞguration not included in this manual is required if you intend to use multiple Þlesystems and/or have some Þle systems built as modules.

Warning! Do NOT boot the new kernel yet! The next step in the deployment processis to transfer your Þle system to the target. The reason we recommend rebuilding thekernel Þrst is that in many cases, you can transfer your kernel to the target systeminside of a Þle-system image.

174 MontaVista� Linux® Professional Edition

Page 183: Monta Vista Users Guide

Chapter 9: DeploymentConfiguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

CramFS To enable CramFS, ensure that the following options under Filesystems have beenenabled:

� Compressed ROM Þle system

� Simple RAM based Þle system support

Note: This option is usually enabled by default in all LSPs.

EXT2 and EXT3 To enable EXT2 or EXT3 in your kernel, ensure that one of the following optionsunder Filesystems is enabled:

� EXT2 File System support or EXT3 File System support

Journaling FLASH Filesystem (JFFS)

To use JFFS or JFFS2, ensure that the following options are enabled:

� MTD. For targets that support MTD, MTD should be enabled bydefault in the kernel supplied by MontaVista Software. If you areusing a custom kernel or a target for which MontaVista Softwaredoes not yet support MTD, information about how to enable MTDis included in this manual. See �MTD� on page 176.

� Under Filesystems:

� Journaling Flash File System (JFFS) support

� Set the level of verbosity for JFFS debugging: JFFSdebugging verbosity (0 = quiet, 3 = noisy)

You now have a kernel with a JFFS or JFFS2 Þle system enabled.

Note: The devices /dev/mtd0 and /dev/mtdblock0 are required for JFFS towork. These devices should be included automatically with the target LSPs thatsupport the ßash driver. Ensure that these devices are present. For more informationabout creating device nodes, see �Creating Standard Device Nodes� on page 124.

During boot-up of the kernel, the MTD driver prints whether the ßash has been foundor not. Also, after boot-up, the command cat /proc/mtd can be used to see thedetails of the MTD device and conÞrm that the driver is active.

ReiserFS To use ReiserFS, ensure that the following options under File systems are enabled:

� ReiserFS File System support

� Additional conÞguration options are explained here: http://www.reiserfs.com/conÞg.html.

Note: If you plan to boot the target from a ReiserFS partition, you must haveReiserFS compiled into the kernel (that is, not as a module). ReiserFS can be built as

MontaVista� Linux® Professional Edition 175

Page 184: Monta Vista Users Guide

Chapter 9: DeploymentConfiguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

a module. However, if you wish to upgrade ReiserFS later, you should still rebuild thewhole kernel and not just the module! Because interfaces to the Þle system arechanging quickly and often, bugs due to recompiling only the module can appear.Such bugs can be cryptic and difÞcult to resolve.

XFS To use XFS, ensure that the following options under File systems are enabled:

� XFS File System support

� Additional conÞguration options are explained here: http://oss.sgi.com/projects/xfs/

MTD If MTD is supported by MontaVista Software, the default kernel has MTD enabled.These instructions are provided as a convenience for those targets where MTD is notyet fully supported.

If the board only has one ßash that you want MTD support on and you only need oneMTD device and the chip is CFI (Common Flash Interface) compliant, to enableMTD support, you need to enable the following options:

� From the main menu, select Memory Technology Device (MTD).

� Enable Memory Technology Device (MTD) support.

� Select the correct ßash type, address, buswidth, etc. for your target.

See �Sample conÞg Þle� on page 178 for a sample conÞg Þle. If theMontaVista LSP for your board enables MTD/JFFS, use thesettings that are already in the conÞg Þle. Otherwise, thisinformation should be available via the board's memory map andother documentation.

Note: �One ßash� means one or more ßash chips linearly mapped into the addressspace. They can be organized as x8, x16 or x32 wide memory interfaces using one ormore x8, x16 or x32 chips. If the chip is not CFI compliant or you need more than oneßash type or partition, to enable MTD support, in addition to the options listed for asingle ßash type, you also need to create a mapping Þle to describe the ßashes andtheir partitions (devices) on the board. See the �The following is an example of amapping Þle.� on page 177 for an example.

176 MontaVista� Linux® Professional Edition

Page 185: Monta Vista Users Guide

Chapter 9: DeploymentConfiguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

Sample mapping Þle

The following is an example of a mapping Þle.

Sample mapping file

* $Id: cstm_cfi_jedec.c,v * * Mapping of a custom board with both AMD CFI and JEDEC flash in partitions. * Config with both CFI and JEDEC device support. * * Basically physmap.c with the addition of partitions and * an array of mapping info to accommodate more than one flash type per board. * * Copyright 2000 MontaVista Software Inc. * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the * Free Software Foundation; either version 2 of the License, or (at your * option) any later version. * * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN * NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. * * You should have received a copy of the GNU General Public License along * with this program; if not, write to the Free Software Foundation, Inc., * 675 Mass Ave, Cambridge, MA 02139, USA. */

#include <linux/module.h>#include <linux/types.h>#include <linux/kernel.h>#include <asm/io.h>#include <linux/mtd/mtd.h>#include <linux/mtd/map.h>#include <linux/mtd/partitions.h>#include <linux/config.h>

#if defined(CONFIG_MIPS_ITE8172) || defined(CONFIG_MIPS_IVR)#include <linux/delay.h>#endif

__u8 cstm_cfi_jedec_read8(struct map_info *map, unsigned long ofs){ return *(__u8 *)(map->map_priv_1 + ofs);}__u16 cstm_cfi_jedec_read16(struct map_info *map, unsigned long ofs){ return *(__u16 *)(map->map_priv_1 + ofs);}

__u32 cstm_cfi_jedec_read32(struct map_info *map, unsigned long ofs){ return *(__u32 *)(map->map_priv_1 + ofs);}

void cstm_cfi_jedec_copy_from(struct map_info *map, void *to, unsigned long from, ssize_t len){ memcpy_fromio(to, map->map_priv_1 + from, len);}void cstm_cfi_jedec_write8(struct map_info *map, __u8 d, unsigned long adr){ *(__u8 *)(map->map_priv_1 + adr) = d;}

MontaVista� Linux® Professional Edition 177

Page 186: Monta Vista Users Guide

Chapter 9: DeploymentConfiguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System

Sample conÞg Þle

The sample conÞg Þle below may not match your ßash. Select the option that matchesyour ßash. You need to select one of the following:

� CFI support for Intel/Sharp Extended Commands

� CFI support for AMD/Fujitsu Standard Commands

Sample config file

[*] Memory Technology Device (MTD) support [ ] Debugging --- Disk-On-Chip Device Drivers [ ] M-Systems Disk-On-Chip 1000 [ ] M-Systems Disk-On-Chip 2000 and Millennium [ ] M-Systems Disk-On-Chip Millennium-only alternative driver (see help)--- RAM/ROM Device Drivers [ ] Ramix PMC551 PCI Mezzanine RAM card support [ ] Uncached system RAM [ ] Support for RAM chips in bus mapping [ ] Support for ROM chips in bus mapping [ ] Test driver using RAM --- Linearly Mapped Flash Device Drivers [*] Common Flash Interface (CFI) support [ ] CFI Advanced configuration options [*] CFI support for Intel/Sharp Extended Commands [ ] CFI support for AMD/Fujitsu Standard Commands [ ] AMD compatible flash chip support (non-CFI) .....[ ] CFI Flash device mapped on RPX Lite or CLLF [ ] CFI Flash device mapped on AMD SC520 CDP [ ] CFI Flash device mapped on Arcom SBC-MediaGX [ ] CFI Flash device mapped on Arcom ELAN-104NC [ ] CFI Flash device mapped on StrongARM SA11x0 [ ] CFI Flash device mapped on DC21285 Footbridge [*] CFI and JEDEC Flash device mapping on custom board (04000000) Physical start address of flash mapping (01c00000) Physical length of flash mapping (4) Bus width in octets [*] JEDEC device support .....[ ] NAND Device Support --- User Modules And Translation Layers [*] Direct char device access to MTD devices [*] Caching block device access to MTD devices [ ] FTL (Flash Translation Layer) support [ ] NFTL (NAND Flash Translation Layer) support

178 MontaVista� Linux® Professional Edition

Page 187: Monta Vista Users Guide

Chapter 9: DeploymentCreating a File-System Image

Creating a File-System Image

At this point, you need to create a Þle-system image and transfer that image to thetarget.

During system integration your should have created and tested a Þle system. See,�System Integration� on page 143 for more information. For deployment you need tocomplete the following steps:

1. For some conÞgurations, the Þle-system image may contain the kernelimage along with the Þle system. Including the kernel in the Þle-systemimage is typical of systems that boot from an IDE. Separate transfer ismore typical of systems that boot from on-board ßash. If yourconÞguration needs the kernel included in the Þle-system image, add acopy of your kernel image to your Þle system.

2. Create a Þle-system image.

3. Copy the image to the target.

This section contains some hints on how to create a Þle-system image and transferthat image to the target.

CramFS CramFS is a read-only Þle system, so unlike other Þle systems, it must be createdalong with its contents. Once the image has been constructed, it can be written toßash/ROM and mounted.

To create a CramFS Þle-system image, you need to use the mkcramfs utility. Hostand target versions of mkcramfs are available.

Assuming that you are storing your kernel and Þle system in ßash, to create a CramFSÞle-system image and transfer that image to the target, complete the following steps:

1. On the host, create the CramFS Þle-system image, use the command:

mkcramfs <fsdirectory> <fsimage>

<fsdirectory> is the root directory of your Þle system and <fsimage> isthe name of the Þle-system image you want to create. For example:

mkcramfs myfilesystem image.cramfs

You now have a CramFS image that can be easily transferred to thetarget.

2. Make sure your ßash is erased.

MontaVista� Linux® Professional Edition 179

Page 188: Monta Vista Users Guide

Chapter 9: DeploymentCreating a File-System Image

3. Assuming you used MTD, copy the CramFS image to your ßash. Forexample:

cp image.cramfs /dev/mtd0

(or mtd1, mtd2... as the case may be, most likely /dev/mtd0).

Note: If you are not using MTD, how you put the image into ßashdepends on the target board you are using. At the time of this writing,speciÞcs for burning an image into ßash for each board were notavailable.

Note: CramFS can be used in conjunction with another type of Þle system. If theCramFS Þle system is not the root Þle system, mount the Þle system on the blockdevice where it will be used. (This method is useful for testing the Þle system.) On thetarget, use a command similar to the following:

mount /dev/mtdblockX /<mount-point> -t cramfs

In mtdblockX in the commands above, X is the block number.

JFFS/JFFS2 The MTD utility mkfs.jffs is used to create the JFFS/JFFS2 Þle-system image.Assuming that you are storing your kernel and Þle system in ßash and that you areusing MTD, to create a JFFS/JFFS2 Þle-system image and transfer it to the target,complete the following steps:

1. Place a copy of your kernel image in your Þle system.

2. On the target, use the mkfs.jffs utility to make a JFFS image Þle.For example:

/usr/sbin/mkfs.jffs -d myfilesystem -o image.jffs

Note: If you are using JFFS2, use the mkfs.jffs2 utility in thecommand above.

3. Make sure your ßash is erased.

4. Assuming you used MTD, copy the JFFS image to your ßash. Forexample:

cp image.jffs /dev/mtd0

(or mtd1, mtd2... as the case may be, most likely /dev/mtd0).

Note: You may also mount an erased mtdblock device directly withoutputting a Þle system on it. This will let you Þll the device interactivelyunder your shell control (that is, copy stuff to the mounted directory).

180 MontaVista� Linux® Professional Edition

Page 189: Monta Vista Users Guide

Chapter 9: DeploymentCreating a File-System Image

The steps above assume that MTD has been enabled in the kernel. MTD is enabled bydefault for LSPs for which MTD is supported. For more information about MTD, see�MTD� on page 176.

EXT2/EXT3 Assuming you are using an IDE device to store your kernel and Þle system, to createand populate an EXT2/EXT3 Þle system for deployment, complete the followingsteps:

1. On the target, use the utility mkfs.ext2 to create a Þle system.

Warning! Creating a Þle system deletes all data on the device where theÞle system will reside.

Use the following command:

mkfs.ext2 /dev/<block-device>

<block-device> is the block device where you wish to create the Þlesystem such as hda1. The block device can have multiple partitions.For more information about partitions, we recommend reading the manpages for parted and fdisk.

The mkfs.ext2 utility, parted, and fdisk are part of the Prodistribution. For more information, see �Running Pro Applications andTools� on page 40 and �Accessing man and info Pages� on page 44.

2. Mount the new partition.

mount /dev/<block-device> /<mount-point> -t ext2

<mount-point> is any mount point you choose. For example:

mount /dev/hda1 /testlocation -t ext2

You now have a kernel with a working EXT2 or EXT3 Þle system.

3. Populate your target�s Þle system with everything that you want it tocontain. Make a tar archive of the Þle-system hierarchy that you createdduring system integration, move the archive to the new location, anduntar the archive.

For example, to move the Þle system in the NFS-mounted directorymy_work_directory/myfilesystem to the new location, on thetarget, use the command:

(cd /my_work_directory/myfilesystem; tar cf - .) | (cd /testlocation; tar xf -)

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

When you boot the kernel in the next step you should have a system running an EXT2Þle system as the root Þle system.

MontaVista� Linux® Professional Edition 181

Page 190: Monta Vista Users Guide

Chapter 9: DeploymentCreating a File-System Image

If desired, convert the EXT2 Þle system to an EXT3 Þle system. To convert yourEXT2 Þle system to EXT3, you need to use the tune2fs utility to add a journal toyour existing EXT2 Þle system. To add journaling to an EXT2 Þle system created onthe bock device, hda1, complete the following steps:

1. Run the following command:

tune2fs -j /dev/hda1

2. Edit the /etc/fstab Þle to change EXT2 to EXT3 on the matchinglines.

Note: To prevent the Þle system from being mounted as EXT2, you need to useinitrd to boot the target.

ReiserFS Assuming you are using an IDE device to store your kernel and Þle system, to createand populate a ReiserFS Þle system for deployment, complete the following steps:

1. On the target, use the utility mkreiserfs to create a Þle system.

Warning! Creating a Þle system deletes all data on the device where theÞle system will reside.

Use the following command:

mkreiserfs /dev/<block-device>

<block-device> is the block device where you wish to create the Þlesystem, such as hda1. You can have multiple partitions. For moreinformation about partitions, we recommend reading the man pages forparted and fdisk.

The mkreiserfs utility, parted, and fdisk are part of the Prodistribution. For more information, see �Running Pro Applications andTools� on page 40 and �Accessing man and info Pages� on page 44.

2. Mount the new Þle system. Use the following command:

mount /dev/<block-device> /<mount-point> -t reiserfs

<mount-point> is any mount point you choose. For example:

mount /dev/hda1 /testlocation -t reiserfs

You now have a working ReiserFS Þle system.

3. Populate your target�s Þle system with everything that you want it tocontain. Make a tar archive of the Þle-system hierarchy that you createdduring system integration, move the archive to the new location, anduntar the archive.

182 MontaVista� Linux® Professional Edition

Page 191: Monta Vista Users Guide

Chapter 9: DeploymentCreating a File-System Image

For example, to move the Þle system in the NFS-mounted directorymy_work_directory/myfilesystem to the new location, on thetarget, use the command:

(cd /my_work_directory/myfilesystem; tar cf - .) | (cd /testlocation; tar xf -)

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

When you boot the kernel in the next step you should have a system running aReiserFS Þle system as the root Þle system.

XFS Assuming you are using an IDE device to store your kernel and Þle system, to createand populate an XFS Þle system for deployment, complete the following steps:

1. On the target, use the utility mkfs to create a Þle system.

Warning! Creating a Þle system deletes all data on the device where theÞle system will reside.

Use the following command:

mkfs -t xfs /dev/<block-device>

<block-device> is the block device where you wish to create the Þlesystem, such as hda1. After you build a partition that is the same size asthe XFS Þle system you want to create, you can use the above commandto create a Þle system on it. For more information about partitions, werecommend reading the man pages for parted and fdisk.

2. Mount the new Þle system. Use the following command:

mount /dev/<block-device> /<mount-point> -t xfs

<mount-point> is any mount point you choose. For example:

mount /dev/hda1 /testlocation -t xfs

You now have a working XFS Þle system.

3. Populate your target�s Þle system with everything that you want it tocontain. Make a tar archive of the Þle system hierarchy that you createdduring system integration, move the archive to the new location, anduntar the archive.

MontaVista� Linux® Professional Edition 183

Page 192: Monta Vista Users Guide

Chapter 9: DeploymentCreating a File-System Image

For example, to move the Þle system in the NFS-mounted directorymy_work_directory/myfilesystem to the new location, on thetarget, use the command:

(cd /my_work_directory/myfilesystem; tar cf - .) | (cd /testlocation; tar xf -)

(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)

When you boot the kernel in the next step you should have a system running an XFSÞle system as the root Þle system.

184 MontaVista� Linux® Professional Edition

Page 193: Monta Vista Users Guide

Chapter 9: DeploymentSetting Up Your File Systems (/etc/fstab)

Setting Up Your File Systems (/etc/fstab)

The Þle /etc/fstab on your target describes your Þle systems. You need to editthis Þle to ensure that the Þle systems you are using are available. You also need toedit this Þle to make sure your swap partitions are available.

Sample 1 Here is a sample /etc/fstab for a system with the an EXT2 root Þle system at/dev/hda6, an EXT3 boot partition /boot at /dev/hda1, the proc Þle system at/proc, and a swap partition at /dev/hda5.

Sample 2 Here is a sample /etc/fstab for a system with an EXT 3 root Þle system at /dev/md1, an EXT3 boot partition /boot at /dev/md0, and the proc Þle system at /proc. This sample does not include a swap partition.

#/etc/fstab#device directory type options#

/dev/hda6 / ext3 defaults/dev/hda1 /boot ext3 defaults proc /proc proc defaults /dev/hda5 swap swap defaults

#/etc/fstab#device directory type options dump pass#/dev/md1 / ext3 defaults,errors=remount-ro 0 0/dev/md0 /boot ext3 defaults,errors=remount-ro 0 0proc /proc proc defaults 0 0

MontaVista� Linux® Professional Edition 185

Page 194: Monta Vista Users Guide

Chapter 9: DeploymentBooting the New Kernel

Booting the New Kernel

How you conÞgure and boot the target depends on the Þrmware used on the target.Before you begin to deploy your target, you should read your target�s vendordocumentation for more information about using the board�s Þrmware or forinformation about hardware conÞgurations. If you have additional questions abouthow to conÞgure and boot a particular target for deployment, contact yourMontaVista representative. Booting the target, usually consists of the following steps:

1. Hardware setup. Hardware setup may include changing DIP switches orshorting jumpers to permit the board to boot from ßash. Hardwarechanges are target speciÞc.

2. Minicom (or other terminal emulation program) conÞguration. You needto use Minicom to communicate with your target. You should use thesame communication parameters that you used during development.

3. Target conÞguration. The Þrmware on the target may need to beconÞgured for booting from ßash or booting from an IDE. Thecommands are Þrmware speciÞc.

4. If the kernel was not included in the Þle-system image, transfer thekernel to a storage device on the target. Typically, this is a ßash deviceor an IDE. The commands for transferring the kernel are ÞrmwarespeciÞc.

5. Booting the target. To boot the target, the Þrmware often requires acommand to begin the boot sequence. The commands are ÞrmwarespeciÞc.

You should now have a system that is a suitable candidate for deployment. If yourtarget does not boot as expected, or you do not have proper access to your Þle system,some solutions to common problems can be found in �Trouble-ShootingDeployment� on page 187.

186 MontaVista� Linux® Professional Edition

Page 195: Monta Vista Users Guide

Chapter 9: DeploymentTrouble-Shooting Deployment

Trouble-Shooting Deployment

Corrupt File System

If you would like to check the integrity of your Þle system, use one of the followingcommands:

For an EXT2/EXT3 Þle system, use the fsck utility. Run the following command:

fsck /dev/<block-device>

For a ReiserFS Þle system, use the resierfsck utility. Run the followingcommand:

resierfsck /dev/<block-device>

MontaVista� Linux® Professional Edition 187

Page 196: Monta Vista Users Guide
Page 197: Monta Vista Users Guide

Appendix A: Pro File-System Layout

OverviewThere are two main components to the Þle-system layout used for Pro: the cross-

development environment layout and the target layout. The cross-developmentenvironment file-system layout was created with several goals in mind: Procomponents must be self-contained, traditional RTOS cross-development layout isneeded, and multiple architectures must be supported.

The Þle-system layout of the target follows the Filesystem Hierarchy Standard (FHS).For more information about FHS, see http://www.pathname.com/fhs/.

The sections below contain detailed descriptions of the Þle-system layout.

� �Base Directories� on page 190

� �/hardhat Directory� on page 191

� �/devkit Directory� on page 192

� �/host Directory� on page 195

MontaVista� Linux® Professional Edition 189

Page 198: Monta Vista Users Guide

Appendix A: Pro File-System LayoutBase Directories

Base DirectoriesAll of the Þles that make up the Pro cross-development environment are locatedinside of a single hardhat directory. This directory, by default, resides in the /optdirectory on the host machine�s Þle system.

The /opt directory is an established standard for Linux add-on software. However,you may install in another location. If you do install in another location, be sure toreplace /opt in all path names in this manual with the directory that you used.

Contents of Base Directories Description

/opt Default installation directory.

/hardhat Pro is fully contained in this directory. By default, the /hardhat directoryis installed within the /opt directory.

190 MontaVista� Linux® Professional Edition

Page 199: Monta Vista Users Guide

Appendix A: Pro File-System Layout/hardhat Directory

/hardhat DirectoryThe hardhat directory contains two directories that are used to segment the cross-development tools into two categories: cross tools and host tools.

More information about the tools included can be found in �Pro Applications� onpage 197.

Contents of /hardhat Directory Description

/devkit Contains cross tools and Linux kernelsource code.

/host Contains host tools.

MontaVista� Linux® Professional Edition 191

Page 200: Monta Vista Users Guide

Appendix A: Pro File-System Layout/devkit Directory

/devkit DirectoryThe /devkit directory contains one directory for each installed architecture family,a /kernel directory and an /lsp directory.

/kernel Directory The /kernel directory contains one or more versions of the MontaVista SoftwareuniÞed kernel. The kernel source located in this directory is generic and not speciÞc toany target board. The directory may also contain related items, such as functionalitypatches. This kernel is for reference only. We strongly recommend that you use thekernel located in the /lsp directory that was created speciÞcally for your referenceboard.

/lsp Directory The /lsp directory contains directories for each reference board LSP installed. Theboard directory contains a conÞgured Linux kernel source for that board. The boarddirectory may also contain board-speciÞc patches, bootloader source code,documentation and control Þles. An example of the /lsp layout for theembeddedplanet-ep8260-ppc_82xx LSP is given below:

Architecture Family Directories

Currently, the arm, mips, ppc, sh, and x86 are defined architectures. In the future,more architectures may be added to this list. These directories are used to group theprocessor types for each architecture family. The various architecture familydirectories are used to group all of the processor-speciÞc cross-development tools andassociated target Þles.

Contents of /devkit Directory Description

/kernel Generic Linux kernel source code andrelated items.

/lsp Board speciÞc Linux kernel sourcecode and related items.

/arm, /mips, /ppc, /sh,/x86, etc.

Architecture family directories.

Sample Contents of an /lsp Directory Description

/embeddedplanet-ep8260-ppc_82xx LSP directory name. In this case, the LSPdirectory name is for the Embedded PlanetEP8260 target board.

/desc Target ConÞguration Tool (TCT) conÞgurationÞle.

/linux-2.4.17_<releasecode> ConÞgured Linux kernel source.

/README LSP readme Þle.

192 MontaVista� Linux® Professional Edition

Page 201: Monta Vista Users Guide

Appendix A: Pro File-System Layout/devkit Directory

An example of the ppc architecture family is given below:

Some architecture families, such as the MIPS architecture, use a different namingscheme:

When the processor version does not adequately describe a given architecture, thearchitecture is listed by floating point and endian.

The architecture and processor directories contain the cross-development tools. Thesetools are run on the host and are tailored to a specific target. The structure of the<processor> directory is listed below:

Sample Contents of an Architecture Family Directory

Description

/devkit By default, the architecture familydirectory is installed in the /devkitdirectory.

/ppc Architecture family directory name. Inthis case, the architecture family nameis for the PowerPC processor type.

/405, /7xx, /74xx, /8xx, /82xx

Processor directory names.

Sample Contents of the MIPS Architecture Family Directory

Description

/devkit By default, the architecture familydirectory is installed in the /devkit directory.

/mips Architecture family directory name. Inthis case, the architecture family nameis for the MIPS processor type.

/fp_be /nfp_be, /fp_le, /nfp_le

Processor directory names.

Processor Directory Structure Description

<architecture> The architecture family directory. Bydefault, the <processor> directoryis installed in the architecture familydirectory.

<processor> Processor directory name, such as ppc,mips, etc.

/bin Cross-development tools.

/doc Documentation Þles.

/etc ConÞguration Þles.

/include Host include Þles.

/info Information pages.

MontaVista� Linux® Professional Edition 193

Page 202: Monta Vista Users Guide

Appendix A: Pro File-System Layout/devkit Directory

/bin Directory The /bin directory contains the various cross-development tools. These toolsinclude the cross-compiler, assemblers, debuggers, etc. It may also include targetconfiguration tools, and other target-specific items.

/etc Directory The /etc directory contains user-changeable conÞguration information for thevarious tools in the /bin directory. This is analogous to the /etc directory of astandard Linux system. This directory may be empty.

If a program requires configuration information, it will look in the user s /homedirectory first, and then in the /etc directory.

/include and /lib Directories

Both the /include and /lib directories contain Þles used to develop additionalcross-development tools. The Þles in these directories are designed to build softwarefor the host architecture.

/doc, /info, and /man Directories

The /doc, /info and /man directories contain various pieces of documentation forthe cross-development tools. The /info and /man directories contain GNUinformation and Linux manual pages, respectively. The /doc directory containspieces of documentation that cover the entire package that was installed. Thisdocumentation includes license information, notes, FAQs, and other pieces ofdocumentation taken from a package�s source code.

/share and /var Directories

The /share and /var directories are analogous to the /usr/share and /vardirectories in a standard Linux Þle system. These may be used for internationalizationand other data Þles required by a cross-development tool.

/lib Host libraries.

/man man pages.

/share Program data Þles.

/var Program data Þles.

<architecture-canonical-name>

Used by GNU tools.

/target Full target Þle system, build/run-timelibraries, etc. This directory can beNFS-mounted on the target.

Processor Directory Structure Description

194 MontaVista� Linux® Professional Edition

Page 203: Monta Vista Users Guide

Appendix A: Pro File-System Layout/host Directory

/host DirectoryThe /host directory contains various tools and applications that are to be run on thehost system and are target independent. While these tools are target independent, theyare required to assist in software development. This directory contains severalsubdirectories:

The structure and purpose of these directories is similar to the cross-developmenttools listed above.

/bin Directory The /bin directory contains the host tools. Programs in these directories aid ingeneric system development. These tools may include programs to augment a host�senvironment.

/etc Directory The /etc directory contains conÞguration information for the various tools in the/bin directory. This is analogous to the /etc directory of a standard Linux system.This directory may be empty.

If a program requires configuration information, it will look in the user s homedirectory first, and then in the /etc directory.

/include and /lib Directories

Both the /include and /lib directories contain Þles used to develop additionalhost tools. The Þles in these directories are designed to build software for the hostarchitecture.

/doc, /info, and /man Directories

The /doc, /info and /man directories contain various pieces of documentation forthe cross-development tools. The /info and /man directories contain GNUinformation and Linux manual pages, respectively. The /doc directory containspieces of documentation that cover the entire package that was installed. Thisdocumentation includes license information, notes, FAQs, and other pieces ofdocumentation taken from a package�s source code.

Contents of the /host Directory Description

/host Host tools (executable Þles).

/bin Cross-development tools.

/doc Documentation Þles.

/etc ConÞguration Þles.

/include Host include Þles.

/info Information pages.

/lib Host libraries.

/man man pages.

/share Program data Þles.

/var Program data Þles.

MontaVista� Linux® Professional Edition 195

Page 204: Monta Vista Users Guide

Appendix A: Pro File-System Layout/host Directory

/share and /var Directories

The /share and /var directories are analogous to the /usr/share and /vardirectories in a standard Linux Þle system. These may be used forinternationalization, and for other data Þles required by a cross-development tool.

196 MontaVista� Linux® Professional Edition

Page 205: Monta Vista Users Guide

Appendix B: Pro Applications

Overview

Pro includes over 280 application packages. Applications are classiÞed as �cross-development applications,� �host applications,� or �target applications.�

Cross-development applications are tools that are run on the host but produce outputintended to run on the target. In general, the cross-development applications arecompilers, linkers, or similar tools. For the list of cross-development applications, see�Cross-Development Application Packages� on page 198.

Host applications provide tools that are run on one of the supported host platforms:SuSE, Red Hat, Solaris, etc. These applications do not relate to the target in any way �they simply provide an environment on the host in which development can take place.An example would be the TFTP server for those hosts that do not have a compatibleversion of TFTP. For the list of host applications, see �Host Application Packages� onpage 200.

Target applications are intended to be used only on the corresponding architecturetarget. The Pro distribution contains pre-compiled and pre-packaged versions of theseapplication packages so that RPM can be used to install them on the target. Fordevelopment, we recommend that NFS be used to provide the target root Þle system.The Þle system served by NFS is considered part of the target system, and thereforecontains only target application packages (that is, �host� and �cross-development�packages are not installed into this NFS portion of the Þle system). For the list oftarget applications, see �Target Application Packages� on page 204.

Note: man and/or info pages are available for many of the applications included. manpages for target applications are not available when using a Solaris host. For moreinformation about using man and info pages, see �Accessing man and info Pages� onpage 44.

MontaVista� Linux® Professional Edition 197

Page 206: Monta Vista Users Guide

Appendix B: Pro ApplicationsCross-Development Application Packages

Cross-Development Application PackagesThe chart below lists the cross-development applications included in the Prodistribution, along with some notes about the applications. Applications are installedby default unless marked as optional in the �Notes� column. Optional applicationscan be installed using the Pro installation script described in �Installing, Upgrading,or Removing Optional Packages� on page 32, using the �Package Name� listed in the�Notes� column.

Note: MontaVista Software does not endorse any of the books or Web sites (otherthan our own) listed in this section. Examples are provided for your convenience only.

Application Package Version Notes Reference Books and Web Sites

binutils 2.11.2 Installed: Default

Description: Cross version of binutils.

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation isfrom 1995; however, it doescontain a good introduction toGNU programming.

bootldr-assabet 2.13.2 Installed: Default for StrongARM targets

Description: Bootloader for the Intel® Assabettarget.

cross-<architecture-prefix>-libtool

1.3.5 Installed: Default

Description: Cross version of libtool for agiven target architecture. Provides the utilitylibtoolize.

If you are building an open-source package using libtool, you need to run the libtoolize utility in this package before building the applica-tion to ensure that the proper libtool control Þles are used. For example: <architecture-prefix>_libtoolize --force --copy

filesystem-arch 2.0 Installed: Default

Description: Creates directories with ownership.Needed by rpm.

filesystem-processor 2.0 Installed: Default

gcc 3.2.1 Installed: Default

Description: Cross version of gcc for a giventarget architecture.

Version change from the Pro 2.1 distribution

Using and Porting the GnuCompiler Collection Gcc Richard StallmaniUniverse.comISBN: 059510035X

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.

198 MontaVista� Linux® Professional Edition

Page 207: Monta Vista Users Guide

Appendix B: Pro ApplicationsCross-Development Application Packages

gdb 5.1 Installed: Default

Description: Cross version of gdb for a giventarget architecture.

Debugging with GDB: TheGNU Source-Level DebuggerRichard M. Stallman, RolandH. PeschUniverse.comISBN: 0595149197

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.

glib 1.2.10 Installed: Default

Description: Cross version of glib for a giventarget architecture.

hardhatutils 1.14 Installed: Default

Description: Various utilities.

ksymoops 2.4.3 Installed: Default

Description: Kernel crash dump analyzer.

ldd 1.0 Installed: Default

Description: Cross version of ldd for a giventarget architecture.

linux86 0.15.4 Installed: Default (x86 only)

Description: Real-mode linker and assembler forx86.

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 199

Page 208: Monta Vista Users Guide

Appendix B: Pro ApplicationsHost Application Packages

Host Application PackagesThe chart below lists the host applications included in the Pro distribution along withsome notes about the applications. Applications are installed by default unless markedas optional in the �Notes� column. Optional applications can be installed using thePro installation script described in �Installing, Upgrading, or Removing OptionalPackages� on page 32, using the package name listed in the �Notes� column.

Note: MontaVista Software does not endorse any of the books or Web sites (otherthan our own) listed in this section. Examples are provided for your convenience only.

Application Package Version Notes Reference Books and Web Sites

autoconf 2.13 Installed: Solaris hosts only

Description: Creates scripts to conÞgure sourcecode packages using templates.

automake 1.4p4 Installed: Solaris hosts only

Description: Automatically creates makeÞle.in�sfrom makeÞle.am�s.

bash 2.05a Installed: Solaris hosts only

Description: Bourne-Again shell

binutils 2.10.91.0.2 Installed: Solaris hosts only

Description: Solaris version of binutils.

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation isfrom 1995; however, it doescontain a good introduction toGNU programming.

bison 1.28 Installed: Solaris hosts only

Description: GNU Project parser generator(yacc replacement)

bzip2 1.0.2 Installed: Solaris hosts only

Description: A block-sorting Þle compressor

cetools 0.3 Installed: Default

Description: Set of tools used to convertMicrosoft® bootable binary images

db 3.2.9 Installed: Solaris hosts only

Description: Database access methods

ddd 3.3.1 Installed: Default

Description: Data Display Debugger � agraphical front end to GDB

ethload 1.2 Installed: Default

Description: Used to load a Microsoft® bootablebinary image via the bootme protocol

filesystem 2.0 Installed: Default

Description: Host-based Þle-system developmentkit

fileutils 4.1 Installed: Solaris hosts only

Description: File utilities

200 MontaVista� Linux® Professional Edition

Page 209: Monta Vista Users Guide

Appendix B: Pro ApplicationsHost Application Packages

findutils 4.1.7 Installed: Solaris hosts only

Description: Find utilities

flex 2.5.4 Installed: Solaris hosts only

Description: A a tool for generating programsthat perform pattern-matching on text

gawk 3.1.0 Installed: Solaris hosts only

Description: The GNU Project's implementationof the AWK programming language

gcc 2.95.3 Installed: Solaris hosts only

Description: Solaris version of gcc

Using and Porting the GnuCompiler Collection Gcc Richard StallmaniUniverse.comISBN: 059510035X

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.

gettext 0.10.35 Installed: Solaris hosts only

Description: GNU internationalization utilities

grep 2.4.2 Installed: Solaris hosts only

Description: Used to print lines matching apattern

gzip 1.2.4 Installed: Solaris hosts only

Description: Used to compress or expand Þles

hardhatutils 1.14 Installed: Default

Description: Miscellaneous utilities used by Proapplications

jflash-assabet 1.2 Installed: Default

Description: Flash tool for the Intel® Assabet

kdelibs 2.2.1 Installed: Default

Description: KDE library used by KDevelop

kdevelop 2.0.1 Installed: Default

Description: C and C++ integrated developmentenvironment

ldd 1.0 Installed: Default

Description: Prints the shared libraries requiredby each program speciÞed on the command line

lesstif 0.92.6 Installed: Default

Description: motif-like library required forddd

libtool 1.3.5 Installed: Solaris hosts only

Description: Generic library support script

ltt 0.9.5a Installed: Default

Description: Linux Trace Toolkit

Version change from the Pro 2.1 distribution

The LTT Reference manual isdistributed with the LTTpackage and once installed,can be found in /opt/hardhat/host/doc/hll-host-ltt-0.9.5a/index.html.

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 201

Page 210: Monta Vista Users Guide

Appendix B: Pro ApplicationsHost Application Packages

m4 1.4 Installed: Solaris hosts only

Description: The GNU macro processor

make 3.79.1 Installed: Solaris hosts only

Description: GNU make utility to maintaingroups of programs

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation isfrom 1995; however, it doescontain a good introduction toGNU programming.

minicom 1.83.0 Installed: Solaris hosts only

Description: Host-to-target communication tool.

mkcramfs 2.4.16 Installed: Default

Description: Used to make a cramfs Þle-systemimage

modutils 2.4.13 Installed: Solaris hosts only

Description: Linux module utilities

ncurses 5.2 Installed: Solaris hosts only

Description: The ncurses library routines givethe user a terminal-independent method ofupdating character screens with reasonableoptimization

patch 2.5.4 Installed: Solaris hosts only

Description: Used to apply a diff Þle to anoriginal

pcmcia-cs 3.1.30 Installed: Default

Description: PCMCIA card services

perl 5.6.1 Installed: Solaris hosts only

Description: Practical Extraction and ReportLanguage

platformtest 0.1.2 Installed: Default

Description: ConÞguration utilities and scriptsfor compiling Pro sources

python 2.0 Installed: Solaris hosts only

Description: Required for TCT

qt 2.3.1 Installed: Default

Description: Name space for miscellaneous identiÞers that need to be global-like

rpm 4.0 Installed: Solaris hosts only

Description: A powerful package manager thatcan be used to build, install, query, verify, update,and uninstall individual software packages.

rpmconfig 2.4.10.1 Installed: Default

Description: ConÞguration utilities and scriptsfor compiling Pro sources

sed 3.02 Installed: Solaris hosts only

Description: A stream editor

shellutils 2.0.11 Installed: Solaris hosts only

Description: Various shell utilities

Application Package Version Notes Reference Books and Web Sites

202 MontaVista� Linux® Professional Edition

Page 211: Monta Vista Users Guide

Appendix B: Pro ApplicationsHost Application Packages

tar 1.13.19 Installed: Solaris hosts only

Description: The GNU version of the tararchiving utility

tcl 8.3.2 Installed: Solaris hosts only

Description: Tcl scripting language

texinfo 4.0b Installed: Solaris hosts only

Description: GNU Documentation system

tftp-hpa 0.17 and 0.31 Installed: Default

Description: Host TFTP program

Version change from the Pro 2.1 distribution

Version 0.17 is installed by default

tk 8.3.2 Installed: Solaris hosts only

Description: TK scripting language

tsload 1.0.0 Installed: Default

Description: Bootloader for various targets

zlib 1.1.3 Installed: Solaris hosts only

Description: A compression and decompressionlibrary

zsrec 1.0 Installed: Default

Description: Needed to produce MotorolaS-Records format

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 203

Page 212: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

Target Application PackagesThe chart below lists the target applications included in the Pro distribution alongwith some notes about the applications. Applications are installed by default unlessmarked as optional in the �Notes� column. Optional applications can be installedusing the Pro installation script described in �Installing, Upgrading, or RemovingOptional Packages� on page 32, using the �Package Name� listed in the �Notes�column.

Note: MontaVista Software does not endorse any of the books or Web sites (otherthan our own) listed in this section. Examples are provided for your convenience only.

Application Package Version Notes Reference Books and Web Sites

adduser 3.24 Installed: Default

Description: Allows users to be added to group orpassword Þles

anacron 2.3 Installed: Default

Description: A cron-like program that can runjobs lost during downtime

Requires cron

apache 1.3.20 Installed: Default

Description: The most widely used Web server onthe Internet

Apache: The DeÞnitive GuideBen Laurie, Peter Laurie,Robert Denn (Editor)O'Reilly & AssociatesISBN: 1565925289

ash 0.3.8 Installed: Default

Description: A smaller version of the Bourneshell (sh). Functionality of interest: sh,ash.static

at 3.1.8 Installed: Default

Description: Job spooling tools

aumix 2.7 Installed: Default

Description: Sound utility

autoconf 2.13 Installed: Default

Description: A GNU tool for automaticallyconÞguring source code

GNU Autoconf, Automake, andLibtoolGary V. Vaughan, Ben Elliston,Tom Tromey, Ian Lance TaylorNew Riders PublishingISBN: 1578701902

autofs 3.1.7 Installed: Default

Description: A tool for automatically mountingand unmounting Þle systems

automake 1.4p4 Installed: Default

Description: A GNU tool for automaticallycreating makeÞles

GNU Autoconf, Automake, andLibtoolGary V. Vaughan, Ben Elliston,Tom Tromey, Ian Lance TaylorNew Riders PublishingISBN: 1578701902

base-files 2.1.PRO Installed: Default

Description: Contents of /etc directory

base-passwd 3.2.0 Installed: Default

Description: Default password and group Þle

204 MontaVista� Linux® Professional Edition

Page 213: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

bash 2.05a Installed: Default

Description: A GNU Bourne Again shell (bash)

Advanced Bash-ScriptingGuideMendel Cooperhttp://linuxdoc.org/LDP/abs/html/index.html

bind 9.1.3 Installed: Default

Description: A DNS (Domain Name System)server

DNS and BIND (4th Edition)Paul Albitz, Cricket LiuO'Reilly & AssociatesISBN: 0596001584

bind 1.28 Installed: Default

Description: The most widely used DNS serveron the Internet

binutils 2.10.91.0.2 Installed: Default

Description: A GNU collection of binary utilities.Functionality of interest: addr2line, ar, as,gasp, nm, objcopy, objdump, ranlib

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation isfrom 1995;however it doescontain a good introduction toGNU programming.

bison 1.28 Installed: Default

Description: A GNU general-purpose parsergenerator

bonnie++ 1.92 Installed: Default

Description: Hard disk bench marking suite

Minor revision update from HHL 2.0

bootldr-assabet 2.13.2 Installed: Default

Description: Bootloader for the Intel® Assabet

bridge-utils 0.9.3 Installed: Default

Description: Utilities to conÞgure the Linuxnetworking bridge interface

bsd-finger 0.17 Installed: Default

Description: Finger client and server

busybox 0.60.2 Installed: default

Description: Multi-call binary capable ofreplacing mount, etc.

Because this package is a multi-call binary, callingit via a different name changes the functionality.

For example, �ln -s busybox ls; ls� willcall busybox with the name ls and causebusybox to �act� like ls.

To automatically activate the links, use TCTto create your Þle system.

bzip2 1.0.2 Installed: Default

Description: A Þle-compression utility

checker 0.9.9.1 Installed: Default - IA-32/x86 only

Description: GNU version of a Purify (memoryleak checker) tool

console-data 1999.08.29 Installed: Default

Description: VGA console fonts

console-tools 0.2.3 Installed: Default

Description: Tools for conÞguring the console

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 205

Page 214: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

cpio 2.4.2 Installed: Default

Description: A GNU archiving program

cprof 1.0.1 Installed: Default � IA-32/x86 only

Description: Thread-safe proÞler

cproto 4.6d Installed: Default

Description: Generates function prototypes andvariable declarations from C code

cracklib 2.7 Installed: Default

Description: Library needed for passwordprocessing

cron 3.0p11 Installed: Default

Description: Manages system resources and launch events/tasks

db 3.2.9 Installed: Default

Description: Berkeley db

devfsd 1.3.11 Installed: Default

Description: Dynamic dev directory daemon. Itautomatically represents present devices

dhcp-client 2.0p|5 Installed: Optional

Package Name: hhl-<architecture>-<processor>-dhcp-client

Description: A DHCP (Dynamic Host ConÞguration Protocol) server and relay agent

The DHCP Handbook:Understanding, Deploying,and Managing AutomatedConÞguration ServicesTed Lemon, Ralph E. DromsPearson Higher Education ISBN: 1578701376

dhcpcd 1.3.19p|5 Installed: Default

Description: A DHCP client

The DHCP Handbook:Understanding, Deploying,and Managing AutomatedConÞguration ServicesTed Lemon, Ralph E. DromsPearson Higher Education ISBN: 1578701376

diff 2.7 Installed: Default

Description: Creates source patches. Includes cmp

dmalloc 4.8.2 Installed: Default

Description: Debug memory allocation utility

dnrd 2.1.0 Installed: Default

Description: Domain name relay daemon

dump 0.4b23 Installed: Default

Description: File-system backup and restore

e2fsprogs 1.22 Installed: Default

Description: Programs for backing up and restoring Þle systems

ed 0.2 Installed: Default

Description: A line-oriented text editor

editline 1.12 Installed: Default

Description: A BSD licensed for the �readline�functionality

Application Package Version Notes Reference Books and Web Sites

206 MontaVista� Linux® Professional Edition

Page 215: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

eject 2.0.2 Installed: Default

Description: A program that ejects removablemedia using software control

exim 3.34 Installed: Default

Description: Local mail handlerRequired by cron

expect 5.32.2 Installed: Default

Description: A program that �talks� to otherinteractive programs based on a script

fbgetty 0.1.4 Installed: Default

Description: Framebuffer getty program forsimple graphical environments.

fbset 2.1 Installed: Default

Description: Tools for managing a framebuffer'svideo mode properties

file 3.33 Installed: Default

Description: A utility for determining Þle types

filesystem 2.0 Installed: Default

Description: The basic directory layout for aLinux system

fileutils 4.1 Installed: Default

Description: The GNU versions of common Þle-management utilitiesFunctionality of interest: fdisk, chgrp,chmod, chown, cp, dd, df, du, ln, ls,mkdir, mknod, mv, rm, rmdir.

findutils 4.1.7 Installed: Default

Description: The GNU versions of Þnd utilities(find and xargs)Functionality of interest: find

flex 2.5.4 Installed: Default

Description: A tool for creating scanners (textpattern recognizers)

gawk 3.1.0 Installed: Default

Description: The GNU version of the awk textprocessing utility

GAWK: The GNU AWK User'sGuideArnold RobbinsFree Software FoundationISBN: 1882114272

gbdm 1.7.3 Installed: Default

Description: A GNU set of database routineswhich use extensible hashing

gcc 3.2.1 Installed: Default

Description: Various compilers (C, C++,Objective-C, Chill, etc.)

Version change from the Pro 2.1 distribution

Using and Porting the GnuCompiler Collection Gcc Richard StallmaniUniverse.comISBN: 059510035X

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation is from 1995;however it does contain a good introduction to GNU programming.

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 207

Page 216: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

gdb 5.1 Installed: Default

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

Debugging with GDB: TheGNU Source-Level DebuggerRichard M. Stallman, RolandH. PeschUniverse.comISBN: 0595149197

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.

genromfs 0.3 Installed: Default

Description: Utility for creating romfs Þlesystems

gettext 0.10.35 Installed: Default

Description: GNU libraries and utilities forproducing multi-lingual messages

glib 1.2.10 Installed: Default

Description: A library of handy utility functions.

glibc 2.2.5 Installed: Default

Description: The GNU libc librariesFunctionality of interest: ldd, ldconfig

Version change from the Pro 2.1 distribution

gpm 1.19.6 Installed: Default

Description: A mouse server for the Linuxconsole

grep 2.4.2 Installed: Default

Description: The GNU versions of grep patternmatching utilities

Grep: Searching for a PatternAlain MagloireiUniverse.comISBN: 0595100392

groff 1.17.2 Installed: Default

Description: A document formatting system

gzip 1.2.4 Installed: Default

Description: The GNU data compressionprogramFunctionality of interest: gzip, gunzip, zcat

hardhatutils 1.14 Installed: Default

Description: Contains various utilities foradministrating a machine, for exampleinitdconfig and shellconfig

The package hardhatutils-which isoptional. The package name is hhl-<architecture>_<processor>-hardhatutils-which

hdparm 3.9a Installed: Default

Description: A utility for displaying and/orsetting hard disk parameters

hostname 2.09 Installed: Default

Description: Sets system host nameRequired by initscripts

Application Package Version Notes Reference Books and Web Sites

208 MontaVista� Linux® Professional Edition

Page 217: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

ifupdown 0.6.4 Installed: Default

Description: Enables/disables network interfaces

ilmtk 0.2 Installed: Default

Description: Interrupt Latency Toolkit

ipgrab 0.8.2 Installed: Default

Description: Network debugging tool similar totcpdump

iproute 2.2.4 Installed: Default

Description: Enhanced IP routing and networkdevice conÞguration tools

iptables 1.2.2 Installed: Default

Description: Used to set up kernel packet Þlteringrules

Revision update from HHL 2.0

jed B0.99.12 Installed: Default

Description: A fast, compact editor based on theS-Lang screen library

The package jed-rgrep is optional. The pack-age name is hhl-<architecture>_<pro-cessor>-jed-rgrep

kernel Installed: Default

Description: The Linux kernel (the core of theLinux operating system)

kernel-headers Installed: Default

Description: Header Þles for the Linux kernel

ksymoops 2.4.3 Installed: Default

Description: Crash dump analyzer (part of thekernel)

lcap 0.0.6 Installed: Default

Description: tcpdump-like program

Revision update from HHL 2.0

less 358 Installed: Default

Description: A text Þle browser similar to more,but better

libcap 1.10 Installed: Default

Description: Library for manipulating POSIX.1estyle �capabilities�

libelf 0.7.0 Installed: Default

libjpeg 6b Installed: Default

Description: A library for manipulating JPEGimage format Þles

liblockfile 1.01.2 Installed: Default

Description: Library and application to do safeÞle locking

libpcap 0.6.1 Installed: Default

libpng 1.0.8 Installed: Default

Description: A library of functions formanipulating PNG image format Þles

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 209

Page 218: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

libtiff 3.4 Installed: Default

Description: A library of functions formanipulating TIFF image format Þles

libtool 1.3.5 Installed: Default

Description: The GNU libtool, which simpliÞesthe use of shared libraries

If you are building an open-source package usinglibtool, you need to run the command:<architecture-prefix>_libtoolize --force --copybefore building the application to ensure that theproper libtool control Þles are used.

GNU Autoconf, Automake, andLibtoolGary V. Vaughan, Ben Elliston,Tom Tromey, Ian Lance TaylorNew Riders PublishingISBN: 1578701902

libungif 4.1.0b1 Installed: Default

Description: A library for manipulating GIFformat image Þles

libwww 5.2.8 Installed: Default

Description: HTTP library of common code

lilo 22.1 Installed: Default - IA-32/x86 only

Description: The boot loader for Linux and otheroperating systems

linux-ftpd 0.17 Installed: Default

Description: Version of ftp

linux86 0.15.4 Installed: Default � IA-32/x86 only

Description: Required to build and run lilo �real-mode tools

linuxinfo 1.1.7 Installed: Default

Description: Displays basic system information

lm_sensors 2.5.4-p10 Installed: Default

Description: Hardware monitoring tools

logrotate 3.5.7 Installed: Default

Description: Rotates, compresses, removes andmails system log Þles

lpr 0.50 Installed: Default

Description: Print utility

lprng 3.7.4 Installed: Optional

Package Name: hhl-<architecture>_<processor>-lprng

Description: LPRng Print Spooler

lsof 4.51 Installed: Default

Description: A utility that lists open Þles on aLinux/UNIX system

ltrace 0.3.10 Installed: Default

Description: Tracks runtime library calls fromdynamically linked executables

This application is NOT available on MIPS norSuperH targets.

Application Package Version Notes Reference Books and Web Sites

210 MontaVista� Linux® Professional Edition

Page 219: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

ltt 0.9.5a Installed: Default

Description: Linux Trace Toolkit

Version change from the Pro 2.1 distribution

lynx 2.8.4dev.20 Installed: Default

Description: A fully-featured World Wide Web(WWW) client for users running cursor-addressable, character-cell display devices

m4 1.4 Installed: Default

Description: The GNU macro processor

mailx 8.1.2 Installed: Default

Description: The /bin/mail program forsending e-mail messages

make 3.79.1 Installed: Default

Description: A GNU tool which simpliÞes thebuild process for users

http://www.oreilly.com/catalog/prognu/Programming with GNUSoftwareISBN 1-56592-112-7

Note: This documentation isfrom 1995; however, it doescontain a good introduction toGNU programming.

makedev 2.3.1 Installed: Default

Description: A program used for creating thedevice Þles in /dev

man-db 2.3.19 Installed: Default

Description: man program

man-pages 1.38 Installed: Default

Description: man page contents

memstat 0.2 Installed: Default

Description: Utility to query free memory

mgetty 1.1.26 Installed: Default

Description: A getty replacement for use withdata and fax modems

mingetty 0.9.4 Installed: Default

Description: A compact getty program for virtualconsoles only

minicom 1.83.0 Installed: Default

Description: A text-based modem control andterminal emulation program

mkcramfs 2.4.16 Installed: Default

Description: Used to make CRAMFS Þle-systemimages

modutils 2.4.13 Installed: Default

Description: Linux module utilities such asmodprob and insmod

mtd-utils 2.4.16_1.16 Installed: Default

Description: Utilities for MTD

nana 2.5 Installed: Default

Description: Debugging library

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 211

Page 220: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

nano 1.0.3 Installed: Default

Description: Pico editor replacement

ncurses 5.2 Installed: Default

Description: Replaces libtermcap andtermcap

net-tools 1.60 Installed: Default

Description: The basic tools for setting upnetworking, such as route and ifconfig

netbase 4.06 Installed: Default

Description: Provides network infrastructurecontrol Þles

netkit-base 0.10 Installed: Default

Description: Network utilitiesFunctionality of interest: inetd, ping

netkit-ftp 0.17 Installed: Default

Description: FTP client - minimal functionality

netkit-ntalk 0.17 Installed: Default

Description: Talk utility

netkit-routed 0.17 Installed: Default

Description: Route daemon that feeds routes intokernel

netkit-rsh 0.17 Installed: Default

Description: Remote shell. Needed for remoteaccess

netkit-rusers 0.11 Installed: Default

Description: User daemons for remote who, etc.

netkit-rwall 0.17 Installed: Default

Description: Remote wall

Revision update from HHL 2.0

netkit-rwho 0.17 Installed: Default

Description: Remote who

Revision update from HHL 2.0

netkit-telnet 0.17 Installed: Default

Description: Telnet client and daemon

nfs-user-server 2.2beta47 Installed: Default

Description: User space NFS servers

nfs-utils 0.3.2 Installed: Default

Description: NFS utilities and supportingdaemons for the kernel NFS server

The package nfs-kernel-server is optional. The package name is hhl-<archi-tecture>_<processor>-jnfs-kernel-server

nis 3.9 Installed: Default

Description: Network information server itemssuch as ypbind

Application Package Version Notes Reference Books and Web Sites

212 MontaVista� Linux® Professional Edition

Page 221: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

ntp 4.0.99g Installed: Default

Description: Synchronizes system time using theNetwork Time Protocol (NTP)

nvi 1.79 Installed: Default

Description: Small embedded vi � useful fordemonstrating embedded target functionality

openssh 3.0.2p1 Installed: Default

Description: OpenSSH free Secure Shell (SSH)implementation

SSH, the Secure Shell: TheDeÞnitive GuideDaniel J. Barrett, RichardSilvermanO'Reilly & Associates ISBN: 0596000111

openssl 0.9.6c Installed: Default

Description: Secure Sockets Layer Toolkit

SSL & TLS Essentials:Securing the Web Stephen A. ThomasJohn Wiley & SonsISBN: 0471383546

p2linux 0.2 Installed: Default

Description: Wind River pSOS® to Linux tool kit

http://support.mvista.com/content/AppInfo/

pam 0.72 Installed: Default

Description: A security tool which providesauthentication for applications

parted 1.4.17 Installed: Default

Description: The GNU disk partition manipulation program

patch 2.5.4 Installed: Default

Description: The GNU patch command, formodifying and upgrading Þles

pciutils 2.1.8 Installed: Default

Description: Linux PCI utilities

pcmcia-cs 3.1.30 Installed: Default

Description: PCMCIA Daemon

perl 5.6.1 Installed: Default

Description: The Perl programming language

Programming Perl (3rdEdition)Larry Wall, Tom Christiansenand Jon OrwantO'Reilly & AssociatesISBN: 0596000278

pidentd 3.0.12 Installed: Default

Description: An implementation of the RFC1413identiÞcation server

portmap 5beta Installed: Default

Description: A program which manages RPCconnections

ppp 2.4.1 Installed: Default

Description: The PPP (Point-to-Point Protocol)daemon

pro-ftpd 1.2.1 Installed: Optional

Package Name: hhl-<architecture>-<processor>-pro-ftpd

Description: ftp applications

procmail 3.15.2 Installed: Default

Description: The procmail mail processingprogram

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 213

Page 222: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

procps 2.0.7 Installed: Default

Description: Utilities for monitoring your systemand the processes on your systemFunctionality of interest: top, free, ps

psmisc 20.1 Installed: Default

Description: Utilities for managing processes onyour system

pump 0.8.3 Installed: Optional

Package Name: hhl-<architecture>-<processor>-pump

Description: A BOOTP and DHCP client forautomatic IP conÞguration

pxelinux 1.62 Installed: Default

Description: Used to facilitate a PXE boot

python 2.0 Installed: Default

Description: An interpreted, interactive object-oriented programming language

Required for using TCT

Programming Python (2ndEdition)Mark LutzO'Reilly & AssociatesISBN: 0596000855

quota 2.00 Installed: Default

Description: System administration tools formonitoring users' disk usage

rarpd 98.11.07 Installed: Default

Description: The RARP daemon

rdate 1.3.0 Installed: Default

Description: Tool for getting the date/time fromanother machine on your network

readline4 4.1 Installed: Default

Description: Library for standard line inputmanipulation. Required by bash

reiserfsprogs 3.x.1b Installed: Default

Description: Reiserfs utilities

rp-pppoe 3.3 Installed: Optional

Description: PPP on Ethernet

Package name: hhl-<architec-ture>_<processor>-rp-pppoe

rpm 4.0 Installed: Default

Description: Customized Red Hat PackageManager

Maximum RPM (RPM)Ed BaileySamsISBN: 0672311054

rstatd 3.03 Installed: Default

Description: Kernel stats daemon

rsync 2.3.2 Installed: Default

Description: A program for synchronizing Þlesover a network

rtsched-utils 0.1 Installed: Default

Description: Real-Time Scheduler utilities

Application Package Version Notes Reference Books and Web Sites

214 MontaVista� Linux® Professional Edition

Page 223: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

samba 2.2.1a Installed: Default

Description: A collection of programs thatimplements the Server Message Block (commonlyabbreviated as SMB) protocol for UNIX systems

Using Samba (O'Reilly SystemAdministration)Robert Eckstein, DavidCollier-BrownO'Reilly & AssociatesISBN: 1565924495

sash 3.4 Installed: Default

Description: A statically linked shell, includingsome built-in basic commands

sed 3.02 Installed: Default

Description: A GNU stream text editor

sendmail 8.11.6 Installed: Optional

Description: A widely used Mail Transport Agent(MTA). MontaVista Software does not provide adefault conÞguration Þle

Package Name: hhl-<architecture>-<processor>-sendmail

SendmailBryan Costales, Eric AllmanO'Reilly & AssociatesISBN: 1565922220

setserial 2.17 Installed: Default

Description: A utility for conÞguring serial ports

shadow 20000902 Installed: Default

Description: Shadow password utilities

shellutils 2.0.11 Installed: Default

Description: Set of POSIX scripts for shellfunctionalityFunctionality of interest: FALSE, TRUE, pwd,sleep, unameIncludes date

The package shellutils-hostname is optional. The package name is hhl-<archi-tecture>_<processor>-shellutils-hostname

slang 1.4.4 Installed: Default

Description: Multi-platform programmer�slibrary

socket 1.1 Installed: Default

Description: Creates an endpoint forcommunication and returns a descriptor

squid 2.4.6 Installed: Default

Description: Internet Object Cache a.k.a WebProxy

stat 2.5 Installed: Default

Description: A tool for Þnding out informationabout a speciÞed Þle

strace 4.3 Installed: Default

Description: Tracks and displays system callsassociated with a running process

sudo 1.6.5pl Installed: Default

Description: Allows restricted root access forspeciÞed users

sysklogd 1.3.31 Installed: Default

Description: System logging and kernel messagetrapping daemons

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 215

Page 224: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

systune 0.5.3 Installed: Default

Description: Kernel tuning utility and scripts

sysutils 1.3.8.1 Installed: Default

Description: Miscellaneous system tools

sysvinit 2.78 Installed: Default

Description: Functionality of interest: init

tar 1.13.19 Installed: Default

Description: A GNU Þle-archiving program

tcl 8.3.2 Installed: Default

Description: Tcl scripting language

Practical Programming in Tcland TkBrent B. WelchPrentice Hall PTRISBN: 0130220280

tcp-wrappers 7.6 Installed: Default

Description: A security tool which acts as awrapper for TCP daemons

tcpdump 3.6.2 Installed: Default

Description: A network trafÞc monitoring tool

texinfo 4.0b Installed: Default

Description: Tools needed to create Texinfoformat documentation Þles

Texinfo Manualhttp://www.gnu.org/doc/texinfo-manual.html

textutils 2.0 Installed: Default

Description: A set of GNU text Þle modifyingutilities.

tftp-hpa 0.31 Installed: Default

Description: TFTP client and server. Needed forÞle transfer and booting

Version change from the Pro 2.1 distribution

thttpd 2.21b Installed: Optional

Package Name: hhl-<architecture>_<processor>-thttpd

Description: Tiny httpd

tiff 3.4 Installed: Default

Description: A library for manipulating TIFFimage format Þles

time 1.7 Installed: Default

Description: A GNU utility for monitoring aprogram's use of system resources

Application Package Version Notes Reference Books and Web Sites

216 MontaVista� Linux® Professional Edition

Page 225: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

tinylogin 0.80 Installed: Default

Description: Multi-call binary capable ofreplacing getty, passwd, etc.

Because this package is a multi-call binary, callingit via a different name changes the functionality.

For example �ln -s tinylogin ls; ls�will call tinylogin with the name ls and causetinylogin to �act� like ls.

The way tinylogin is packaged is that themain binary is in the root package. For example:hhl-ppc_7xx-tinylogin-0.80.ppc_7xx.rpm The root package contains no links. Eachsubpackage contains links to busybox that conßictwith their respective packages. For example:hhl-ppc_7xx-tinylogin-fileutils-0.80.ppc_7xx.rpm would contain links to tinylogin that conßictwith the real fileutils.

traceroute 1.4a12 Installed: Default

Description: Traces the route taken by packetsover a TCP/IP network

ucd-snmp 4.2.3 Installed: Default

Description: A collection of SNMP protocol toolsfrom UC-DavisFunctionality of interest: snmpd, snmp-devel, snmp-utils

Essential SNMPDouglas R. Mauro, Kevin J.SchmidtO'Reilly & Associates ISBN: 0596000200

usbutils 0.8 Installed: Default

Description: Display info about USB devices

util-linux 2.11h Installed: Default

Description: A collection of basic system utilities

Functionality of interest: kill, mkswap, more, swapoff, swapon, umount

v2linux 0.2 Installed: Default

Description: Wind River VxWorks® to Linuxtool kit

http://support.mvista.com/content/AppInfo/

vim 5.7.019 Installed: Default

Description: Replaces vi

Vi iMproved (VIM)Steve OuallineNew Riders PublishingISBN: 0735710015

which 2.12 Installed: Default

Description: Displays where a particular programin your path is located

wireless-tools 22+23beta3 Installed: Default

Description: Tools for wireless networking

wu-ftpd 2.6.1 Installed: Default

Description: An FTP server

xinetd 2.3.3 Installed: Default

Description: A secure replacement for inetd

Application Package Version Notes Reference Books and Web Sites

MontaVista� Linux® Professional Edition 217

Page 226: Monta Vista Users Guide

Appendix B: Pro ApplicationsTarget Application Packages

zebra 0.92a Installed: Default

Description: GNU BGP/OSPF/RIP capablerouting daemon

zlib 1.1.3 Installed: Default

Description: The zlib compression anddecompression library

Application Package Version Notes Reference Books and Web Sites

218 MontaVista� Linux® Professional Edition

Page 227: Monta Vista Users Guide

Appendix B: Pro ApplicationsUsing RSH

Using RSH

RSH (Remote shell) is a Berkeley Unix networking command used to run a givencommand on a remote host, passing it input and receiving its output. To conÞgureRSH, complete the following steps:

1. On the target where the command is being run, open the Þleinetd.conf for editing, and uncomment the following lines:

shell stream tcp nowait root /usr/sbin/tcpd in.rshd -aL login stream tcp nowait root /usr/sbin/tcpd in.rlogind -a

2. For Pro, the setuid bit needs to be set for /usr/bin/rlogin and/usr/bin/rsh. To set the setuid bit, enter the followingcommands:

chmod 4755 /usr/bin/rlogin

chmod 4755 /usr/bin/rsh

You should see output similar to the following:

3. In the user's home directory on the target, open the Þle .rhosts forediting, and add a line with the following format:

<targetIPaddress or name> <userID>

For example, in the Þle /home/kbryla/.rhosts, you would add aline such as:

4. On the target, open the Þle /etc/hosts.equiv and edit it to allowaccess to the host and user. Add a line with the following format:

+

For example, the Þle /etc/hosts.equiv could be:

# chmod 4755 /usr/bin/rlogin root@test2:/etc# ls -l /usr/bin/rlogin -rwsr-xr-x 1 root root 15449 May 24 2002 /usr/bin/rlogin

# chmod 4755 /usr/bin/rsh root@test2:/etc# ls -l /usr/bin/rsh -rwsr-xr-x 1 root root 11163 May 24 2002 /usr/bin/rsh

10.0.0.83 kbryla

# /etc/hosts.equiv: list of hosts and users that # are granted "trusted" r command access to your system.+

MontaVista� Linux® Professional Edition 219

Page 228: Monta Vista Users Guide

Appendix B: Pro ApplicationsUsing RSH

5. On the target, start or restart inetd. Use the following command:

/etc/init.d/inetd restart

Note: The command netstat -at shows that shell and login are bothlistening.

6. On the host (Red Hat 7.3):

� Open the Þles /etc/xinetd.d/rsh and /etc/xinetd.d/rlogin for editing and to set disable to no.

� Open the Þle .rhosts in the user's home directory (such as, /home/kbryla/.rhosts) and add a line with the followingformat:

<target IP address> <userID>

For example, in the Þle /home/kbryla/.rhosts, you wouldadd a line such as:

� Open the Þle /etc/hosts.equiv and edit it to allow access tothe host and user. Add a line with the following format:

+

For example, the Þle /etc/hosts.equiv could be:

� Start or restart xinetd. use the command:

/etc/init.d/xinetd restart

Note: Running the command netstat -at should show that shelland login are both listening.

You should now be able to use RSH.

10.0.0.83 kbryla

# /etc/hosts.equiv: list of hosts and users that # are granted "trusted" r command access to your system.+

220 MontaVista� Linux® Professional Edition

Page 229: Monta Vista Users Guide

Appendix C: Notices and License Agreements

Notices

By providing information, you understand and acknowledge that MontaVistaSoftware, Inc. (�MontaVista Software�) is not providing legal advice to you nor doesMontaVista Software endorse any particular product or any Web site, including thoselisted herein. The licensed software described in this publication, including alllicensed material available for it, is provided to you by MontaVista Software subjectto the terms of the MontaVista Software Product Subscription and Software LicenseAgreement, or any equivalent agreement between us, and any license agreementsMontaVista Software passes through to you from its licensors or suppliers.

MontaVista Software, its licensors or its suppliers, may have patents, or pendingpatent applications, or other intellectual property rights in, or covering, the subjectmatter described in this publication. The furnishing of this publication does not giveyou any license to these patents or such other intellectual property rights ofMontaVista Software or its licensors or suppliers, except as may be provided in aseparate license agreement relating to the particular licensed software.

Any references in this publication to non-MontaVista Software Web sites are providedfor your convenience only and do not, in any manner, serve as an endorsement byMontaVista Software of such Web sites or their content. Information contained insuch Web sites are not under the control of MontaVista Software, Inc., nor are theypart of the materials for this MontaVista Software product. MontaVista Software isnot responsible for any changes or updates to such sites and your use of any such Websites and/or any content contained therein is solely at your own risk.

Any performance data contained herein was determined in a controlled environment.Therefore, the results obtained in other operating environments may varysigniÞcantly. Some measurements may have been made on development-levelsystems and MontaVista Software makes no guarantee that these measurements willbe the same on generally available systems or on your speciÞc environment.Furthermore, some measurement may have been estimated through extrapolation,actual results may vary. You, as a user of this publication, should verify the applicabledata for your speciÞc environment. This publication may also contain sample

MontaVista� Linux® Professional Edition 221

Page 230: Monta Vista Users Guide

Appendix C: Notices and License AgreementsNotices

application programs in source language, which illustrate programming techniques onvarious operating platforms. These examples have not been thoroughly tested underall conditions and MontaVista Software, therefore, cannot guarantee or implyreliability, serviceability, or function of such programs. You may copy, modify anddistribute these sample programs subject to the license agreements and copyrightnotices accompanying such sample application programs.

This publication may contain examples of data and reports used in daily businessoperations. To illustrate them as best as possible, the examples may include referencesto Þctional characters, companies, brands and/or products. MontaVista Software's useof such named Þctitious characters, companies, brands and/or products is forillustration only. Any similarity to actual persons, companies, brands, products orbusiness enterprises is unintentional and entirely coincidental.

222 MontaVista� Linux® Professional Edition

Page 231: Monta Vista Users Guide

Appendix C: Notices and License AgreementsLicense Agreements

License Agreements

MontaVista� Linux® Professional Edition is licensed, not sold, to you under theterms of the MontaVista Product Subscription and Software License Agreement, orany equivalent agreement between us.

MontaVista� Linux® Professional Edition 223

Page 232: Monta Vista Users Guide

Appendix C: Notices and License AgreementsTarget Configuration Tool End User License Agreement

Target ConÞguration Tool End User License Agreement

IMPORTANT-READ CAREFULLY: This MontaVista Software, Inc. End-UserLicense Agreement (�EULA�) is a legal agreement between you (either an individualor a single entity) and MontaVista Software, Inc. for the MontaVista Software, Inc.software product identiÞed above, which includes computer software (binary andsource) and may include associated media, printed materials, and �online� orelectronic documentation (�Software Product�). By installing, copying, or otherwiseusing the Software Product, you agree to be bound by the terms of this EULA. If youdo not agree to the terms of this EULA, do not install or use the Software Product. Ifapplicable, you may return it to your place of purchase for a full refund of anyseparate fees paid for the Software Product. MontaVista Software, Inc. shall bereferred to in this EULA as �Licensor.�

Any third party software that is provided with the Software Product includes suchthird party�s license agreements (in either electronic or printed form) (including theGNU General Public License) for use at your option. If you choose to use suchsoftware, then such use shall be governed by such third party license agreements andnot by this Agreement.

The Software Product is protected by copyright laws and international copyrighttreaties, as well as other intellectual property laws and treaties. The Software Productis licensed, not sold.

LICENSE GRANT. Licensor grants you a non-exclusive and non-transferable licenseto use the Software Product and accompanying documentation (�Documentation�),subject to the limitations below. This license grant is subject to the payment ofapplicable license fees. Unless you have purchased a product subscription for theSoftware Product, the license granted under this Agreement does not grant you anyright to any enhancement or update to the Software Product.

LIMITATIONS ON USE; NO REDISTRIBUTION. With respect to the SoftwareProduct, you may not, and may not authorize any third party to: (1) distribute to anythird party the source code of the Software Product or any modiÞcations or derivativeworks thereof, or any copies of the Documentation; (2) rent, lease, grant a securityinterest in, or otherwise transfer rights to the Software Product; or (3) remove or alterany trademark, logo, copyright or other proprietary notices, legends, symbols orlabels in the Software Product, or in copies you have made of the Software Product;

LIMITED WARRANTY. If license fees have been paid, Licensor warrants that for aperiod of ninety (90) days from the date of acquisition, the Software Product, ifoperated as directed, will substantially achieve the functionality described in theDocumentation. Licensor does not warrant, however, that your use of the SoftwareProduct will be uninterrupted or that the operation of the Software Product will beerror-free or secure. Licensor�s sole liability for any breach of this warranty shall be,in Licensor�s sole discretion: (i) to replace your defective Software Product; or (ii) toadvise you how to achieve substantially the same functionality with the SoftwareProduct as described in the Documentation through a procedure different from that setforth in the Documentation; or (iii) for individual consumers, if the above remediesare impracticable, to refund the license fee you paid for the Software Product separate

224 MontaVista� Linux® Professional Edition

Page 233: Monta Vista Users Guide

Appendix C: Notices and License AgreementsTarget Configuration Tool End User License Agreement

and apart from other products, if any such separate fee was paid for the SoftwareProduct, minus a reasonable allowance for the time you have used the SoftwareProduct. Only if you inform Licensor of your problem with the Software Productduring the applicable warranty period and provide evidence of the date you purchaseda license to the Software Product will Licensor be obligated to honor this warranty.This warranty shall immediately terminate: (1) if any modiÞcations are made to theSoftware Product by you during the warranty period; (2) if the media is subjected toaccident, abuse, or improper use; or (3) if you violate the terms of this Agreement.This warranty shall not apply if the Software Product is used on or in conjunctionwith hardware or software other than the unmodiÞed version of hardware andsoftware with which the Software Product was intended to be used as described in theDocumentation.

NO OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BYAPPLICABLE LAW, LICENSOR DISCLAIMS ALL OTHER WARRANTIES ANDCONDITIONS, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOTLIMITED TO, IMPLIED WARRANTIES OR MERCHANTABILITY, FITNESSFOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITHREGARD TO THE SOFTWARE PRODUCT, AND THE PROVISION OF ORFAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED WARRANTYGIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICHVARY FROM STATE/JURISDICTION TO STATE/JURISDICTION.

TITLE. Title, ownership, and intellectual property rights in the Software Product andDocumentation shall remain in Licensor. You acknowledge such ownership andintellectual property rights and will not take any action to jeopardize, limit or interferein any manner with Licensor�s ownership of or rights with respect to the SoftwareProduct and Documentation. The Software Product and Documentation are protectedby copyright and other intellectual property laws and international treaties.

TERMINATION. This EULA and the license granted hereunder will terminateautomatically if you fail to comply with the conditions described herein. Upontermination, you must destroy all copies of the Software Product and Documentation.Your obligations to pay accrued charges and fees shall survive any termination of thisEULA.

EXPORT CONTROLS. The Software Product is subject to the regulations of theUnited States government and agencies thereof, including the Bureau of ExportAdministration. None of the Software Product of underlying information or theunderlying information or technology may be downloaded or otherwise exported orreexported into prohibited countries (including Cuba, Iraq, Libya, Sudan, NorthKorea, Iran, Syria or any other country to which the United States has embargoedgoods). By downloading or using the Software Product, you agree that you are notlocated in, under the control of, or a national or resident of any such country.

LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BYAPPLICABLE LAW, IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANYSPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGESWHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSSOF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESSINFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE

MontaVista� Linux® Professional Edition 225

Page 234: Monta Vista Users Guide

Appendix C: Notices and License AgreementsTarget Configuration Tool End User License Agreement

USE OF OR INABILITY TO USE THE SOFTWARE PRODUCT OR THEPROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES, EVEN IFLICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.IN ANY CASE, LICENSOR�S ENTIRE LIABILITY UNDER ANY PROVISIONOF THIS EULA SHALL BE LIMITED TO THE AMOUNT ACTUALLY PAID BYYOU SEPARATELY FOR THE SOFTWARE PRODUCT. BECAUSE SOMESTATES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION ORLIMITATION OF LIABILITY, THE ABOVE LIMITATION MAY NOT APPLY TOYOU.

HIGH RISK ACTIVITIES. The Software Product is not fault-tolerant and is notdesigned, manufactured or intended for use or resale as on-line control equipment inhazardous environments requiring fail-safe performance, such as in the operation ofnuclear facilities, aircraft navigation or communication systems, air trafÞc control,direct life support machines, or weapons systems, in which the failure of the SoftwareProduct could lead directly to death, personal injury, or severe physical orenvironmental damage (�High Risk Activities�). Accordingly, Licensor and itssuppliers speciÞcally disclaim any express or implied warranty of Þtness for HighRisk Activities.

MISCELLANEOUS. This EULA represents the complete agreement concerning thelicense granted hereunder and may be amended only by a writing executed by bothparties. THE ACCEPTANCE OF ANY PURCHASE ORDER PLACED BY YOU ISEXPRESSLY MADE CONDITIONAL ON YOUR ASSENT TO THE TERMS SETFORTH HEREIN, AND NOT ON THOSE IN YOUR PURCHASE ORDER. If anyprovision of this EULA is held to be unenforceable, such provision shall be reformedonly to the extent necessary to make it enforceable. All disputes relating to thisEULA shall be resolved by binding arbitration in Santa Clara County, California. ThisEULA shall be governed by California law, excluding conßict of law provisions. Theapplication of the United Nations Convention on Contracts for the International Saleof Goods is expressly excluded.

226 MontaVista� Linux® Professional Edition

Page 235: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe �Artistic License�

The �Artistic License�

Preamble

The intent of this document is to state the conditions under which a Package may becopied, such that the Copyright Holder maintains some semblance of artistic controlover the development of the package, while giving the users of the package the rightto use and distribute the Package in a more-or-less customary fashion, plus the right tomake reasonable modiÞcations.

DeÞnitions:

�Package� refers to the collection of Þles distributed by the Copyright Holder, andderivatives of that collection of Þles created through textual modiÞcation.

�Standard Version� refers to such a Package if it has not been modiÞed, or has beenmodiÞed in accordance with the wishes of the Copyright Holder as speciÞed below.

�Copyright Holder� is whoever is named in the copyright or copyrights for thepackage.

�You� is you, if you're thinking about copying or distributing this Package.

�Reasonable copying fee� is whatever you can justify on the basis of media cost,duplication charges, time of people involved, and so on. (You will not be required tojustify it to the Copyright Holder, but only to the computing community at large as amarket that must bear the fee.)

�Freely Available� means that no fee is charged for the item itself, though there maybe fees involved in handling the item. It also means that recipients of the item mayredistribute it under the same conditions they received it.

1. You may make and give away verbatim copies of the source form of the StandardVersion of this Package without restriction, provided that you duplicate all of theoriginal copyright notices and associated disclaimers.

2. You may apply bug Þxes, portability Þxes and other modiÞcations derived from thePublic Domain or from the Copyright Holder. A Package modiÞed in such a way shallstill be considered the Standard Version.

3. You may otherwise modify your copy of this Package in any way, provided thatyou insert a prominent notice in each changed Þle stating how and when you changedthat Þle, and provided that you do at least ONE of the following:

� a) place your modiÞcations in the Public Domain or otherwisemake them Freely Available, such as by posting said modiÞcationsto Usenet or an equivalent medium, or placing the modiÞcations ona major archive site such as uunet.uu.net, or by allowing the

MontaVista� Linux® Professional Edition 227

Page 236: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe �Artistic License�

Copyright Holder to include your modiÞcations in the StandardVersion of the Package.

� b) use the modiÞed Package only within your corporation ororganization.

� c) rename any non-standard executables so the names do notconßict with standard executables, which must also be provided,and provide a separate manual page for each non-standardexecutable that clearly documents how it differs from the StandardVersion.

� d) make other distribution arrangements with the Copyright Holder.

4. You may distribute the programs of this Package in object code or executable form,provided that you do at least ONE of the following:

� a) distribute a Standard Version of the executables and library Þles,together with instructions (in the manual page or equivalent) onwhere to get the Standard Version.

� b) accompany the distribution with the machine-readable source ofthe Package with your modiÞcations.

� c) give non-standard executables non-standard names, and clearlydocument the differences in manual pages (or equivalent), togetherwith instructions on where to get the Standard Version.

� d) make other distribution arrangements with the Copyright Holder.

5. You may charge a reasonable copying fee for any distribution of this Package. Youmay charge any fee you choose for support of this Package. You may not charge a feefor this Package itself. However, you may distribute this Package in aggregate withother (possibly commercial) programs as part of a larger (possibly commercial)software distribution provided that you do not advertise this Package as a product ofyour own. You may embed this Package's interpreter within an executable of yours(by linking); this shall be construed as a mere form of aggregation, provided that thecomplete Standard Version of the interpreter is so embedded.

6. The scripts and library Þles supplied as input to or produced as output from theprograms of this Package do not automatically fall under the copyright of thisPackage, but belong to whoever generated them, and may be sold commercially, andmay be aggregated with this Package. If such scripts or library Þles are aggregatedwith this Package via the so-called �undump� or �unexec� methods of producing abinary executable image, then distribution of such an image shall neither be construedas a distribution of this Package nor shall it fall under the restrictions of Paragraphs 3and 4, provided that you do not represent such an executable image as a StandardVersion of this Package.

228 MontaVista� Linux® Professional Edition

Page 237: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe �Artistic License�

7. C subroutines (or comparably compiled subroutines in other languages) suppliedby you and linked into this Package in order to emulate subroutines and variables ofthe language deÞned by this Package shall not be considered part of this Package, butare the equivalent of input as in Paragraph 6, provided these subroutines do notchange the language in any way that would cause it to fail the regression tests for thelanguage.

8. Aggregation of this Package with a commercial distribution is always permittedprovided that the use of this Package is embedded; that is, when no overt attempt ismade to make this Package's interfaces visible to the end user of the commercialdistribution. Such use shall not be construed as a distribution of this Package.

9. The name of the Copyright Holder may not be used to endorse or promote productsderived from this software without speciÞc prior written permission.

10. THIS PACKAGE IS PROVIDED �AS IS� AND WITHOUT ANY EXPRESS ORIMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THEIMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR APARTICULAR PURPOSE.

The End

MontaVista� Linux® Professional Edition 229

Page 238: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

GNU General Public License, or GNU GPLVersion 2, June 1991

Copyright (C) 1989, 1991 Free Software Foundation, Inc. 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA

Everyone is permitted to copy and distribute verbatim copies of this licensedocument, but changing it is not allowed.

Preamble

The licenses for most software are designed to take away your freedom to share andchange it. By contrast, the GNU General Public License is intended to guarantee yourfreedom to share and change free software--to make sure the software is free for all itsusers. This General Public License applies to most of the Free Software Foundation'ssoftware and to any other program whose authors commit to using it. (Some otherFree Software Foundation software is covered by the GNU Library General PublicLicense instead.) You can apply it to your programs, too.

When we speak of free software, we are referring to freedom, not price. Our GeneralPublic Licenses are designed to make sure that you have the freedom to distributecopies of free software (and charge for this service if you wish), that you receivesource code or can get it if you want it, that you can change the software or use piecesof it in new free programs; and that you know you can do these things.

To protect your rights, we need to make restrictions that forbid anyone to deny youthese rights or to ask you to surrender the rights.

These restrictions translate to certain responsibilities for you if you distribute copiesof the software, or if you modify it.

For example, if you distribute copies of such a program, whether gratis or for a fee,you must give the recipients all the rights that you have. You must make sure that they,too, receive or can get the source code. And you must show them these terms so theyknow their rights.

We protect your rights with two steps: (1) copyright the software, and (2) offer youthis license which gives you legal permission to copy, distribute and/or modify thesoftware.

Also, for each author's protection and ours, we want to make certain that everyoneunderstands that there is no warranty for this free software. If the software is modiÞedby someone else and passed on, we want its recipients to know that what they have isnot the original, so that any problems introduced by others will not reßect on theoriginal authors' reputations.

Finally, any free program is threatened constantly by software patents. We wish toavoid the danger that redistributors of a free program will individually obtain patent

230 MontaVista� Linux® Professional Edition

Page 239: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

licenses, in effect making the program proprietary. To prevent this, we have made itclear that any patent must be licensed for everyone's free use or not licensed at all.

The precise terms and conditions for copying, distribution and modiÞcation follow.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION ANDMODIFICATION

0. This License applies to any program or other work which contains a notice placedby the copyright holder saying it may be distributed under the terms of this GeneralPublic License. The �Program�, below, refers to any such program or work, and a�work based on the Program� means either the Program or any derivative work undercopyright law: that is to say, a work containing the Program or a portion of it, eitherverbatim or with modiÞcations and/or translated into another language. (Hereinafter,translation is included without limitation in the term �modiÞcation�.) Each licensee isaddressed as �you�.

Activities other than copying, distribution and modiÞcation are not covered by thisLicense; they are outside its scope. The act of running the Program is not restricted,and the output from the Program is covered only if its contents constitute a workbased on the Program (independent of having been made by running the Program).Whether that is true depends on what the Program does.

1. You may copy and distribute verbatim copies of the Program's source code as youreceive it, in any medium, provided that you conspicuously and appropriately publishon each copy an appropriate copyright notice and disclaimer of warranty; keep intactall the notices that refer to this License and to the absence of any warranty; and giveany other recipients of the Program a copy of this License along with the Program.

You may charge a fee for the physical act of transferring a copy, and you may at youroption offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Program or any portion of it, thusforming a work based on the Program, and copy and distribute such modiÞcations orwork under the terms of Section 1 above, provided that you also meet all of theseconditions:

� a) You must cause the modiÞed Þles to carry prominent noticesstating that you changed the Þles and the date of any change.

� b) You must cause any work that you distribute or publish, that inwhole or in part contains or is derived from the Program or any partthereof, to be licensed as a whole at no charge to all third partiesunder the terms of this License.

� c) If the modiÞed program normally reads commands interactivelywhen run, you must cause it, when started running for suchinteractive use in the most ordinary way, to print or display anannouncement including an appropriate copyright notice and anotice that there is no warranty (or else, saying that you provide awarranty) and that users may redistribute the program under these

MontaVista� Linux® Professional Edition 231

Page 240: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

conditions, and telling the user how to view a copy of this License.(Exception: if the Program itself is interactive but does notnormally print such an announcement, your work based on theProgram is not required to print an announcement.)

These requirements apply to the modiÞed work as a whole. If identiÞable sections ofthat work are not derived from the Program, and can be reasonably consideredindependent and separate works in themselves, then this License, and its terms, do notapply to those sections when you distribute them as separate works. But when youdistribute the same sections as part of a whole which is a work based on the Program,the distribution of the whole must be on the terms of this License, whose permissionsfor other licensees extend to the entire whole, and thus to each and every partregardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to workwritten entirely by you; rather, the intent is to exercise the right to control thedistribution of derivative or collective works based on the Program.

In addition, mere aggregation of another work not based on the Program with theProgram (or with a work based on the Program) on a volume of a storage ordistribution medium does not bring the other work under the scope of this License.

3. You may copy and distribute the Program (or a work based on it, under Section 2)in object code or executable form under the terms of Sections 1 and 2 above providedthat you also do one of the following:

� a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms ofSections 1 and 2 above on a medium customarily used for softwareinterchange; or,

� b) Accompany it with a written offer, valid for at least three years,to give any third party, for a charge no more than your cost ofphysically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributedunder the terms of Sections 1 and 2 above on a medium customarilyused for software interchange; or,

� c) Accompany it with the information you received as to the offer todistribute corresponding source code. (This alternative is allowedonly for noncommercial distribution and only if you received theprogram in object code or executable form with such an offer, inaccord with Subsection b above.)

The source code for a work means the preferred form of the work for makingmodiÞcations to it. For an executable work, complete source code means all thesource code for all modules it contains, plus any associated interface deÞnition Þles,plus the scripts used to control compilation and installation of the executable.However, as a special exception, the source code distributed need not includeanything that is normally distributed (in either source or binary form) with the major

232 MontaVista� Linux® Professional Edition

Page 241: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

components (compiler, kernel, and so on) of the operating system on which theexecutable runs, unless that component itself accompanies the executable.

If distribution of executable or object code is made by offering access to copy from adesignated place, then offering equivalent access to copy the source code from thesame place counts as distribution of the source code, even though third parties are notcompelled to copy the source along with the object code.

4. You may not copy, modify, sublicense, or distribute the Program except asexpressly provided under this License. Any attempt otherwise to copy, modify,sublicense or distribute the Program is void, and will automatically terminate yourrights under this License. However, parties who have received copies, or rights, fromyou under this License will not have their licenses terminated so long as such partiesremain in full compliance.

5. You are not required to accept this License, since you have not signed it. However,nothing else grants you permission to modify or distribute the Program or itsderivative works. These actions are prohibited by law if you do not accept thisLicense. Therefore, by modifying or distributing the Program (or any work based onthe Program), you indicate your acceptance of this License to do so, and all its termsand conditions for copying, distributing or modifying the Program or works based onit.

6. Each time you redistribute the Program (or any work based on the Program), therecipient automatically receives a license from the original licensor to copy, distributeor modify the Program subject to these terms and conditions. You may not impose anyfurther restrictions on the recipients' exercise of the rights granted herein. You are notresponsible for enforcing compliance by third parties to this License.

7. If, as a consequence of a court judgment or allegation of patent infringement or forany other reason (not limited to patent issues), conditions are imposed on you(whether by court order, agreement or otherwise) that contradict the conditions of thisLicense, they do not excuse you from the conditions of this License. If you cannotdistribute so as to satisfy simultaneously your obligations under this License and anyother pertinent obligations, then as a consequence you may not distribute the Programat all. For example, if a patent license would not permit royalty-free redistribution ofthe Program by all those who receive copies directly or indirectly through you, thenthe only way you could satisfy both it and this License would be to refrain entirelyfrom distribution of the Program.

If any portion of this section is held invalid or unenforceable under any particularcircumstance, the balance of the section is intended to apply and the section as awhole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or otherproperty right claims or to contest validity of any such claims; this section has the solepurpose of protecting the integrity of the free software distribution system, which isimplemented by public license practices. Many people have made generouscontributions to the wide range of software distributed through that system in relianceon consistent application of that system; it is up to the author/donor to decide if he or

MontaVista� Linux® Professional Edition 233

Page 242: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

she is willing to distribute software through any other system and a licensee cannotimpose that choice.

This section is intended to make thoroughly clear what is believed to be aconsequence of the rest of this License.

8. If the distribution and/or use of the Program is restricted in certain countries eitherby patents or by copyrighted interfaces, the original copyright holder who places theProgram under this License may add an explicit geographical distribution limitationexcluding those countries, so that distribution is permitted only in or among countriesnot thus excluded. In such case, this License incorporates the limitation as if writtenin the body of this License.

9. The Free Software Foundation may publish revised and/or new versions of theGeneral Public License from time to time. Such new versions will be similar in spiritto the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Program speciÞes aversion number of this License which applies to it and �any later version�, you havethe option of following the terms and conditions either of that version or of any laterversion published by the Free Software Foundation. If the Program does not specify aversion number of this License, you may choose any version ever published by theFree Software Foundation.

10. If you wish to incorporate parts of the Program into other free programs whosedistribution conditions are different, write to the author to ask for permission. Forsoftware which is copyrighted by the Free Software Foundation, write to the FreeSoftware Foundation; we sometimes make exceptions for this. Our decision will beguided by the two goals of preserving the free status of all derivatives of our freesoftware and of promoting the sharing and reuse of software generally.

NO WARRANTY

11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE ISNO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BYAPPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THECOPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM�AS IS� WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THEENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THEPROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE,YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR ORCORRECTION.

12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREEDTO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTYWHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM ASPERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANYGENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGESARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM

234 MontaVista� Linux® Professional Edition

Page 243: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEINGRENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRDPARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANYOTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HASBEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest possible use to thepublic, the best way to achieve this is to make it free software which everyone canredistribute and change under these terms.

To do so, attach the following notices to the program. It is safest to attach them to thestart of each source Þle to most effectively convey the exclusion of warranty; and eachÞle should have at least the �copyright� line and a pointer to where the full notice isfound.

one line to give the program's name and an idea of what itdoes.Copyright (C) yyyy name of author

This program is free software; you can redistribute itand/or modify it under the terms of the GNU General PublicLicense as published by the Free Software Foundation;either version 2 of the License, or (at your option) anylater version.

This program is distributed in the hope that it will beuseful, but WITHOUT ANY WARRANTY; without even theimplied warranty of MERCHANTABILITY or FITNESS FOR APARTICULAR PURPOSE. See the GNU General Public Licensefor more details.

You should have received a copy of the GNU General PublicLicense along with this program; if not, write to the FreeSoftware Foundation, Inc., 59 Temple Place - Suite 330,Boston, MA 02111-1307, USA.

Also add information on how to contact you by electronic and paper mail.

If the program is interactive, make it output a short notice like this when it starts in aninteractive mode:

Gnomovision version 69, Copyright (C) year name of authorGnomovision comes with ABSOLUTELY NO WARRANTY; fordetails type `show w'. This is free software, and you arewelcome to redistribute it under certain conditions; type`show c' for details.

MontaVista� Linux® Professional Edition 235

Page 244: Monta Vista Users Guide

Appendix C: Notices and License AgreementsGNU General Public License, or GNU GPL

The hypothetical commands `show w' and `show c' should show the appropriate partsof the General Public License. Of course, the commands you use may be calledsomething other than `show w' and `show c'; they could even be mouse-clicks ormenu items--whatever suits your program.

You should also get your employer (if you work as a programmer) or your school, ifany, to sign a �copyright disclaimer� for the program, if necessary. Here is a sample;alter the names:

Yoyodyne, Inc., hereby disclaims all copyrightinterest in the program `Gnomovision'(which makes passes at compilers) written by James Hacker.

signature of Ty Coon, 1 April 1989Ty Coon, President of Vice

This General Public License does not permit incorporating your program intoproprietary programs. If your program is a subroutine library, you may consider itmore useful to permit linking proprietary applications with the library. If this is whatyou want to do, use the GNU Library General Public License instead of this License.

236 MontaVista� Linux® Professional Edition

Page 245: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

The GNU Lesser General Public License, or GNU LGPL

Version 2.1, February 1999

Copyright (C) 1991, 1999 Free Software Foundation, Inc.59 Temple Place, Suite 330, Boston, MA 02111-1307 USAEveryone is permitted to copy and distribute verbatimcopies of this license document, but changing it is notallowed.

[This is the first released version of the Lesser GPL. Italso counts as the successor of the GNU Library PublicLicense, version 2, hence the version number 2.1.]

Preamble

The licenses for most software are designed to take away your freedom to share andchange it. By contrast, the GNU General Public Licenses are intended to guaranteeyour freedom to share and change free software--to make sure the software is free forall its users.

This license, the Lesser General Public License, applies to some specially designatedsoftware packages--typically libraries--of the Free Software Foundation and otherauthors who decide to use it. You can use it too, but we suggest you Þrst thinkcarefully about whether this license or the ordinary General Public License is thebetter strategy to use in any particular case, based on the explanations below.

When we speak of free software, we are referring to freedom of use, not price. OurGeneral Public Licenses are designed to make sure that you have the freedom todistribute copies of free software (and charge for this service if you wish); that youreceive source code or can get it if you want it; that you can change the software anduse pieces of it in new free programs; and that you are informed that you can do thesethings.

To protect your rights, we need to make restrictions that forbid distributors to denyyou these rights or to ask you to surrender these rights. These restrictions translate tocertain responsibilities for you if you distribute copies of the library or if you modifyit.

For example, if you distribute copies of the library, whether gratis or for a fee, youmust give the recipients all the rights that we gave you. You must make sure that they,too, receive or can get the source code. If you link other code with the library, youmust provide complete object Þles to the recipients, so that they can relink them withthe library after making changes to the library and recompiling it. And you must showthem these terms so they know their rights.

We protect your rights with a two-step method: (1) we copyright the library, and (2)we offer you this license, which gives you legal permission to copy, distribute and/ormodify the library.

MontaVista� Linux® Professional Edition 237

Page 246: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

To protect each distributor, we want to make it very clear that there is no warranty forthe free library. Also, if the library is modiÞed by someone else and passed on, therecipients should know that what they have is not the original version, so that theoriginal author's reputation will not be affected by problems that might be introducedby others.

Finally, software patents pose a constant threat to the existence of any free program.We wish to make sure that a company cannot effectively restrict the users of a freeprogram by obtaining a restrictive license from a patent holder. Therefore, we insistthat any patent license obtained for a version of the library must be consistent with thefull freedom of use speciÞed in this license.

Most GNU software, including some libraries, is covered by the ordinary GNUGeneral Public License. This license, the GNU Lesser General Public License,applies to certain designated libraries, and is quite different from the ordinary GeneralPublic License. We use this license for certain libraries in order to permit linkingthose libraries into non-free programs.

When a program is linked with a library, whether statically or using a shared library,the combination of the two is legally speaking a combined work, a derivative of theoriginal library. The ordinary General Public License therefore permits such linkingonly if the entire combination Þts its criteria of freedom. The Lesser General PublicLicense permits more lax criteria for linking other code with the library.

We call this license the �Lesser� General Public License because it does Less toprotect the user's freedom than the ordinary General Public License. It also providesother free software developers Less of an advantage over competing non-freeprograms. These disadvantages are the reason we use the ordinary General PublicLicense for many libraries. However, the Lesser license provides advantages incertain special circumstances.

For example, on rare occasions, there may be a special need to encourage the widestpossible use of a certain library, so that it becomes a de-facto standard. To achievethis, non-free programs must be allowed to use the library. A more frequent case isthat a free library does the same job as widely used non-free libraries. In this case,there is little to gain by limiting the free library to free software only, so we use theLesser General Public License.

In other cases, permission to use a particular library in non-free programs enables agreater number of people to use a large body of free software. For example,permission to use the GNU C Library in non-free programs enables many morepeople to use the whole GNU operating system, as well as its variant, the GNU/Linuxoperating system.

Although the Lesser General Public License is Less protective of the users' freedom,it does ensure that the user of a program that is linked with the Library has thefreedom and the wherewithal to run that program using a modiÞed version of theLibrary.

The precise terms and conditions for copying, distribution and modiÞcation follow.Pay close attention to the difference between a �work based on the library� and a

238 MontaVista� Linux® Professional Edition

Page 247: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

�work that uses the library�. The former contains code derived from the library,whereas the latter must be combined with the library in order to run.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION ANDMODIFICATION

0. This License Agreement applies to any software library or other program whichcontains a notice placed by the copyright holder or

other authorized party saying it may be distributed under the terms of this LesserGeneral Public License (also called �this License�). Each licensee is addressed as�you�.

A �library� means a collection of software functions and/or data prepared so as to beconveniently linked with application programs (which use some of those functionsand data) to form executables.

The �Library�, below, refers to any such software library or work which has beendistributed under these terms. A �work based on the Library� means either the Libraryor any derivative work under copyright law: that is to say, a work containing theLibrary or a portion of it, either verbatim or with modiÞcations and/or translatedstraightforwardly into another language. (Hereinafter, translation is included withoutlimitation in the term �modiÞcation�.)

�Source code� for a work means the preferred form of the work for makingmodiÞcations to it. For a library, complete source code means all the source code forall modules it contains, plus any associated interface deÞnition Þles, plus the scriptsused to control compilation and installation of the library.

Activities other than copying, distribution and modiÞcation are not covered by thisLicense; they are outside its scope. The act of running a program using the Library isnot restricted, and output from such a program is covered only if its contentsconstitute a work based on the Library (independent of the use of the Library in a toolfor writing it). Whether that is true depends on what the Library does and what theprogram that uses the Library does.

1. You may copy and distribute verbatim copies of the Library's complete sourcecode as you receive it, in any medium, provided that you conspicuously andappropriately publish on each copy an appropriate copyright notice and disclaimer ofwarranty; keep intact all the notices that refer to this License and to the absence of anywarranty; and distribute a copy of this License along with the Library.

You may charge a fee for the physical act of transferring a copy, and you may at youroption offer warranty protection in exchange for a fee.

2. You may modify your copy or copies of the Library or any portion of it, thusforming a work based on the Library, and copy and distribute such modiÞcations orwork under the terms of Section 1 above, provided that you also meet all of theseconditions:

� a) The modiÞed work must itself be a software library.

MontaVista� Linux® Professional Edition 239

Page 248: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

� b) You must cause the Þles modiÞed to carry prominent noticesstating that you changed the Þles and the date of any change.

� c) You must cause the whole of the work to be licensed at no chargeto all third parties under the terms of this License.

� d) If a facility in the modiÞed Library refers to a function or a tableof data to be supplied by an application program that uses thefacility, other than as an argument passed when the facility isinvoked, then you must make a good faith effort to ensure that, inthe event an application does not supply such function or table, thefacility still operates, and performs whatever part of its purposeremains meaningful.

(For example, a function in a library to compute square roots has apurpose that is entirely well-deÞned independent of the application.Therefore, Subsection 2d requires that any application-suppliedfunction or table used by this function must be optional: if theapplication does not supply it, the square root function must stillcompute square roots.)

These requirements apply to the modiÞed work as a whole. IfidentiÞable sections of that work are not derived from the Library,and can be reasonably considered independent and separate worksin themselves, then this License, and its terms, do not apply to thosesections when you distribute them as separate works. But when youdistribute the same sections as part of a whole which is a workbased on the Library, the distribution of the whole must be on theterms of this License, whose permissions for other licensees extendto the entire whole, and thus to each and every part regardless ofwho wrote it.

Thus, it is not the intent of this section to claim rights or contestyour rights to work written entirely by you; rather, the intent is toexercise the right to control the distribution of derivative orcollective works based on the Library.

In addition, mere aggregation of another work not based on theLibrary with the Library (or with a work based on the Library) on avolume of a storage or distribution medium does not bring the otherwork under the scope of this License.

3. You may opt to apply the terms of the ordinary GNU General Public Licenseinstead of this License to a given copy of the Library. To do this, you must alter all thenotices that refer to this License, so that they refer to the ordinary GNU GeneralPublic License, version 2, instead of to this License. (If a newer version than version 2of the ordinary GNU General Public License has appeared, then you can specify thatversion instead if you wish.) Do not make any other change in these notices.

Once this change is made in a given copy, it is irreversible for that copy, so theordinary GNU General Public License applies to all subsequent copies and derivativeworks made from that copy.

240 MontaVista� Linux® Professional Edition

Page 249: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

This option is useful when you wish to copy part of the code of the Library into aprogram that is not a library.

4. You may copy and distribute the Library (or a portion or derivative of it, underSection 2) in object code or executable form under the terms of Sections 1 and 2above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2above on a medium customarily used for software interchange.

If distribution of object code is made by offering access to copy from a designatedplace, then offering equivalent access to copy the

source code from the same place satisÞes the requirement to distribute the sourcecode, even though third parties are not compelled to copy the source along with theobject code.

5. A program that contains no derivative of any portion of the Library, but is designedto work with the Library by being compiled or linked with it, is called a �work thatuses the Library�. Such a work, in isolation, is not a derivative work of the Library,and therefore falls outside the scope of this License.

However, linking a �work that uses the Library� with the Library creates anexecutable that is a derivative of the Library (because it contains portions of theLibrary), rather than a �work that uses the library�. The executable is thereforecovered by this License. Section 6 states terms for distribution of such executables.

When a �work that uses the Library� uses material from a header Þle that is part of theLibrary, the object code for the work may be a derivative work of the Library eventhough the source code is not. Whether this is true is especially signiÞcant if the workcan be linked without the Library, or if the work is itself a library. The threshold forthis to be true is not precisely deÞned by law.

If such an object Þle uses only numerical parameters, data structure layouts andaccessors, and small macros and small inline functions (ten lines or less in length),then the use of the object Þle is unrestricted, regardless of whether it is legally aderivative work. (Executables containing this object code plus portions of the Librarywill still fall under Section 6.)

Otherwise, if the work is a derivative of the Library, you may distribute the objectcode for the work under the terms of Section 6. Any executables containing that workalso fall under Section 6, whether or not they are linked directly with the Libraryitself.

6. As an exception to the Sections above, you may also combine or link a �work thatuses the Library� with the Library to produce a work containing portions of theLibrary, and distribute that work under terms of your choice, provided that the termspermit modiÞcation of the work for the customer's own use and reverse engineeringfor debugging such modiÞcations.

You must give prominent notice with each copy of the work that the Library is used init and that the Library and its use are covered by this License. You must supply a copy

MontaVista� Linux® Professional Edition 241

Page 250: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

of this License. If the work during execution displays copyright notices, you mustinclude the copyright notice for the Library among them, as well as a referencedirecting the user to the copy of this License. Also, you must do one of these things:

� a) Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changeswere used in the work (which must be distributed under Sections 1and 2 above); and, if the work is an executable linked with theLibrary, with the complete machine-readable �work that uses theLibrary�, as object code and/or source code, so that the user canmodify the Library and then relink to produce a modiÞedexecutable containing the modiÞed Library. (It is understood thatthe user who changes the contents of deÞnitions Þles in the Librarywill not necessarily be able to recompile the application to use themodiÞed deÞnitions.)

� b) Use a suitable shared library mechanism for linking with theLibrary. A suitable mechanism is one that (1) uses at run time acopy of the library already present on the user's computer system,rather than copying library functions into the executable, and (2)will operate properly with a modiÞed version of the library, if theuser installs one, as long as the modiÞed version is interface-compatible with the version that the work was made with.

� c) Accompany the work with a written offer, valid for at least threeyears, to give the same user the materials speciÞed in Subsection6a, above, for a charge no more than the cost of performing thisdistribution.

� d) If distribution of the work is made by offering access to copyfrom a designated place, offer equivalent access to copy the abovespeciÞed materials from the same place.

� e) Verify that the user has already received a copy of these materialsor that you have already sent this user a copy.

For an executable, the required form of the �work that uses the Library� must includeany data and utility programs needed for reproducing the executable from it.However, as a special exception, the materials to be distributed need not includeanything that is normally distributed (in either source or binary form) with the majorcomponents (compiler, kernel, and so on) of the operating system on which theexecutable runs, unless that component itself accompanies the executable.

It may happen that this requirement contradicts the license restrictions of otherproprietary libraries that do not normally accompany the operating system. Such acontradiction means you cannot use both them and the Library together in anexecutable that you distribute.

242 MontaVista� Linux® Professional Edition

Page 251: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

7. You may place library facilities that are a work based on the Library side-by-sidein a single library together with other library facilities not covered by this License,and distribute such a combined library, provided that the separate distribution of thework based on the Library and of the other library facilities is otherwise permitted,and provided that you do these two things:

� a) Accompany the combined library with a copy of the same workbased on the Library, uncombined with any other library facilities.This must be distributed under the terms of the Sections above.

� b) Give prominent notice with the combined library of the fact thatpart of it is a work based on the Library, and explaining where toÞnd the accompanying uncombined form of the same work.

8. You may not copy, modify, sublicense, link with, or distribute the Library exceptas expressly provided under this License. Any attempt otherwise to copy, modify,sublicense, link with, or distribute the Library is void, and will automaticallyterminate your rights under this License. However, parties who have received copies,or rights, from you under this License will not have their licenses terminated so longas such parties remain in full compliance.

9. You are not required to accept this License, since you have not signed it. However,nothing else grants you permission to modify or distribute the Library or its derivativeworks. These actions are prohibited by law if you do not accept this License.Therefore, by modifying or distributing the Library (or any work based on theLibrary), you indicate your acceptance of this License to do so, and all its terms andconditions for copying, distributing or modifying the Library or works based on it.

10. Each time you redistribute the Library (or any work based on the Library), therecipient automatically receives a license from the original licensor to copy,distribute, link with or modify the Library subject to these terms and conditions. Youmay not impose any further restrictions on the recipients' exercise of the rightsgranted herein. You are not responsible for enforcing compliance by third parties withthis License.

11. If, as a consequence of a court judgment or allegation of patent infringement orfor any other reason (not limited to patent issues), conditions are imposed on you(whether by court order, agreement or otherwise) that contradict the conditions of thisLicense, they do not excuse you from the conditions of this License. If you cannotdistribute so as to satisfy simultaneously your obligations under this License and anyother pertinent obligations, then as a consequence you may not distribute the Libraryat all. For example, if a patent license would not permit royalty-free redistribution ofthe Library by all those who receive copies directly or indirectly through you, then theonly way you could satisfy both it and this License would be to refrain entirely fromdistribution of the Library.

If any portion of this section is held invalid or unenforceable under any particularcircumstance, the balance of the section is intended to apply, and the section as awhole is intended to apply in other circumstances.

MontaVista� Linux® Professional Edition 243

Page 252: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

It is not the purpose of this section to induce you to infringe any patents or otherproperty right claims or to contest validity of any such claims; this section has the solepurpose of protecting the integrity of the free software distribution system which isimplemented by public license practices. Many people have made generouscontributions to the wide range of software distributed through that system in relianceon consistent application of that system; it is up to the author/donor to decide if he orshe is willing to distribute software through any other system and a licensee cannotimpose that choice.

This section is intended to make thoroughly clear what is believed to be aconsequence of the rest of this License.

12. If the distribution and/or use of the Library is restricted in certain countries eitherby patents or by copyrighted interfaces, the original copyright holder who places theLibrary under this License may add an explicit geographical distribution limitationexcluding those countries, so that distribution is permitted only in or among countriesnot thus excluded. In such case, this License incorporates the limitation as if writtenin the body of this License.

13. The Free Software Foundation may publish revised and/or new versions of theLesser General Public License from time to time. Such new versions will be similar inspirit to the present version, but may differ in detail to address new problems orconcerns.

Each version is given a distinguishing version number. If the Library speciÞes aversion number of this License which applies to it and �any later version�, you havethe option of following the terms and conditions either of that version or of any laterversion published by the Free Software Foundation. If the Library does not specify alicense version number, you may choose any version ever published by the FreeSoftware Foundation.

14. If you wish to incorporate parts of the Library into other free programs whosedistribution conditions are incompatible with these, write to the author to ask forpermission. For software which is copyrighted by the Free Software Foundation,write to the Free Software Foundation; we sometimes make exceptions for this. Ourdecision will be guided by the two goals of preserving the free status of all derivativesof our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY

15. BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NOWARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BYAPPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THECOPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY�AS IS� WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED ORIMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIESOF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THEENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARYIS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUMETHE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

244 MontaVista� Linux® Professional Edition

Page 253: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREEDTO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTYWHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY ASPERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANYGENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGESARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEINGRENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRDPARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHERSOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEENADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to thepublic, we recommend making it free software that everyone can redistribute andchange. You can do so by permitting redistribution under these terms (or, alternatively,under the terms of the ordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attachthem to the start of each source Þle to most effectively convey the exclusion ofwarranty; and each Þle should have at least the �copyright� line and a pointer to wherethe full notice is found.

one line to give the library's name and an idea of what itdoes.Copyright (C) year name of author

This library is free software; you can redistribute itand/or modify it under the terms of the GNU Lesser GeneralPublic License as published by the Free SoftwareFoundation; either version 2.1 of the License, or (atyour option) any later version.

This library is distributed in the hope that it will beuseful, but WITHOUT ANY WARRANTY; without even theimplied warranty of MERCHANTABILITY or FITNESS FOR APARTICULAR PURPOSE. See the GNU Lesser General PublicLicense for more details.

You should have received a copy of the GNU Lesser GeneralPublic License along with this library; if not, write tothe Free Software Foundation, Inc., 59 Temple Place,Suite 330, Boston, MA 02111-1307 USA

MontaVista� Linux® Professional Edition 245

Page 254: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe GNU Lesser General Public License, or GNU LGPL

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, ifany, to sign a �copyright disclaimer� for the library, if necessary. Here is a sample;alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interestin the library `Frob' (a library for tweaking knobs)written by James Random Hacker.

signature of Ty Coon, 1 April 1990Ty Coon, President of Vice

That's all there is to it!

246 MontaVista� Linux® Professional Edition

Page 255: Monta Vista Users Guide

Appendix C: Notices and License AgreementsThe Modified BSD License

The ModiÞed BSD LicenseRedistribution and use in source and binary forms, with or without modiÞcation, arepermitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice,this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyrightnotice, this list of conditions and the following disclaimer in thedocumentation and/or other materials provided with the distribution.

3. The name of the author may not be used to endorse or promote productsderived from this software without speciÞc prior written permission.

THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANYEXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR APARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THEAUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOTLIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER INCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OROTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

MontaVista� Linux® Professional Edition 247

Page 256: Monta Vista Users Guide
Page 257: Monta Vista Users Guide

Appendix D:Documentation Naming Conventions

Naming Conventions

<application> An application name. For example bash or man.

<architecture> Architecture family directories. For example /arm, /mips, /ppc, /sh, /sparc, /x86, etc.

<architecture-canonical-name>

Architecture family name used by GNU tools.

<architecture-preÞx>

The preÞx used for the cross-development applications to indicate the targetarchitecture. A list of architecture preÞxes can be found in �Running Pro Applicationsand Tools� on page 40.

<block-device> The block device where you wish to create a spare partition such as hda1. For moreinformation about partitions, we recommend reading the man pages for parted andfdisk.

<build-directory> An directory where you intend to build the kernel, application, etc.

<destree> The base of a Þle hierarchy.

<fsdirectory> A directory containing your Þle system.

MontaVista� Linux® Professional Edition 249

Page 258: Monta Vista Users Guide

Appendix D: Documentation Naming ConventionsNaming Conventions

<fsimage> An image Þle of your Þle system.

<install-dir> The installation location for Pro or for an application.

<kernel-binary-image>

The name of the kernel binary image Þle. Typically this is vmlinux.

<levels> Run levels for the conÞguration programs.

<lsp-name> The name of the target board LSP. If the <lsp-name> is not known, a listing of legal<lsp-name>s for the current architecture may be obtained using the --list optionwith the hhl-host-install tool. <lsp-name>s are listed in quick start guide foryour target.

<mount-point> The directory where media (or Þle system) has been mounted.

<name> The name or full path (as seen by the target) to a shell or other application.

<package-name> The name of a single Pro package. See �Pro Applications� on page 197 for a list of theapplication packages and availability by architecture.

<path> A Linux directory path.

<priority> Any priority level required.

<processor> Processor directory name, such as /405, /7xx, /74xx, /8xx, or /82xx for PPC or /fp_be/nfp_be, or /fp_le, /nfp_le for MIPS.

<srctree> The name of the root of the Þle hierarchy.

<target> The name of the target board, such as embeddedplanet-rpxlite. See thequick start guide for your target for more information about the name you should use.

250 MontaVista� Linux® Professional Edition

Page 259: Monta Vista Users Guide

Appendix D: Documentation Naming ConventionsNaming Conventions

<targetIPaddress orname>

The system prompt used on the target.

<userID> A person�s user ID.

<version-number> The version number.

MontaVista� Linux® Professional Edition 251

Page 260: Monta Vista Users Guide
Page 261: Monta Vista Users Guide

Glossary of Terms

API Application Programming Interface, deÞning how programmers write source codethat makes use of library or operating system facilities by accessing the behavior andstate of classes and objects.

BOOT ROM Target-resident Þrmware, executed when power is applied or the reset button ispressed on the target.

BOOTP A standard protocol, often used in Boot ROM. BOOTP determines networkconÞguration values via DHCP, Dynamic Host ConÞguration Protocol.

Compiler A tool that translates high-level source code in a language such as C or Pascal intomachine-executable programs. The term may also refer speciÞcally to the tool thattranslates from source to assembly language.

Cross-development This refers to creating code on one architecture, but being able to compile it for adifferent architecture. An example would be to create code on a x86 host, butcompiling the code so that it will run on a PowerPC or MIPS target. Though thearchitectures might not be the same endian or process code the same way, the GCCcompiler provided by MontaVista Software builds code that will run on the target.

Note: If the host and target architectures are different, then code built for the targetwill not run on the host.

MontaVista� Linux® Professional Edition 253

Page 262: Monta Vista Users Guide

Debugger A tool that allows programmers to examine and control program execution, typicallyfor the purpose of Þnding errors in the program.

Embedded System A computer system used as a component in a larger appliance and the end-user, if any,may be unaware or indifferent to the presence of the computer. The embeddedcomputer frequently has a pre-programmed purpose and the user has little, if any,control over program execution.

FSF The Free Software Foundation. The FSF �is dedicated to eliminating restrictions onpeople�s right to use, copy, modify and redistribute computer programs.� The GNUProject is an FSF effort.

gdb Main debugger used with GNU tools (command-line interface).

gcc Acronym for the GNU C compiler. Interchangeably used with capitalization, as GCC.

Glibc A standard compliant C library that has been ported to a number of operating systems,and provides ANSI/ISO, POSIX, BSD and SystemV compatibility.

GNU Recursive acronym for GNU's Not Unix. The GNU Project was launched in 1984 todevelop a complete Unix-like operating system which is free software: the GNUsystem.

Host A host is a system that is a typical workstation such as a PC system running Red Hator a Sun system running Solaris. The Pro tools are installed on this system. The hostsystem is used for compiling, linking, remote debugging and associated developmentactivities. Sometimes referred to as the �server� system.

IDE Integrated Development Environment, a GUI tool or a set of tools that uses GUIfunctionality.

JTAG Joint Test Advisory Group, referring to a type of hardware interface that allows thetesting of chips and boards within a complete system; programs running on processorswith JTAG support may be controlled through the processor JTAG port.

254 MontaVista� Linux® Professional Edition

Page 263: Monta Vista Users Guide

ICE In-Circuit Emulator

Linux Linux is a Unix-type operating system originally created by Linus Torvalds with theassistance of developers around the world. Developed under the GNU General PublicLicense, the source code for Linux is freely available to everyone.

LSP Linux Support Package. An LSP contains a set of Linux Þles, binary and source,designed for a reference target board. These Þles can include: a runtime kernel(sometimes named vmlinux or vmlinuz); host-resident, target-executable programs(shell and shell utilities: mkdir, cd, rm, etc�) and; host-resident, host-executableprograms (compiler, binary Þle converters, debugger).

Patch A patch is a Þle that describes a source code change. It is genenerated by the diffuntility and applied to the original source code with the patch utility.

PROM Programmable Read-Only Memory, ROM that can be programmed using specialequipment. PROMs can be programmed only once.

Registers Registers are storage locations within a processor, allowing for faster access to data.Registers are divided into several classes: machine registers, pseudo registers, andtemporary registers.

ROM Read-Only Memory, non-volatile memory that can be read, but not written, by themicroprocessor.

RTOS Real-Time Operating System.

Target A target is a reference board that you plan to use as the base for your product. Mostembedded targets either don�t have an IDE drive or the drive is too small to have a fullcomplement of tools for building kernels and applications.

TFTP A standard protocol, possibly used by the Boot ROM, by which a system (targetboard) retrieves an executable Þle from another system (from the �host� system).

MontaVista� Linux® Professional Edition 255

Page 264: Monta Vista Users Guide

Toolchain Informal term for the collection of programs that make up a complete set ofcompilation tools. Generally refering to binutils, gcc and glibc.

256 MontaVista� Linux® Professional Edition