Monta Vista Users Guide
This document was uploaded by user and they confirmed that they have the permission to share it. If you are author or own the copyright of this book, please report to us by using this DMCA report form. Report DMCA
Overview
Download & View Monta Vista Users Guide as PDF for free.
More details
- Words: 66,974
- Pages: 264
MontaVista™ Linux® Professional Edition
User’s Guide Version 3.0
1237 E. Arques Ave. Sunnyvale, CA 94085
Copyright Copyright © 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. MontaVista Linux Professional Edition Version
Documentation Release Date
Notes
3.0
December 16, 2003
First Release
3.0
January 10, 2003
First typos.
Acknowledgements Thank 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.
Contact You are welcome to contact us: [email protected]
Contents
Chapter 1
Welcome to MontaVista™ Linux® Professional Edition ................... 1 What is MontaVista™ Linux® Professional Edition? .................................. 1 What Are Linux Support Packages? ........................................................ 1 Pro Is Reproducible ................................................................................. 2 Cross- and Local-Compilation Environments ......................................... 2 Developing Embedded Applications With Pro.............................................. 5 Prepare the Development Environment ................................................... 5 Develop Your Kernel and/or Application................................................. 6 Integrate Your System Components......................................................... 9 Deploy Your Embedded Application ....................................................... 10 About This Manual........................................................................................ 11 Other Documentation .............................................................................. 11 Support .......................................................................................................... 12
Chapter 2
Installation .............................................................................................. 13 Overview ....................................................................................................... 13 Requirements................................................................................................. 15 Host.......................................................................................................... 15 Target ....................................................................................................... 16 The hhl-host-install Tool ................................................................. 17 Usage ....................................................................................................... 17 Options..................................................................................................... 17 Displaying the Product Directory.................................................................. 20 Installing or Upgrading Pro........................................................................... 22 Install ....................................................................................................... 22 Upgrade ................................................................................................... 24 Installing or Upgrading an Additional LSP................................................... 28 Removing Pro................................................................................................ 30 Remove a Single LSP .............................................................................. 30
MontaVista™ Linux® Professional Edition
i
Remove All of Pro ................................................................................... 30 Installing, Upgrading, or Removing Optional Packages ............................... 32 Install ....................................................................................................... 32 Upgrade or Remove ................................................................................. 33 Trouble-Shooting........................................................................................... 34
Chapter 3
The Development Environment ............................................................37 Overview........................................................................................................ 37 Project Directories ......................................................................................... 38 Create Project Directories........................................................................ 38 Populate Project Directories .................................................................... 38 Running Pro Applications and Tools ............................................................. 40 Cross-Development Application PreÞxes ................................................ 42 Accessing man and info Pages ...................................................................... 44 man Pages ................................................................................................ 44 info 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.............................................................................................. 54 ConÞgure Minicom.................................................................................. 54 Start Minicom .......................................................................................... 55 Exit Minicom ........................................................................................... 55 Help.......................................................................................................... 55
Chapter 5
Target ConÞguration Tool (TCT) .........................................................57 Overview........................................................................................................ 57 Starting TCT .................................................................................................. 58 Start TCT ................................................................................................. 58 Create a New Project ............................................................................... 58 Open a Project.......................................................................................... 60 Remove a Project ..................................................................................... 60 TCT Project Menus ....................................................................................... 61 The File Menu.......................................................................................... 61 The View Menu........................................................................................ 64 The Info Menu ......................................................................................... 67 Using TCT ..................................................................................................... 68 Create a ConÞguration File...................................................................... 68 Create/Edit Kernel ConÞguration ............................................................ 69 Create/Edit File System ........................................................................... 70 Build the Target Kernel and File System ................................................. 71 Using the Tar Archive Created by TCT ......................................................... 72
ii
MontaVista™ Linux® Professional Edition
The targetpkg Utility............................................................................... 73 Usage ....................................................................................................... 73 Examples ................................................................................................. 73
Chapter 6
Linux Kernel Development ................................................................... 75 Overview ....................................................................................................... 75 Building and ConÞguring the Kernel ............................................................ 76 Build the Kernel With TCT ..................................................................... 76 Build the Kernel Without TCT ................................................................ 76 Enabling Loadable Kernel Modules.............................................................. 80 Enabling Real-Time Performance Enhancements......................................... 81 MontaVista Real-Time Scheduler............................................................ 81 Preemptible Kernel .................................................................................. 82 Limitations............................................................................................... 83 Enabling Standard Devices............................................................................ 84 Framebuffer Support................................................................................ 84 Videocard Support ................................................................................... 85 PS/2 Keyboard and Mouse Support......................................................... 86 Building Custom Device Drivers .................................................................. 88 Load and Unload the Driver (Kernel Module) ........................................ 89 Code the Kernel Portions of the Driver ................................................... 90 Initial Coding of the Driver ..................................................................... 91 Wrap Up .................................................................................................. 101 Additional Information ............................................................................ 102 Enabling File Systems ................................................................................... 103 Debugging the Kernel.................................................................................... 104 KGDB...................................................................................................... 104 Linux Trace Toolkit (LTT)....................................................................... 107 Abatron BDI2000 .................................................................................... 108
Chapter 7
Application Development ...................................................................... 113 Overview ....................................................................................................... 113 Building Programs Using KDevelop............................................................. 114 MontaVista Customizations..................................................................... 115 Install KDevelop ...................................................................................... 116 Start KDevelop ........................................................................................ 117 Use KDevelop for Cross-Development ................................................... 117 Help ......................................................................................................... 127 Building Programs Using GCC and G++...................................................... 128 Example of a C Program ......................................................................... 128 Example of a C++ Program ..................................................................... 129 Additional Information ............................................................................ 129 Using Threads................................................................................................ 131 Debugging Programs Using GDB and DDD ................................................ 132 Additional Documentation ...................................................................... 132 Example of Using GDB........................................................................... 133 Example of Using GDB and DDD Together ........................................... 134 MontaVista™ Linux® Professional Edition
iii
Debugging Programs Which Call fork(), vfork(), and execve().................... 135 Debugging Multi-Threaded Applications...................................................... 136 Additional Information ............................................................................ 136 Additional Tools for Programming and Debugging ...................................... 137 cbrowser................................................................................................... 137 cßow......................................................................................................... 137 cscope ...................................................................................................... 137 dmalloc .................................................................................................... 138 ltrace ........................................................................................................ 138 mtrace ...................................................................................................... 138 strace ........................................................................................................ 139 showasm................................................................................................... 139 Using AltiVec™ Technology by Motorola .................................................... 140 Features.................................................................................................... 140 Limitations ............................................................................................... 140 Additional Information ............................................................................ 141
Chapter 8
System Integration .................................................................................143 Overview........................................................................................................ 143 Creating Your File-System Hierarchy............................................................ 145 Select a Deployment File-System Type ................................................... 145 Use TCT to Select Applications............................................................... 149 Add Your Custom Application ................................................................. 150 Booting the Target and NFS-Mounting Your File System............................. 151 ConÞguring the User-Space Environment..................................................... 152 Enable Run-Level Services (Startup Scripts) .......................................... 152 ConÞgure the Target for Serial Console or Virtual Terminal................... 156 Create Standard Device Nodes ................................................................ 158 Add Shells................................................................................................ 158 Start PCMCIA ......................................................................................... 160 ConÞgure Networking ............................................................................. 160 Testing Your Environment ............................................................................. 165 Reducing the Size of Your File System ......................................................... 166 Library Optimizer Tool (LOT)................................................................. 166 Example ................................................................................................... 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 .................................................................................................... 175 EXT2 and EXT3 ...................................................................................... 175 Journaling FLASH Filesystem (JFFS)..................................................... 175 ReiserFS................................................................................................... 175 XFS .......................................................................................................... 176 MTD ........................................................................................................ 176
iv
MontaVista™ Linux® Professional Edition
Creating a File-System Image ....................................................................... 179 CramFS.................................................................................................... 179 JFFS/JFFS2.............................................................................................. 180 EXT2/EXT3............................................................................................. 181 ReiserFS................................................................................................... 182 XFS.......................................................................................................... 183 Setting Up Your File Systems (/etc/fstab) ..................................................... 185 Sample 2 .................................................................................................. 185 Booting the New Kernel ................................................................................ 186 Trouble-Shooting Deployment ...................................................................... 187 Corrupt 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 ........................................................................................... 192 Architecture 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
How to Apply These Terms to Your New Programs ................................ 235 The GNU Lesser General Public License, or GNU LGPL ........................... 237 How to Apply These Terms to Your New Libraries ................................. 245 The ModiÞed BSD License ........................................................................... 247
Appendix D
Documentation Naming Conventions...................................................249 Naming Conventions ..................................................................................... 249
Glossary of Terms............................................................................................................................. 253
vi
MontaVista™ Linux® Professional Edition
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 the supported target CPUs, along with a full complement of development tools designed to help you design, develop, and deploy an embedded application. Whether you’re building Internet appliances, portable devices, networking equipment, telephony interfaces, or other embedded and pervasive applications, you can count on MontaVista 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-level platforms of any embedded Linux development solution available today. Pro highlights include:
What Are Linux Support Packages?
•
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
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
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition What is MontaVista™ Linux® Professional Edition?
(shell and shell utilities: mkdir, cd, rm, etc.); and host-resident, host-executable programs (compiler, binary Þle converters, debugger). Pro includes LSPs for over 78 different reference boards. The advantage of using an LSP for kernel or Þle system development is that by using a system that is known to work as a base for your development, you can greatly decrease your development time.
Pro Is Reproducible
Pro can be reproduced without using any proprietary products. The advantage to this design is that you, the developer, can view the source code of the software, tailor the software as needed, and learn from the software. You may not need to recompile any portion of Pro; however, if you do need to recompile Pro (due to contract issues), it is possible.
Cross- and LocalCompilation Environments
Pro is designed to be a cross-compilation environment that is capable of being used as a 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 one architecture 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 it runs on a PowerPC or MIPS target. Though the architectures might not be the same endian or process code the same way, the gcc compiler provided by MontaVista builds code that will run on the target. Note: If the host and target architectures are different, then code built for the target will 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 are used for compiling, linking, remote debugging, and associated development activities.
2
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition What is MontaVista™ Linux® Professional Edition?
A target is a reference board that you plan to use as the base for your product. Most embedded targets either don’t have an IDE drive or have a drive that is too small to have 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: Cross-Compilation Environment
Local Network Pro 3.0 --------------Red Hat 7.3
MontaVista Linux
Serial .................. ................... Target
Host
The advantage of a cross-compilation system is that the host system is generally faster and easier to develop on compared to the target system. Another advantage is that it is easier to recover your system should a change render your kernel un-bootable. Those of you with experience as Real-Time Operating System (RTOS) developers may already be accustomed to using a cross-compilation environment.
The local-compilation environment In a local-compilation environment, all of the tools and applications required to rebuild the system are installed directly on the target system. Local-compilation refers to creating code or developing applications on (and for) the architecture and operating system being used. For IA-32/x86 targets, Pro can be installed directly on the target for local-compilation development. Using a local-compilation environment, no network connection or
MontaVista™ Linux® Professional Edition
3
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition What is MontaVista™ Linux® Professional Edition?
cross-compilation host is needed. For a typical IA-32/x86 system, the localcompilation environment appears as in the diagram below: Local-Compilation Environment
Pro 3.0 (x86 development tools and basic file system)
.................. .................. Target (with keyboard and VGA display)
Most open-source and commercial developers are already accustomed to developing applications on (and for) the operating system that they use every day. This is one of the advantages of having a local-compilation system. Another advantage of having a local-compilation system is that it can provide a quick development-to-deployment environment. However, in the embedded-systems industry, most systems are small; therefore, local-compilation development could potentially increase costs and reduce productivity. Note: This manual focuses on the cross-compilation environment. Information about using local compilation can be found in a separate MontaVista publication, Using MontaVista Linux Professional Edition for Local Compilation.
4
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing 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 in Pro to build your embedded application. The outline below covers the development cycles of the three main components of an embedded Linux application – kernel development, application development, and system integration. For some projects, the Linux kernel and MontaVista provided applications can be used without modiÞcation, allowing you more time to focus on your custom applications. For other projects, you may Þnd that you need to modify the kernel to support custom features for your board, 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 recommend pursuing your project in the following order. The steps described below are explained in 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. By installing the LSP for your reference board, you have a default environment that can be 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 reference board’s architecture and processor, and you have all of the cross-compilation tools that 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 you followed the instructions in the quick start guide for your target provided by MontaVista, the target’s root Þle system is NFS-mounted on the host. The development environment directory structure appears as follows:
NFS root file system
Target System
Host System /opt/hardhat /devkit /<architecture> /<processor> /target /bin /etc /lib ... /host
MontaVista™ Linux® Professional Edition
5
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing 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 target system 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 ready to begin development. Included in the Pro distribution are over 280 application packages. If you do not know how to use these applications, documentation in the form 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 you need to modify to a work directory elsewhere on your host. This way, you can easily return to the default conÞgurations provided by MontaVista. In addition, it is important that you do not make changes to the /target directory. This directory is used by the MontaVista Target ConÞguration Tool (TCT) for Þle system development. Changes can result in problems when creating your Þle system. Assuming that you are doing kernel and application development, you could create a work directory structure such as the following: my_work_directory /mykernel /myapplication /myfilesystem
The mykernel directory can be used for kernel development. The myapplication directory can be used for application development. The myfilesystem directory is where you can integrate your Þle system hierarchy and your 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
6
Once you have prepared your environment, you are ready to begin development. Application and kernel development cycles are very similar. Typically, kernel development work is done before application work; however, kernel work and application work can occur in parallel and be merged later for testing and Þnal deployment.
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
The typical development cycle for building a kernel and/or application appears as follows: Begin development
Compile the kernel and/or application on the host Modify the kernel and/or application on the host
Make the kernel and/or application available to the target
Run the target to test the kernel and/or application
Success! Whether you are working on kernel code or application code, we recommend making only a few changes to your target’s environment at a time. This method allows you to track your progress and isolate bugs more easily. It will also help the MontaVista Support team answer your questions more quickly. Simply stated, by starting from an environment 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 tool provided by MontaVista used to manage kernel and Þle system development, or you may use the compilers and kernel debuggers distributed with Pro. Whether you use TCT or another method, you should create a work directory (such as mykernel) for kernel development that contains a copy of the LSP kernel. If you use TCT, the LSP kernel and conÞguration Þles are copied automatically to a work directory when you create a TCT project. If you do not use TCT, you need to copy the LSP kernel by hand. TCT stores kernel conÞguration information in a conÞguration Þle. One advantage of using TCT is that you can easily save multiple kernel (and Þle system) conÞgurations for a single project. However, if you use TCT, it is important to note that changes made to the kernel using another tool, such as make menuconfig, will not be stored 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 your development depends on whether you are customizing kernel code, adding a custom device driver, or conÞguring the kernel. If you are adding custom kernel code or adding a custom device driver, we recommend that you use the copy of the kernel in your project directory.
MontaVista™ Linux® Professional Edition
7
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
If you are conÞguring the kernel, we recommend that you use TCT. Before you , conÞgure your kernel, you should make some decisions about the kernel options you need to enable. Because rebuilding the kernel can take time, it is best to make your kernel conÞguration selections all at once. Here are some things to think about when you 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 performance enhancements? (real-time scheduler or preemptible kernel)
•
Which type of Þle system do you want to use in your deployed embedded project? (EXT2, ReiserFS, JFFS, etc.)
Once you have Þnished building the kernel, you can boot the target with the new kernel 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 with Pro. Whether you use KDevelop or another tool, you should create a work directory (such as myapplication) for application development. After you have written and compiled your application on the host, move the application to an NFS-mounted Þle system on the target to test the application. There are a number of advantages to using a cross-development environment with an NFS-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 fault isolation.
•
The NFS root Þle system provides a large selection of applications that the typical embedded target would not be able to have locally as it would not, in most cases, have enough resources.
•
In most environments, compiles more quickly on the host than on the target, because the host is usually faster and has more resources than 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 the target; however, in most cases, using the host’s environment makes more sense.
8
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
Integrate Your System Components
Once you are satisÞed with your kernel and application, it is time to integrate your system components and test your embedded environment. Integrating the system components includes the following steps: •
Determine which libraries and applications are required to support your application, and then build a Þle system with those applications and libraries. We recommend that you use TCT to select 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 build directory (such as myfilesystem) as the location for integrating your Þle system and application.
•
Export the myfilesystem directory containing your Þle system and application as NFS to the target system. By exporting the Þle system directory as NFS, you can test your environment on the target before spending the development time to reduce the Þle system size or burn the Þle system into ßash.
•
ConÞgure the user environment. Doing this for your application can include activities such as adding your application to start-up scripts (setting the run levels), creating required device nodes, or conÞguring the networking components used.
Once you have completed the tasks above, you should have a system that appears as follows: User-Space Configs
Local Network Pro 3.0 --------------Red Hat 7.3
Custom Apps NFS Root File System
Custom Kernel
Target File System
Serial
.................. ................... Target Host
When you know you have an environment that works, you can proceed to reducing the size of your Þle system. After reducing the size of your Þle system, you should use proÞling tools to evaluate the your project’s performance and to look for memory
MontaVista™ Linux® Professional Edition
9
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
leaks, etc. You will want to use the same development cycle you used for initial kernel and application development to Þx and test problems uncovered with these tools.
Deploy Your Embedded Application
When your kernel and application have been proven in a test environment, then it’s time 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: User-Space Configs
Custom Apps Local Root File System
Custom Kernel
.................. ................... Target
Disconnecting the target from the host may require building a kernel and Þle-system image that can be booted from ßash, or it may require a system than can be booted via LILO. Some general strategies are outlined later in this manual.
10
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition About This Manual
About This Manual This manual describes how to install and use Pro to develop embedded systems based on Pro. This manual covers all supported target architectures, and it is included on each of the Pro CDs in PDF format. The host system in this manual is assumed to be a Red Hat® host. If you are using another host, we recommend that you read one of the Pro host manuals for more information and requirements regarding the host OS you are using. This manual assumes that you know how to use Linux. If you are unfamiliar with Linux, there are many books available to help you get started using and understanding Linux. Note: MontaVista Software does not endorse the book listed below. The following example is provided for your convenience only: •
Other Documentation
Running Linux, Matt Welsh, Matthias Kalle Dalheimer, and Lar Kaufman. Sebastopol, California: O'Reilly & Associates [1999]. (ISBN: 156592469X)
MontaVista Linux Professional Edition Quick Start Guides For each supported target, MontaVista Software provides a Pro quick start guide. The quick start guides contain step-by-step instructions for booting Pro on the target using a Red Hat® Linux host. Copies of the quick start guides can be found on the “Pro Host Binaries” CD-ROM in the /docs/quickstarts directory. In addition, as updates 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 use one of the other supported hosts, MontaVista Software provides host manuals. These manuals provide step-by-step instructions on how to conÞgure the host along with usage notes about using Pro with that host OS. Host manuals are available for Solaris™, SuSE®, YellowDog®, and Mandrake™ as well as for using a localcompilation environment. Copies of the Pro host manuals can be found on the “Pro Host Binaries” CD-ROM in the /docs/hostmanuals directory. In addition, as updates are made, the latest versions will be available on MontaVista Zone.
MontaVista Zone MontaVista Zone (http://support.mvista.com) is the MontaVista subscriber-only support Web site. MontaVista Zone provides focused information to assist in getting products to market faster. On MontaVista Zone, you will Þnd embedded Linux information, access to MontaVista-developed software, and MontaVista FAQs.
MontaVista™ Linux® Professional Edition
11
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Support
Support In-depth technical engineering assistance is available for the distributed software that MontaVista Software develops, for example, MontaVista Linux Professional Edition. Customers can request help with installation, conÞguration, usage, and other questions concerning Pro. Generally, this software is fully supported for development and 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 Support Packages (LSPs) may be deemed for “development only.” This means one or both of the following: •
MontaVista Software still considers this LSP to be under development and does not guarantee, support, or recommend its use for deployment in end customer products.
•
MontaVista Software considers this LSP to be useful and supports the use of this LSP for customers to develop on and with. These LSPs usually are updated regularly and the customer should visit MontaVista Zone (http://support.mvista.com) to look for updates. The purpose of this classiÞcation is to get LSPs to customers as quickly as possible. The LSP may be as complete as it is planned to be, and following a release or update, the LSP will be changed from “development only” to “development and deployment.”
General technical assistance only is provided for third-party products that MontaVista Software recommends for use with Pro. This service may range from answering questions to providing work-arounds. Since MontaVista Software is not responsible for the development of these third party products, some issues may require input from the original applications vendor. Note that MontaVista only provides assistance for these products when they are being used with Pro. No assistance is provided for non-system software, e.g. games or I/O drivers for nonMontaVista Software certiÞed systems and boards. MontaVista Software maintains a hardware support environment of supported boards and systems to duplicate the reference hardware environment of the customer. If a customer is having a problem on a custom board or customized enhancements that they’ve made to our standard products, MontaVista Software may request that the customer duplicate the problem on a reference board Þrst before troubleshooting the problem. MontaVista Software wants your input regarding how well MontaVista Software is performing, 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
Chapter 2: Installation
Overview To use Pro 3.0, you Þrst need to install it on your host machine. Step-by-step instructions for installing Pro 3.0 for a cross-compilation development environment can also be found in the quick start guide for your target. For instructions on how to install Pro 3.0 on an IA-32/x86 target for a local-compilation development environment, see Using MontaVista Linux Professional Edition for Local Compilation. Pro 3.0 is distributed as a multiple CD-ROM set. The number and complement of CDROMs in your set depends on the product subscription you have purchased. Each Pro 3.0 subscription CD-ROM set contains: •
A “Pro 3.0 Host Binaries” CD-ROM, containing the components for all supported development host platforms
•
One or more Pro 3.0 target architecture CD-ROMs, containing the target platform components
•
A “Pro 3.0 Source” CD-ROM containing all of the source packages (SRPMS) corresponding to installable packages on the other CD-ROMs
To install Pro 3.0 for cross-compilation, you need to use the hhl-host-install tool. 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
Chapter 2: Installation Overview
•
“Removing Pro” on page 30
•
“Installing, Upgrading, or Removing Optional Packages” on page 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
Chapter 2: Installation Requirements
Requirements Before you begin, make sure your host and target machines meet the requirements provided below.
Host
Pro 3.0 supports a variety of different host environments for cross-compilation development. You may use any of the supported host systems with any of the supported 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 software that you need in order to install and use Pro. For Red Hat hosts, if you are using a standard Workstation installation (all versions) with X windows and Gnome or KDE and Software Development package groups (7.2 and 7.3) installed, you need to install dhcp (individual package) from the Red Hat installation CD-ROMs. For Red Hat 7.2 and 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, along with any restrictions and work-arounds for using a particular host, can be found in the host manuals. Regardless of which host system you are using, your system must meet the following requirements: •
For a basic installation of a single architecture and a single LSP, the host system must have a minimum of 1100 MB disk space available. Note: For each additional architecture, you need an additional 800 MB of disk space. For each additional LSP, you need an additional 150 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 either a serial connection to the host, or a VGA display and keyboard connected to the target. (Refer to the quick start guide for your target to determine your connection type.)
MontaVista™ Linux® Professional Edition
15
Chapter 2: Installation Requirements
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 different target 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 information about support levels, see “Support” on page 12.
16
MontaVista™ Linux® Professional Edition
Chapter 2: Installation The 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--help hhl-host-install--version hhl-host-install--install | --upgrade | --remove | --list [ --quiet | --verbose ] [ --confirm | --noconfirm ] [ --noprogress | --progress ] [ --media { /mnt/cdrom | <mediamountpoint> } ] [ --prefix { /opt | } ] [ --lsp ] { | } --package <package-name>
Options
The following list contains a description of each option: •
--help This option produces an installer usage display similar to the above.
•
--version This option displays the version of the installer.
•
--install This option speciÞes operation of the installer which results in an install of all packages on a fresh system, or to install an additional LSP to an existing environment. If neither --install, --upgrade, --remove, or --list is speciÞed, --install is assumed.
•
--upgrade This option speciÞes an upgrade operation whereby existing packages are upgraded from copies on the distribution.
•
--remove This option speciÞes a remove operation to remove all or part of a previous MontaVista Linux installation from the host.
•
--list This option produces a listing of the LSPs on the distribution and/or previously 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 --list options are mutually exclusive.
•
--verbose This option speciÞes that installation steps are to produce verbose
MontaVista™ Linux® Professional Edition
17
Chapter 2: Installation The hhl-host-install Tool
output with respect to actions taken, such as complete lists of installed Þles.
18
•
--quiet This option speciÞes that installation steps produce compact output for each step. This is the default.
•
--progress This option displays progress bars ("#") during package installation.
•
--noprogress This option does not display progress bars during package installation. This is the default.
•
--confirm This option speciÞes that the user is prompted to make decisions about the progress of the installation process. This is the default. The instructions below assume that conÞrmation is in effect and show the types of prompts received in this mode.
•
--noconfirm This option speciÞes that the installation is to run unattended and default responses are assumed for actions which would evoke a prompt in conÞrmation mode. In some cases where a media change or password is required, operation cannot be completely unattended.
•
--media This option speciÞes the location of the distribution media. The default is the mount point of the distribution media, generally /mnt/cdrom, the default CD-ROM mount point. If another medium (such as NFS) or different CD-ROM mount point is used, specify the mount point for that distribution here.
•
--prefix This option speciÞes the installation location for the product. The default is /opt/hardhat, the MontaVista Linux default installation directory. If an alternate install directory is desired, specify it here.
•
--lsp --lsp This option speciÞes an Linux Support Package (LSP) for a given target platform to be listed, installed, upgraded, or removed according to the operation option selected. The keyword “--lsp” is optional. This option has no default. If an LSP is required for the current operation and none is speciÞed in this option, the installer will prompt for an LSP name. Legal values for are listed under the “LSP Name” column of the display produced by
MontaVista™ Linux® Professional Edition
Chapter 2: Installation The hhl-host-install Tool
the --list option. In addition, the remove operation accepts the special values “all” or “hhl” to denote all LSPs. If is speciÞed instead of , it contains one or more Linux Þlename pattern-matching characters. Such a value may need to be quoted to protect the value from shell expansion. For install, upgrade, and remove operations, must match at most one ; if an LSP is required for the current operation and the pattern matches multiple s, the installer will prompt for an LSP name. For list operations, the installer will display all s that match the pattern. The --lsp and --package options are mutually exclusive. •
--package <package-name> This option speciÞes a single host, cross-development, or target architecture package to be installed, upgraded, or removed according to the operation selected. The operation modiÞes the installed MontaVista Linux environment. Incorrect use of this option may render the cross-development environment or the target board unusable. This option has no default. <package-name> is the MontaVista Linux RPM package name beginning with “hhl-”. Installed MontaVista Linux packages may be listed using RPM. All package-oriented operations must take place using a single installation location speciÞed by --prefix or using the default in this 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. An afÞrmative reply is required to continue. An attempt to install a package already installed, or remove a package not installed, results in an error. However, it is okay to upgrade a package that is already installed.
MontaVista™ Linux® Professional Edition
19
Chapter 2: Installation Displaying the Product Directory
Displaying the Product Directory To display a list of all the LSPs contained in the product along with the location of those 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 used need 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 product directory. To see the complete list of LSPs in the product, enter the following command: /mnt/cdrom/bin/hhl-host-install --list
To see an abbreviated list of LSPs that match a pattern, enter the pattern using Linux Þle-name pattern-matching characters. /mnt/cdrom/bin/hhl-host-install --list
For example: /mnt/cdrom/bin/hhl-host-install --list motorola*
Note: You may need to quote the value to protect pattern-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 tool for installation, upgrade, or removal; for example, as part of the --lsp option. Under “Target Board” is the manufacturer's name and the well-known product name for the target hardware supported by the speciÞed LSP.
20
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Displaying the Product Directory
Under “Location” is the text of the printed label for the CD-ROM on which the LSP is distributed. It may be the same CD-ROM currently mounted for the --list operation, or any other CD-ROM in the product set. Note: You may not have subscribed to all architectures included in Pro; therefore, you may 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
Chapter 2: Installation Installing 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 product installed and you would like to upgrade to Pro, follow the instructions in “Upgrade” on page 24. Note: Even if you are not installing the same LSP as in the previous version, you need to upgrade to the Pro rather than perform a new installation because the required host packages must be upgraded.
•
If you have already installed Pro 3.0 (or upgraded to Pro 3.0) and you want to install or upgrade an additional LSP, follow the instructions in “Installing or Upgrading an Additional LSP” on page 28.
Warning! Some of the host OS default installations do not include all of the software that you need to install and use Pro. Information about the additional components and steps required for a particular host along with any restrictions and work-arounds for using a particular host can be found in the host manuals. Host manuals are located on the “Pro Host Binaries” CD-ROM in the /docs/hostmanuals directory. Host manuals are also available on MontaVista Zone.
Install
The following steps are used to install the Pro product for the Þrst time. First-time Pro installation requires two CD-ROMs: •
The “Pro Host Binaries” CD-ROM, which applies to all installations
•
The target architecture CD-ROMs, containing the target LSP you want to install Note: You may identify the correct target architecture CD-ROM using the tables in appendix A of the quick start guide for your target or by using the --list option of the installation tool. The label 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 Þrst CD-ROM and the installation will not proceed. For this reason, you should either print out this documentation or make a local copy on your machine. Viewing the documentation from the CD-ROM will cause the CD-ROM device to be busy.
22
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing 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 to run the tool, as this will cause the tool to be unable to unmount the Þrst CD-ROM. To install to an alternate location, include the --prefix option in the command. For example, use the command: /mnt/cdrom/bin/hhl-host-install --prefix
is the selected installation location. Note: All Pro base and optional products must be installed in the same location. Select a location that provides enough space both to complete the Þrst-time installation and to allow for expansion if you intend to install 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 platform hardware you wish to install. LSP names are listed in the quick start guide for your target. LSP names can also be listed by typing ? at the prompt. A list of LSP names will be displayed and the prompt above will be repeated. The host platform packages will be installed into the location selected in step 5. The installation tool ejects the “Pro Host Binaries” CD-ROM and displays the message:
MontaVista™ Linux® Professional Edition
23
Chapter 2: Installation Installing or Upgrading Pro
hhl-host-install: Insert MontaVista Linux CD and press enter:
speciÞes the label of the target architecture CD-ROM needed to complete installation. 7.
Insert the appropriately-labeled CD-ROM speciÞed in the message into the 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 architecture CD-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 more information, see “Trouble-Shooting” on page 34.
Upgrade
Important: The Pro 3.0 installation tool allows you to use the --upgrade option to upgrade 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.1 already installed on your host machine.
Should I upgrade? While we generally recommend that you upgrade to Pro 3.0, there are some situations where we recommend not upgrading at this time. These include: •
If you are using a MontaVista add-on product (such as VisualAge Micro Edition 1.4 for MontaVista™ Linux®) that has not yet been updated for use with Pro 3.0. Upgrading to Pro version 3.0 will cause the add-on to no longer function correctly. If your project relies on having the add-on functionality available, we recommend not upgrading at this time.
•
If you decide to upgrade to Pro 3.0, you must upgrade all LSPs at once. Failure to do so will “break” the LSPs that were not upgraded. If you are using multiple LSPs and your development cycle prohibits upgrading all LSPs, you may not want to upgrade at this 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
Chapter 2: Installation Installing or Upgrading Pro
Installations of Pro 3.0 and Pro 2.1 CANNOT coexist, because they use a shared RPM database; therefore, the installation tool upgrades MontaVista-distributed packages in place. For that reason, you must upgrade Pro 3.0 using the same directory as 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 all installations
•
The Pro 3.0 target architecture CD-ROM, containing the target LSP you want to install Note: You may identify the correct target architecture CD-ROM using the tables in appendix A of the quick start guide for your target or by using the --list option of the installation tool. The label 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 Þrst CD-ROM and the installation will not proceed. For this reason, you should either print out this documentation or make a local copy on your machine. Viewing the documentation 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
Chapter 2: Installation Installing or Upgrading Pro
Warning! Do NOT change directories to the CD-ROM mount point to run the installation tool, as this will cause the tool to be unable to unmount the Þrst CD-ROM. To install at an alternate location, include the --prefix option in the command. Use the command: /mnt/cdrom/bin/hhl-host-install --upgrade --prefix
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) is the selected installation location. Note: If you installed Pro 2.1 in an alternate directory you must specify that directory using the --prefix option. The installation tool does not permit you to have simultaneous installations of MontaVista Linux products. You’ll be prompted to conÞrm that you want to overwrite the existing LSP. You must reply afÞrmatively to continue. 6.
Enter the name of the LSP that corresponds to the target hardware you wish to install. LSP names are listed in the quick start guide for your target. LSP names can also be viewed by typing ? at the prompt. A list of LSP names will be displayed and the prompt above will be repeated. The host platform packages will be installed into the location selected in step 5. The installer ejects the “Pro 3.0 Host Binaries” CD-ROM and displays the message: hhl-host-install: Insert the MontaVista Linux CD and press enter:
speciÞes the label of the target architecture CD-ROM needed to complete installation. 7.
Insert the target architecture CD-ROM speciÞed in the message into the CD-ROM drive and press Enter. The appropriate target platform 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 architecture CD-ROM.
26
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing or Upgrading Pro
If the upgrade is successful, you receive a message indicating upgrade is complete. In the event of a failure, review the error message and correct the problem. For additional information, see “Trouble-Shooting” on page 34.
MontaVista™ Linux® Professional Edition
27
Chapter 2: Installation Installing 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 to Pro version 3.0 for at least one LSP. To install Pro version 3.0 for the Þrst time, use the steps 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-ROM containing the desired target platform LSP. The correct target architecture CD-ROM is listed in the quick start guide for your target. You may also use the --list option of the installation tool. The label of the correct target architecture CD-ROM is displayed 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 additional LSP 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 default location, /opt/hardhat, use the command: /mnt/cdrom/bin/hhl-host-install
Warning! Do NOT change directories to the CD-ROM mount point to run the installation tool, as this will cause the tool to be unable to unmount the Þrst CD-ROM. If hhl-host-install is run while accessing the mounted CDROM, the installer will abort. If the CD-ROM is referenced from another 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 the command: /mnt/cdrom/bin/hhl-host-install --upgrade
To install (or upgrade) to an alternate location, include the --prefix option in the command. For example, to install to an alternate location, use the command:
28
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing or Upgrading an Additional LSP
/mnt/cdrom/bin/hhl-host-install --prefix
is the selected installation location. Note: All Pro base and optional products must be installed (or upgraded) in the same location. Use the default location for the product installation if you previously used the default location to install Pro. If an alternate location was chosen for Pro, use that same location for this installation. You’ll be prompted to conÞrm that you want to overwrite the existing LSP. You must reply afÞrmatively to continue. 5.
Enter the name of the LSP that corresponds to the target platform hardware you wish to install. LSP names are listed in the quick start guide for your target. LSP names can also be viewed by typing ? at the prompt. A list of LSP names will be displayed and the prompt above is repeated.
All target platform packages related to the selected LSP are installed at the location selected in step 4. Packages which were previously installed as part of another LSP are 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
Chapter 2: Installation Removing Pro
Removing Pro If you installed the incorrect LSP or would like to remove your installation of Pro, use hhl-host-install. Note: For removals, the Pro CD-ROM does NOT need to be available. Once Pro is installed, 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 in a location other than the default, replace /opt in the path above and in the commands below 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 were originally installed. You may also remove the last remaining LSP. In this case, the host platform 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
You receive a message conÞrming your intentions: hhl-host-install: This operation will remove all installed 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 components that 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
Chapter 2: Installation Removing 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 components that these services may depend on are no longer present on your system.
MontaVista™ Linux® Professional Edition
31
Chapter 2: Installation Installing, Upgrading, or Removing Optional Packages
Installing, Upgrading, or Removing Optional Packages Not 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 if installed simultaneously. See “Pro Applications” on page 197 for a list of applications appearing 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 (and therefore the optional target application) you need 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 with the --package <package-name> option to 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 “Pro Applications” 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 was previously 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
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) For example, to install the optional dhcpcd package for a Pentium II target when the non-default installation directory /group1 was
32
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing, Upgrading, or Removing Optional Packages
previously chosen for Pro installation, you would use the following command: /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 of mutually exclusive packages you may, for example, remove a previously installed optional package from a mutually exclusive set and install an alternative package from 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 to continue. An attempt to install a package already installed, or remove a package not installed, results in an error. However, it is okay to upgrade a package that is already installed.
MontaVista™ Linux® Professional Edition
33
Chapter 2: Installation Trouble-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 automounter running, logging into a KDE or Gnome desktop and then using the su command to become 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 runs under a non-root userID. Under these conditions, the automounter will mount the distribution CD-ROM using the noexec option (implied by user), rendering the hhl-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 root login desktop session rather than using the command su root from a non-root desktop session. Another option is to disable the automounter. To disable the automounter, you need to edit the Þle /etc/fstab to either add the exec option before 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 eject the Þrst CD-ROM and installation will not proceed. Three of the most typical reasons are: •
For some desktop environments, when the automounter mounts a CD-ROM, a Þle-system browser window appears. You need to close this window to allow the CD-ROM to be unmounted by the installer.
•
If you changed directories to the CD-ROM mount point to run the installation 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 cause the CD-ROM device to be busy. You should either print this manual or make a local copy on your machine.
Unable to burn CDs Pro CD images can be downloaded via MontaVista Zone. MontaVista Software recommends burning CDs and installing from those CDs. If you are unable to burn CDs, Pro can be installed from the CD images using the --media-host or
34
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Trouble-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 a command 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 you wish to install that you previously downloaded, using a loopback mount. Loopback mounts are available only on Linux host systems. Use a command 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 location of the two CD images: /mnt/prof-host/bin/hhl-host-install --install --media-host <mounted-cdimage-dir> --media-arch <mounted-cdimage-dir>
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) <mounted-cdimage-dir> is the CD image mounted on /mnt/profhost or /mnt/prof-arch. You may run the hhl-hostinstall tool from either the CD image mounted on /mnt/profhost or /mnt/prof-arch. The same installation tool is provided in both CD images. If the <prof-target-cdimage-Þle> you supply does not correspond to the correct architecture for, 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 from the beginning with the correct image.
MontaVista™ Linux® Professional Edition
35
Chapter 2: Installation Trouble-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
Chapter 3: The Development Environment
Overview Pro contains everything you need to build an embedded Linux kernel. Full source is provided to allow for a custom kernel and for custom device drivers, as well as for application development. For more information about the Pro directory structure installed, see “Pro File-System Layout” on page 189. Included in the Pro distribution are over 280 application packages. If you do not know how to use these applications, man and info pages are available that can help. A complete list of the applications, along with a brief description and pointers to reference 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 ready to begin development. This chapter provides step-by-step instructions on how to conÞgure your development environment to allow you to easily use the tools included with 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
Chapter 3: The Development Environment Project Directories
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 you need to modify to a work directory elsewhere on your host. We make this recommendation for the following reasons: •
It allows you to easily return to the default conÞgurations provided by MontaVista Software.
•
The /opt/hardhat/devkit/<architecture>/ <processor>/target/ directory is used by the MontaVista Target 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 steps below: 1.
Create project directories.
2.
Populate your project directories with copies of the default Þles from MontaVista 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 a work directory structure such as the following: my_work_directory /mykernel /myapplication /myfilesystem
The mykernel directory can be used for kernel development. The myapplication directory can be used for application development. The myfilesystem directory is where you can integrate your Þle system hierarchy and your 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 project directories. The sections below describe what we recommend each project directory contain.
mykernel In this directory, you should place a copy of your development kernel. How you copy the development kernel over depends on whether you are using Target ConÞguration
38
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Project Directories
Tool (TCT) (recommended), or another utility, such as make menuconfig, for your kernel development. TCT. If you are using TCT, when you create your TCT project directory, select the mykernel directory to save your project. TCT will automatically copy everything you need for kernel and Þle-system development to the mykernel directory. make menuconÞg. If you are using another tool, such as make menuconfig, use the following commands to copy everything in the appropriate linux directory in the kernel source tree to your mykernel directory: cd my_work_directory/mykernel cp -a /opt/hardhat/devkit/lsp//linux- .
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 another method for copying the Þles over, be sure to include options for copying symbolic linking and permissions.
myapplication Use this directory to build your application. At this time, there is nothing that needs to be copied from the Pro distribution to your application work directory for you to begin development. If you are using KDevelop, you need to specify this directory when setting up your project.
myÞlesystem In this directory, you will eventually want to create a sub-directory for each of your test Þle systems. The Þle system we recommend you start with is a copy of the target’s default root Þle system directory. Other Þle systems you will want to test are those that 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 Þles are 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 convenient location for testing your application on the target.
MontaVista™ Linux® Professional Edition
39
Chapter 3: The Development Environment Running Pro Applications and Tools
Running Pro Applications and Tools Pro includes over 280 application packages. Applications are classiÞed as “crossdevelopment applications,” “host applications,” or “target applications.” Cross-development applications are tools that are run on the host but produce output intended to run on the target. In general, the cross-development applications are compilers, 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 compatible version of TFTP. For the list of host applications, see “Host Application Packages” on page 200. Target applications are intended to be used only on the corresponding architecture target. The Pro distribution contains pre-compiled and pre-packaged versions of these application packages so that RPM can be used to install them on the target. For development, we recommend that NFS be used to provide the target root. The Þle system served by NFS is considered part of the target system, and therefore contains only target application packages (i.e., “host” and “cross-development” packages are not installed into this NFS portion of the Þle system). For the list of target applications, see “Target Application Packages” on page 204.
40
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Running Pro Applications and Tools
The chart below shows the full installation paths for the Pro applications and tools. If you installed Pro using relocation, replace /opt in the paths listed below with the path you used. Applications Target
Path 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
Crossdevelopment
/opt/hardhat/devkit/<architecture>/<processor>/bin
To run any of Pro applications, update your executable search path to include the Pro applications. 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 the application start command at the host or target system prompt. For help on any of the applications, see the man or info page for that application. For more information, see “Accessing man and info Pages” on page 44.
MontaVista™ Linux® Professional Edition
41
Chapter 3: The Development Environment Running Pro Applications and Tools
Note: Cross-development applications contain a preÞx indicating the target architecture and processor. For a list of the preÞxes, see “Cross-Development Application PreÞxes” on page 42. For example, to update your executable search path to include the Pro host applications 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)
CrossDevelopment Application PreÞxes
Cross-development applications use a preÞx that indicates the architecture and processor in the application’s start command. For example, to run GCC to compile code 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 CPU architecture and processor types. Architecture and Processor
42
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
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Running Pro Applications and Tools
Architecture and Processor
Prefix
Example
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
MontaVista™ Linux® Professional Edition
43
Chapter 3: The Development Environment Accessing man and info Pages
Accessing man and info Pages Linux has fairly extensive online documentation. Most of the applications included with Pro have man and/or info pages available. Info pages are online manuals for the given application. A typical man page provides a description of the application and its options, 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 the chart below. If you installed Pro using relocation, replace /opt in the paths listed below with the path you used.
Applications
Path
Target
/opt/hardhat/devkit/<architecture>/<processor>/target/ usr/share/man
Host
/opt/hardhat/host/man
Cross
/opt/hardhat/devkit/<architecture>/<processor>/man
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 search path 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 for the host applications for bash, use the command: export MANPATH=/opt/hardhat/host/man:$MANPATH
44
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Accessing 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 the following command at the host or target system prompt: man
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 man pages are displayed, enter the command: man -aw
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 for man. 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 the chart below. If you installed Pro using relocation, replace /opt in the paths listed below 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
Chapter 3: The Development Environment Accessing man and info Pages
Viewing info pages To view info pages for any of the Pro applications, update your executable search path to 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 for the 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 the following command at the host or target system prompt: info
For example, to view the info page for bash, enter the command: info bash
46
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Accessing man and info Pages
Additional information Additional information about info pages can be obtained by reading the info page for info. To view the info page for info, enter the command: info info
MontaVista™ Linux® Professional Edition
47
Chapter 3: The Development Environment Other 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:
48
•
/opt/hardhat/devkit/<architecture>/ <processor>/doc
•
/opt/hardhat/host/doc
•
/opt/hardhat/devkit/lsp//linux/Documentation
MontaVista™ Linux® Professional Edition
Chapter 4: Target ConÞguration and Boot
Overview Once you have installed Pro on your host machine and conÞgured your development environment, 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” on page 50
•
“Booting the Target with a Custom Kernel” on page 52
•
“Using Minicom” on page 54
MontaVista™ Linux® Professional Edition
49
Chapter 4: Target Configuration and Boot Booting 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 Software provides a quick start guide. The quick start guides contain step-by-step instructions for booting Pro on the target for a cross-compilation development environment. For instructions on how to install Pro for local-compilation development on an IA-32/x86 target, see Using MontaVista Linux Professional Edition for Local Compilation. Copies of the Pro quick start guides and the local-compilation manual can be found on the “Pro Host Binaries” CD-ROM in the /docs/quickstarts directory. In addition, as updates are made, the latest versions will be available on MontaVista Zone. In general, booting the target for cross-compilation development consists of the following steps: Warning! These steps are generic. For step-by-step instructions for your target, see the Pro quick start guide for your target. 1.
Hardware setup. This involves connecting the target to the host using a serial connection and connecting the target to a LAN. Some targets also require a speciÞc power supply setup or Abatron BDI setup. For others, hardware setup may also include changing DIP switches or installing EEPROMS.
2.
Minicom (or other terminal emulation program) conÞguration. You need to use a terminal emulation program such as Minicom to communicate with your target. For step-by-step instructions on using Minicom, see “Using Minicom” on page 54. The parameters for communicating with your 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 host IP address. Some targets also require you to set the connection speed.
4.
Host conÞguration. Many of the targets use a network boot. All targets mount their root Þle system via NFS. Depending on the Þrmware used by your target, you’ll need to conÞgure all or some of the following host services: 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, MontaVista Software provides host manuals. These manuals provide host requirements, step-by-step instruction on how to conÞgure the required host services, and notes on using that host for development. Host manuals are available for Solaris, SuSE, and Mandrake. Copies of the Pro host manuals can be found on the “Pro Host Binaries” CD in the / docs/hostmanuals directory. In addition, as updates are made, the latest versions will be available on MontaVista Zone.
50
MontaVista™ Linux® Professional Edition
Chapter 4: Target Configuration and Boot Booting the Target with the MontaVista Supplied Kernel
5.
Booting the target. To boot the target, the Þrmware often requires a command to begin the booting sequence. The commands are Þrmware speciÞc.
6.
Once Linux boots, you are placed at a login prompt: login:
7.
At this point, you can login as root with no password. You are placed at a bash shell prompt. Note: We recommend that you change the root password as soon as possible.
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 to work. Once you have proven that the target boots, you can begin development. Note: In the chapter “The Development Environment” on page 37, we recommended creating a directory called “myfilesystem” as a location for doing Þle-system development. We recommend that you NFS export this directory in addition to the default system created by MontaVista Software. By exporting the Þle-system directory as NFS, you can test your environment on the target before spending the development time to reduce the Þle-system size or adding the Þle system to ßash. In general, you will want to continue using the NFS-mounted root Þle system until Þnal deployment. For more information about how to NFS export an additional directory, see “How to NFS export your Þle-system project directory” on page 53.
MontaVista™ Linux® Professional Edition
51
Chapter 4: Target Configuration and Boot Booting 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 the system.map Þle in the top level of the Linux tree. For compressed images, 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 the kernel image in /tftpboot to the new kernel image.The image name and 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 directory of the local system for your target. Loadable module are typically located in /lib/modules. If you don’t already have a directory for your modules, create one by using the command: mkdir //lib/modules
•
Copy your modules to the directory you just created. Use the command: cp -a /<module>/lib/ modules/<module>
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) <module> is the full path and name of the module you wish to include. 3.
Add a line in the /etc/rc.sysinit Þle on the target to insmod the module. See the man page for insmod for information about use and syntax.
4.
Complete the steps listed in the quick start guide for your target using the new kernel image and path, rather than the default kernel images and paths listed in the manual. Note: The quick start guide for your target includes information about how to NFS export the target’s default root Þle system directory (/opt/hardhat/devkit/<architecture>/<processor>/ target/). In the chapter “The Development Environment” on page 37, we recommended creating a directory called “myfilesystem” as the location for Þle-system development. We recommend that you NFS export this directory in addition to the default system created by MontaVista Software. By exporting the Þle system directory as NFS, you can test your environment on the target before spending the development time to reduce the Þle-system size or adding
52
MontaVista™ Linux® Professional Edition
Chapter 4: Target Configuration and Boot Booting the Target with a Custom Kernel
the Þle system to ßash. In general, you will want to continue using the NFS-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 can be exported as the root Þle system. In addition to conÞguring NFS, if you would like to make a particular directory the target’s root Þle system directory, you also need to reconÞgure DHCP. To specify that a directory should be the root Þle system, follow the instructions in the quick start guide (or appropriate host manual, if you are not using a Red Hat host) to conÞgure DHCP. Be sure to replace the line /opt/ hardhat/devkit/<architecture>/<processor>/target/ in the DHCP conÞguration Þle with the path to the directory you want to use for the root Þle system.
MontaVista™ Linux® Professional Edition
53
Chapter 4: Target Configuration and Boot Using Minicom
Using Minicom Minicom is a terminal emulation and modem interface program included in most Linux 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: Filenames and paths File transfer protocols Serial port setup Modem and dialing Screen and keyboard Save setup as dfl Save setup as.. Exit Exit from Minicom
2.
Select Serial port setup and set the options for your target. The quick start guide for your target contains the parameters you need to set to be able to communicate with your target. Note: The serial device values given are typical. They can change depending 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.
A B C D E F G H I J
-
Init string ......... Reset string ........ Dialing prefix #1.... Dialing suffix #1.... Dialing prefix #2.... Dialing suffix #2.... Dialing prefix #3.... Dialing suffix #3.... Connect string ...... No connect strings ..
K L M N O
-
Hang-up string ...... Dial cancel string .. Dial time ........... Delay before redial . Number of tries .....
ATDT ^M ATDP ^M ATX1DT ;X4D^M CONNECT NO CARRIER NO DIALTONE ^M 45 2 10
Q R S T
-
BUSY VOICE Auto bps detect ..... Modem has DCD line .. Status line shows ... Multi-line untag ....
P - DTR drop time (0=no). 1 Change which setting?
54
MontaVista™ Linux® Professional Edition
(Return or Esc to exit)
No Yes DTE speed No
Chapter 4: Target Configuration and Boot Using Minicom
Start 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.
When you enter Minicom again, you are able to communicate with your target by using the command: minicom
Note: You may need to initiate a board hardware reset after restarting Minicom to successfully 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.
Help
Press Enter to exit.
For help using Minicom, complete the following step: 1.
Use the following command: control-A Z
MontaVista™ Linux® Professional Edition
55
Chapter 5: Target ConÞguration Tool (TCT)
Overview Now that you have Pro installed and your target booted, you are ready to begin development of your embedded application. To help you right-size the Linux kernel and create an optimal Þle system, MontaVista Software provides Target ConÞguration Tool (TCT). This GUI-based utility enables you to select only needed modules and drivers for inclusion in kernel builds, allowing bootable footprints scaled below 500K. Using TCT avoids the drudgery of hand-editing conÞguration and make Þles while managing dependencies among components. TCT also lets you choose pre-built packages for inclusion in your Þle system, including system binaries and data. As the base for kernel and Þle-system development, TCT uses the Þles and conÞgurations provided in the reference LSP selected for your project. By starting with the default system provided in the LSP, you can greatly reduce your development time, 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 system package selections. By allowing you to maintain multiple conÞgurations, TCT allows you 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
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 create a 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 Pro applications. Instructions on how to run Pro applications can be found in “Running Pro Applications and Tools” on page 40. The Project Manager window appears:
Create a New Project
58
To create a new project, complete the following steps: 1.
Click the New Project button in the right-hand pane of the Project Manager window.
MontaVista™ Linux® Professional Edition
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 must have a unique name.
•
Directory... This is the directory where the project is stored. If you click on the Directory... button, a Directory Selection dialog box appears. From there, you can browse to and choose an empty directory you already created or click the New Directory button to create 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 select an LSP. Selecting an LSP ensures that the correct default target directory and cross-compilers are used by TCT for your target board. In addition, by selecting an LSP, you have a kernel that is known to boot on the reference board as a starting point for your development.
•
If you are using a custom kernel, make sure Use Custom Kernel is selected. Note: If you do not select the Use Custom Kernel option, TCT assumes 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
Chapter 5: Target Configuration Tool (TCT) Starting TCT
A project directory is created, and if you are using a custom kernel, the kernel is copied to the new directory. Copying the kernel can take some time (there is no progress indicator).
Open a Project
Remove 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 Open Project button in the right-hand pane of the Project Manager window.
•
Or simply double-click on the name of the project in the left-hand pane of the Project Manager window that you want to open.
To remove an existing project, complete the following step: 1.
Highlight the project you want to remove, then click the Remove Project 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 to remove these Þles from your system, you must do so manually.
60
MontaVista™ Linux® Professional Edition
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. For each 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. You can 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
Chapter 5: Target Configuration Tool (TCT) TCT Project Menus
Once selected, a conÞguration selection dialog box appears. Select the conÞguration you 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 .cfg extension.
Close ConÞg Select this option to close the conÞguration that you are viewing without saving changes.
Build Target Select this menu option to build the kernel and Þle system for your target.
62
MontaVista™ Linux® Professional Edition
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 easy identiÞcation. The build log is also stored in the project directory.
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. You can scroll through the status messages to Þnd out what happened. Click Done when you are Þnished.
MontaVista™ Linux® Professional Edition
63
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 set options for the Þnal build using the View menu.
Kernel ConÞgure This view can be used to change kernel conÞguration parameters. The interface for editing the conÞguration is the same as when using make xconfig in the Linux source 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Þcally stated on the MontaVista Zone page for your target are supported.
64
MontaVista™ Linux® Professional Edition
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. The packages in a selected group are displayed in a hierarchical manner in the pane on the right. When an arrow pointing to the right is displayed next to the name of a package or 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 it again to hide the subcomponents. For more information about how to list which packages are in which group, see “The targetpkg Utility” on page 73. Warning! The checkboxes only show the packages you selected. If a package has a dependency on another package, that package is automatically installed with the selected package; however, the check box for that package remains unchanged. At the bottom of the Package Selector view are two values - Total size and Stripped size. •
Total Size is the total size of the packages selected.
•
Stripped Size is the total size of the packages selected once they have been ‘stripped’ of all symbol information.
Using the Target Options view, you can decide if you want to strip the binaries before they 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
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 Options This category always includes the option to Strip Binary Files.
•
Install Kernel Files This category is for custom kernels only. The options displayed here are different for each kernel. For most LSPs, these options include the type of kernel images to build and place in the Þle system tar archive created when you build the target. You want to make sure to select the kernel image type required for your target. The Kernel Modules option is almost always present, and it is selected by default – any modules that are conÞgured by the kernel conÞguration selections will be installed. No options are available when using a pre-built kernel.
•
66
Filesystem Image TAR Þle name: Use this Þeld to enter the Þle name that you would like the tar archive saved as. The default name is fsimage.tar. If you are saving multiple conÞgurations, to prevent overwriting an older conÞguration, make sure you change this Þle name.
MontaVista™ Linux® Professional Edition
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 Info menu.
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
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 the following TCT activities:
Create a ConÞguration File
•
“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
You can use TCT to create a target conÞguration Þle. A target conÞguration Þle contains the options you have selected for your target Þle system, the options selected for your custom kernel conÞguration, and options regarding how to build the target kernel 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 make menuconfig or by running make xconfig independent of TCT are NOT stored in 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 or build 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 new conÞ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 .cfg extension.
68
MontaVista™ Linux® Professional Edition
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 following steps: 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 TCT project. (See “Starting TCT” on page 58.) Warning! Changes made to the kernel conÞguration using another tool such as make menuconfig or by running make xconfig independent of TCT are NOT stored in your project’s conÞguration Þle. To create/edit a new kernel conÞguration for your project, complete the following steps: 1.
Open your project and the conÞguration you want to edit. (See “Starting TCT” 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-time enhancements, standard devices, or Þle-system types, see “Linux Kernel Development” on page 75. Note: While many features are available for conÞguration, only features speciÞcally stated on the MontaVista Zone page for your target are supported.
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
Chapter 5: Target Configuration Tool (TCT) Using TCT
The kernel options are now saved in the open conÞguration Þle. TCT does not build the kernel until the Build Target option from the File menu is selected. For more information, 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 product determines the size and type of Þle system, which in turn dictates how many applications can be included. You should be aware of the type of Þle system you want to use in your deployed product before creating the Þle-system hierarchy, as different Þle-system types have different constraints. The section “Select a Deployment FileSystem Type” on page 145 has some information about the features and limitations of each 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 “Starting TCT” 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 on the left. For more information about how to list which packages are in each 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. (Also in 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 automatically selects a useful subset of its associated subcomponents. You may also select or deselect any of the subcomponents if you wish to control the selections at a Þner level. When you select a package, the Package Selector reports any conßicts with other packages already selected. Warning! The checkboxes only show the packages you selected. If a package has a dependency on another package, that package is automatically installed with the selected package; however, the check box for that package remains unchanged. Note: At the bottom of the Package Selector view are two values - Total size and Stripped size. As size is a major consideration for many
70
MontaVista™ Linux® Professional Edition
Chapter 5: Target Configuration Tool (TCT) Using TCT
embedded development projects, pay attention to these values as you build your Þle system. 5.
Select Save ConÞg from the File menu to save your changes to the current 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 more information, 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 current open conÞguration, complete the following steps: 1.
From the View menu, select Target Options. The Target Options window appears.
2.
Select the build options you want to use. Be sure to change the name of the Þle-system image, or you may overwrite a previous image. For more information about the options available, see “Target Options” on page 66. Note: You should select the kernel image format you need for your target in this screen. If you do not, you will need to convert the kernel image to the correct format before booting.
3.
Select Save ConÞg from the File menu to save your changes to the project 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 in red text for easy identiÞcation. This build log is also stored in the project directory. 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 this point you can scroll through the status messages to Þnd out what happened.
5.
Click Done when you are Þnished.
The build process creates a tar archive of the Þle system (and kernel) in your project directory. See “Using the Tar Archive Created by TCT” on page 72 for more information 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 make menuconfig or by running make xconfig independent of TCT were NOT stored in your project’s conÞguration Þle, and therefore not built in the kernel.
MontaVista™ Linux® Professional Edition
71
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 project directory. The tar archive contains: •
a Þle-system hierarchy with the applications and libraries you selected
•
kernel images – depending on the selections you made in the Target Options screen, there may be multiple kernel images of different formats
The tar archive must be extracted for use for kernel development or Þle-system development. 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 you created for your Þle system.
3.
Use GNU tar to untar the Þle-system tar archive into your Þle-system directory. For example, to untar the Þle project1.tar into the directory 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 and group 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 Target Options screen, you should have a kernel image of the correct type to boot your target.
•
If your CPU or board Þrmware uses an image type not available on the Target Options screen, or you did not select the image type you need, 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 a Custom Kernel” on page 52.
72
MontaVista™ Linux® Professional Edition
Chapter 5: Target Configuration Tool (TCT) The targetpkg Utility
The targetpkg Utility Included with TCT is a command-line utility called targetpkg. This utility allows you to list the TCT groups with the packages and Þles in the groups. To use targetpkg, you need to update your executable search path to include the Pro applications. Instructions on how to run Pro applications can be found in “Running Pro Applications and Tools” on page 40.
Usage
Use of the targetpkg utility is described below. targetpkg [-f] <architecture>_<processor>
targetpkg accepts the following option: •
Examples
-f List all Þles. By default, targetpkg only lists the packages.
If you want to see all of the packages listed in TCT for a PowerPC 8xx target, you would use the command: targetpkg ppc_8xx
You would see output similar to the following: admin admin web devel doc ...
adduser anacron apache apache-dev apache-html_manual
In the example above, the Þrst column is the TCT group and the second column is the package. If you want to see all of the packages and Þles listed in TCT for a PowerPC 8xx target, you would use: targetpkg -f ppc_8xx
You would see output similar to the following: admin admin admin admin admin ...
adduser/base adduser/base adduser/base adduser/base adduser/base
/etc/adduser.conf /etc/deluser.conf /usr/lib/perl5/AdduserCommon.pm /usr/sbin/adduser /usr/sbin/deluser
In the example above, the Þrst column is the TCT group, the second column is the package, and the third column is the Þle.
MontaVista™ Linux® Professional Edition
73
Chapter 6: Linux Kernel Development
Overview The kernel binary is at the core of every MontaVista Linux execution. It handles scheduling, resource allocation, and use of programs. Pro provides you with two kernels: an LSP-speciÞc kernel and a generic kernel. The LSP kernel (with MontaVista Software patches) is built speciÞcally for the supported reference boards. MontaVista recommends that you use the LSP kernel for all development. The sources for this kernel are installed automatically when you install Pro and can be found in: /opt/hardhat/devkit/lsp// linux- 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 the directory: /opt/hardhat/devkit/kernel/linux- 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
Chapter 6: Linux Kernel Development Building 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 GUIbased tool that provides you with the ability to easily choose kernel options and select target Þle system packages. You can also use TCT to manage kernel builds and to control options such as whether target binaries are stripped. In addition, TCT supports multiple 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 make menuconfig or by running make xconfig independent of TCT are NOT stored in 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 following steps: 1.
Copy everything in the appropriate linux directory in the kernel source tree to the directory where you wish to build the new kernel. Use the command: cp -a /opt/hardhat/devkit/lsp//linux //
(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 upgrading Pro. For that reason, we strongly recommend that you copy everything to a build directory, such as mykernel. For example: cp -a /opt/hardhat/devkit/lsp//linux /mykernel/
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) 2.
Change to the directory containing your copy of the kernel. For example: 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
Chapter 6: Linux Kernel Development Building and Configuring the Kernel
make menuconfig
Use this command to select conÞguration options from hierarchical groups. To enable an option using make menuconfig, place an asterisk (*) 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 CPU options, make menuconfig will not correctly conÞgure the kernel. make xconfig
This is a mouse-driven conÞguration tool. To enable an option, click the check box for “yes” next to the option you wish to enable. Note: To run any of the Pro tools, you need to update your executable search path to include the Pro applications and tools. Instructions on how to run Pro tools, can be found in “Running Pro Applications and Tools” on page 40. Note: While many features are available for conÞguration, only features speciÞcally stated on the MontaVista Zone page for your target are supported. Note: If you intend to use loadable kernel modules, you must ensure that Loadable module support is enabled in your conÞguration. For more information about kernel modules, see “Enabling Loadable Kernel Modules” on page 80. 4.
Remove old kernel images, dependency Þles, or other old Þles that may disrupt 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, you do not need to do anything.
MontaVista™ Linux® Professional Edition
77
Chapter 6: Linux Kernel Development Building 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 the new kernel image to the appropriate location for your target to replace the default kernel image. For example, if you were to use a PowerPC 8xx target, you would use the command: ppc_8xx-objcopy -O srec vmlinux vmlinux.srec
For example, if you were to use a MIPS ßoating point little-endian target, 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 littleendian target, you would use the command: arm_920t_le-objcopy -S -O srec compressed/vmlinux vmlinuz.srec
-R
.stack
arch/arm/boot/
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) or arm_720t_le-objcopy -S -O srec compressed/vmlinux vmlinuz.srec
-R
.stack
arch/arm/boot/
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) 8.
If you conÞgured any of the parts of the kernel as a module and enabled Loadable 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 is required if you enabled or disabled any modules. If you do not recompile the modules, you will receive “unresolved symbols” errors during or after kernel boot. 9.
Boot the target. For instructions on how to boot the target with your new kernel, see “Booting the Target with a Custom Kernel” on page 52.
For more information about conÞguring and building the kernel, see the README Þle and the Þles in the Documentation subdirectory in the kernel source directory. Warning! Changes made to the kernel conÞguration using tools such as make menuconfig or by running make xconfig independent of TCT are NOT stored in your TCT project’s conÞguration Þle, and therefore will not be built in the kernel
78
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building and Configuring the Kernel
created by TCT. If you did not use TCT for your kernel development but did use TCT for your Þle-system development, ignore the kernel generated by TCT.
MontaVista™ Linux® Professional Edition
79
Chapter 6: Linux Kernel Development Enabling Loadable Kernel Modules
Enabling Loadable Kernel Modules Rather than having all device drivers built into the kernel, the Linux kernel supports loadable modules – that is, modules that can be inserted or removed from memory at runtime. The advantage of loadable kernel modules is that you do not need to rebuild the kernel to test or enable a new device. When building your own custom device driver, we recommend that you Þrst write and test your device driver as a loadable kernel module (see “Building Custom Device Drivers” on page 88). For that to work, you need to ensure that support for loadable modules has been enabled in the kernel. Loadable kernel modules is on by default in most LSPs. To enable loadable kernel modules, complete the following steps: 1.
Start make menuconfig or make xconfig. The latter can be run on 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 and ConÞ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 those applications.
80
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling 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 in improving the real-time performance characteristics of the Linux kernel. This approach to real-time Linux doesn't alter the APIs of the programming model. By leveraging the inherent capabilities of the kernel, changes required of applications that utilize these real-time performance improvements are minimized. MontaVista Software engineering efforts into benchmarking and improving the realtime performance of the Linux kernel have resulted in the following improvements to the kernel:
MontaVista RealTime Scheduler
•
“MontaVista Real-Time Scheduler” on page 81
•
“Preemptible Kernel” on page 82
The MontaVista Real-Time Scheduler (RTS) is a supplemental scheduler for the Linux kernel that takes scheduling custody of real-time processes. The MontaVista Real-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 dispatch times of real-time tasks. Non-real-time (SCHED_OTHER) tasks are handled in a fashion similar to the standard scheduler; however, the management of the time slice calculation is modiÞed to be much faster while having the same end result.
Support The scheduler is available on all supported architectures; including Symmetric Multiprocessing (SMP) Systems. Check the MontaVista Zone page for your target for information 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 by default. To enable the MontaVista Real-Time Scheduler, complete the following steps: 1.
Start make menuconfig or make xconfig. The latter can be run on its own or through TCT.
2.
Depending on the target architecture, select Processor type and features or Platform support.
3.
Enable Real Time Scheduler.
4.
Enter a value for the Maximum Priority? option. This option allows you 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
Chapter 6: Linux Kernel Development Enabling 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 2047 are changed to 2047. The default is set to 127, and in most cases, this is what you would use. 5.
Save your changes.
6.
Rebuild the kernel, using TCT or the procedure in “Building and ConÞguring the Kernel” on page 76.
The MontaVista Real-Time scheduler is now enabled. Warning: The MontaVista Real-Time Scheduler does not honor the allowed_cpus member of the task_struct; thus, it will not honor any attempt to 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 cause performance degradation.
Additional information The MontaVista Real-Time Scheduler is an open-source project and it is hosted at: •
Preemptible Kernel
http://rtsched.sourceforge.net/
The Preemptible Kernel (CONFIG_PREEMPT) option reduces the latency of the kernel when reacting to real-time or interactive events by allowing a low-priority process to be preempted, even if it is in kernel mode executing a system call. This feature allows applications that need real-time response – such as audio and other multimedia applications – to run more reliably, even when the system is under an increased load due to other lower-priority processes.
Features The new preemption model allows the kernel to be preempted any time it is not locked, which is very different from the model where preemption is actively requested by the currently executing code. Using the new model, when an event occurs causing a higher priority task to be executable, the system will preempt the current task and run the higher priority task. In the following instances, preemption should not occur, and the Preemptible Kernel option does not allow it:
82
•
while handling interrupts
•
while doing “bottom half” processing -- bottom half processing is work that an interrupt routine needs to do, but that can be done at a more relaxed pace
•
while holding a spinlock, writelock, or readlock
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling Real-Time Performance Enhancements
These locks exist in the kernel to protect it from other processors in Symmetric Multiprocessing (SMP) Systems. While these locks are held, the kernel is not preemptible for re-entrancy or data protection reasons (just as in the SMP case). •
while the kernel is executing the scheduler itself -- the scheduler is charged with executing the “best” task, and if it is engaged in making that decision, it should not be confused by asking it to give up the processor
At all other times, the MontaVista algorithm allows preemption. Also, whenever the system exits from one of the above states, it tests to see if preemption is called for. If so, the current task is preempted.
Support Check the MontaVista Zone page for your target for information about support for this 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 can be 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 and ConÞ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 is experimental.
MontaVista™ Linux® Professional Edition
83
Chapter 6: Linux Kernel Development Enabling Standard Devices
Enabling Standard Devices Pro 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-/linux/ Documentation/devices.txt. The Þle above contains a list of devices and device numbers. While these drivers are available 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 are supported. 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 for this 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 the SVGA_MODE variable. To set the SVGA_MODE variable, change the SVGA_MODE variable setting from NORMAL to what is appropriate for your setup. Read /opt/hardhat/devkit/lsp// linux-/Documentation/fb/ vesafb.txt to determine the value you should use. For example, to set the SVGA_MODE variable for 640x480 resolution at 256 colors, use the following line in your makefile: export SVGA_MODE=
84
-DSVGA_MODE=0x301
2.
Start make menuconfig or make xconfig. The latter can be run 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.
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling Standard Devices
7.
Rebuild the kernel, using TCT or the procedure in “Building and ConÞ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 for this 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 run on 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 and ConÞguring the Kernel” on page 76. To verify that videocard support has been enabled, load and boot the new kernel on the target. If you see a penguin in the upper left-hand corner of your target screen, you have succeeded.
MontaVista™ Linux® Professional Edition
85
Chapter 6: Linux Kernel Development Enabling Standard Devices
PS/2 Keyboard and Mouse Support
Support Check the MontaVista Zone page for your target for information about support for this 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 run on 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 and ConÞguring the Kernel” on page 76.
7.
On the target, ensure that you have a psaux device. Use the following command to list the devices: ls /dev/psaux
If you do not have a psaux device, use the following command to create one: mknod /dev/psaux c 10 1
For more information about creating standard device nodes, see “Create Standard Device 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
Chapter 6: Linux Kernel Development Enabling Standard Devices
Sample Startup/Kill Scripts. Startup and kill scripts can be used rather than the gpm daemon. 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=ps2 device=/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.pid GPM=/usr/sbin/gpm CFG=/etc/gpm.conf test -x $GPM || exit 0 if [ "$(id -u)" != "0" ] then echo "You must be root to start, stop or restart gpm." exit 1 fi cmdln= 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"; fi fi gpm_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 1 esac exit 0
MontaVista™ Linux® Professional Edition
87
Chapter 6: Linux Kernel Development Building Custom Device Drivers
Building Custom Device Drivers While there are hundreds of drivers available for Linux, you may Þnd that the exact driver you need does not exist for your device. In this case, you need to either write your own driver or simply modify a similar driver. Whether you are writing a new driver or modifying an existing driver, you should write and test your driver in an incremental fashion. By working in increments, you can easily track your progress and isolate bugs. A test program, developed in lockstep 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 sample driver outlined in this section, the Þrst steps to developing the driver are to write and test 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 much easier to test each section of driver code as you write it. 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 the driver works, you can compile the driver 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 the particulars for building a device driver are dependent on the device, Linux device drivers have many common features. There are hundreds of examples available in /opt/hardhat/devkit/lsp//linux-/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, almost everything shown in the example driver is required in a PCI-device driver as well.
88
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building 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 a kernel module), create the /dev node, and launch a test program. The test program should be written as you write your driver to test each new piece of functionality. Your kernel must have loadable kernel module support enabled. See “Enabling Loadable Kernel Modules” on page 80 for more information. Refer to the appropriate man and info pages for details on each of these operations. Sample load module and test program script #!/bin/sh # Insert mydriver and run the test program # mknod /dev/mydriver c 120 0 insmod mydriver.o ./test_mydriver
First, the mknod command creates a character (c) device entry in the /dev Þle system. The driver will use major device 120, one of the numbers reserved for experimental use. The minor device number, 0 in the above example, will be passed to the driver each time the driver is used, and has no meaning other than what the driver makes of it. Note: If the driver (kernel module) is going to allow Linux to assign the major device number, insmod must be executed before mknod, and some additional shell programming will be needed to extract the answer from /proc/devices before mknod can be executed. (Finally, it is possible to do the mknod(2) operation in the driver itself.) Next, assuming the driver (kernel module) has been compiled as mydriver.o, the insmod command inserts (loads) the driver into the running system. Within the driver (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 current directory – hence the “./” preÞx – this program tests the driver by issuing typical I/O calls and checking the results. The test program should also test boundary conditions as well as verify the error-checking in the driver itself. For example, device drivers must validate user-space addresses. Failure to do so could result in a system panic. The test program should, therefore, attempt some operations using invalid addresses and verify that the driver returns the proper error status. It is not uncommon for a test program to be several times larger than the driver being tested.
MontaVista™ Linux® Professional Edition
89
Chapter 6: Linux Kernel Development Building Custom Device Drivers
When a problem is detected in the driver source code, the driver must be removed from the system, the error must be corrected, and the driver must then be recompiled and reloaded. For consistent results, a removal script, such as the following, should be used: Sample remove module script #!/bin/sh # Remove mydriver # rmmod mydriver rm -f /dev/mydriver
First, the removal script undoes the insertion. Note that the driver's name no longer carries 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 will be 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 is ready to be tested again, expect an error message when the mknod command is executed because the /dev/mydriver node is still present from the previous life of the system.
Code the Kernel Portions of the Driver
While writing and testing the driver, the kernel module provides a carrier for loading and unloading the device driver. As such, the kernel module should be written and debugged Þrst. Once it can be inserted and removed at will, coding of the driver can begin. For this to work, your kernel must have loadable kernel module support enabled. 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 the driver works, you can compile the driver as you desire – as a loadable module or as part of the kernel. Below is a very simple kernel module example: Sample kernel module #include #include #include static int __init init_myself(void) { printk("myself is loaded\n"); return 0; } static void __exit remove_myself(void) { printk("myself is being removed now\n"); } module_init(init_myself); module_exit(remove_myself);
90
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
The three #include statements are all required. The linux/init.h header Þle contains, 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 later built 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 more information about running the cross-compiler for your target, see “Running Pro Applications and Tools” on page 40. The following describes the other options used: •
The -c option tells the compiler to generate the object Þle from mydriver.c, but to proceed no farther.
•
The -DMODULE option is needed when compiling a kernel module Some compilers do not, by default, generate reentrant code. For device drivers, this is a necessity. Note: If you are compiling your driver as part of the kernel rather than as a module, you would use the -DKERNEL option in place of the -DMODULE option.
•
The -I <path-to-kernel>/include instructs the compiler to use the kernel include Þles (rather than user-space Þles.) Replace <path-to-kernel> with the proper path where the kernel source code used to build the kernel image used on the target board.
•
The -nostdinc option ensures that the compiler does not pick up any user-space paths.
•
The -Wall option instructs the compiler to issue all relevant warnings. Tracking down the source of these and carefully implementing the proper correction is very important when working in the kernel, much more so than in user-space programs.
•
The -O option turns on compiler optimizations. For user-space programs, this is a good idea. For code that will execute in the kernel, however, it is required.
At this point, the kernel module should be compiled and the load and unload scripts tested. 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
Chapter 6: Linux Kernel Development Building 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 and tested. 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 the corresponding read routine. Once write is Þnished, it can often be copied and pasted into 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(). This system operation registers the fact that a new driver is present in the system, which should be done when the driver (kernel module) is loaded. The driver's initialization routine 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. This particular operation is used in practically every driver in Linux. There are hundreds of examples beneath the drivers directory. Look for a directory named drivers in /opt/hardhat/devkit/lsp//linux-/drivers. For example: find /opt/hardhat/devkit/lsp/ibm-walnut/linux-/ 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 major device number, or letting Linux assign one. The Þrst argument in register_chrdev() may contain either a non-zero number, or zero. A non-zero number tells Linux what major device number to use. Linux will return success (0) or failure (non-zero). Conversely, coding a zero as the Þrst argument to register_chrdev() asks Linux to automatically assign an unused major device number to the driver. In that
92
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
case a return value of non-zero means success and the returned value is the assigned major device number. Should Linux return a zero, however, there are no major device numbers available, and the register_chrdev() operation has failed. The second argument to register_chrdev() is the driver's name. Although it could be anything, for consistency, it is a good idea to make this name the same as the name used in the /dev Þle system. The Þnal argument is the name of a structure containing pointers to the driver entry points. 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 structure deÞ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 they will, 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 driver initialization routine, and, conversely, the unregister_chrdev() call is the only function required to be in the driver remove routine. There are other system operations commonly found in the initialization code of device drivers. These are ioremap(), tasklet_init() and, quite often, the operations needed to reset the hardware device being controlled. ioremap() programs the processor's address translation unit (or discovers the previously programmed address) for the hardware device the driver is controlling. For portability, it is important to recognize that the return from ioremap() is an “I/O Space Address,” which is not necessarily accessible by a direct memory reference. Special functions are provided for all I/O space address references. Drivers that dereference these pointers directly will not be portable and may also suffer byte-order problems. tasklet_init() initializes the structure used to trigger a tasklet which, in most drivers, is used for the post-processing of an interrupt. (Earlier Linux implementations provided “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 bottomhalves and soft IRQs and should use tasklets.) For both ioremap() and tasklet_init(), refer to examples in the Linux driver source Þles. Finally, if an ioremap() is coded in the driver initialization routine, an iounmap() should probably be written into the remove routine. There is no counterpart to tasklet_init(). Testing the initialization and remove routines. With the initialization and remove routines coded, this is a good point to test the driver 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
Chapter 6: Linux Kernel Development Building Custom Device Drivers
The above command displays the current registry of major device numbers and names known to Linux. If run after loading the driver, by Þnding the driver's name in the output 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 number of different types of devices, and the different ways in which they may be installed and used with Linux. Therefore, it may be useful to examine several drivers and compare the approaches implemented in them with the suggestions herein. The Open routine in a device driver often associates an external hardware interrupt with a piece of code in the driver, the ISR or Interrupt Service Routine. The request_irq() function provides this service. Before it can be used, however, the driver must determine which IRQ (Interrupt ReQest number) it should use. Depending on the hardware design and the device's capabilities, there are several techniques to choose from. First, the device may simply be hard-wired with a particular IRQ number. This is often true of on-board devices that are soldered in place. For these devices, the hardware designer may have made the selection of IRQ number and documented the answer in the hardware reference materials. If the device is PCI-based, however, the device will have been programmed in the PCI subsystem or possibly earlier, in BIOS if present, or in a comparable part of the system’s initialization code. For PCI-based devices, the PCI subsystem will know the IRQ number. Again, refer to the Linux sources for the most reliable answer. Locate a device driver containing both a call to request_irq() and also a call to, for example, pci_enable_device(). Another technique is probing for an IRQ number. The kernel routines probe_irq_on() and probe_irq_off() are used, in sequence, to determine what IRQ number a particular device is using. In between those two operations, the device driver is expected to do something to the device to provoke an interrupt. Linux monitors the unused IRQ lines and returns the IRQ number when probe_irq_off() is called. Although useful in some environments, probing may exhibit some undesirable behavior in some systems. It should, therefore, be avoided if possible. Note: Examination of the sources for Linux drivers will reveal a dozen or more additional techniques. Choose one appropriate for the hardware you are using. The IRQ number is the Þrst argument to request_irq(). The second argument is the name of the function to be executed in the interrupt context. This is the driver's ISR. Note: It is important to note, throughout the driver, the context of execution of a particular function. Interrupt Service Routines execute in the interrupt context. Most
94
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building 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 be considered a third type of context. Of these, the portions of a driver that execute in the process context can be interrupted by tasklets and interrupts, tasklets themselves can be interrupted by interrupts, and in some cases, interrupts can even be interrupted by other interrupts. This is what the -D_REENTRANT ßag is for when compiling a driver. And, this is what things like kernel MUTEXes, spin locks and interrupt masking are designed to help a driver handle. If these are new concepts, a careful and thorough study of these topics is recommended and, unfortunately, is much more than can be dealt with here. The third argument to request_irq() is a group of ßags that may be OR'd together. These include whether or not the driver is a “fast” or “slow” interrupt handler, is willing to share the IRQ with other drivers, and whether or not interrupts from the device tend to occur at random times. The relevant ßags are SA_INTERRUPT (a “Fast” handler), SA_SHIRQ (the driver will “share” the IRQ line), and SA_SAMPLE_RANDOM (interrupts occur at random times). The converse of each ß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 the capabilities of the hardware, “slow” interrupt handlers execute with interrupts other than their own re-enabled. This allows for the nesting of other (often “higher priority”) 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 probable choice. The name used with request_irq() will be displayed through the /proc/interrupts interface that shows how many interrupts have occurred at each IRQ number. And the Þnal argument to request_irq() is any value of use to the driver. This value will be passed to the driver's interrupt service routine whenever an interrupt occurs. It is often used to pass a pointer to some driver control structure needed at interrupt time. The Þnal item needed in the driver's open routine is the MOD_INC_USE_COUNT macro. This increments a counter and is used to determine when a module may be unloaded. A corresponding MOD_DEC_USE_COUNT should, therefore, appear in the release routine, which should also include a free_irq() call to release the IRQ number. It may also be a good idea to disable the device or otherwise prevent it from generating interrupts in the future. With the open and release handlers coded and compiled, the test program can be enhanced to test the new entry points. In the test program, open(“/dev/ mydriver”,...) will return a Þle descriptor. Prior to that, however, the driver entry point will be executed. The driver must, therefore, return success (0) if everything is working. On the other hand, if the request_irq() or other operation
MontaVista™ Linux® Professional Edition
95
Chapter 6: Linux Kernel Development Building Custom Device Drivers
fails, the driver’s open routine should return an appropriate error number. Examine various driver sources and note the methods used. They are relatively straightforward and common across many drivers. At this point, all the test program can do is open() and close() the driver. But these should cause the driver's corresponding entry points to execute. If desired, a few printk()s could be placed throughout these routines in the driver to verify operation.
Write to a device The write and read portions of the driver will be handled and tested separately, and they should probably be coded and debugged in that order: write before read. This is simply because it is easier to code a test program that makes up random data to be written to a device than it is to cause a device to make readable data available. Testing is 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 the existing data and the number of bytes therein. The address the program speciÞes, and which is passed to the driver, is a user-space address. That area of memory, including various portions or all of it, might not be resident in RAM at the time the I/O call is issued. The driver, therefore, must not attempt to touch the user-speciÞed data directly. 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 this purpose. The buffer must be large enough to hold the maximum size write (or read) to be handled by the driver. In many cases this means very large writes (and reads) will actually 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's initialization routine may be selected for this operation. The difference between these two depends on how many kernel-space buffers will be needed by the driver. The driver initialization routine is executed once. The open routine, on the other hand, is executed once for each minor device that is opened. Drivers supporting multiple minor devices and needing a kernel-space buffer for each such device may do the kmalloc() operation in the open routine, and the corresponding kfree() in the release routine. When a user program issues a write operation, the device driver's write handler must copy the data from user space to kernel space. The copy_from_user() function provides 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 paged out, the copy_from_user() function will initiate a page-in operation and put the current operation to sleep until it completes. This means that the driver's write routine may be put to sleep during the copy_from_user() operation. Note: Sleeping is perfectly acceptable in a process (or thread) context. It is not allowed; however, in an interrupt or tasklet context. Since different portions of the device driver will execute in different contexts, it will be important to remember what is and is not allowed in each part of the driver.
96
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
In addition to coping with page faults, copy_from_user() will also validate the user-space addresses over the entire range of indicated addresses. If the user program speciÞes an invalid address, or if the user-space buffer beginning address is valid but the length extends into forbidden space, copy_from_user() will return a nonzero value to the driver. The driver is then obligated to return -EFAULT to the user program. This will probably result in a segment violation signal to the requesting process, typically a fatal event. Arguments to copy_from_user() are straightforward: kernel-space destination address, user-space source address, and number of bytes. Two of these values, userspace 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 kernelspace buffer, is then transferred to the I/O device. Sometimes this is a copy from kernel-space to I/O-space, memcpy_toio(), or, in the case of a device that handles only a single byte, “word” (two bytes) or “longword” (four bytes) at a time, writeb(), writew(), and writel(). In cases where the device is capable of fetching the contents of system memory, the appropriate memory address must be programmed into the device. Because devices are assumed to exist in I/O space which may be different from the processor's memory space, the kernel-space address must be 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. Physical addresses 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 data transfer. These calls access the system's I/O space: the pointers to the I/O device should be the value returned by the ioremap() call in the driver's initialization routine, or some offset. If a delay occurs between starting the data transfer and when it completes, the process is typically put to sleep by having the driver call interruptible_sleep_on(). Later, if an interrupt occurs at the end of the data transfer, the driver's ISR or tasklet can issue the corresponding wake_up_interruptible() operation. When that occurs, the driver will reawaken at the line of code immediately after the interruptible_sleep_on(). Some drivers provide one or two common variants; however, instead of waiting for the operation to complete, some drivers may support O_NONBLOCK operation. When an application program requests an O_NONBLOCK operation, it is asking for the driver to complete the transfer of data from user space immediately and to allow the program to continue running without possibility of sleep. In other words, the driver should copy the data from user space, start the data transfer with the I/O device, but then immediately return from the write routine. Later, when the I/O completion interrupt occurs, the ISR (or tasklet) must be smart enough to know if it should not do the wake_up_interruptible() call, since no one is sleeping. In addition, the driver must also know that the device is busy. If an additional O_NONBLOCK operation is requested while the device is busy, the -EBUSY status should be returned. The -EBUSY status tells the application program that the non-blocking operation was not possible.
MontaVista™ Linux® Professional Edition
97
Chapter 6: Linux Kernel Development Building Custom Device Drivers
The second alternative is the FASYNC operation. This is similar to O_NONBLOCK except that in the former case, the application program cannot know when the data transfer to the external device has been completed. FASYNC operation, on the other hand, asks the driver to send a signal to the process. Driver support of FASYNC is usually 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 its hardware device is causing an interrupt. Drivers for devices that “share” IRQ lines may be called with a different device on the same IRQ line that is requesting an interrupt. Therefore, drivers must check to see if their device is generating an interrupt. If not, the ISR should simply return to Linux. If the driver's device is causing an interrupt, then the question becomes, why? And once 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 we wait too long
•
defer as much work as possible into a tasklet probably by adding entries to a queue of work to be done (the kernel's list_head manipulating routines may be particularly useful)
•
use tasklet_schedule() to cause the tasklet to execute at some later time
When should everything be done in the ISR and when should a tasklet be used are good questions with no clear answers. It is probably safe to say that if deferring the work takes longer than doing it, then a tasklet is not warranted. On the other hand, if the work is complex and may involve a backlog or transactions, then a tasklet is a good 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 Linux returns to the execution of any process. Tasklets are, therefore, a third type of “things that can execute code” and, in importance, they fall between hardware interrupts and processes. The content of the ISR and tasklet, if any, depends on the I/O device and the type of execution (O_NONBLOCK, FASYNC, etc.) desired by the application program, and by the designer. SufÞce it to say that these considerations and the discussion in the section “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 were transferred, and return that count.
98
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
With the driver write routine coded and ready to be tested, the test program must be modiÞed. Here's where things start to get involved in the test program. There are several questions to be answered. First, what types of data are acceptable to the device? What lengths of data are allowed? Does the driver support O_NONBLOCK operation? Does it support the FASYNC style of transfer? Of course, all the permitted combinations must be tested. Additionally, various combinations of illegal and nonsensical operations must also be attempted. In all cases, the value returned from the driver must be compared to see if the driver is giving the correct response. This is also the time to begin stressing the driver to see if it continues to behave well under load. Depending on the driver, the use of a kernel MUTEX may be required. These are initialized with init_MUTEX() and then manipulated with down_interruptible() and up(), and occasionally with plain down(). A kernel MUTEX is used in a driver to prevent multiple processes (or threads) from using critical portions of the driver at the same time. When one process successfully executes the down_interruptible() operation, any subsequent process reaching that same point will be put to sleep until the Þrst process executes the corresponding up() operation. Note that as before, ISRs and tasklets are not allowed to 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, including down_interruptible() as well as interruptible_sleep_on() and its variants, special handling is needed immediately thereafter. These kernel operations are “interruptible” in the sense that a signal could be sent to the process while it is sleeping, 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 two signals and noting their precise meaning. Also note that when a data transfer is initiated and the process is put to sleep, in most devices there will be an interrupt to let the driver know the I/O has been completed. If the 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 case as the “sleep queue” is presumed to be empty. Depending on the driver and the application, this behavior and its consequence should be carefully considered. And Þnally, there is another potentially larger problem. If an application program asks a driver to transfer data to a device, and then a signal causes that application program to be terminated, should the driver Þnish transferring the data? And what about when a 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 where the 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 is driver-speciÞc and application-speciÞc. You need to decide based on your driver and application needs.
MontaVista™ Linux® Professional Edition
99
Chapter 6: Linux Kernel Development Building Custom Device Drivers
Read from a device At this point, the driver's write routine should be 100% functional. It should be fairly well tested under normal, stress, and abusive conditions. It should handle bad pointers from users, deal with reentrancy issues using MUTEXes, and be fully coordinated with the driver's ISR and tasklet. As needed, it should handle normal, non-blocking and asynchronous writes. To code the read routine, copy the core of the write routine and paste it into the read function. Once there, review the sequence of events and make any necessary adjustments. For example, instead of copy_from_user(), the read routine uses the copy_to_user() function. Since the data to be read won't be available until near the end of the read routine, the call should probably move to the end of the read handler. In the case of a normal (sleeping) data transfer, the copy_to_user() function would belong shortly after the interruptible_sleep_on(). In that case, the device interrupt would essentially mean “the data is now ready in the kernel buffer.” Other details of the read handler in the device driver should be relatively obvious. As with 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 test program for the read routine. Other issues to be tested may involve the concurrency of reads and writes to the same device at the same time. There is no absolute rule here. It depends on what your driver is supposed to be capable of supporting. With some hardware devices, only one read or one write can be performed at any instant. The driver should take this into account, therefore, and serialize use of the device accordingly. But if the device supports reading and writing at the same time, the driver 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 Þrst doesn'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 data variables or device control registers that might also be accessed or manipulated in the interrupt or tasklet context should be considered a critical region. The classic method of ensuring integrity of the data is to simply preclude a change of context. This is most easily done by disabling (blocking) all hardware interrupts. Use the save_flags(); cli(); sequence to Þrst save the current state of the interrupt mask and then set it into the disabled state and, later, use restore_flags() to restore the former setting. Using this sequence is “safe” no matter what the interrupt state is at the beginning. It will always set it back to the correct value. Testing for reentrancy problems is difÞcult. Although it is theoretically possible to test a driver for all possible cases, in practice, the hardware is usually not available to try all combinations. Instead, most drivers are subjected to long-running stress tests with randomized data and timings. The hope is that, given enough time and enough random variation, all the bugs will eventually be found.
100
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
For the test program, this means that all of the foregoing tests must be repeated thousands and thousands of times, meticulously checking each and every operation for proper behavior. Multi-threading in the test program is a common way of achieving a high degree of parallelism but, if overdone, can drive the system so hard that 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 multiple application programs to execute in true concurrent fashion. In those systems, one application program may call a device driver at exactly the same time as a different application program on another processor calls the exact same driver. The previously described MUTEX will adequately handle this case, but what if one processor is initiating a data transfer and, nanoseconds later, the device causes an interrupt and the hardware decides to allow a different processor handle the interrupt? In that case, the driver's ISR and read/write handler will both be executing, literally at the exact same time. If they both access a common data structure at the same time, the data could easily be corrupted. The situation above demonstrates the need for spin locks. A spin lock is a bit that is either on (locked) or off (unlocked). The processor provides some basic mechanism for testing and setting these bits, and Linux provides well-documented and portable interfaces 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, a driver 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 acquires a spin_lock but also disables interrupts on the local processor. The corresponding spin_unlock_irqrestore() is then used later to undo both the spin lock and the processor's interrupt mask. Finally, because spin locks may cause other processors to “spin in their tracks,” their use should be as rare and for as brief a period of time as possible. Study of the source code to other drivers will show that, in most cases, spin locks are rarely held for longer 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 test program, developed in lock-step with the coding of the driver, can be used to test each piece. As the driver gains in capability, the test program is similarly enhanced to thoroughly probe the driver and verify proper operation. This includes giving the appropriate 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 and the driver's kernel module “carrier.” The associated kernel module initialization and removal routines are tested at this initial stage.
MontaVista™ Linux® Professional Edition
101
Chapter 6: Linux Kernel Development Building Custom Device Drivers
Then, the driver's initialization and prepare to be removed functions are coded and tested. These include the Þrst use of the kernel via the register_chrdev() and unregister_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 interrupt handler and, if necessary, the driver's tasklet. To test the new code, the test program is enhanced to include normal (legal) writes as well as writes specifying invalid addresses and other illegal operations the driver is supposed to catch. The test program veriÞes that the driver not only catches the errors, but also returns the proper indication. When the write handler is Þnished, it is copied into the read handler and, after some fairly minor adjustments, it is ready to be tested. The test program is modiÞed accordingly and run. Issues of reentrancy abound. Kernel MUTEXes, spin locks and interrupt masking must all be used in various places and combinations. Testing becomes less certain of Þnding all problems and “long duration stressing” is often used in partial compensation. The main driver entry points have been sketched out here. The driver's handlers for open(), close(), read() and write() are almost complete. However, most drivers will also include handlers for ioctl() and others. Many will also provide interfaces for poll(), mmap(), media_change(), revalidate() and several others. And, practically every one of these will have only a passing similarity from one driver to the next.
Additional Information
The best information on Linux device drivers are the hundreds of Linux device drivers, all of which are provided in source form in: •
/opt/hardhat/devkit/lsp//linux/drivers
In addition, there are many good books that provide details on building Linux device drivers. Note: MontaVista Software does not endorse the book listed below. The following example is provided for your convenience only. Linux Device Drivers (Nutshell Handbook), Second Edition, Alessandro Rubini, Andy Oram (Editor). Sebastopol, California: O'Reilly & Associates ISBN: 1565922921
102
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling File Systems
Enabling File Systems The Linux kernel supplies Þle-system services for a of variety Þle-system types. File systems 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 system support on your target. As part of deployment (see “Deployment” on page 171), you need to build a Þle system for your embedded system. Building a Þle system requires, among other things, 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 for JFFS), see: •
“ConÞguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System” on page 173
MontaVista™ Linux® Professional Edition
103
Chapter 6: Linux Kernel Development Debugging the Kernel
Debugging the Kernel Pro provides a number of tools and conÞguration Þles that can be used to debug the kernel. The tools and conÞguration Þles are:
KGDB
•
KGDB
•
Linux Trace Toolkit (LTT)
•
Abatron BDI2000 ConÞguration Files
KGDB is a debugging tool that can be used to debug the Linux kernel. Using KGDB is most practical when you are implementing kernel device drivers and other similar functions. 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 is not on by default in the kernel; however, the ability to turn on KGDB is there for each kernel. 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. To enable kernel debugging, complete the following steps:
104
1.
Start make menuconfig or make xconfig. The latter can be run on its own or through TCT.
2.
Depending on the target architecture, select Kernel Hacking or Kernel Debugging.
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Debugging the Kernel
3.
Enable GDB stub kernel debug or KGDB.
4.
The makefile in the same directory where .config for the kernel resides 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 GDB for symbolic debugging. Removing the –fomit-frame-pointer allows the capability to do stack traces and walkbacks. 5.
Rebuild the kernel, using TCT or the procedure in “Building and ConÞ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 the target with the new kernel, see “Booting the Target with a Custom Kernel” on page 52.
Set up GDB to debug the kernel Now that everything is set to debug the kernel, it is necessary to connect to it using GDB. To connect to the target using GDB, complete the following steps: 1.
Terminate the Minicom (or other terminal emulator) connection to target.
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. A copy 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
The file command loads the symbols for the kernel into GDB to enable symbolic debugging. By being in the correct directory, the full source is also available for display.
MontaVista™ Linux® Professional Edition
105
Chapter 6: Linux Kernel Development Debugging the Kernel
Note: The kernel binary image Þle to download into GDB is located in the top-level directory of the tree used to build the kernel, and it is usually 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.
7.
Enter a breakpoint command at the address or function where debugging should begin. There are two convenient places to set breakpoints. They are: •
b panic This is the entry point to panic routines. This traps all panics to GDB.
•
b sys_sync By entering a sync command, the system will go to the breakpoint for sys_sync.
Enter continue to start the kernel running again.
GDB is now running and in control of the kernel. It will stop at the breakpoint entered above. This allows for examining variables and watching how the code ßows.
Additional information For more information about using KGDB and kernel debugging, see the following help document on MontaVista Zone (http://support.mvista.com/content/Kernel).
106
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Debugging the Kernel
Linux Trace Toolkit (LTT)
LTT provides a general-purpose event logging and analysis system, with many useful pre-deÞned events. The pre-deÞned events are in the areas of:
•
system calls
•
Þle-system management
•
traps
•
timer management
•
interrupts
•
memory management
•
scheduler
•
socket communications
•
kernel timer
•
SystemV IPC
•
soft IRQ management
•
communications
• •
process management
network device management
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 received for 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 for Solaris. For all hosts, the LTT tracevisualizer data analysis tool is linked in statically to avoid an install-time dependency on some graphics packages, such as glib, XFree86-libs, and gtk+. This results in problem using some GTK themes. These problems depend on 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.
MontaVista™ Linux® Professional Edition
107
Chapter 6: Linux Kernel Development Debugging the Kernel
•
Remove ~/.gtkrc (you might want to save a copy).
•
The hhl-host-ltt-dynamic package contains a version of the tracevisualizer data analysis tool that is linked with shared libraries. Remove the hhl-host-ltt-0.9.5a package and install the hhl-host-ltt-dynamic-0.9.5a package available on the Pro distribution CD-ROMS. To remove the hhl-host-ltt-0.9.5a package, use the command: rpm -e
hhl-host-ltt-0.9.5q-mvl3.0.5.rpm
To install the hhl-host-ltt-dynamic-0.9.5a package, use the command: rpm -Uhv --ignorearch mvl3.0.5.rpm
hhl-host-ltt-dynamic-0.9.5q-
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) Note: is i386, ppc or solaris2.7-sparc64 depending on the host you are using.
Additional information For more information about what LTT does and how to use it, see the LTT reference manual 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 solely through the stable on-chip debugging services. This debugging mode runs even when the target system crashes, and it enables you to continue investigating the cause of the crash. Host-to-BDI communication uses the standard GDB remote protocol, as in the diagram below:
Serial Connection
Host
(Optional for console)
LAN
AbatronBDI2000 (Functions as a GDB server)
108
MontaVista™ Linux® Professional Edition
Target
BDM/JTAG
Chapter 6: Linux Kernel Development Debugging 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 network capability
•
supports built-in on-board programming of ßash memories
•
supports internal break register (allows debugging of code running out 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 LSPs for which we support the use of the Abatron BDI2000 debugger. Check the MontaVista Zone page for your target for information about support for this feature on your target.
MontaVista™ Linux® Professional Edition
109
Chapter 6: Linux Kernel Development Debugging 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 to follow 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 that contains bdisetup.zip.
3.
Copy the .cnf and .def Þles that came with the BDI2000 into the directory that your TFTP server gives access to. If a .cnf Þle came with 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 and then make a copy of the Þle. Edit the copy to change the conÞguration values to Þt your particular environment. You will want to refer to the BDI2000 documentation for more details. You will need the name of this Þle in Step 8.
4.
Connect your BDI2000 to your host with a serial cable, the network with a LAN cable and then connect its power. Do NOT connect the BDI2000 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 -u option. The defaults for the options can be determined by looking in the source, but it is probably easier to just specify all options. The application 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 BDI2000 from the Þles in the current directory using the serial port /dev/ttyS1 running at 38400 baud. The Þrmware and logic that is loaded is for a PPC400 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, and the IP address of your gateway. The conÞguration Þle should be the name 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
Chapter 6: Linux Kernel Development Debugging the Kernel
9.
Make sure that the Þrmware is programmed correctly and then tell the BDI2000 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 LED should no longer be blinking on the BDI2000 and you should be able to telnet to it. When you telnet to the BDI2000, it will show a help screen and then report that it is waiting for the target Vcc. 10. Make sure that your target's power is turned off. You can then connect the JTAG or BDM ribbon cable between your target and the BDI2000. Turn on the target's power. If all is well, the BDI2000 resets and initializes the target with no errors. You are now ready to start using the BDI2000. Using the telnet interface, you can do such 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 apparent when you start using it as a gdbserver. You will be able to debug boot code, the kernel, drivers, and modules. If you compile your code with -ggdb and use ddd, you will 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
Chapter 7: Application Development
Overview There are a variety of ways to build your application using Pro. You can build the application on the host using KDevelop (a C/C++ IDE) or the command-line crosscompilers included with Pro. Whether you use KDevelop or the command-line tools, we recommend that you do NOT work directly in the /opt/hardhat/devkit tree. Rather, you should create a build directory for your work (for example, myapplication) Once you have written and compiled your program, you should copy 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 the target for testing. When choosing a location for your application in the target Þle system, we recommend following the Filesystem Hierarchy Standard (FHS). For more information, see http://www.pathname.com/fhs/. Note: You can also write and debug programs directly on the target using the targetspeciÞc command-line compilers. This chapter provides examples of writing simple programs and information on how to 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
Chapter 7: Application Development Building 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, KDevelop provides: •
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 selected project type, Þle templates and appropriate includes and libraries are 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 as Compiler, Linker, automake and autoconf. MontaVista Software has customized KDevelop for use in the cross-development environment. See “MontaVista Customizations” on page 115 for more information. The KDevelop documentation set includes The User Manual to KDevelop and The KDevelop Programming Handbook. Both of these manuals are part of the KDevelop distribution and are also available via MontaVista Zone. While fairly complete, the KDevelop documentation does not cover using KDevelop in a cross-development environment. The sections below provide information about the customizations MontaVista Software made to KDevelop, as well as information about how to use KDevelop in the cross-development environment.
114
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
MontaVista Customizations
KDevelop 2.0.1 was used as the base for the Pro distribution. MontaVista customizations include: •
Menu Bar changes: •
Project-> New (New Project Wizard). Provides a “Target Non-Graphic” major project type as a starting point for target cross-development. “Non-graphic” means that support is not provided for a graphical environment (X11, Qt/Embedded, KDE, or Gnome) on the target.
•
Tools: Provides DDD (debugger) and TCT (Target ConÞguration Tool) entries if those components are installed as part of Pro. (TCT and DDD are installed by default with Pro.)
•
Options->Tools... Includes DDD and TCT entries.
•
Help->MontaVista Support: Provides direct access to MontaVista Zone via a Web browser.
•
KDevelop senses which cross-development environments are installed in /opt/hardhat/devkit. This allows projects to be deÞned either for the development host (normal, natively hosted development) or for any of the cross-development targets. Various menus and options throughout KDevelop were adjusted for this option.
•
The second pane of the Application Wizard presents a Target pulldown menu that allows you to select either Development Host for natively-hosted development (using the host system's own toolchain) or one of the MontaVista architecture/processor strings for cross-development using the appropriate toolchain for your target.
•
The Compiler Options pane has been changed to include a Target Arch/Proc pull-down. This initially shows the target chosen during project creation. Clicking this pull-down and changing the selection redeÞnes the project for a new target. Selecting Development Host converts the project from cross-development to natively-hosted development.
•
The Þeld Pro Development Kit shows the root of the Pro crossdevelopment tree. This value is set based on the installed location of Pro (typically /opt/hardhat/devkit.) Replace the value of this Þeld if the development kit has been moved. (Warning: Pro cannot be relocated after installation and any attempts to do so will break the development environment; however, this option may be useful for customers who have multiple products installed.)
•
Under the Build menu, the options Execute and Execute with Arguments can only be used for natively hosted projects. Because
MontaVista™ Linux® Professional Edition
115
Chapter 7: Application Development Building Programs Using KDevelop
these menu items run the application on the local host system, when a cross-development project is deÞned, these menu items are disabled. Cross-development binaries must be moved to the target system and run and debugged remotely. •
Under the Debug menu, the options Start and Start (other)... start the debugger. If DDD is installed for cross-development, the debugger is conÞgured to be DDD for the current target. For example, if the project target is set to arm_sa_le, by default, the debugger is deÞned to be: ddd --debugger arm_sa_le-gdb
The default value can be overridden by selecting KDevelop Setup from 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 the architecture-speciÞc debugger; instead, it uses the options speciÞed in the Options->Tools... conÞguration. If you intend to use DDD via the 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 installation of Pro. Note: Many host distributions have a version of KDevelop already installed. The version 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, you may see some look-and-feel and desktop interaction differences when running the MontaVista provided KDevelop. These differences are most noticeable when running in a non-KDE desktop (Gnome, CDE, OpenWindows, Motif). For a KDE desktop older 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 that when 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 MontaVista provided KDevelop. For example, if the “File Browsing Preferences” were changed via the control panel, those changes would not affect the MontaVista provided KDevelop. In general, the MontaVista provided KDevelop is isolated from the desktop, since its main purpose is to build tools for the target.
116
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building 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 host versions 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 the full path when starting the MontaVista provided KDevelop. Alternatively, the PATH variable must be set to give priority to the Pro host tools. The base system installs KDevelop into /usr/bin or /opt/kde2/bin while Pro installs by default into /opt/hardhat/host/bin.
Use KDevelop for CrossDevelopment
The sections below provide an example of how to use KDevelop in the crossdevelopment 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 userinterface
•
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 starting KDevelop 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 erases the “recently opened project” list. KDevelop project deÞnitions and directories are not disturbed. Following setup, you need to open existing projects by explicitly selecting Open... from the Projects menu. You may also change some (but not all) settings established without re-starting in setup mode by selecting KDevelop Setup... from the Options menu.
MontaVista™ Linux® Professional Edition
117
Chapter 7: Application Development Building Programs Using KDevelop
Creating a new cross-development project To create a new project that will use the cross-compilers for your target, 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 Target Non-Graphic major project type, select either C or C++. The Target Non-Graphic major project type is a starting point for target cross-development. The target is assumed to only contain the Pro development environment, and support is not provided for a graphical environment (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.
118
Select Next to move to the next screen.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
5.
Fill in the Þelds in the Generate settings panel. The examples in this manual use mynewproject as the application project directory name.
6.
From the Target pull-down menu, select the architecture/processor type of your target board. Note: KDevelop automatically detects which architecture/processor types have been installed as part of previous Pro installations. Only the architecture/processor types installed, along with the native host option, are available. Note: Only one architecture/processor type can be selected at a time, so a single project cannot simultaneously be built for multiple architecture/ processor types. For team development, all developers share the same project metadata and therefore must use the same architecture/processor type.
7.
Select any additional features that you need for your project, such as API-Documentation or GNU-Standard-Files.
MontaVista™ Linux® Professional Edition
119
Chapter 7: Application Development Building 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 control system, select CVS from the pull-down menu and enter the information about your repository in the VCS Support Þelds. If you are using a nonlocal 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 to create 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 required makeÞles. You can now write your application. Note: Following initial deÞnition of a project, the target may be changed at any time by selecting Options from the Project menu. If any project options are changed, the project will be reconÞgured upon closing the Project->Options menu. If the development target was changed, the project will be reconÞgured to use the new development toolchain; however, the project is not rebuilt for the new architecture
120
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
until you select Rebuild from the Build menu. Source code that is not written in an architecture-independent manner remains unchanged, and if the target is changed, the code 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, select Custom project.
3.
Continue to use the Application Wizard just as you would for any new project. (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 browse through the Þle system and select the source code and makeÞle you want 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 process will use (that is, the one you imported).
MontaVista™ Linux® Professional Edition
121
Chapter 7: Application Development Building 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 the Classbrowser, Classtools, and Þle views to help you easily view and edit your project source Þles. For typical application development you might see a screen similar to the one below:
Once you have written your application, you can build your application by selecting Rebuild from the Build menu. Note: The Build menu commands Execute and Execute with Arguments can only be used for natively-hosted projects. Because these menu items run the application on the local host system, when a cross-development project is deÞned, these menu items are disabled. Cross-development binaries must be moved to the target system and must be run and debugged remotely.
122
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
Moving the application to the target Cross-development binaries must be moved to the target system and then run or debugged remotely. If you followed the steps listed in the quick start guide for your target, you will have NFS exported the default root Þle system (/opt/hardhat/ devkit/<architecture>/<processor>/target). We recommend that you NOT work directly in the /opt/hardhat/devkit tree. Rather, you should create a directory for your Þle system (for example, my_work_directory/myfilesystem) that contains a copy of the default target Þle system or the Þle-system you are developing. You should then NFS export your custom Þle system directory as the root Þle system on your target. See “How to NFS 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 to the target’s Þle system (/my_work_directory/myfilesystem), where it can be run and debugged (recommended). When choosing a location for your application in 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 any associated data Þles to the cross-development Þle-system tree. To use KDevelop for this purpose, complete the following steps: 1.
In your project’s makeÞle, specify the location where you wish to move the executable. For example, you could move the application to a work directory 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 write access to the directory (or to the target subtree in general) speciÞed. 2.
From the Build menu, select Install. KDevelop performs a make install which moves the executable and any associated data Þles to the cross-development Þle-system tree that you speciÞed in the project makeÞle.
Your application can now be run and debugged on the target.
MontaVista™ Linux® Professional Edition
123
Chapter 7: Application Development Building Programs Using KDevelop
Debugging an application For cross-development, the debugger is conÞgured to be DDD for the current project target, 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 is deÞned to be: ddd --debugger arm_sa_le-gdb
Note: This default can be overridden by selecting KDevelop Setup from the Options menu. To debug the current open application, complete the following steps: 1.
From the Options menu, select KDevelop Setup to set the options used by 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 debugger checkbox is not checked) that is not useful for remote debugging and is not supported by MontaVista Software. Since DDD was installed as part of Pro, KDevelop detects it and automatically selects Use external debugger and predeÞnes the Select debug command Þeld to ddd. Note: Although the command line is shown as ddd, the actual command line used is the following:
124
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
ddd --debugger gdb
for native host development deÞned projects can be speciÞed in the Select debug command Þeld following ddd. 4.
In the cross-development environment, DDD establishes a connection to a remote debugging stub, usually gdbserver, via a serial or TCP connection. Since the location and type of connection to the target is not known, you must set those options. One of the options related to remote debugging over a serial line is: •
-b <speed>
to set the line speed for a serial connection from GDB to gdbserver To add user options, enter the options into the Select debug command Þeld following ddd. For example, to set the line speed for remote debugging 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:<port> <program>
is the target system's domain name or IP address, <port> is the TCP port number on which the debugging stub is listening, and <program> is the full path to the program to be debugged. For example, to debug a program called hello using the gdbserver 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 “Debugging Programs Using GDB and DDD” on page 132. 7.
In KDevelop, run the debugger. From the Debug menu, select Start or Start (other)... This launches DDD using the options speciÞed.
8.
DDD creates a window with two panes. The lower, smaller pane provides a work space for direct entry of GDB commands and viewing GDB responses.
MontaVista™ Linux® Professional Edition
125
Chapter 7: Application Development Building Programs Using KDevelop
•
To connect to the remote debugging stub using a TCP connection, enter: target remote:<port>
where is the target system's domain name or IP address and <port> is the TCP port number on which the debugging stub is listening (both values are parameters to the debugging stub when the latter is started). For the example debugging stub started in step 6, the DDD connection established from 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 system being debugged. This connection will run at the serial-line speed speciÞ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 to run 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. Executable and Menu Text should contain the correct information by default.
3.
In the Arguments Þeld, enter: --host --login <userID> <program>
where is the name of your target system, <userID> is the login user name on that system, and <program> is the full path to a copy of your debug executable, previously moved or NFSexported 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
126
4.
Ensure that the box Capture output is checked.
5.
Click the Replace button.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
6.
Click the OK button.
You may now run DDD with remote debugging on your executable by selecting DDD from the Tools menu.
Help
You can access MontaVista Zone from inside KDevelop by selecting MontaVista Support from the Help menu. For more information about MontaVista Zone, see “MontaVista Zone” on page 11. A supported Web browser must be available in the desktop execution environment to view the content. For Linux systems, supported browsers include Konqueror (KDE 2), Netscape (netscape-communicator), and Mozilla. For additional information about using GDB and DDD, see the GNU manuals for those applications. The GNU GDB and DDD manuals are available on MontaVista Zone.
MontaVista™ Linux® Professional Edition
127
Chapter 7: Application Development Building 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 your programs rather than the KDevelop IDE. When using the command-line compilers to build 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 a my_work_directory/myapplication directory for your application development and a my_work_directory/myfilesystem directory for your Þle-system development. These directories will be used in all examples below. We also recommended that you NFS mount the myfilesystem directory on the target for testing. It is assumed in the examples below that the myfilesystem directory contains your target Þle system and that it is NFS-mounted as the target’s root Þle system. For all of these examples, the user’s executable search path has been updated to include 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 is 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, write your program. For this example, we’ll use the simple “hello world” program saved as hello.c. #include <stdio.h> main(int argc, char **argv) { printf("hello world\n"); }
2.
Using the cross-development tools included with Pro, on the host, build the 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 using gcc, 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/
128
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building 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: ./hello hello world
Example of a C++ Program
The following is an example of a simple C++ program on a PowerPC 8xx target. Bold is 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, write your program. For this example, we’ll use a simple “hello” program saved as hello.cc. #include using namespace std; main() { cout << "hello from C++\n"; }
2.
Using the cross-development tools included with Pro, on the host, build the 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 using g++, 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: ./hello hello 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
MontaVista™ Linux® Professional Edition
129
Chapter 7: Application Development Building Programs Using GCC and G++
130
•
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
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Using Threads
Using Threads For building multi-threaded applications, Pro provides LinuxThreads. LinuxThreads is an implementation of the POSIX threading library speciÞcation IEEE 1003.1c. LinuxThreads implements a 1:1 threading model, allocating one kernel thread for each user-space thread created by the program. LinuxThreads is the standard Linux threading library. To use LinuxThreads in your application, you need to do the following: •
Use #include in your source code.
•
Add -lpthread to your application's compilation options to link against 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
Chapter 7: Application Development Debugging Programs Using GDB and DDD
Debugging Programs Using GDB and DDD Pro provides a number of tools for debugging code; however, the main troubleshooting tool available for debugging application code is currently GDB. GDB is a command-line debugger that allows you to step through code, set break points, and print 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 the execution of the program being debugged
•
a client that runs on the host and provides a command interface and access 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 being debugged 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 catch bugs: •
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 to experiment with the effects of a change
Pro also includes the program DDD. DDD is a graphical front-end for Linux debuggers, including the GDB debugger. Using DDD with GDB, it is possible to point and click through debugging an application program. You can use GDB to debug programs written in C, C++, and assembly. Examples follow 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 to include the Pro applications. For information on how to update your path, see “Running Pro Applications and Tools” on page 40.
Additional Documentation
132
For additional information about using GDB and DDD, see the GNU manuals for those applications. The GNU GDB and DDD manuals are available via MontaVista Zone.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Debugging Programs Using GDB and DDD
Example of Using GDB
Following is an example of using GDB to debug a Pentium III target system. In the default 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 to strip programs to save space on the target, and doing so prevents the GDB client from accessing symbol information. Note: When working with a stripped binary on the target, the host requires a nonstripped 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’s usr/bin directory, you can begin debugging in the target environment, as in the example below. Bold indicates user input.: cd /usr/bin : gdbserver host:2345 hello Process hello created; pid = 18
On the GDB server command line, 2345 is the network port number on which the server waits for a connection from the client. This can be any available port number on 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 name and the port is 2345, you can begin debugging in the host environment as shown in the 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 you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i686-pc-linux-gnu --target=i686linux". (gdb) target remote Voyager:2345 Remote debugging using Voyager:2345 0x3000ffbc in ?? () (gdb)
MontaVista™ Linux® Professional Edition
133
Chapter 7: Application Development Debugging 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 III target system. In the default conÞguration for Pro for Pentium III, 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 to strip programs to save space on the target, and doing so prevents the GDB client from accessing symbol information. Bold indicates user input. Note: When working with a stripped binary on the target, the host requires a nonstripped 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 a connection from the client. This can be any available port number on the target. 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. Use the 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 console similar to the following: Remote debugging using Voyager:1000
Voyager is the machine name and the port is 1000. You can now begin debugging in the host environment using the interface provided by DDD.
134
5.
Set a breakpoint on main by double clicking or entering on the command line: b main
6.
Click the cont button.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Debugging 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 call fork(), vfork(), and execve(). To stop execution when the debugged program calls fork, vfork, or exec respectively, 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 the default), 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
Chapter 7: Application Development Debugging Multi-Threaded Applications
Debugging Multi-Threaded Applications With 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 about threads: •
Threads in Linux are not child processes of the creator thread – all threads 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 particular thread and to set a break point. There are two ways to set a break point with threads using DDD:
Additional Information
•
You can specify the address of the break point and the thread number.
•
Or you can attach to the thread and then set the break point.
There are several good sources of information about threads available. Note: MontaVista Software does not endorse any of the books or Web sites (other than our own) listed in this section. Examples are provided for your convenience only.
Books Pthreads Programming. by Bradford Nichols, Dick Buttlar and Jacqueline Proulx Farrell. O'Reilly & Associates, 1996 ISBN: 1565921151 POSIX
Web Sites The Linux Threads FAQ on MontaVista Zone http://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
Chapter 7: Application Development Additional Tools for Programming and Debugging
Additional Tools for Programming and Debugging The following tools have been found to be valuable time-savers in developing and debugging Linux applications. Many of these applications are free-source and available 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 answer questions 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: •
cßow
http://www.ziplink.net/~felaco/cbrowser/
cflow reads a list of source Þles and prints a graph of the program's function call hierarchy. Called functions are indented with respect to their calling functions. cflow can be downloaded from: •
cscope
http://metalab.unc.edu/pub/Linux/devel/lang/c/!INDEX.short.html
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
Chapter 7: Application Development Additional Tools for Programming and Debugging
cscope builds a symbol database that can be searched for the answers to those questions. It searches the database and displays a window of the Þles, which can then be opened in your favorite editor. cscope can be downloaded from: •
dmalloc
http://cscope.sourceforge.net
dmalloc is a memory allocation debugger that supports both C++ and threading. dmalloc is part of the Pro distribution. More information about how to use dmalloc 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 the executed process and the signals that are received by that process. ltrace is part of the Pro distribution. More information about how to use ltrace can be found by reading the man page for ltrace.
mtrace
There is a feature of the GNU C Library called mtrace. Using this feature allows you to detect memory leaks caused by unbalanced malloc and free calls. mtrace is implemented as a function call to turn on tracing. When implemented, mtrace creates a log Þle of addresses malloc'd and free'd. A perl script is used to display the log Þle listing only the unbalanced combinations and, if the source Þle is available, 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 C Library: •
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 and view the Memory Allocation section. In particular, within the Memory Allocation section, see the section on Allocation Debugging. Information on mtrace was the April 2001 Tip and Trick article on MontaVista Zone (http://support.mvista.com/content/TipArchive/april2001.html), which included sample programs and scripts.
138
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Additional Tools for Programming and Debugging
strace
strace is a focused debugging tool for tracing system calls and signals by intercepting and recording system calls called and received by a process. strace is part of the Pro distribution. More information about how to use strace can 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 that is easy to read. It is easy to Þgure out which assembly code each C-source line generated. Color is used to make the output easier to read. showasm can be downloaded from MontaVista Zone.
MontaVista™ Linux® Professional Edition
139
Chapter 7: Application Development Using AltiVec™ Technology by Motorola
Using AltiVec™ Technology by Motorola AltiVec™ technology provides general-purpose processing for PowerPC microprocessors while concurrently addressing high-bandwidth data processing and algorithmic-intensive computations in a single-chip solution. Using AltiVec technology can:
Features
Limitations
•
provide multichannel modems, echo cancellation equipment, and base-station processing
•
enable encryption methods optimized for the SIMD processing model
•
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 3D graphics, etc.)
When using Motorola's AltiVec technology with Pro: •
assembler supports AltiVec instructions -- allows user applications to be written with in-line assembly AltiVec code
•
the Kernel and C Library support saving and restoring AltiVec registers
•
the C library supports the use of setjmp and longjmp in combination with AltiVec code
No direct support is available for AltiVec C extensions. MontaVista Software is evaluating these extensions. The kernel currently ignores VRSAVE and saves all registers when switching between two user tasks running AltiVec code. These actions:
140
•
may hide errors when using VRSAVE in user code
•
may cause problems in the future if optimizations to use VRSAVE to determine which registers to save and restore are implemented in the kernel
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Using 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
Chapter 8: System Integration
Overview Once you have Þnished developing your kernel and application, you are ready to begin deployment of your embedded application. The Þrst thing you need to do is integrate your system components (the kernel and the application) in a test environment. The steps listed below are guidelines. You may need to change the order of integration, depending on the type of Þle system you have or other development needs. 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
Chapter 8: System Integration Overview
Once you have completed the steps above, you should have a system that appears as follows: User-Space Configs
Local Network Pro --------------Red Hat 7.3
Custom Apps NFS Root File System
Custom Kernel
Target File System
Serial
................... .................. Target Host
144
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Creating Your File-System Hierarchy
Creating Your File-System Hierarchy Once you are satisÞed with your kernel and application, you need to determine which additional libraries and applications are required to support your application so that you 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 by MontaVista that you need in your embedded system.
3.
Add your custom applications to the Þle system hierarchy created by TCT.
Guidelines on how to complete the above steps are included in the sections below.
Select a Deployment FileSystem Type
Knowing which ßash, memory, and disk drive provided by the board in your product will determine the size and type of your Þle system, which in turn will dictate how many applications can be included. You should know the type of Þle system you want to 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 target boards 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 such as CramFS. In addition, MontaVista Software also provides a tool for reducing the size 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 wider range of choices. One choice is ReiserFS, a journaling Þle system, which can be a good choice if your embedded application will need to be turned on and off on a regular 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 of XFS include quick journaling recovery, fast transactions, high scalability, and excellent bandwidth. MontaVista Software supports the following Þle system types: •
CramFS
•
EXT2 and EXT3
•
Journaling FLASH Filesystem (JFFS)
•
ReiserFS
•
XFS
MontaVista™ Linux® Professional Edition
145
Chapter 8: System Integration Creating Your File-System Hierarchy
Not all of the Þle systems listed in this section can be used with all target boards. To help you decide which Þle system you want to use, here are some notes about the features and limitations for each Þle-system type. In addition, check the MontaVista Zone 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 than 16MB, 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 created along 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 in conjunction with another Þle system and can be used with MTD (Memory Technology Device). Check the MontaVista Zone page for your target for information about 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 using CramFS 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 and CD-ROM drives. EXT2 supports up to 4 Terabyte Þle system sizes and Þle name sizes of up to 255 characters. EXT3 is the latest version of the EXT Þle system. Two big improvements included in EXT3 are support for access control lists (ACLs) conforming to Posix Semantics (IEEE 1992), and journaling (automatic recovery when the Þle system is remounted). EXT2 is supported on all Pro architectures. EXT3 is experimental; however, it is available for all Pro architectures. Check the MontaVista Zone page for your target for 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
Chapter 8: System Integration Creating Your File-System Hierarchy
Journaling FLASH File System (JFFS) The Journaling Flash Filesystem (JFFS) was developed by Axis Communications in Sweden. JFFS: •
provides a Þle system directly on ßash, rather than emulating a block device
•
is designed for use on ßash-ROM chips and it recognizes ßashROM 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 times erase_sector_size times the number of ßash chips that is required for garbage collection. JFFS has some limitations. It doesn’t do garbage collection incrementally, and it blocks read during the garbage collection erase sectors, which may last for several seconds. In some cases, JFFS has failed after consecutive power cycles during writes to the ßash. JFFS2 is the next version of JFFS. JFFS2 provides improved wear-levelling and garbage-collection performance; improved RAM footprint and response to systemmemory pressure, improved concurrency and support for suspending flash erases; marking of bad sectors with continued use of the remaining good sectors, thus enhancing the write-life of the devices; native data compression inside the file system design; and support for hard links. Check the MontaVista Zone page for your target for information about support for this 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, the supplied MTD Utilities (in /usr/sbin), and some frequently asked questions about JFFS and MTD.
•
http://developer.axis.com/software/jffs/
•
http://www.linux-mtd.infradead.org/
MontaVista™ Linux® Professional Edition
147
Chapter 8: System Integration Creating Your File-System Hierarchy
•
ftp://ftp.uk.linux.org/pub/people/dwmw2/mtd/cvs/mtd/mtd-jffsHOWTO.txt
ReiserFS ReiserFS is a journaling Þle system. The main beneÞt of ReiserFS is that there is no need for a lengthy Þle-system check (fsck) when the system is rebooted. During normal operation, ReiserFS logs all changes to Þle-system structure (metadata) to a special 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 for non-journaling Þle systems. The ReiserFS journal area is currently Þxed in size at 30 megabytes. This makes ReiserFS unsuitable for Þle systems that are less than about 100 megabytes in size. ReiserFS is currently supported on all Pro architectures. Check the MontaVista Zone page 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/Þlesystemsblock.html
XFS XFS is a journaling Þle system developed by SGI and used in IRIX operating system from SGI. XFS combines advanced journaling technology with full 64-bit addressing and scalable structures and algorithms. The main features of XFS include quick journaling recovery, fast transactions, high scalability, and excellent bandwidth. XFS provides the following beneÞts:
148
•
sub-second Þle system recovery after crashes, which means no long fscks 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 per directory)
•
two terabyte Þle system limit is due to the Linux block device I/O layer
•
extremely scalable using Btrees extensively to support large and/or sparse Þles and extremely large directories
•
resizing
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Creating 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 block addressing limitation effectively limiting the maximum Þle system size to 137 GB
SGI XFS is currently supported on all Pro architectures. Check the MontaVista Zone page for your target for information about support for this feature on your target. Additional information about SGI XFS is available at: •
XFS FAQ http://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 on MontaVista 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 a dependency on another package, that package is automatically installed with the selected package. TCT will also tell you the size of your Þle system. Once you have selected 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 a dependency on another package, that package is automatically installed with the selected 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 include in your Þle system.
2.
Use TCT to build the Þle system. TCT creates a tar-archive of the Þle system.
MontaVista™ Linux® Professional Edition
149
Chapter 8: System Integration Creating 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 to a build directory (for example, myfilesystem), the next step is to add you application. Copy your application to where you want it to reside in the target Þle system. The default Þle system layout of the target follows the Filesystem Hierarchy Standard (FHS). When deciding where to place your application, we recommend that you follow the FHS guidelines. For more information, see: •
150
http://www.pathname.com/fhs/
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Booting 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 boot the target with the new kernel and NFS-mount your Þle system. The kernel is either the one you modiÞed for your embedded application, or, if you chose not to modify the kernel, it is the default kernel supplied by MontaVista Software. If you used TCT to develop your kernel, your kernel image is included in the tar archive created by TCT. 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 the Target with a Custom Kernel” on page 52. Note: The instructions include NFS mounting the target’s root Þle system. By exporting the Þle system directory as NFS, you can test your environment on the target before spending the development time to reduce the size of the Þle system or adding the Þle system to ßash.
MontaVista™ Linux® Professional Edition
151
Chapter 8: System Integration Configuring the User-Space Environment
ConÞguring the User-Space Environment Once you have installed Pro and completed your kernel, application and Þle-system development, and you have exported the Þle-system directory as NFS, the next step in system integration is to tailor your target’s user-space environment to your application. While we cannot anticipate the particulars of every situation, some examples of common setups are provided below. This section contains information about the following conÞguration settings and tools:
Enable Run-Level Services (Startup Scripts)
•
“Enable Run-Level Services (Startup Scripts)” on page 152
•
“ConÞgure the Target for Serial Console or Virtual Terminal” on page 156
•
“Create Standard Device Nodes” on page 158
•
“Add Shells” on page 158
•
“Start PCMCIA” on page 160
•
“ConÞgure Networking” on page 160
initdconfig is used to enable run-level services for initscripts. For more information 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 Applications and Tools” on page 40 for more information about how to update your executable path to easily run this script and how to access man and info pages. The following is the command line help for initdconfig: Usage: initdconfig initdconfig initdconfig initdconfig initdconfig initdconfig
Levels - S 0 1 2 3 4 5 6
--add ... --del ... --list [name ...] [--level ] --help --version
Startup halt Single User Multiuser (No networking) Normal/Multiuser (w/ networking) reserved for local use (same as 3) xdm or equiv graphic login reboot
Note: The levels indicated in the help are guidelines. They are not hard and fast rules.
152
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 similar to this:
mountfs umountnfs.sh urandom ifupdown cron anacron
0:on 0:on
6:on 6:on
S:off S:on 2:off 2:off
3:off 3:off
4:off 4:off
5:off 5:off
In the above example: •
The initscripts, umountfs and umountnfs.sh execute in run levels 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, and 5. 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 ...
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 the command: initdconfig [--level]
For example, if you want cron to only run in levels 3 and 4, use the command: initdconfig --level 34 cron on
MontaVista™ Linux® Professional Edition
153
Chapter 8: System Integration Configuring the User-Space Environment
Disabling an initscript To disable an initscript in all run levels (speciÞed by the initscript) use the --del option, followed by the initscript name. Use the command: initdconfig --del ...
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 the command: initdconfig [--level]
For example, if you want to disable the run levels 3 and 4 for cron, use the command: initdconfig --level 34 cron off
Note: The reset option (in place of on/off) Þrst turns the run levels off and then turns them 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 created by 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.d directory. The symbolic links are named SXXname or KXXname. Here is what each component 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 the initscripts 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 the scripts in /etc/rc.d/rcS.d. Once those scripts have been started, control is returned to sysvinit. When run levels change, /etc/init.d/rc is run with the argument of the new run level. This script is responsible for stopping all of the services beginning with a K at the speciÞed run-level and higher-numbered run levels and starting all of the services beginning with an S at the speciÞed run level and lower-numbered run levels.
154
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 the following 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 by the initdconfig program. Starting run levels may be any combination of S, 0, 1, 2, 3, 4, 5, and 6. The starting run level implies the stopping run level. If you specify S as the starting run level then the stopping run levels are automatically 0 and 6. If you specify 0, 1, 2, 3, 4, 5, or 6 then 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 stop processes. If there are two items with the same start/stop priority there is no guarantee to 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. For example, 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 is never started, but stops in run levels 0 and 6. The /etc/init.d/skeleton example also shows the parameters most initscripts contain: •
start starts the item
•
stop stops the item
•
reload reloads the item if possible (usually by sending a SIGHUP)
MontaVista™ Linux® Professional Edition
155
Chapter 8: System Integration Configuring the User-Space Environment
•
ConÞgure the Target for Serial Console or Virtual Terminal
restart and force-reload should stop and then restart the daemon (force-reload is only implemented if reload is implemented.)
The /etc/inittab Þle on your target is used to conÞgure the target for use with a serial console or virtual terminal. Once the target has been booted, edit the /etc/inittab Þle to reßect the setup you are using (serial console or virtual terminal.) Example Þles are included in the Pro distribution for both virtual terminals (video consoles) and serial consoles. Comments are included in the example Þles to help you determine 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 by adding a “#” at the beginning: con:2345:respawn:/sbin/getty console
3.
Enable the correct console for your system by uncommenting the line for 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 serial port, you need to uncomment one of the following lines (depending on which serial port 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 on ttySA0 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 also wish 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
Chapter 8: System Integration Configuring 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 Runlevel 1 is Runlevels 2-5 Runlevel 6 is
halt. single-user. are multi-user. reboot.
l0:0:wait:/etc/init.d/rc 0 l1:1:wait:/etc/init.d/rc 1 l2:2:wait:/etc/init.d/rc 2 l3:3:wait:/etc/init.d/rc 3 l4:4:wait:/etc/init.d/rc 4 l5:5:wait:/etc/init.d/rc 5 l6: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 start pn::powerfailnow:/etc/init.d/powerfail now po::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: #:::<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
Chapter 8: System Integration Configuring 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 creates device 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 the how 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 the target, 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 following commands: cd /dev ./MAKEDEV fb
To create all of the normal audio device nodes, on the target, enter the following commands: cd /dev ./MAKEDEV audio
Add Shells
shellconfig is used to add shells to the /etc/shells Þle and to set the symbolic 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 Applications and Tools” on page 40 for more information about the how to update your executable path to easily run this script and how to access the man and info pages for this application. The following is the command line help for shellconfig: Usage: shellconfig shellconfig shellconfig shellconfig shellconfig
--add <priority> --del ... --list [name ...] --help --version
If you are using shellconfig as a cross-development application, you need to use the architecture and processor preÞx in the commands in the following sections (<architecture-prefix>-shellconfig).
158
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 similar to the following: Name Priority /bin/ash: 10 /bin/ash.static: 11 /bin/bash: 1 /usr/bin/sash: 50 /bin/sh is linked to /bin/bash.
POSIX Shell (sh) yes yes yes yes
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, and is 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 adding a shell with --add, the Þeld is the full path (as seen by the target) to the shell and then the priority number. For example, to add the shell /bin/something with priority level 5, use the command: shellconfig --add /bin/something 5
Removing a shell You can remove a shell from the conÞguration Þles with the --del option. You may list as many shells on the command line as you want and each of them will be removed from the list. When deleting a shell, the Þeld is the full path (as seen 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
Chapter 8: System Integration Configuring the User-Space Environment
Start PCMCIA
Pro provides pre-built PCMCIA. Check the MontaVista Zone page for your target for information about support for this feature, along with information about the cards tested and enabled with your LSP. Note: If your application requires a type of card not tested or enabled by MontaVista Software, you need to enable the PCMCIA driver in the kernel conÞguration and rebuild the kernel. For more information about rebuilding the kernel, see “Building and ConÞguring the Kernel” on page 76. Once PCMCIA is enabled in the kernel, to start PCMCIA, on the target, enter the following command: /etc/init.d/pcmcia start
The above command loads the card services modules and starts the cardmgr daemon. To start PCMCIA at boot, use the utility initdconfig either on the host or the target. (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 the loopback device by default. An entry for eth0 is not necessary, because the LSPs enable the auto IP option in the kernel. When you are ready to build a stand-alone system for deployment, you may wish to use a different conÞguration. Pro includes Internet Protocol Version 6 (IPv6). The sections below provide information about IPv6, an example to show how to set-up a minimal network using either IPv4 or IPv6, and information about MontaVista Net (a PCI-based back-panel communication product).
IPv6 Internet Protocol Version 6 (IPv6) is the next generation of the internal protocol and is beginning to replace the more standard IPv4. IPv6 adds many improvements over IPv4 in areas such as routing, network autoconÞguration, security, and scalability. The most signiÞcant change is that IPv6 uses 128bit address space (4 times longer than IPv4) allowing for more available addresses. Note: Some IPv6 speciÞcations are NOT supported. For more information, see MontaVista Zone.
Enabling IPv6 IPv6 is enabled as a module by default.
160
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 run on 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 and ConÞ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 will not be served. The following list contains the target utilities included with Pro that can be used with IPv6:
•
apache
•
netkit-rsh
•
atm
•
ping
•
bsd-Þnger
•
proftp
•
inetd
•
radvd
•
iproute
•
sendmail
•
libinet6
•
sysklogd
•
linux-ftpd
•
tcpdump
•
netkit-base
•
tcp-wappers
•
netkit-ftp
•
ucd-snmp
•
netkit-telnet
•
xinetd
•
net-tools
MontaVista™ Linux® Professional Edition
161
Chapter 8: System Integration Configuring 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/Work station would. This example assumes that you have networking enabled in the kernel and that you have loaded the appropriate packages. As an incomplete list, these packages 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:
162
•
/etc/hostname
•
/etc/hosts/
•
/etc/services
•
/etc/inetd.conf
•
/etc/nsswitch.conf
•
/etc/resolv.conf
•
/etc/network/interfaces
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring the User-Space Environment
The above Þles have the following format: /etc/hostname test.mvista.com
/etc/hosts #IPv4 Address 127.0.0.1 192.168.2.202 192.168.2.190
localhost test.mvista.com rootnfs.mvista.com
#IPv6 addresses ::1 3ffe:305:1002:8010::1
localhost.localdomain test rootnfs
ipv6-localhost test.mvista.com
ipv6-loopback test
/etc/nsswitch.conf passwd: files group: files hosts: files networks: files ethers: files protocols:files rpc: files services: files
/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 the hosts: entry in the /etc/nsswitch.conf Þle above. domain mvista.com search mvista.com nameserver 192.168.14.10 nameserver 192.168.14.38
/etc/network/interfaces Use the examples provided in the /etc/network/interfaces Þle to create an entry like the following to set up each Ethernet interface: #IPv4 Addresses auto eth0 iface 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 addresses auto eth0 iface eth0 inet6 static address 3ffe:305:1002:8010::1 netmask 64
MontaVista™ Linux® Professional Edition
163
Chapter 8: System Integration Configuring the User-Space Environment
MontaVista Net MontaVista Net is a PCI-based back-panel communication product. MontaVista Net can be used in one of two ways: •
to off load conventional Ethernet interfaces for transactions between processors in the same chassis
•
as a complete replacement for Ethernet – this option allows Peripheral Processors to boot from ßash and remote mount the root Þle system via NFS, through the MontaVista Net back-panel interface
Instructions for conÞguring and using MontaVista Net can be found on MontaVista Zone.
164
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Testing Your Environment
Testing Your Environment At this stage in your application’s development, you should fully test your application. Because every project is different and has different requirements on the system, how you test your project is up to you. We do, however, recommend that you do incremental tests. By starting with a system that works, when you reduce the Þlesystem size you can more easily determine which libraries and applications are still needed by your application. We also highly recommend doing complete testing before you reduce the size of your Þle system, as in many cases, doing so will remove the symbol information required for proper debugging.
MontaVista™ Linux® Professional Edition
165
Chapter 8: System Integration Reducing 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 reduce the 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 to determine which components of supported shared libraries are required by the included executables and shared libraries. LOT then rebuilds the supported shared libraries so they contain only the required code, which often results in a signiÞcant size reduction. Because LOT removes symbols used for debugging, it is important that you test and debug 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 a shared library to be supported for use with LOT, the library packages containing detailed information about the contents of the library must be installed on the host machine. Currently, two libraries distributed with Pro have the detailed optimization information. They are: •
glibc
•
ncurses
The library packages containing the detailed optimization information for glibc and ncurses were installed by default when you installed Pro.
Usage LOT is a command-line tool. To run LOT, update your executable search PATH to include the Pro applications. Instructions on how to run Pro applications can be found in “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:
166
•
-s Strips the optimized libraries of all debugging information. Libraries or executables in the speciÞed tree that do not have the required optimization information are not stripped.
•
-d <destree> SpeciÞes the base of the Þle hierarchy where the resulting
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Reducing the Size of Your File System
optimized libraries will be placed. This directory must be a directory 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 is required.
We recommend that the target directory be a separate tree that you have built. When using LOT, you should work in a project directory created for building your Þle system. In the section “Project Directories” on page 38, we recommend creating a my_work_directory/myfilesystem directory for your Þle-system development. We also recommended that you NFS-mount the myfilesystem directory on the target for testing. It is assumed in the example below that the myfilesystem directory contains your target Þle system, and that it is NFSmounted as the target’s root Þle system. One good way to build the target directory is to untar the Þle-system tar archive created 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 will be on the target (this includes your applications). We make this recommendation because if a destination tree is not speciÞed, the optimizer writes over the full versions of the libraries. If your <srctree> is in the /opt/hardhat tree, the library packages 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 directory hierarchy to be optimized is my_work_directory/myfilesystem/fs-1. The directory mylib contains the bash shell executable. The directory fs-1/lib contains the libraries for glibc that have the required detailed optimization information and the libraries for myprogram that do not. The directory fs-2 is where 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
Chapter 8: System Integration Reducing the Size of Your File System
168
•
The Þle tree under fs-1 is scanned for executables and shared libraries. Standard library search rules are used, so shared libraries should be located in the same relative directory as they will be on the target.
•
For each shared library that contains the detailed optimization information (glibc in this example), LOT: •
determines which symbols and code are required
•
removes the symbols not required (along with the associated code)
•
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 required optimization information (myprogram and bash shell, in this example) LOT simply determines which symbols are required. These Þles are left in myfs unchanged (that is, not stripped and not copied to fs-2).
•
The same directory structure used in fs-1 is used in fs-2
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Profiling Your Embedded Application
ProÞling Your Embedded Application Once you have completed development of your environment, you should use proÞling tools to evaluate the project performance and to look for memory leaks, etc. Tools such as Linux Trace Toolkit (LTT) and mtrace, among others, are provided with Pro to help with proÞling your application. In addition, other tools that could not be distributed with Pro, such as netperf, are available via MontaVista Zone.
MontaVista™ Linux® Professional Edition
169
Chapter 9: Deployment
Overview Once you have completed development of your embedded project, you will want to disconnect the target from its reliance on the host and create a stand-alone environment 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. Other conÞgurations that have been used involve using Compact Flash, RAW ßash or SCSI conÞgurations. Because on-board ßash and IDE solutions are most common, this manual provides information about deployment in those conÞgurations. When you are ready to create a deployment candidate, you may wish to discuss your deployment strategy with the MontaVista representative assigned to your account. A stand-alone target may appear as in the diagram below: User-Space Configs
Custom Apps Local Root File System
Custom Kernel
.................. ................... Target
MontaVista™ Linux® Professional Edition
171
Chapter 9: Deployment Overview
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 Deployable Root 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. Once completed, you should have a suitable candidate for deployment. Note: Because there are so many differences between the supported targets and embedded projects, these steps are generic. Your target may not follow these steps exactly as listed and you may need to perform additional steps to enable other functionality. For some hints on trouble-shooting, see “Trouble-Shooting Deployment” on page 187.
172
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Configuring 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 and to enable a deployable root Þle system. The kernel supplied by MontaVista Software sends BOOTP queries and NFS mounts the root Þle system. In this conÞguration, the kernel cannot be run as a system that is stand-alone (that is, without a host or network connection). For deployment, you need to rebuild the kernel to be stand-alone. To rebuild the kernel for a stand-alone conÞguration and to enable a deployable Þle system, complete the following steps: 1.
Start make menuconfig or make xconfig. The latter can be run 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 the desired 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 using MTD 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
Chapter 9: Deployment Configuring 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 and you need to use MTD (Memory Technology Device), ensure that MTD has been enabled in the kernel. For targets that support MTD, MTD should be enabled by default in the kernel supplied by MontaVista Software. If you are using a custom kernel or a target for which MontaVista Software does not yet support MTD, 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 embedded system. For more information about the options to select for each of the supported Þ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 are using 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 the module. See the man page for insmod for information about use and syntax. Another option is to use modprobe rather than insmod. See the man page for modprobe for information about use and syntax. 14. Rebuild the kernel, using TCT or the procedure in “Building and ConÞ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 Þle system. This manual only covers creating a root Þle system for your target. Additional conÞguration not included in this manual is required if you intend to use multiple Þle systems and/or have some Þle systems built as modules. Warning! Do NOT boot the new kernel yet! The next step in the deployment process is to transfer your Þle system to the target. The reason we recommend rebuilding the kernel Þrst is that in many cases, you can transfer your kernel to the target system inside of a Þle-system image.
174
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Configuring 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 been enabled: •
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 options under Filesystems is enabled: •
Journaling FLASH Filesystem (JFFS)
EXT2 File System support or EXT3 File System support
To use JFFS or JFFS2, ensure that the following options are enabled: •
MTD. For targets that support MTD, MTD should be enabled by default in the kernel supplied by MontaVista Software. If you are using a custom kernel or a target for which MontaVista Software does not yet support MTD, information about how to enable MTD is 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: JFFS debugging 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 to work. These devices should be included automatically with the target LSPs that support the ßash driver. Ensure that these devices are present. For more information about 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 found or not. Also, after boot-up, the command cat /proc/mtd can be used to see the details 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 have ReiserFS compiled into the kernel (that is, not as a module). ReiserFS can be built as
MontaVista™ Linux® Professional Edition
175
Chapter 9: Deployment Configuring 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 the whole kernel and not just the module! Because interfaces to the Þle system are changing quickly and often, bugs due to recompiling only the module can appear. Such bugs can be cryptic and difÞcult to resolve.
XFS
MTD
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/
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 not yet fully supported. If the board only has one ßash that you want MTD support on and you only need one MTD device and the chip is CFI (Common Flash Interface) compliant, to enable MTD 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 the MontaVista LSP for your board enables MTD/JFFS, use the settings that are already in the conÞg Þle. Otherwise, this information should be available via the board's memory map and other documentation.
Note: “One ßash” means one or more ßash chips linearly mapped into the address space. They can be organized as x8, x16 or x32 wide memory interfaces using one or more 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 a single ßash type, you also need to create a mapping Þle to describe the ßashes and their partitions (devices) on the board. See the “The following is an example of a mapping Þle.” on page 177 for an example.
176
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Configuring 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 #include #include #include #include #include #include #include
#if defined(CONFIG_MIPS_ITE8172) || defined(CONFIG_MIPS_IVR) #include #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
Chapter 9: Deployment Configuring 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 matches your ß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
Chapter 9: Deployment Creating 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 the target. 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 to complete the following steps: 1.
For some conÞgurations, the Þle-system image may contain the kernel image along with the Þle system. Including the kernel in the Þle-system image is typical of systems that boot from an IDE. Separate transfer is more typical of systems that boot from on-board ßash. If your conÞguration needs the kernel included in the Þle-system image, add a copy 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 transfer that image to the target.
CramFS
CramFS is a read-only Þle system, so unlike other Þle systems, it must be created along 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. Host and 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
is the root directory of your Þle system and is the 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 the target. 2.
Make sure your ßash is erased.
MontaVista™ Linux® Professional Edition
179
Chapter 9: Deployment Creating a File-System Image
3.
Assuming you used MTD, copy the CramFS image to your ßash. For example: 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 ßash depends 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 not available. Note: CramFS can be used in conjunction with another type of Þle system. If the CramFS Þle system is not the root Þle system, mount the Þle system on the block device where it will be used. (This method is useful for testing the Þle system.) On the target, 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 are using 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 the command above. 3.
Make sure your ßash is erased.
4.
Assuming you used MTD, copy the JFFS image to your ßash. For example: 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 without putting a Þle system on it. This will let you Þll the device interactively under your shell control (that is, copy stuff to the mounted directory).
180
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Creating a File-System Image
The steps above assume that MTD has been enabled in the kernel. MTD is enabled by default 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 create and populate an EXT2/EXT3 Þle system for deployment, complete the following steps: 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/
is the block device where you wish to create the Þle system such as hda1. The block device can have multiple partitions. For more information about partitions, we recommend reading the man pages for parted and fdisk. The mkfs.ext2 utility, parted, and fdisk are part of the Pro distribution. For more information, see “Running Pro Applications and Tools” on page 40 and “Accessing man and info Pages” on page 44. 2.
Mount the new partition. mount /dev/ /<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 to contain. Make a tar archive of the Þle-system hierarchy that you created during system integration, move the archive to the new location, and untar the archive. For example, to move the Þle system in the NFS-mounted directory my_work_directory/myfilesystem to the new location, on the target, 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
Chapter 9: Deployment Creating a File-System Image
If desired, convert the EXT2 Þle system to an EXT3 Þle system. To convert your EXT2 Þle system to EXT3, you need to use the tune2fs utility to add a journal to your existing EXT2 Þle system. To add journaling to an EXT2 Þle system created on the 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 matching lines.
Note: To prevent the Þle system from being mounted as EXT2, you need to use initrd to boot the target.
ReiserFS
Assuming you are using an IDE device to store your kernel and Þle system, to create and 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/
is the block device where you wish to create the Þle system, such as hda1. You can have multiple partitions. For more information about partitions, we recommend reading the man pages for parted and fdisk. The mkreiserfs utility, parted, and fdisk are part of the Pro distribution. For more information, see “Running Pro Applications and Tools” on page 40 and “Accessing man and info Pages” on page 44. 2.
Mount the new Þle system. Use the following command: mount /dev/ /<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.
182
Populate your target’s Þle system with everything that you want it to contain. Make a tar archive of the Þle-system hierarchy that you created during system integration, move the archive to the new location, and untar the archive.
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Creating a File-System Image
For example, to move the Þle system in the NFS-mounted directory my_work_directory/myfilesystem to the new location, on the target, 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 a ReiserFS Þle system as the root Þle system.
XFS
Assuming you are using an IDE device to store your kernel and Þle system, to create and 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/
is the block device where you wish to create the Þle system, such as hda1. After you build a partition that is the same size as the XFS Þle system you want to create, you can use the above command to create a Þle system on it. For more information about partitions, we recommend reading the man pages for parted and fdisk. 2.
Mount the new Þle system. Use the following command: mount /dev/ /<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 to contain. Make a tar archive of the Þle system hierarchy that you created during system integration, move the archive to the new location, and untar the archive.
MontaVista™ Linux® Professional Edition
183
Chapter 9: Deployment Creating a File-System Image
For example, to move the Þle system in the NFS-mounted directory my_work_directory/myfilesystem to the new location, on the target, 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
Chapter 9: Deployment Setting 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 edit this Þle to ensure that the Þle systems you are using are available. You also need to edit 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. #/etc/fstab #device #
directory
/dev/hda6 /dev/hda1 proc /dev/hda5
Sample 2
type
/ /boot /proc swap
ext3 ext3 proc swap
options defaults defaults defaults defaults
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 # /dev/md1 /dev/md0 proc
directory
type
options
/ /boot /proc
ext3 ext3 proc
defaults,errors=remount-ro defaults,errors=remount-ro defaults
dump pass 0 0 0 0 0 0
MontaVista™ Linux® Professional Edition
185
Chapter 9: Deployment Booting 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 vendor documentation for more information about using the board’s Þrmware or for information about hardware conÞgurations. If you have additional questions about how to conÞgure and boot a particular target for deployment, contact your MontaVista representative. Booting the target, usually consists of the following steps: 1.
Hardware setup. Hardware setup may include changing DIP switches or shorting jumpers to permit the board to boot from ßash. Hardware changes are target speciÞc.
2.
Minicom (or other terminal emulation program) conÞguration. You need to use Minicom to communicate with your target. You should use the same communication parameters that you used during development.
3.
Target conÞguration. The Þrmware on the target may need to be conÞgured for booting from ßash or booting from an IDE. The commands are Þrmware speciÞc.
4.
If the kernel was not included in the Þle-system image, transfer the kernel to a storage device on the target. Typically, this is a ßash device or an IDE. The commands for transferring the kernel are Þrmware speciÞc.
5.
Booting the target. To boot the target, the Þrmware often requires a command to begin the boot sequence. The commands are Þrmware speciÞc.
You should now have a system that is a suitable candidate for deployment. If your target 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-Shooting Deployment” on page 187.
186
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Trouble-Shooting Deployment
Trouble-Shooting Deployment Corrupt File System
If you would like to check the integrity of your Þle system, use one of the following commands: For an EXT2/EXT3 Þle system, use the fsck utility. Run the following command: fsck /dev/
For a ReiserFS Þle system, use the resierfsck utility. Run the following command: resierfsck /dev/
MontaVista™ Linux® Professional Edition
187
Appendix A: Pro File-System Layout
Overview There are two main components to the Þle-system layout used for Pro: the crossdevelopment environment layout and the target layout. The cross-development environment file-system layout was created with several goals in mind: Pro components must be self-contained, traditional RTOS cross-development layout is needed, 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
Appendix A: Pro File-System Layout Base Directories
Base Directories All of the Þles that make up the Pro cross-development environment are located inside of a single hardhat directory. This directory, by default, resides in the /opt directory on the host machine’s Þle system. Contents of Base Directories /opt /hardhat
Description Default installation directory. Pro is fully contained in this directory. By default, the /hardhat directory is installed within the /opt directory.
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 to replace /opt in all path names in this manual with the directory that you used.
190
MontaVista™ Linux® Professional Edition
Appendix A: Pro File-System Layout /hardhat Directory
/hardhat Directory The hardhat directory contains two directories that are used to segment the crossdevelopment tools into two categories: cross tools and host tools. Contents of /hardhat Directory
Description
/devkit
Contains cross tools and Linux kernel source code.
/host
Contains host tools.
More information about the tools included can be found in “Pro Applications” on page 197.
MontaVista™ Linux® Professional Edition
191
Appendix A: Pro File-System Layout /devkit Directory
/devkit Directory The /devkit directory contains one directory for each installed architecture family, a /kernel directory and an /lsp directory. Contents of /devkit Directory
Description
/kernel
Generic Linux kernel source code and related items.
/lsp
Board speciÞc Linux kernel source code and related items.
/arm, /mips, /ppc, /sh, /x86, etc.
Architecture family directories.
/kernel Directory
The /kernel directory contains one or more versions of the MontaVista Software uniÞed kernel. The kernel source located in this directory is generic and not speciÞc to any target board. The directory may also contain related items, such as functionality patches. This kernel is for reference only. We strongly recommend that you use the kernel located in the /lsp directory that was created speciÞcally for your reference board.
/lsp Directory
The /lsp directory contains directories for each reference board LSP installed. The board directory contains a conÞgured Linux kernel source for that board. The board directory may also contain board-speciÞc patches, bootloader source code, documentation and control Þles. An example of the /lsp layout for the embeddedplanet-ep8260-ppc_82xx LSP is given below: Sample Contents of an /lsp Directory /embeddedplanet-ep8260-ppc_82xx
Architecture Family Directories
192
Description LSP directory name. In this case, the LSP directory name is for the Embedded Planet EP8260 target board.
/desc
Target ConÞguration Tool (TCT) conÞguration Þle.
/linux-2.4.17_
ConÞgured Linux kernel source.
/README
LSP readme Þle.
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 the processor types for each architecture family. The various architecture family directories are used to group all of the processor-speciÞc cross-development tools and associated target Þles.
MontaVista™ Linux® Professional Edition
Appendix A: Pro File-System Layout /devkit Directory
An example of the ppc architecture family is given below: Sample Contents of an Architecture Family Directory
Description
/devkit
By default, the architecture family directory is installed in the /devkit directory.
/ppc
Architecture family directory name. In this case, the architecture family name is for the PowerPC processor type.
/405, /7xx, /74xx, /8xx, /82xx
Processor directory names.
Some architecture families, such as the MIPS architecture, use a different naming scheme:
Sample Contents of the MIPS Architecture Family Directory /devkit
Description By default, the architecture family directory is installed in the /devkit directory.
/mips
Architecture family directory name. In this case, the architecture family name is for the MIPS processor type.
/fp_be /nfp_be, /fp_le, /nfp_le
Processor directory names.
When the processor version does not adequately describe a given architecture, the architecture is listed by floating point and endian. The architecture and processor directories contain the cross-development tools. These tools are run on the host and are tailored to a specific target. The structure of the <processor> directory is listed below: Processor Directory Structure
Description
<architecture>
The architecture family directory. By default, the <processor> directory is installed in the architecture family directory.
<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
Appendix A: Pro File-System Layout /devkit Directory
Processor Directory Structure
Description
/lib
Host libraries.
/man
man pages.
/share
Program data Þles.
/var
Program data Þles.
<architecturecanonical-name> /target
Used by GNU tools.
Full target Þle system, build/run-time libraries, etc. This directory can be NFS-mounted on the target.
/bin Directory
The /bin directory contains the various cross-development tools. These tools include the cross-compiler, assemblers, debuggers, etc. It may also include target configuration tools, and other target-specific items.
/etc Directory
The /etc directory contains user-changeable 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 /home directory first, and then in the /etc directory.
/include and /lib Directories
Both the /include and /lib directories contain Þles used to develop additional cross-development tools. The Þles in these directories are designed to build software for the host architecture.
/doc, /info, and /man Directories
The /doc, /info and /man directories contain various pieces of documentation for the cross-development tools. The /info and /man directories contain GNU information and Linux manual pages, respectively. The /doc directory contains pieces of documentation that cover the entire package that was installed. This documentation includes license information, notes, FAQs, and other pieces of documentation taken from a package’s source code.
/share and /var Directories
The /share and /var directories are analogous to the /usr/share and /var directories in a standard Linux Þle system. These may be used for internationalization and other data Þles required by a cross-development tool.
194
MontaVista™ Linux® Professional Edition
Appendix A: Pro File-System Layout /host Directory
/host Directory The /host directory contains various tools and applications that are to be run on the host system and are target independent. While these tools are target independent, they are required to assist in software development. This directory contains several subdirectories: Contents of the /host Directory /host
Description 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.
The structure and purpose of these directories is similar to the cross-development tools listed above.
/bin Directory
The /bin directory contains the host tools. Programs in these directories aid in generic system development. These tools may include programs to augment a host’s environment.
/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 home directory first, and then in the /etc directory.
/include and /lib Directories
Both the /include and /lib directories contain Þles used to develop additional host tools. The Þles in these directories are designed to build software for the host architecture.
/doc, /info, and /man Directories
The /doc, /info and /man directories contain various pieces of documentation for the cross-development tools. The /info and /man directories contain GNU information and Linux manual pages, respectively. The /doc directory contains pieces of documentation that cover the entire package that was installed. This documentation includes license information, notes, FAQs, and other pieces of documentation taken from a package’s source code.
MontaVista™ Linux® Professional Edition
195
Appendix A: Pro File-System Layout /host Directory
/share and /var Directories
196
The /share and /var directories are analogous to the /usr/share and /var directories in a standard Linux Þle system. These may be used for internationalization, and for other data Þles required by a cross-development tool.
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications
Overview Pro includes over 280 application packages. Applications are classiÞed as “crossdevelopment applications,” “host applications,” or “target applications.” Cross-development applications are tools that are run on the host but produce output intended to run on the target. In general, the cross-development applications are compilers, 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 compatible version of TFTP. For the list of host applications, see “Host Application Packages” on page 200. Target applications are intended to be used only on the corresponding architecture target. The Pro distribution contains pre-compiled and pre-packaged versions of these application packages so that RPM can be used to install them on the target. For development, 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 therefore contains 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 of target applications, see “Target Application Packages” on page 204. Note: man and/or info pages are available for many of the applications included. man pages for target applications are not available when using a Solaris host. For more information about using man and info pages, see “Accessing man and info Pages” on page 44.
MontaVista™ Linux® Professional Edition
197
Appendix B: Pro Applications Cross-Development Application Packages
Cross-Development Application Packages The chart below lists the cross-development applications included in the Pro distribution, along with some notes about the applications. Applications are installed by default unless marked as optional in the “Notes” column. Optional applications can 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 (other than our own) listed in this section. Examples are provided for your convenience only. Application Package binutils
Version 2.11.2
Notes Installed: Default Description: Cross version of binutils.
Reference Books and Web Sites http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
bootldr-assabet
2.13.2
Installed: Default for StrongARM targets Description: Bootloader for the Intel® Assabet target.
cross-<architectureprefix>-libtool
1.3.5
Installed: Default Description: Cross version of libtool for a given target architecture. Provides the utility libtoolize. If you are building an open-source package using libtool, you need to run the libtoolize utility in this package before building the application 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 given target architecture.
Using and Porting the Gnu Compiler Collection Gcc Richard Stallman iUniverse.com ISBN: 059510035X
Version change from the Pro 2.1 distribution http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 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
Appendix B: Pro Applications Cross-Development Application Packages
Application Package gdb
Version 5.1
Notes Installed: Default Description: Cross version of gdb for a given target architecture.
Reference Books and Web Sites Debugging with GDB: The GNU Source-Level Debugger Richard M. Stallman, Roland H. Pesch Universe.com ISBN: 0595149197 http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 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 given target architecture.
hardhatutils
1.14
Installed: Default
ksymoops
2.4.3
Installed: Default
ldd
1.0
Description: Various utilities.
Description: Kernel crash dump analyzer. Installed: Default Description: Cross version of ldd for a given target architecture. linux86
0.15.4
Installed: Default (x86 only) Description: Real-mode linker and assembler for x86.
MontaVista™ Linux® Professional Edition
199
Appendix B: Pro Applications Host Application Packages
Host Application Packages The chart below lists the host applications included in the Pro distribution along with some notes about the applications. Applications are installed by default unless marked as optional in the “Notes” column. Optional applications can 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 (other than our own) listed in this section. Examples are provided for your convenience only. Application Package autoconf
Version 2.13
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: Creates scripts to conÞgure source code packages using templates.
automake
1.4p4
Installed: Solaris hosts only Description: Automatically creates makeÞle.in’s from makeÞle.am’s.
bash
2.05a
binutils
2.10.91.0.2
Installed: Solaris hosts only Description: Bourne-Again shell Installed: Solaris hosts only Description: Solaris version of binutils.
http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
bison
1.28
Installed: Solaris hosts only Description: GNU Project parser generator (yacc replacement)
bzip2
1.0.2
cetools
0.3
Installed: Solaris hosts only Description: A block-sorting Þle compressor Installed: Default Description: Set of tools used to convert Microsoft® bootable binary images
db
3.2.9
ddd
3.3.1
Installed: Solaris hosts only Description: Database access methods Installed: Default Description: Data Display Debugger – a graphical front end to GDB
ethload
1.2
Installed: Default Description: Used to load a Microsoft® bootable binary image via the bootme protocol
filesystem
2.0
Installed: Default Description: Host-based Þle-system development kit
fileutils
4.1
Installed: Solaris hosts only Description: File utilities
200
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications Host Application Packages
Application Package
Version
findutils
4.1.7
flex
2.5.4
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: Find utilities Installed: Solaris hosts only Description: A a tool for generating programs that perform pattern-matching on text
gawk
3.1.0
Installed: Solaris hosts only Description: The GNU Project's implementation of the AWK programming language
gcc
2.95.3
Installed: Solaris hosts only Description: Solaris version of gcc
Using and Porting the Gnu Compiler Collection Gcc Richard Stallman iUniverse.com ISBN: 059510035X http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
gettext
0.10.35
grep
2.4.2
Installed: Solaris hosts only Description: GNU internationalization utilities Installed: Solaris hosts only Description: Used to print lines matching a pattern
gzip
1.2.4
hardhatutils
1.14
Installed: Solaris hosts only Description: Used to compress or expand Þles Installed: Default Description: Miscellaneous utilities used by Pro applications
jflash-assabet
1.2
kdelibs
2.2.1
kdevelop
2.0.1
Installed: Default Description: Flash tool for the Intel® Assabet Installed: Default Description: KDE library used by KDevelop Installed: Default Description: C and C++ integrated development environment
ldd
1.0
Installed: Default Description: Prints the shared libraries required by each program speciÞed on the command line
lesstif
0.92.6
Installed: Default Description: motif-like library required for ddd
libtool
1.3.5
ltt
0.9.5a
Installed: Solaris hosts only Description: Generic library support script Installed: Default Description: Linux Trace Toolkit Version change from the Pro 2.1 distribution
The LTT Reference manual is distributed with the LTT package and once installed, can be found in /opt/hardhat/ host/doc/hll-host-ltt-0.9.5a/ index.html.
MontaVista™ Linux® Professional Edition
201
Appendix B: Pro Applications Host Application Packages
Application Package
Version
m4
1.4
make
3.79.1
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: The GNU macro processor Installed: Solaris hosts only Description: GNU make utility to maintain groups of programs
http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
minicom
1.83.0
mkcramfs
2.4.16
Installed: Solaris hosts only Description: Host-to-target communication tool. Installed: Default Description: Used to make a cramfs Þle-system image
modutils
2.4.13
ncurses
5.2
Installed: Solaris hosts only Description: Linux module utilities Installed: Solaris hosts only Description: The ncurses library routines give the user a terminal-independent method of updating character screens with reasonable optimization
patch
2.5.4
Installed: Solaris hosts only Description: Used to apply a diff Þle to an original
pcmcia-cs
3.1.30
perl
5.6.1
Installed: Default Description: PCMCIA card services Installed: Solaris hosts only Description: Practical Extraction and Report Language
platformtest
0.1.2
Installed: Default Description: ConÞguration utilities and scripts for compiling Pro sources
python
2.0
qt
2.3.1
Installed: Solaris hosts only Description: Required for TCT 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 that can 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 scripts for compiling Pro sources
sed
3.02
shellutils
2.0.11
Installed: Solaris hosts only Description: A stream editor Installed: Solaris hosts only Description: Various shell utilities
202
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications Host Application Packages
Application Package tar
Version 1.13.19
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: The GNU version of the tar archiving utility
tcl
8.3.2
texinfo
4.0b
tftp-hpa
0.17 and 0.31
Installed: Solaris hosts only Description: Tcl scripting language Installed: Solaris hosts only Description: GNU Documentation system 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
tsload
1.0.0
zlib
1.1.3
Installed: Solaris hosts only Description: TK scripting language Installed: Default Description: Bootloader for various targets Installed: Solaris hosts only Description: A compression and decompression library
zsrec
1.0
Installed: Default Description: Needed S-Records format
to
produce
Motorola
MontaVista™ Linux® Professional Edition
203
Appendix B: Pro Applications Target Application Packages
Target Application Packages The chart below lists the target applications included in the Pro distribution along with some notes about the applications. Applications are installed by default unless marked as optional in the “Notes” column. Optional applications can 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 (other than our own) listed in this section. Examples are provided for your convenience only. Application Package adduser
Version 3.24
Notes
Reference Books and Web Sites
Installed: Default Description: Allows users to be added to group or password Þles
anacron
2.3
Installed: Default Description: A cron-like program that can run jobs lost during downtime Requires cron
apache
1.3.20
Installed: Default Description: The most widely used Web server on the Internet
ash
0.3.8
Apache: The DeÞnitive Guide Ben Laurie, Peter Laurie, Robert Denn (Editor) O'Reilly & Associates ISBN: 1565925289
Installed: Default Description: A smaller version of the Bourne shell (sh). Functionality of interest: sh, ash.static
at
3.1.8
aumix
2.7
autoconf
2.13
Installed: Default Description: Job spooling tools Installed: Default Description: Sound utility Installed: Default Description: A GNU tool for automatically conÞguring source code
autofs
3.1.7
GNU Autoconf, Automake, and Libtool Gary V. Vaughan, Ben Elliston, Tom Tromey, Ian Lance Taylor New Riders Publishing ISBN: 1578701902
Installed: Default Description: A tool for automatically mounting and unmounting Þle systems
automake
1.4p4
Installed: Default Description: A GNU tool for automatically creating makeÞles
base-files
2.1.PRO
base-passwd
3.2.0
Installed: Default Description: Contents of /etc directory Installed: Default Description: Default password and group Þle
204
MontaVista™ Linux® Professional Edition
GNU Autoconf, Automake, and Libtool Gary V. Vaughan, Ben Elliston, Tom Tromey, Ian Lance Taylor New Riders Publishing ISBN: 1578701902
Appendix B: Pro Applications Target Application Packages
Application Package bash
Version 2.05a
Notes
Reference Books and Web Sites
Installed: Default Description: A GNU Bourne Again shell (bash)
bind
9.1.3
Installed: Default Description: A DNS (Domain Name System) server
bind
1.28
Advanced Bash-Scripting Guide Mendel Cooper http://linuxdoc.org/LDP/abs/ html/index.html DNS and BIND (4th Edition) Paul Albitz, Cricket Liu O'Reilly & Associates ISBN: 0596001584
Installed: Default Description: The most widely used DNS server on 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 GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995;however it does contain a good introduction to GNU programming.
bison
1.28
Installed: Default Description: A GNU general-purpose parser generator
bonnie++
1.92
Installed: Default Description: Hard disk bench marking suite Minor revision update from HHL 2.0
bootldr-assabet
2.13.2
bridge-utils
0.9.3
Installed: Default Description: Bootloader for the Intel® Assabet Installed: Default Description: Utilities to conÞgure the Linux networking bridge interface
bsd-finger
0.17
busybox
0.60.2
Installed: Default Description: Finger client and server Installed: default Description: Multi-call replacing mount, etc.
binary
capable
of
Because this package is a multi-call binary, calling it via a different name changes the functionality. For example, “ln -s busybox ls; ls” will call busybox with the name ls and cause busybox to “act” like ls. To automatically activate the links, use TCT to create your Þle system. bzip2
1.0.2
checker
0.9.9.1
Installed: Default Description: A Þle-compression utility Installed: Default - IA-32/x86 only Description: GNU version of a Purify (memory leak checker) tool
console-data
1999.08.29
Installed: Default
console-tools
0.2.3
Installed: Default
Description: VGA console fonts
Description: Tools for conÞguring the console
MontaVista™ Linux® Professional Edition
205
Appendix B: Pro Applications Target Application Packages
Application Package
Version
cpio
2.4.2
cprof
1.0.1
cproto
4.6d
Notes
Reference Books and Web Sites
Installed: Default Description: A GNU archiving program Installed: Default – IA-32/x86 only Description: Thread-safe proÞler Installed: Default Description: Generates function prototypes and variable declarations from C code
cracklib
2.7
Installed: Default Description: processing
cron
3.0p11
Library
needed
for
password
Installed: Default Description: Manages system resources and launch events/tasks
db
3.2.9
devfsd
1.3.11
Installed: Default Description: Berkeley db Installed: Default Description: Dynamic dev directory daemon. It automatically 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
dhcpcd
1.3.19p|5
Installed: Default Description: A DHCP client
diff
2.7
Installed: Default Description: Creates source patches. Includes
cmp dmalloc
4.8.2
dnrd
2.1.0
dump
0.4b23
e2fsprogs
1.22
Installed: Default Description: Debug memory allocation utility Installed: Default Description: Domain name relay daemon Installed: Default Description: File-system backup and restore Installed: Default Description: Programs for backing up and restoring Þle systems
ed
0.2
editline
1.12
Installed: Default Description: A line-oriented text editor Installed: Default Description: A BSD licensed for the “readline” functionality
206
MontaVista™ Linux® Professional Edition
The DHCP Handbook: Understanding, Deploying, and Managing Automated ConÞguration Services Ted Lemon, Ralph E. Droms Pearson Higher Education ISBN: 1578701376 The DHCP Handbook: Understanding, Deploying, and Managing Automated ConÞguration Services Ted Lemon, Ralph E. Droms Pearson Higher Education ISBN: 1578701376
Appendix B: Pro Applications Target Application Packages
Application Package eject
Version 2.0.2
Notes
Reference Books and Web Sites
Installed: Default Description: A program that ejects removable media using software control
exim
3.34
Installed: Default Description: Local mail handler Required by cron
expect
5.32.2
Installed: Default Description: A program that “talks” to other interactive programs based on a script
fbgetty
0.1.4
Installed: Default Description: Framebuffer getty program for simple graphical environments.
fbset
2.1
Installed: Default Description: Tools for managing a framebuffer's video mode properties
file
3.33
filesystem
2.0
Installed: Default Description: A utility for determining Þle types Installed: Default Description: The basic directory layout for a Linux system
fileutils
4.1
Installed: Default Description: The GNU versions of common Þlemanagement utilities Functionality 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 (text pattern recognizers)
gawk
3.1.0
Installed: Default Description: The GNU version of the awk text processing utility
gbdm
1.7.3
GAWK: The GNU AWK User's Guide Arnold Robbins Free Software Foundation ISBN: 1882114272
Installed: Default Description: A GNU set of database routines which use extensible hashing
gcc
3.2.1
Installed: Default Description: Various compilers Objective-C, Chill, etc.)
(C,
C++,
Using and Porting the Gnu Compiler Collection Gcc Richard Stallman iUniverse.com ISBN: 059510035X
Version change from the Pro 2.1 distribution http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995;however it does contain a good introduction to GNU programming.
MontaVista™ Linux® Professional Edition
207
Appendix B: Pro Applications Target Application Packages
Application Package gdb
Version 5.1
Notes Installed: Default Description: A GNU source-level debugger for C, C++ and Fortran
Reference Books and Web Sites Debugging with GDB: The GNU Source-Level Debugger Richard M. Stallman, Roland H. Pesch Universe.com ISBN: 0595149197 http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 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 Þle systems
gettext
0.10.35
Installed: Default Description: GNU libraries and utilities for producing multi-lingual messages
glib
1.2.10
glibc
2.2.5
Installed: Default Description: A library of handy utility functions. Installed: Default Description: The GNU libc libraries Functionality of interest: ldd, ldconfig Version change from the Pro 2.1 distribution
gpm
1.19.6
Installed: Default Description: A mouse server for the Linux console
grep
2.4.2
Installed: Default Description: The GNU versions of grep pattern matching utilities
groff
1.17.2
gzip
1.2.4
Installed: Default Description: A document formatting system Installed: Default Description: The GNU data compression program Functionality of interest: gzip, gunzip, zcat
hardhatutils
1.14
Installed: Default Description: Contains various utilities for administrating a machine, for example initdconfig and shellconfig The package hardhatutils-which is optional. The package name is hhl<architecture>_<processor>hardhatutils-which
hdparm
3.9a
Installed: Default Description: A utility for displaying and/or setting hard disk parameters
hostname
2.09
Installed: Default Description: Sets system host name Required by initscripts
208
MontaVista™ Linux® Professional Edition
Grep: Searching for a Pattern Alain Magloire iUniverse.com ISBN: 0595100392
Appendix B: Pro Applications Target Application Packages
Application Package
Version
ifupdown
0.6.4
ilmtk
0.2
ipgrab
0.8.2
Notes
Reference Books and Web Sites
Installed: Default Description: Enables/disables network interfaces Installed: Default Description: Interrupt Latency Toolkit Installed: Default Description: Network debugging tool similar to tcpdump
iproute
2.2.4
Installed: Default Description: Enhanced IP routing and network device conÞguration tools
iptables
1.2.2
Installed: Default Description: Used to set up kernel packet Þltering rules Revision update from HHL 2.0
jed
B0.99.12
Installed: Default Description: A fast, compact editor based on the S-Lang screen library The package jed-rgrep is optional. The package name is hhl-<architecture>_<processor>-jed-rgrep
kernel
Installed: Default Description: The Linux kernel (the core of the Linux 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 the kernel)
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.1e style “capabilities”
libelf
0.7.0
Installed: Default
libjpeg
6b
Installed: Default Description: A library for manipulating JPEG image 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 manipulating PNG image format Þles
for
MontaVista™ Linux® Professional Edition
209
Appendix B: Pro Applications Target Application Packages
Application Package libtiff
Version 3.4
Notes Installed: Default Description: A library of functions manipulating TIFF image format Þles
libtool
1.3.5
Reference Books and Web Sites for
Installed: Default Description: The GNU libtool, which simpliÞes the use of shared libraries If you are building an open-source package using libtool, you need to run the command: <architecture-prefix>_libtoolize --force --copy before building the application to ensure that the proper libtool control Þles are used.
libungif
4.1.0b1
Installed: Default Description: A library for manipulating GIF format image Þles
libwww
5.2.8
lilo
22.1
Installed: Default Description: HTTP library of common code Installed: Default - IA-32/x86 only Description: The boot loader for Linux and other operating systems
linux-ftpd
0.17
Installed: Default
linux86
0.15.4
Installed: Default – IA-32/x86 only
Description: Version of ftp
Description: Required to build and run lilo – real-mode tools linuxinfo
1.1.7
lm_sensors
2.5.4-p10
logrotate
3.5.7
Installed: Default Description: Displays basic system information Installed: Default Description: Hardware monitoring tools Installed: Default Description: Rotates, compresses, removes and mails system log Þles
lpr
0.50
lprng
3.7.4
Installed: Default Description: Print utility 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 a Linux/UNIX system
ltrace
0.3.10
Installed: Default Description: Tracks runtime library calls from dynamically linked executables This application is NOT available on MIPS nor SuperH targets.
210
MontaVista™ Linux® Professional Edition
GNU Autoconf, Automake, and Libtool Gary V. Vaughan, Ben Elliston, Tom Tromey, Ian Lance Taylor New Riders Publishing ISBN: 1578701902
Appendix B: Pro Applications Target Application Packages
Application Package ltt
Version 0.9.5a
Notes
Reference Books and Web Sites
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 cursoraddressable, character-cell display devices
m4
1.4
mailx
8.1.2
Installed: Default Description: The GNU macro processor Installed: Default Description: The /bin/mail program for sending e-mail messages
make
3.79.1
Installed: Default Description: A GNU tool which simpliÞes the build process for users
http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
makedev
2.3.1
Installed: Default Description: A program used for creating the device Þles in /dev
man-db
2.3.19
man-pages
1.38
memstat
0.2
mgetty
1.1.26
Installed: Default Description: man program Installed: Default Description: man page contents Installed: Default Description: Utility to query free memory Installed: Default Description: A getty replacement for use with data and fax modems
mingetty
0.9.4
Installed: Default Description: A compact getty program for virtual consoles only
minicom
1.83.0
Installed: Default Description: A text-based modem control and terminal emulation program
mkcramfs
2.4.16
Installed: Default Description: Used to make CRAMFS Þle-system images
modutils
2.4.13
Installed: Default Description: Linux module utilities such as modprob and insmod
mtd-utils
2.4.16_1.16
nana
2.5
Installed: Default Description: Utilities for MTD Installed: Default Description: Debugging library
MontaVista™ Linux® Professional Edition
211
Appendix B: Pro Applications Target Application Packages
Application Package
Version
nano
1.0.3
ncurses
5.2
Notes
Reference Books and Web Sites
Installed: Default Description: Pico editor replacement Installed: Default Description: termcap
net-tools
1.60
Replaces
libtermcap
and
Installed: Default Description: The basic tools for setting up networking, such as route and ifconfig
netbase
4.06
Installed: Default Description: Provides network infrastructure control Þles
netkit-base
0.10
Installed: Default Description: Network utilities Functionality of interest: inetd, ping
netkit-ftp
0.17
netkit-ntalk
0.17
netkit-routed
0.17
Installed: Default Description: FTP client - minimal functionality Installed: Default Description: Talk utility Installed: Default Description: Route daemon that feeds routes into kernel
netkit-rsh
0.17
Installed: Default Description: Remote shell. Needed for remote access
netkit-rusers
0.11
Installed: Default
netkit-rwall
0.17
Installed: Default
Description: User daemons for remote who, etc.
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
nfs-user-server
2.2beta47
Installed: Default
nfs-utils
0.3.2
Description: Telnet client and daemon
Description: User space NFS servers Installed: Default Description: NFS utilities and daemons for the kernel NFS server
supporting
The package nfs-kernel-server is optional. The package name is hhl-<architecture>_<processor>-jnfs-kernelserver nis
3.9
Installed: Default Description: Network information server items such as ypbind
212
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications Target Application Packages
Application Package ntp
Version 4.0.99g
Notes
Reference Books and Web Sites
Installed: Default Description: Synchronizes system time using the Network Time Protocol (NTP)
nvi
1.79
Installed: Default Description: Small embedded vi – useful for demonstrating embedded target functionality
openssh
3.0.2p1
Installed: Default Description: OpenSSH free Secure Shell (SSH) implementation
openssl
0.9.6c
Installed: Default Description: Secure Sockets Layer Toolkit
p2linux
0.2
pam
0.72
Installed: Default
SSH, the Secure Shell: The DeÞnitive Guide Daniel J. Barrett, Richard Silverman O'Reilly & Associates ISBN: 0596000111 SSL & TLS Essentials: Securing the Web Stephen A. Thomas John Wiley & Sons ISBN: 0471383546 http://support.mvista.com/ content/AppInfo/
Description: Wind River pSOS® to Linux tool kit Installed: Default Description: A security tool which provides authentication 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, for modifying and upgrading Þles
pciutils
2.1.8
pcmcia-cs
3.1.30
perl
5.6.1
Installed: Default Description: Linux PCI utilities Installed: Default Description: PCMCIA Daemon Installed: Default Description: The Perl programming language
pidentd
3.0.12
Programming Perl (3rd Edition) Larry Wall, Tom Christiansen and Jon Orwant O'Reilly & Associates ISBN: 0596000278
Installed: Default Description: An implementation of the RFC1413 identiÞcation server
portmap
5beta
Installed: Default Description: A program which manages RPC connections
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 processing program
MontaVista™ Linux® Professional Edition
213
Appendix B: Pro Applications Target Application Packages
Application Package procps
Version 2.0.7
Notes
Reference Books and Web Sites
Installed: Default Description: Utilities for monitoring your system and the processes on your system Functionality of interest: top, free, ps
psmisc
20.1
Installed: Default Description: Utilities for managing processes on your system
pump
0.8.3
Installed: Optional Package Name: hhl-<architecture><processor>-pump Description: A BOOTP and DHCP client for automatic IP conÞguration
pxelinux
1.62
python
2.0
Installed: Default Description: Used to facilitate a PXE boot Installed: Default Description: An interpreted, interactive objectoriented programming language
Programming Python Edition) Mark Lutz O'Reilly & Associates ISBN: 0596000855
Required for using TCT quota
2.00
Installed: Default Description: System administration tools for monitoring users' disk usage
rarpd
98.11.07
rdate
1.3.0
Installed: Default Description: The RARP daemon Installed: Default Description: Tool for getting the date/time from another machine on your network
readline4
4.1
Installed: Default Description: Library for standard line input manipulation. Required by bash
reiserfsprogs
3.x.1b
rp-pppoe
3.3
Installed: Default Description: Reiserfs utilities Installed: Optional Description: PPP on Ethernet Package name: hhl-<architecture>_<processor>-rp-pppoe
rpm
4.0
Installed: Default Description: Customized Red Hat Package Manager
rstatd
3.03
rsync
2.3.2
Installed: Default Description: Kernel stats daemon Installed: Default Description: A program for synchronizing Þles over a network
rtsched-utils
0.1
Installed: Default Description: Real-Time Scheduler utilities
214
MontaVista™ Linux® Professional Edition
Maximum RPM (RPM) Ed Bailey Sams ISBN: 0672311054
(2nd
Appendix B: Pro Applications Target Application Packages
Application Package samba
Version 2.2.1a
Notes Installed: Default Description: A collection of programs that implements the Server Message Block (commonly abbreviated as SMB) protocol for UNIX systems
sash
3.4
Reference Books and Web Sites Using Samba (O'Reilly System Administration) Robert Eckstein, David Collier-Brown O'Reilly & Associates ISBN: 1565924495
Installed: Default Description: A statically linked shell, including some built-in basic commands
sed
3.02
sendmail
8.11.6
Installed: Default Description: A GNU stream text editor Installed: Optional Description: A widely used Mail Transport Agent (MTA). MontaVista Software does not provide a default conÞguration Þle
Sendmail Bryan Costales, Eric Allman O'Reilly & Associates ISBN: 1565922220
Package Name: hhl-<architecture><processor>-sendmail setserial
2.17
shadow
20000902
shellutils
2.0.11
Installed: Default Description: A utility for conÞguring serial ports Installed: Default Description: Shadow password utilities Installed: Default Description: Set of POSIX scripts for shell functionality Functionality of interest: FALSE, TRUE, pwd, sleep, uname Includes date The package shellutils-hostname is optional. The package name is hhl-<architecture>_<processor>-shellutilshostname
slang
1.4.4
Installed: Default Description: Multi-platform programmer’s library
socket
1.1
Installed: Default Description: Creates an endpoint for communication and returns a descriptor
squid
2.4.6
Installed: Default Description: Internet Object Cache a.k.a Web Proxy
stat
2.5
Installed: Default Description: A tool for Þnding out information about a speciÞed Þle
strace
4.3
Installed: Default Description: Tracks and displays system calls associated with a running process
sudo
1.6.5pl
Installed: Default Description: Allows restricted root access for speciÞed users
sysklogd
1.3.31
Installed: Default Description: System logging and kernel message trapping daemons
MontaVista™ Linux® Professional Edition
215
Appendix B: Pro Applications Target Application Packages
Application Package
Version
systune
0.5.3
sysutils
1.3.8.1
sysvinit
2.78
tar
1.13.19
tcl
8.3.2
Notes
Reference Books and Web Sites
Installed: Default Description: Kernel tuning utility and scripts Installed: Default Description: Miscellaneous system tools Installed: Default Description: Functionality of interest: init Installed: Default Description: A GNU Þle-archiving program Installed: Default Description: Tcl scripting language
tcp-wrappers
7.6
Practical Programming in Tcl and Tk Brent B. Welch Prentice Hall PTR ISBN: 0130220280
Installed: Default Description: A security tool which acts as a wrapper for TCP daemons
tcpdump
3.6.2
texinfo
4.0b
Installed: Default Description: A network trafÞc monitoring tool Installed: Default Description: Tools needed to create Texinfo format documentation Þles
textutils
2.0
Installed: Default Description: A set of GNU text Þle modifying utilities.
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 TIFF image format Þles
time
1.7
Installed: Default Description: A GNU utility for monitoring a program's use of system resources
216
MontaVista™ Linux® Professional Edition
Texinfo Manual http://www.gnu.org/doc/ texinfo-manual.html
Appendix B: Pro Applications Target Application Packages
Application Package tinylogin
Version 0.80
Notes
Reference Books and Web Sites
Installed: Default Description: Multi-call binary replacing getty, passwd, etc.
capable
of
Because this package is a multi-call binary, calling it via a different name changes the functionality. For example “ln -s tinylogin ls; ls” will call tinylogin with the name ls and cause tinylogin to “act” like ls. The way tinylogin is packaged is that the main binary is in the root package. For example: hhl-ppc_7xx-tinylogin0.80.ppc_7xx.rpm The root package contains no links. Each subpackage contains links to busybox that conßict with their respective packages. For example: hhl-ppc_7xx-tinylogin-fileutils0.80.ppc_7xx.rpm would contain links to tinylogin that conßict with the real fileutils. traceroute
1.4a12
Installed: Default Description: Traces the route taken by packets over a TCP/IP network
ucd-snmp
4.2.3
Installed: Default Description: A collection of SNMP protocol tools from UC-Davis Functionality of interest: snmpd, snmp-devel, snmp-utils
usbutils
0.8
util-linux
2.11h
Essential SNMP Douglas R. Mauro, Kevin J. Schmidt O'Reilly & Associates ISBN: 0596000200
Installed: Default Description: Display info about USB devices Installed: Default Description: A collection of basic system utilities Functionality of interest: kill, mkswap, more, swapoff, swapon, umount
v2linux
0.2
http://support.mvista.com/ content/AppInfo/
Installed: Default Description: Wind River VxWorks® to Linux tool kit
vim
5.7.019
Installed: Default Description: Replaces vi
which
2.12
Vi iMproved (VIM) Steve Oualline New Riders Publishing ISBN: 0735710015
Installed: Default Description: Displays where a particular program in your path is located
wireless-tools
22+23beta3
wu-ftpd
2.6.1
xinetd
2.3.3
Installed: Default Description: Tools for wireless networking Installed: Default Description: An FTP server Installed: Default Description: A secure replacement for inetd
MontaVista™ Linux® Professional Edition
217
Appendix B: Pro Applications Target Application Packages
Application Package zebra
Version 0.92a
Notes Installed: Default Description: GNU routing daemon
zlib
1.1.3
BGP/OSPF/RIP
capable
Installed: Default Description: The zlib decompression library
218
Reference Books and Web Sites
MontaVista™ Linux® Professional Edition
compression
and
Appendix B: Pro Applications Using RSH
Using RSH RSH (Remote shell) is a Berkeley Unix networking command used to run a given command on a remote host, passing it input and receiving its output. To conÞgure RSH, complete the following steps: 1.
shell login
On the target where the command is being run, open the Þle inetd.conf for editing, and uncomment the following lines:
stream stream
2.
tcp tcp
nowait nowait
root root
/usr/sbin/tcpd /usr/sbin/tcpd
in.rshd -aL in.rlogind -a
For Pro, the setuid bit needs to be set for /usr/bin/rlogin and /usr/bin/rsh. To set the setuid bit, enter the following commands: chmod 4755 /usr/bin/rlogin chmod 4755 /usr/bin/rsh
You should see output similar to the following:
# 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
3.
In the user's home directory on the target, open the Þle .rhosts for editing, and add a line with the following format:
<userID>
For example, in the Þle /home/kbryla/.rhosts, you would add a line such as: 10.0.0.83
4.
kbryla
On the target, open the Þle /etc/hosts.equiv and edit it to allow access to the host and user. Add a line with the following format: +
For example, the Þle /etc/hosts.equiv could be:
# /etc/hosts.equiv: list of hosts and users that # are granted "trusted" r command access to your system. +
MontaVista™ Linux® Professional Edition
219
Appendix B: Pro Applications Using 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 both listening. 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 following format:
<userID>
For example, in the Þle /home/kbryla/.rhosts, you would add a line such as:
10.0.0.83
kbryla
•
Open the Þle /etc/hosts.equiv and edit it to allow access to the host and user. Add a line with the following format: +
For example, the Þle /etc/hosts.equiv could be:
# /etc/hosts.equiv: list of hosts and users that # are granted "trusted" r command access to your system. +
•
Start or restart xinetd. use the command: /etc/init.d/xinetd restart
Note: Running the command netstat -at should show that shell and login are both listening. You should now be able to use RSH.
220
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements
Notices By providing information, you understand and acknowledge that MontaVista Software, Inc. (“MontaVista Software”) is not providing legal advice to you nor does MontaVista Software endorse any particular product or any Web site, including those listed herein. The licensed software described in this publication, including all licensed material available for it, is provided to you by MontaVista Software subject to the terms of the MontaVista Software Product Subscription and Software License Agreement, or any equivalent agreement between us, and any license agreements MontaVista Software passes through to you from its licensors or suppliers. MontaVista Software, its licensors or its suppliers, may have patents, or pending patent applications, or other intellectual property rights in, or covering, the subject matter described in this publication. The furnishing of this publication does not give you any license to these patents or such other intellectual property rights of MontaVista Software or its licensors or suppliers, except as may be provided in a separate license agreement relating to the particular licensed software. Any references in this publication to non-MontaVista Software Web sites are provided for your convenience only and do not, in any manner, serve as an endorsement by MontaVista Software of such Web sites or their content. Information contained in such Web sites are not under the control of MontaVista Software, Inc., nor are they part of the materials for this MontaVista Software product. MontaVista Software is not responsible for any changes or updates to such sites and your use of any such Web sites 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 vary signiÞcantly. Some measurements may have been made on development-level systems and MontaVista Software makes no guarantee that these measurements will be 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 applicable data for your speciÞc environment. This publication may also contain sample
MontaVista™ Linux® Professional Edition
221
Appendix C: Notices and License Agreements Notices
application programs in source language, which illustrate programming techniques on various operating platforms. These examples have not been thoroughly tested under all conditions and MontaVista Software, therefore, cannot guarantee or imply reliability, serviceability, or function of such programs. You may copy, modify and distribute these sample programs subject to the license agreements and copyright notices accompanying such sample application programs. This publication may contain examples of data and reports used in daily business operations. To illustrate them as best as possible, the examples may include references to Þctional characters, companies, brands and/or products. MontaVista Software's use of such named Þctitious characters, companies, brands and/or products is for illustration only. Any similarity to actual persons, companies, brands, products or business enterprises is unintentional and entirely coincidental.
222
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements License Agreements
License Agreements MontaVista™ Linux® Professional Edition is licensed, not sold, to you under the terms of the MontaVista Product Subscription and Software License Agreement, or any equivalent agreement between us.
MontaVista™ Linux® Professional Edition
223
Appendix C: Notices and License Agreements Target Configuration Tool End User License Agreement
Target ConÞguration Tool End User License Agreement IMPORTANT-READ CAREFULLY: This MontaVista Software, Inc. End-User License Agreement (“EULA”) is a legal agreement between you (either an individual or a single entity) and MontaVista Software, Inc. for the MontaVista Software, Inc. software product identiÞed above, which includes computer software (binary and source) and may include associated media, printed materials, and “online” or electronic documentation (“Software Product”). By installing, copying, or otherwise using the Software Product, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the Software Product. If applicable, you may return it to your place of purchase for a full refund of any separate fees paid for the Software Product. MontaVista Software, Inc. shall be referred to in this EULA as “Licensor.” Any third party software that is provided with the Software Product includes such third party’s license agreements (in either electronic or printed form) (including the GNU General Public License) for use at your option. If you choose to use such software, then such use shall be governed by such third party license agreements and not by this Agreement. The Software Product is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The Software Product is licensed, not sold. LICENSE GRANT. Licensor grants you a non-exclusive and non-transferable license to use the Software Product and accompanying documentation (“Documentation”), subject to the limitations below. This license grant is subject to the payment of applicable license fees. Unless you have purchased a product subscription for the Software Product, the license granted under this Agreement does not grant you any right to any enhancement or update to the Software Product. LIMITATIONS ON USE; NO REDISTRIBUTION. With respect to the Software Product, you may not, and may not authorize any third party to: (1) distribute to any third party the source code of the Software Product or any modiÞcations or derivative works thereof, or any copies of the Documentation; (2) rent, lease, grant a security interest in, or otherwise transfer rights to the Software Product; or (3) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols or labels 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 a period of ninety (90) days from the date of acquisition, the Software Product, if operated as directed, will substantially achieve the functionality described in the Documentation. Licensor does not warrant, however, that your use of the Software Product will be uninterrupted or that the operation of the Software Product will be error-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) to advise you how to achieve substantially the same functionality with the Software Product as described in the Documentation through a procedure different from that set forth in the Documentation; or (iii) for individual consumers, if the above remedies are impracticable, to refund the license fee you paid for the Software Product separate
224
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements Target Configuration Tool End User License Agreement
and apart from other products, if any such separate fee was paid for the Software Product, minus a reasonable allowance for the time you have used the Software Product. Only if you inform Licensor of your problem with the Software Product during the applicable warranty period and provide evidence of the date you purchased a 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 the Software Product by you during the warranty period; (2) if the media is subjected to accident, 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 conjunction with hardware or software other than the unmodiÞed version of hardware and software with which the Software Product was intended to be used as described in the Documentation. NO OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR DISCLAIMS ALL OTHER WARRANTIES AND CONDITIONS, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OR MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE PRODUCT, AND THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION. TITLE. Title, ownership, and intellectual property rights in the Software Product and Documentation shall remain in Licensor. You acknowledge such ownership and intellectual property rights and will not take any action to jeopardize, limit or interfere in any manner with Licensor’s ownership of or rights with respect to the Software Product and Documentation. The Software Product and Documentation are protected by copyright and other intellectual property laws and international treaties. TERMINATION. This EULA and the license granted hereunder will terminate automatically if you fail to comply with the conditions described herein. Upon termination, you must destroy all copies of the Software Product and Documentation. Your obligations to pay accrued charges and fees shall survive any termination of this EULA. EXPORT CONTROLS. The Software Product is subject to the regulations of the United States government and agencies thereof, including the Bureau of Export Administration. None of the Software Product of underlying information or the underlying information or technology may be downloaded or otherwise exported or reexported into prohibited countries (including Cuba, Iraq, Libya, Sudan, North Korea, Iran, Syria or any other country to which the United States has embargoed goods). By downloading or using the Software Product, you agree that you are not located in, under the control of, or a national or resident of any such country. LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE
MontaVista™ Linux® Professional Edition
225
Appendix C: Notices and License Agreements Target Configuration Tool End User License Agreement
USE OF OR INABILITY TO USE THE SOFTWARE PRODUCT OR THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN ANY CASE, LICENSOR’S ENTIRE LIABILITY UNDER ANY PROVISION OF THIS EULA SHALL BE LIMITED TO THE AMOUNT ACTUALLY PAID BY YOU SEPARATELY FOR THE SOFTWARE PRODUCT. BECAUSE SOME STATES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. HIGH RISK ACTIVITIES. The Software Product is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air trafÞc control, direct life support machines, or weapons systems, in which the failure of the Software Product could lead directly to death, personal injury, or severe physical or environmental damage (“High Risk Activities”). Accordingly, Licensor and its suppliers speciÞcally disclaim any express or implied warranty of Þtness for High Risk Activities. MISCELLANEOUS. This EULA represents the complete agreement concerning the license granted hereunder and may be amended only by a writing executed by both parties. THE ACCEPTANCE OF ANY PURCHASE ORDER PLACED BY YOU IS EXPRESSLY MADE CONDITIONAL ON YOUR ASSENT TO THE TERMS SET FORTH HEREIN, AND NOT ON THOSE IN YOUR PURCHASE ORDER. If any provision of this EULA is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. All disputes relating to this EULA shall be resolved by binding arbitration in Santa Clara County, California. This EULA shall be governed by California law, excluding conßict of law provisions. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded.
226
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The “Artistic License”
The “Artistic License” Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modiÞcations.
DeÞnitions: “Package” refers to the collection of Þles distributed by the Copyright Holder, and derivatives 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 been modiÞ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 the package. “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 to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) “Freely Available” means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug Þxes, portability Þxes and other modiÞcations derived from the Public Domain or from the Copyright Holder. A Package modiÞed in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed Þle stating how and when you changed that Þle, and provided that you do at least ONE of the following: •
a) place your modiÞcations in the Public Domain or otherwise make them Freely Available, such as by posting said modiÞcations to Usenet or an equivalent medium, or placing the modiÞcations on a major archive site such as uunet.uu.net, or by allowing the
MontaVista™ Linux® Professional Edition
227
Appendix C: Notices and License Agreements The “Artistic License”
Copyright Holder to include your modiÞcations in the Standard Version of the Package. •
b) use the modiÞed Package only within your corporation or organization.
•
c) rename any non-standard executables so the names do not conßict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version.
•
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) on where to get the Standard Version.
•
b) accompany the distribution with the machine-readable source of the Package with your modiÞcations.
•
c) give non-standard executables non-standard names, and clearly document the differences in manual pages (or equivalent), together with 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. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your 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 the complete Standard Version of the interpreter is so embedded. 6. The scripts and library Þles supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whoever generated them, and may be sold commercially, and may be aggregated with this Package. If such scripts or library Þles are aggregated with this Package via the so-called “undump” or “unexec” methods of producing a binary executable image, then distribution of such an image shall neither be construed as a distribution of this Package nor shall it fall under the restrictions of Paragraphs 3 and 4, provided that you do not represent such an executable image as a Standard Version of this Package.
228
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The “Artistic License”
7. C subroutines (or comparably compiled subroutines in other languages) supplied by you and linked into this Package in order to emulate subroutines and variables of the language deÞned by this Package shall not be considered part of this Package, but are the equivalent of input as in Paragraph 6, provided these subroutines do not change the language in any way that would cause it to fail the regression tests for the language. 8. Aggregation of this Package with a commercial distribution is always permitted provided that the use of this Package is embedded; that is, when no overt attempt is made to make this Package's interfaces visible to the end user of the commercial distribution. 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 products derived from this software without speciÞc prior written permission. 10. THIS PACKAGE IS PROVIDED “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End
MontaVista™ Linux® Professional Edition
229
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
GNU General Public License, or GNU GPL Version 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 license document, but changing it is not allowed.
Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of 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 you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of 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 they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modiÞed by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reßect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent
230
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
licenses, in effect making the program proprietary. To prevent this, we have made it clear 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 AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public 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 under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modiÞcations and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modiÞcation”.) Each licensee is addressed as “you”. Activities other than copying, distribution and modiÞcation are not covered by this License; 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 work based 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 you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any 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 your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modiÞcations or work under the terms of Section 1 above, provided that you also meet all of these conditions: •
a) You must cause the modiÞed Þles to carry prominent notices stating that you changed the Þles and the date of any change.
•
b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
•
c) If the modiÞed program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these
MontaVista™ Linux® Professional Edition
231
Appendix C: Notices and License Agreements GNU 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 not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modiÞed work as a whole. If identiÞable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute 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 permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution 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 provided that you also do one of the following: •
a) Accompany it with the complete corresponding machinereadable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; 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 of physically performing source distribution, a complete machinereadable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
•
c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modiÞcations to it. For an executable work, complete source code means all the source 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 include anything that is normally distributed (in either source or binary form) with the major
232
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate 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 long as such parties remain 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 its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for 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 this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or
MontaVista™ Linux® Professional Edition
233
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to 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 a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
234
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 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 the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start 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 is found. one line to give the program's name and an idea of what it does. Copyright (C) yyyy name of author 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 program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 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., 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 an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
MontaVista™ Linux® Professional Edition
235
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
236
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The 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 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.]
Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you Þrst think carefully about whether this license or the ordinary General Public License is the better 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. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must 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, you must provide complete object Þles to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them 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/or modify the library.
MontaVista™ Linux® Professional Edition
237
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modiÞed by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by 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 free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use speciÞed in this license. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those 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 the original library. The ordinary General Public License therefore permits such linking only if the entire combination Þts its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. We call this license the “Lesser” General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that 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 the Lesser General Public License. In other cases, permission to use a particular library in non-free programs enables a greater 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 more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating 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 the freedom and the wherewithal to run that program using a modiÞed version of the Library. 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
Appendix C: Notices and License Agreements The 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 AND MODIFICATION 0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General 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 be conveniently linked with application programs (which use some of those functions and data) to form executables. The “Library”, below, refers to any such software library or work which has been distributed under these terms. A “work based on the Library” means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modiÞcations and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term “modiÞcation”.) “Source code” for a work means the preferred form of the work for making modiÞcations to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface deÞnition Þles, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modiÞcation are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; 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 your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modiÞcations or work under the terms of Section 1 above, provided that you also meet all of these conditions: •
a) The modiÞed work must itself be a software library.
MontaVista™ Linux® Professional Edition
239
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
•
b) You must cause the Þles modiÞed to carry prominent notices stating 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 charge to all third parties under the terms of this License.
•
d) If a facility in the modiÞed Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-deÞned independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modiÞed work as a whole. If identiÞable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version 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 the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.
240
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The 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 a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machinereadable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisÞes the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a “work that uses 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 an executable that is a derivative of the Library (because it contains portions of the Library), rather than a “work that uses the library”. The executable is therefore covered 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 the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially signiÞcant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely deÞned by law. If such an object Þle uses only numerical parameters, data structure layouts and accessors, 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 a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also combine or link a “work that uses the Library” with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modiÞcation of the work for the customer's own use and reverse engineering for debugging such modiÞcations. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy
MontaVista™ Linux® Professional Edition
241
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: •
a) Accompany the work with the complete corresponding machinereadable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable “work that uses the Library”, as object code and/or source code, so that the user can modify the Library and then relink to produce a modiÞed executable containing the modiÞed Library. (It is understood that the user who changes the contents of deÞnitions Þles in the Library will not necessarily be able to recompile the application to use the modiÞed deÞnitions.)
•
b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy 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 the user installs one, as long as the modiÞed version is interfacecompatible with the version that the work was made with.
•
c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials speciÞed in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
•
d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above speciÞed materials from the same place.
•
e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.
For an executable, the required form of the “work that uses the Library” must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
242
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
7. You may place library facilities that are a work based on the Library side-by-side in 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 the work 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 work based 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 that part 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 except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate 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 long as 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 derivative works. 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 the Library), you indicate your acceptance of this License to do so, and all its terms and conditions 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), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for 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 this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.
MontaVista™ Linux® Professional Edition
243
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library speciÞes a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of 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 NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
244
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED 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 the public, we recommend making it free software that everyone can redistribute and change. 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 attach them to the start 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 is found. one line to give the library's name and an idea of what it does. Copyright (C) year name of author This library is free software; and/or modify it under the terms Public License as published Foundation; either version 2.1 your option) any later version.
you can redistribute it of the GNU Lesser General by the Free Software of the License, or (at
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
MontaVista™ Linux® Professional Edition
245
Appendix C: Notices and License Agreements The 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, if any, to sign a “copyright disclaimer” for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. signature of Ty Coon, 1 April 1990 Ty Coon, President of Vice That's all there is to it!
246
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The Modified BSD License
The ModiÞed BSD License Redistribution and use in source and binary forms, with or without modiÞcation, are permitted 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 copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3.
The name of the author may not be used to endorse or promote products derived from this software without speciÞc prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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.
MontaVista™ Linux® Professional Edition
247
Appendix D:Documentation Naming Conventions
Naming Conventions
An application name. For example bash or man.
<architecture>
Architecture family directories. For example /arm, /mips, /ppc, /sh, /sparc, /x86, etc.
<architecturecanonical-name>
Architecture family name used by GNU tools.
<architecturepreÞx>
The preÞx used for the cross-development applications to indicate the target architecture. A list of architecture preÞxes can be found in “Running Pro Applications and Tools” on page 40.
The block device where you wish to create a spare partition such as hda1. For more information about partitions, we recommend reading the man pages for parted and fdisk.
An directory where you intend to build the kernel, application, etc.
<destree>
The base of a Þle hierarchy.
A directory containing your Þle system.
MontaVista™ Linux® Professional Edition
249
Appendix D: Documentation Naming Conventions Naming Conventions
An image Þle of your Þle system.
The installation location for Pro or for an application.
The name of the kernel binary image Þle. Typically this is vmlinux.
Run levels for the conÞguration programs.
The name of the target board LSP. If the is not known, a listing of legal s for the current architecture may be obtained using the --list option with the hhl-host-install tool. s are listed in quick start guide for your target.
<mount-point>
The directory where media (or Þle system) has been mounted.
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 the application 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.
The name of the target board, such as embeddedplanet-rpxlite. See the quick start guide for your target for more information about the name you should use.
250
MontaVista™ Linux® Professional Edition
Appendix D: Documentation Naming Conventions Naming Conventions
The system prompt used on the target.
<userID>
A person’s user ID.
The version number.
MontaVista™ Linux® Professional Edition
251
Glossary of Terms
API
Application Programming Interface, deÞning how programmers write source code that makes use of library or operating system facilities by accessing the behavior and state of classes and objects.
BOOT ROM
Target-resident Þrmware, executed when power is applied or the reset button is pressed on the target.
BOOTP
A standard protocol, often used in Boot ROM. BOOTP determines network conÞ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 into machine-executable programs. The term may also refer speciÞcally to the tool that translates from source to assembly language.
Cross-development
This refers to creating code on one architecture, but being able to compile it for a different architecture. An example would be to create code on a x86 host, but compiling the code so that it will run on a PowerPC or MIPS target. Though the architectures might not be the same endian or process code the same way, the GCC compiler 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 target will not run on the host.
MontaVista™ Linux® Professional
Edition
253
Debugger
A tool that allows programmers to examine and control program execution, typically for 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 embedded computer 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 on people’s right to use, copy, modify and redistribute computer programs.” The GNU Project 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 to develop a complete Unix-like operating system which is free software: the GNU system.
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. The Pro tools are installed on this system. The host system is used for compiling, linking, remote debugging and associated development activities. Sometimes referred to as the “server” system.
IDE
Integrated Development Environment, a GUI tool or a set of tools that uses GUI functionality.
JTAG
Joint Test Advisory Group, referring to a type of hardware interface that allows the testing of chips and boards within a complete system; programs running on processors with JTAG support may be controlled through the processor JTAG port.
254
MontaVista™ Linux® Professional Edition
ICE
In-Circuit Emulator
Linux
Linux is a Unix-type operating system originally created by Linus Torvalds with the assistance of developers around the world. Developed under the GNU General Public License, 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-executable programs (compiler, binary Þle converters, debugger).
Patch
A patch is a Þle that describes a source code change. It is genenerated by the diff untility and applied to the original source code with the patch utility.
PROM
Programmable Read-Only Memory, ROM that can be programmed using special equipment. 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, and temporary registers.
ROM
Read-Only Memory, non-volatile memory that can be read, but not written, by the microprocessor.
RTOS
Real-Time Operating System.
Target
A target is a reference board that you plan to use as the base for your product. Most embedded targets either don’t have an IDE drive or the drive is too small to have a full complement of tools for building kernels and applications.
TFTP
A standard protocol, possibly used by the Boot ROM, by which a system (target board) retrieves an executable Þle from another system (from the “host” system).
MontaVista™ Linux® Professional Edition
255
Toolchain
256
Informal term for the collection of programs that make up a complete set of compilation tools. Generally refering to binutils, gcc and glibc.
MontaVista™ Linux® Professional Edition
User’s Guide Version 3.0
1237 E. Arques Ave. Sunnyvale, CA 94085
Copyright Copyright © 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. MontaVista Linux Professional Edition Version
Documentation Release Date
Notes
3.0
December 16, 2003
First Release
3.0
January 10, 2003
First typos.
Acknowledgements Thank 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.
Contact You are welcome to contact us: [email protected]
Contents
Chapter 1
Welcome to MontaVista™ Linux® Professional Edition ................... 1 What is MontaVista™ Linux® Professional Edition? .................................. 1 What Are Linux Support Packages? ........................................................ 1 Pro Is Reproducible ................................................................................. 2 Cross- and Local-Compilation Environments ......................................... 2 Developing Embedded Applications With Pro.............................................. 5 Prepare the Development Environment ................................................... 5 Develop Your Kernel and/or Application................................................. 6 Integrate Your System Components......................................................... 9 Deploy Your Embedded Application ....................................................... 10 About This Manual........................................................................................ 11 Other Documentation .............................................................................. 11 Support .......................................................................................................... 12
Chapter 2
Installation .............................................................................................. 13 Overview ....................................................................................................... 13 Requirements................................................................................................. 15 Host.......................................................................................................... 15 Target ....................................................................................................... 16 The hhl-host-install Tool ................................................................. 17 Usage ....................................................................................................... 17 Options..................................................................................................... 17 Displaying the Product Directory.................................................................. 20 Installing or Upgrading Pro........................................................................... 22 Install ....................................................................................................... 22 Upgrade ................................................................................................... 24 Installing or Upgrading an Additional LSP................................................... 28 Removing Pro................................................................................................ 30 Remove a Single LSP .............................................................................. 30
MontaVista™ Linux® Professional Edition
i
Remove All of Pro ................................................................................... 30 Installing, Upgrading, or Removing Optional Packages ............................... 32 Install ....................................................................................................... 32 Upgrade or Remove ................................................................................. 33 Trouble-Shooting........................................................................................... 34
Chapter 3
The Development Environment ............................................................37 Overview........................................................................................................ 37 Project Directories ......................................................................................... 38 Create Project Directories........................................................................ 38 Populate Project Directories .................................................................... 38 Running Pro Applications and Tools ............................................................. 40 Cross-Development Application PreÞxes ................................................ 42 Accessing man and info Pages ...................................................................... 44 man Pages ................................................................................................ 44 info 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.............................................................................................. 54 ConÞgure Minicom.................................................................................. 54 Start Minicom .......................................................................................... 55 Exit Minicom ........................................................................................... 55 Help.......................................................................................................... 55
Chapter 5
Target ConÞguration Tool (TCT) .........................................................57 Overview........................................................................................................ 57 Starting TCT .................................................................................................. 58 Start TCT ................................................................................................. 58 Create a New Project ............................................................................... 58 Open a Project.......................................................................................... 60 Remove a Project ..................................................................................... 60 TCT Project Menus ....................................................................................... 61 The File Menu.......................................................................................... 61 The View Menu........................................................................................ 64 The Info Menu ......................................................................................... 67 Using TCT ..................................................................................................... 68 Create a ConÞguration File...................................................................... 68 Create/Edit Kernel ConÞguration ............................................................ 69 Create/Edit File System ........................................................................... 70 Build the Target Kernel and File System ................................................. 71 Using the Tar Archive Created by TCT ......................................................... 72
ii
MontaVista™ Linux® Professional Edition
The targetpkg Utility............................................................................... 73 Usage ....................................................................................................... 73 Examples ................................................................................................. 73
Chapter 6
Linux Kernel Development ................................................................... 75 Overview ....................................................................................................... 75 Building and ConÞguring the Kernel ............................................................ 76 Build the Kernel With TCT ..................................................................... 76 Build the Kernel Without TCT ................................................................ 76 Enabling Loadable Kernel Modules.............................................................. 80 Enabling Real-Time Performance Enhancements......................................... 81 MontaVista Real-Time Scheduler............................................................ 81 Preemptible Kernel .................................................................................. 82 Limitations............................................................................................... 83 Enabling Standard Devices............................................................................ 84 Framebuffer Support................................................................................ 84 Videocard Support ................................................................................... 85 PS/2 Keyboard and Mouse Support......................................................... 86 Building Custom Device Drivers .................................................................. 88 Load and Unload the Driver (Kernel Module) ........................................ 89 Code the Kernel Portions of the Driver ................................................... 90 Initial Coding of the Driver ..................................................................... 91 Wrap Up .................................................................................................. 101 Additional Information ............................................................................ 102 Enabling File Systems ................................................................................... 103 Debugging the Kernel.................................................................................... 104 KGDB...................................................................................................... 104 Linux Trace Toolkit (LTT)....................................................................... 107 Abatron BDI2000 .................................................................................... 108
Chapter 7
Application Development ...................................................................... 113 Overview ....................................................................................................... 113 Building Programs Using KDevelop............................................................. 114 MontaVista Customizations..................................................................... 115 Install KDevelop ...................................................................................... 116 Start KDevelop ........................................................................................ 117 Use KDevelop for Cross-Development ................................................... 117 Help ......................................................................................................... 127 Building Programs Using GCC and G++...................................................... 128 Example of a C Program ......................................................................... 128 Example of a C++ Program ..................................................................... 129 Additional Information ............................................................................ 129 Using Threads................................................................................................ 131 Debugging Programs Using GDB and DDD ................................................ 132 Additional Documentation ...................................................................... 132 Example of Using GDB........................................................................... 133 Example of Using GDB and DDD Together ........................................... 134 MontaVista™ Linux® Professional Edition
iii
Debugging Programs Which Call fork(), vfork(), and execve().................... 135 Debugging Multi-Threaded Applications...................................................... 136 Additional Information ............................................................................ 136 Additional Tools for Programming and Debugging ...................................... 137 cbrowser................................................................................................... 137 cßow......................................................................................................... 137 cscope ...................................................................................................... 137 dmalloc .................................................................................................... 138 ltrace ........................................................................................................ 138 mtrace ...................................................................................................... 138 strace ........................................................................................................ 139 showasm................................................................................................... 139 Using AltiVec™ Technology by Motorola .................................................... 140 Features.................................................................................................... 140 Limitations ............................................................................................... 140 Additional Information ............................................................................ 141
Chapter 8
System Integration .................................................................................143 Overview........................................................................................................ 143 Creating Your File-System Hierarchy............................................................ 145 Select a Deployment File-System Type ................................................... 145 Use TCT to Select Applications............................................................... 149 Add Your Custom Application ................................................................. 150 Booting the Target and NFS-Mounting Your File System............................. 151 ConÞguring the User-Space Environment..................................................... 152 Enable Run-Level Services (Startup Scripts) .......................................... 152 ConÞgure the Target for Serial Console or Virtual Terminal................... 156 Create Standard Device Nodes ................................................................ 158 Add Shells................................................................................................ 158 Start PCMCIA ......................................................................................... 160 ConÞgure Networking ............................................................................. 160 Testing Your Environment ............................................................................. 165 Reducing the Size of Your File System ......................................................... 166 Library Optimizer Tool (LOT)................................................................. 166 Example ................................................................................................... 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 .................................................................................................... 175 EXT2 and EXT3 ...................................................................................... 175 Journaling FLASH Filesystem (JFFS)..................................................... 175 ReiserFS................................................................................................... 175 XFS .......................................................................................................... 176 MTD ........................................................................................................ 176
iv
MontaVista™ Linux® Professional Edition
Creating a File-System Image ....................................................................... 179 CramFS.................................................................................................... 179 JFFS/JFFS2.............................................................................................. 180 EXT2/EXT3............................................................................................. 181 ReiserFS................................................................................................... 182 XFS.......................................................................................................... 183 Setting Up Your File Systems (/etc/fstab) ..................................................... 185 Sample 2 .................................................................................................. 185 Booting the New Kernel ................................................................................ 186 Trouble-Shooting Deployment ...................................................................... 187 Corrupt 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 ........................................................................................... 192 Architecture 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
How to Apply These Terms to Your New Programs ................................ 235 The GNU Lesser General Public License, or GNU LGPL ........................... 237 How to Apply These Terms to Your New Libraries ................................. 245 The ModiÞed BSD License ........................................................................... 247
Appendix D
Documentation Naming Conventions...................................................249 Naming Conventions ..................................................................................... 249
Glossary of Terms............................................................................................................................. 253
vi
MontaVista™ Linux® Professional Edition
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 the supported target CPUs, along with a full complement of development tools designed to help you design, develop, and deploy an embedded application. Whether you’re building Internet appliances, portable devices, networking equipment, telephony interfaces, or other embedded and pervasive applications, you can count on MontaVista 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-level platforms of any embedded Linux development solution available today. Pro highlights include:
What Are Linux Support Packages?
•
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
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
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition What is MontaVista™ Linux® Professional Edition?
(shell and shell utilities: mkdir, cd, rm, etc.); and host-resident, host-executable programs (compiler, binary Þle converters, debugger). Pro includes LSPs for over 78 different reference boards. The advantage of using an LSP for kernel or Þle system development is that by using a system that is known to work as a base for your development, you can greatly decrease your development time.
Pro Is Reproducible
Pro can be reproduced without using any proprietary products. The advantage to this design is that you, the developer, can view the source code of the software, tailor the software as needed, and learn from the software. You may not need to recompile any portion of Pro; however, if you do need to recompile Pro (due to contract issues), it is possible.
Cross- and LocalCompilation Environments
Pro is designed to be a cross-compilation environment that is capable of being used as a 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 one architecture 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 it runs on a PowerPC or MIPS target. Though the architectures might not be the same endian or process code the same way, the gcc compiler provided by MontaVista builds code that will run on the target. Note: If the host and target architectures are different, then code built for the target will 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 are used for compiling, linking, remote debugging, and associated development activities.
2
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition What is MontaVista™ Linux® Professional Edition?
A target is a reference board that you plan to use as the base for your product. Most embedded targets either don’t have an IDE drive or have a drive that is too small to have 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: Cross-Compilation Environment
Local Network Pro 3.0 --------------Red Hat 7.3
MontaVista Linux
Serial .................. ................... Target
Host
The advantage of a cross-compilation system is that the host system is generally faster and easier to develop on compared to the target system. Another advantage is that it is easier to recover your system should a change render your kernel un-bootable. Those of you with experience as Real-Time Operating System (RTOS) developers may already be accustomed to using a cross-compilation environment.
The local-compilation environment In a local-compilation environment, all of the tools and applications required to rebuild the system are installed directly on the target system. Local-compilation refers to creating code or developing applications on (and for) the architecture and operating system being used. For IA-32/x86 targets, Pro can be installed directly on the target for local-compilation development. Using a local-compilation environment, no network connection or
MontaVista™ Linux® Professional Edition
3
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition What is MontaVista™ Linux® Professional Edition?
cross-compilation host is needed. For a typical IA-32/x86 system, the localcompilation environment appears as in the diagram below: Local-Compilation Environment
Pro 3.0 (x86 development tools and basic file system)
.................. .................. Target (with keyboard and VGA display)
Most open-source and commercial developers are already accustomed to developing applications on (and for) the operating system that they use every day. This is one of the advantages of having a local-compilation system. Another advantage of having a local-compilation system is that it can provide a quick development-to-deployment environment. However, in the embedded-systems industry, most systems are small; therefore, local-compilation development could potentially increase costs and reduce productivity. Note: This manual focuses on the cross-compilation environment. Information about using local compilation can be found in a separate MontaVista publication, Using MontaVista Linux Professional Edition for Local Compilation.
4
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing 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 in Pro to build your embedded application. The outline below covers the development cycles of the three main components of an embedded Linux application – kernel development, application development, and system integration. For some projects, the Linux kernel and MontaVista provided applications can be used without modiÞcation, allowing you more time to focus on your custom applications. For other projects, you may Þnd that you need to modify the kernel to support custom features for your board, 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 recommend pursuing your project in the following order. The steps described below are explained in 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. By installing the LSP for your reference board, you have a default environment that can be 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 reference board’s architecture and processor, and you have all of the cross-compilation tools that 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 you followed the instructions in the quick start guide for your target provided by MontaVista, the target’s root Þle system is NFS-mounted on the host. The development environment directory structure appears as follows:
NFS root file system
Target System
Host System /opt/hardhat /devkit /<architecture> /<processor> /target /bin /etc /lib ... /host
MontaVista™ Linux® Professional Edition
5
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing 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 target system 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 ready to begin development. Included in the Pro distribution are over 280 application packages. If you do not know how to use these applications, documentation in the form 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 you need to modify to a work directory elsewhere on your host. This way, you can easily return to the default conÞgurations provided by MontaVista. In addition, it is important that you do not make changes to the /target directory. This directory is used by the MontaVista Target ConÞguration Tool (TCT) for Þle system development. Changes can result in problems when creating your Þle system. Assuming that you are doing kernel and application development, you could create a work directory structure such as the following: my_work_directory /mykernel /myapplication /myfilesystem
The mykernel directory can be used for kernel development. The myapplication directory can be used for application development. The myfilesystem directory is where you can integrate your Þle system hierarchy and your 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
6
Once you have prepared your environment, you are ready to begin development. Application and kernel development cycles are very similar. Typically, kernel development work is done before application work; however, kernel work and application work can occur in parallel and be merged later for testing and Þnal deployment.
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
The typical development cycle for building a kernel and/or application appears as follows: Begin development
Compile the kernel and/or application on the host Modify the kernel and/or application on the host
Make the kernel and/or application available to the target
Run the target to test the kernel and/or application
Success! Whether you are working on kernel code or application code, we recommend making only a few changes to your target’s environment at a time. This method allows you to track your progress and isolate bugs more easily. It will also help the MontaVista Support team answer your questions more quickly. Simply stated, by starting from an environment 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 tool provided by MontaVista used to manage kernel and Þle system development, or you may use the compilers and kernel debuggers distributed with Pro. Whether you use TCT or another method, you should create a work directory (such as mykernel) for kernel development that contains a copy of the LSP kernel. If you use TCT, the LSP kernel and conÞguration Þles are copied automatically to a work directory when you create a TCT project. If you do not use TCT, you need to copy the LSP kernel by hand. TCT stores kernel conÞguration information in a conÞguration Þle. One advantage of using TCT is that you can easily save multiple kernel (and Þle system) conÞgurations for a single project. However, if you use TCT, it is important to note that changes made to the kernel using another tool, such as make menuconfig, will not be stored 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 your development depends on whether you are customizing kernel code, adding a custom device driver, or conÞguring the kernel. If you are adding custom kernel code or adding a custom device driver, we recommend that you use the copy of the kernel in your project directory.
MontaVista™ Linux® Professional Edition
7
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
If you are conÞguring the kernel, we recommend that you use TCT. Before you , conÞgure your kernel, you should make some decisions about the kernel options you need to enable. Because rebuilding the kernel can take time, it is best to make your kernel conÞguration selections all at once. Here are some things to think about when you 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 performance enhancements? (real-time scheduler or preemptible kernel)
•
Which type of Þle system do you want to use in your deployed embedded project? (EXT2, ReiserFS, JFFS, etc.)
Once you have Þnished building the kernel, you can boot the target with the new kernel 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 with Pro. Whether you use KDevelop or another tool, you should create a work directory (such as myapplication) for application development. After you have written and compiled your application on the host, move the application to an NFS-mounted Þle system on the target to test the application. There are a number of advantages to using a cross-development environment with an NFS-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 fault isolation.
•
The NFS root Þle system provides a large selection of applications that the typical embedded target would not be able to have locally as it would not, in most cases, have enough resources.
•
In most environments, compiles more quickly on the host than on the target, because the host is usually faster and has more resources than 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 the target; however, in most cases, using the host’s environment makes more sense.
8
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
Integrate Your System Components
Once you are satisÞed with your kernel and application, it is time to integrate your system components and test your embedded environment. Integrating the system components includes the following steps: •
Determine which libraries and applications are required to support your application, and then build a Þle system with those applications and libraries. We recommend that you use TCT to select 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 build directory (such as myfilesystem) as the location for integrating your Þle system and application.
•
Export the myfilesystem directory containing your Þle system and application as NFS to the target system. By exporting the Þle system directory as NFS, you can test your environment on the target before spending the development time to reduce the Þle system size or burn the Þle system into ßash.
•
ConÞgure the user environment. Doing this for your application can include activities such as adding your application to start-up scripts (setting the run levels), creating required device nodes, or conÞguring the networking components used.
Once you have completed the tasks above, you should have a system that appears as follows: User-Space Configs
Local Network Pro 3.0 --------------Red Hat 7.3
Custom Apps NFS Root File System
Custom Kernel
Target File System
Serial
.................. ................... Target Host
When you know you have an environment that works, you can proceed to reducing the size of your Þle system. After reducing the size of your Þle system, you should use proÞling tools to evaluate the your project’s performance and to look for memory
MontaVista™ Linux® Professional Edition
9
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Developing Embedded Applications With Pro
leaks, etc. You will want to use the same development cycle you used for initial kernel and application development to Þx and test problems uncovered with these tools.
Deploy Your Embedded Application
When your kernel and application have been proven in a test environment, then it’s time 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: User-Space Configs
Custom Apps Local Root File System
Custom Kernel
.................. ................... Target
Disconnecting the target from the host may require building a kernel and Þle-system image that can be booted from ßash, or it may require a system than can be booted via LILO. Some general strategies are outlined later in this manual.
10
MontaVista™ Linux® Professional Edition
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition About This Manual
About This Manual This manual describes how to install and use Pro to develop embedded systems based on Pro. This manual covers all supported target architectures, and it is included on each of the Pro CDs in PDF format. The host system in this manual is assumed to be a Red Hat® host. If you are using another host, we recommend that you read one of the Pro host manuals for more information and requirements regarding the host OS you are using. This manual assumes that you know how to use Linux. If you are unfamiliar with Linux, there are many books available to help you get started using and understanding Linux. Note: MontaVista Software does not endorse the book listed below. The following example is provided for your convenience only: •
Other Documentation
Running Linux, Matt Welsh, Matthias Kalle Dalheimer, and Lar Kaufman. Sebastopol, California: O'Reilly & Associates [1999]. (ISBN: 156592469X)
MontaVista Linux Professional Edition Quick Start Guides For each supported target, MontaVista Software provides a Pro quick start guide. The quick start guides contain step-by-step instructions for booting Pro on the target using a Red Hat® Linux host. Copies of the quick start guides can be found on the “Pro Host Binaries” CD-ROM in the /docs/quickstarts directory. In addition, as updates 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 use one of the other supported hosts, MontaVista Software provides host manuals. These manuals provide step-by-step instructions on how to conÞgure the host along with usage notes about using Pro with that host OS. Host manuals are available for Solaris™, SuSE®, YellowDog®, and Mandrake™ as well as for using a localcompilation environment. Copies of the Pro host manuals can be found on the “Pro Host Binaries” CD-ROM in the /docs/hostmanuals directory. In addition, as updates are made, the latest versions will be available on MontaVista Zone.
MontaVista Zone MontaVista Zone (http://support.mvista.com) is the MontaVista subscriber-only support Web site. MontaVista Zone provides focused information to assist in getting products to market faster. On MontaVista Zone, you will Þnd embedded Linux information, access to MontaVista-developed software, and MontaVista FAQs.
MontaVista™ Linux® Professional Edition
11
Chapter 1: Welcome to MontaVista™ Linux® Professional Edition Support
Support In-depth technical engineering assistance is available for the distributed software that MontaVista Software develops, for example, MontaVista Linux Professional Edition. Customers can request help with installation, conÞguration, usage, and other questions concerning Pro. Generally, this software is fully supported for development and 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 Support Packages (LSPs) may be deemed for “development only.” This means one or both of the following: •
MontaVista Software still considers this LSP to be under development and does not guarantee, support, or recommend its use for deployment in end customer products.
•
MontaVista Software considers this LSP to be useful and supports the use of this LSP for customers to develop on and with. These LSPs usually are updated regularly and the customer should visit MontaVista Zone (http://support.mvista.com) to look for updates. The purpose of this classiÞcation is to get LSPs to customers as quickly as possible. The LSP may be as complete as it is planned to be, and following a release or update, the LSP will be changed from “development only” to “development and deployment.”
General technical assistance only is provided for third-party products that MontaVista Software recommends for use with Pro. This service may range from answering questions to providing work-arounds. Since MontaVista Software is not responsible for the development of these third party products, some issues may require input from the original applications vendor. Note that MontaVista only provides assistance for these products when they are being used with Pro. No assistance is provided for non-system software, e.g. games or I/O drivers for nonMontaVista Software certiÞed systems and boards. MontaVista Software maintains a hardware support environment of supported boards and systems to duplicate the reference hardware environment of the customer. If a customer is having a problem on a custom board or customized enhancements that they’ve made to our standard products, MontaVista Software may request that the customer duplicate the problem on a reference board Þrst before troubleshooting the problem. MontaVista Software wants your input regarding how well MontaVista Software is performing, 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
Chapter 2: Installation
Overview To use Pro 3.0, you Þrst need to install it on your host machine. Step-by-step instructions for installing Pro 3.0 for a cross-compilation development environment can also be found in the quick start guide for your target. For instructions on how to install Pro 3.0 on an IA-32/x86 target for a local-compilation development environment, see Using MontaVista Linux Professional Edition for Local Compilation. Pro 3.0 is distributed as a multiple CD-ROM set. The number and complement of CDROMs in your set depends on the product subscription you have purchased. Each Pro 3.0 subscription CD-ROM set contains: •
A “Pro 3.0 Host Binaries” CD-ROM, containing the components for all supported development host platforms
•
One or more Pro 3.0 target architecture CD-ROMs, containing the target platform components
•
A “Pro 3.0 Source” CD-ROM containing all of the source packages (SRPMS) corresponding to installable packages on the other CD-ROMs
To install Pro 3.0 for cross-compilation, you need to use the hhl-host-install tool. 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
Chapter 2: Installation Overview
•
“Removing Pro” on page 30
•
“Installing, Upgrading, or Removing Optional Packages” on page 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
Chapter 2: Installation Requirements
Requirements Before you begin, make sure your host and target machines meet the requirements provided below.
Host
Pro 3.0 supports a variety of different host environments for cross-compilation development. You may use any of the supported host systems with any of the supported 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 software that you need in order to install and use Pro. For Red Hat hosts, if you are using a standard Workstation installation (all versions) with X windows and Gnome or KDE and Software Development package groups (7.2 and 7.3) installed, you need to install dhcp (individual package) from the Red Hat installation CD-ROMs. For Red Hat 7.2 and 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, along with any restrictions and work-arounds for using a particular host, can be found in the host manuals. Regardless of which host system you are using, your system must meet the following requirements: •
For a basic installation of a single architecture and a single LSP, the host system must have a minimum of 1100 MB disk space available. Note: For each additional architecture, you need an additional 800 MB of disk space. For each additional LSP, you need an additional 150 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 either a serial connection to the host, or a VGA display and keyboard connected to the target. (Refer to the quick start guide for your target to determine your connection type.)
MontaVista™ Linux® Professional Edition
15
Chapter 2: Installation Requirements
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 different target 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 information about support levels, see “Support” on page 12.
16
MontaVista™ Linux® Professional Edition
Chapter 2: Installation The 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--help hhl-host-install--version hhl-host-install--install | --upgrade | --remove | --list [ --quiet | --verbose ] [ --confirm | --noconfirm ] [ --noprogress | --progress ] [ --media { /mnt/cdrom | <mediamountpoint> } ] [ --prefix { /opt |
Options
The following list contains a description of each option: •
--help This option produces an installer usage display similar to the above.
•
--version This option displays the version of the installer.
•
--install This option speciÞes operation of the installer which results in an install of all packages on a fresh system, or to install an additional LSP to an existing environment. If neither --install, --upgrade, --remove, or --list is speciÞed, --install is assumed.
•
--upgrade This option speciÞes an upgrade operation whereby existing packages are upgraded from copies on the distribution.
•
--remove This option speciÞes a remove operation to remove all or part of a previous MontaVista Linux installation from the host.
•
--list This option produces a listing of the LSPs on the distribution and/or previously 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 --list options are mutually exclusive.
•
--verbose This option speciÞes that installation steps are to produce verbose
MontaVista™ Linux® Professional Edition
17
Chapter 2: Installation The hhl-host-install Tool
output with respect to actions taken, such as complete lists of installed Þles.
18
•
--quiet This option speciÞes that installation steps produce compact output for each step. This is the default.
•
--progress This option displays progress bars ("#") during package installation.
•
--noprogress This option does not display progress bars during package installation. This is the default.
•
--confirm This option speciÞes that the user is prompted to make decisions about the progress of the installation process. This is the default. The instructions below assume that conÞrmation is in effect and show the types of prompts received in this mode.
•
--noconfirm This option speciÞes that the installation is to run unattended and default responses are assumed for actions which would evoke a prompt in conÞrmation mode. In some cases where a media change or password is required, operation cannot be completely unattended.
•
--media This option speciÞes the location of the distribution media. The default is the mount point of the distribution media, generally /mnt/cdrom, the default CD-ROM mount point. If another medium (such as NFS) or different CD-ROM mount point is used, specify the mount point for that distribution here.
•
--prefix This option speciÞes the installation location for the product. The default is /opt/hardhat, the MontaVista Linux default installation directory. If an alternate install directory is desired, specify it here.
•
--lsp
MontaVista™ Linux® Professional Edition
Chapter 2: Installation The hhl-host-install Tool
the --list option. In addition, the remove operation accepts the special values “all” or “hhl” to denote all LSPs. If
--package <package-name> This option speciÞes a single host, cross-development, or target architecture package to be installed, upgraded, or removed according to the operation selected. The operation modiÞes the installed MontaVista Linux environment. Incorrect use of this option may render the cross-development environment or the target board unusable. This option has no default. <package-name> is the MontaVista Linux RPM package name beginning with “hhl-”. Installed MontaVista Linux packages may be listed using RPM. All package-oriented operations must take place using a single installation location speciÞed by --prefix or using the default in this 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. An afÞrmative reply is required to continue. An attempt to install a package already installed, or remove a package not installed, results in an error. However, it is okay to upgrade a package that is already installed.
MontaVista™ Linux® Professional Edition
19
Chapter 2: Installation Displaying the Product Directory
Displaying the Product Directory To display a list of all the LSPs contained in the product along with the location of those 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 used need 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 product directory. To see the complete list of LSPs in the product, enter the following command: /mnt/cdrom/bin/hhl-host-install --list
To see an abbreviated list of LSPs that match a pattern, enter the pattern using Linux Þle-name pattern-matching characters. /mnt/cdrom/bin/hhl-host-install --list
For example: /mnt/cdrom/bin/hhl-host-install --list motorola*
Note: You may need to quote the
Target Board
Location
Under “LSP Name” is the name by which you identify the LSP to the installation tool for installation, upgrade, or removal; for example, as part of the --lsp
20
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Displaying the Product Directory
Under “Location” is the text of the printed label for the CD-ROM on which the LSP is distributed. It may be the same CD-ROM currently mounted for the --list operation, or any other CD-ROM in the product set. Note: You may not have subscribed to all architectures included in Pro; therefore, you may 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
Chapter 2: Installation Installing 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 product installed and you would like to upgrade to Pro, follow the instructions in “Upgrade” on page 24. Note: Even if you are not installing the same LSP as in the previous version, you need to upgrade to the Pro rather than perform a new installation because the required host packages must be upgraded.
•
If you have already installed Pro 3.0 (or upgraded to Pro 3.0) and you want to install or upgrade an additional LSP, follow the instructions in “Installing or Upgrading an Additional LSP” on page 28.
Warning! Some of the host OS default installations do not include all of the software that you need to install and use Pro. Information about the additional components and steps required for a particular host along with any restrictions and work-arounds for using a particular host can be found in the host manuals. Host manuals are located on the “Pro Host Binaries” CD-ROM in the /docs/hostmanuals directory. Host manuals are also available on MontaVista Zone.
Install
The following steps are used to install the Pro product for the Þrst time. First-time Pro installation requires two CD-ROMs: •
The “Pro Host Binaries” CD-ROM, which applies to all installations
•
The target architecture CD-ROMs, containing the target LSP you want to install Note: You may identify the correct target architecture CD-ROM using the tables in appendix A of the quick start guide for your target or by using the --list option of the installation tool. The label 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 Þrst CD-ROM and the installation will not proceed. For this reason, you should either print out this documentation or make a local copy on your machine. Viewing the documentation from the CD-ROM will cause the CD-ROM device to be busy.
22
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing 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 to run the tool, as this will cause the tool to be unable to unmount the Þrst CD-ROM. To install to an alternate location, include the --prefix
6.
Enter the name of the LSP that corresponds to the target platform hardware you wish to install. LSP names are listed in the quick start guide for your target. LSP names can also be listed by typing ? at the prompt. A list of LSP names will be displayed and the prompt above will be repeated. The host platform packages will be installed into the location selected in step 5. The installation tool ejects the “Pro Host Binaries” CD-ROM and displays the message:
MontaVista™ Linux® Professional Edition
23
Chapter 2: Installation Installing or Upgrading Pro
hhl-host-install: Insert MontaVista Linux
Insert the appropriately-labeled CD-ROM speciÞed in the message into the 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 architecture CD-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 more information, see “Trouble-Shooting” on page 34.
Upgrade
Important: The Pro 3.0 installation tool allows you to use the --upgrade option to upgrade 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.1 already installed on your host machine.
Should I upgrade? While we generally recommend that you upgrade to Pro 3.0, there are some situations where we recommend not upgrading at this time. These include: •
If you are using a MontaVista add-on product (such as VisualAge Micro Edition 1.4 for MontaVista™ Linux®) that has not yet been updated for use with Pro 3.0. Upgrading to Pro version 3.0 will cause the add-on to no longer function correctly. If your project relies on having the add-on functionality available, we recommend not upgrading at this time.
•
If you decide to upgrade to Pro 3.0, you must upgrade all LSPs at once. Failure to do so will “break” the LSPs that were not upgraded. If you are using multiple LSPs and your development cycle prohibits upgrading all LSPs, you may not want to upgrade at this 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
Chapter 2: Installation Installing or Upgrading Pro
Installations of Pro 3.0 and Pro 2.1 CANNOT coexist, because they use a shared RPM database; therefore, the installation tool upgrades MontaVista-distributed packages in place. For that reason, you must upgrade Pro 3.0 using the same directory as 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 all installations
•
The Pro 3.0 target architecture CD-ROM, containing the target LSP you want to install Note: You may identify the correct target architecture CD-ROM using the tables in appendix A of the quick start guide for your target or by using the --list option of the installation tool. The label 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 Þrst CD-ROM and the installation will not proceed. For this reason, you should either print out this documentation or make a local copy on your machine. Viewing the documentation 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
Chapter 2: Installation Installing or Upgrading Pro
Warning! Do NOT change directories to the CD-ROM mount point to run the installation tool, as this will cause the tool to be unable to unmount the Þrst CD-ROM. To install at an alternate location, include the --prefix
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.)
Enter the name of the LSP that corresponds to the target hardware you wish to install. LSP names are listed in the quick start guide for your target. LSP names can also be viewed by typing ? at the prompt. A list of LSP names will be displayed and the prompt above will be repeated. The host platform packages will be installed into the location selected in step 5. The installer ejects the “Pro 3.0 Host Binaries” CD-ROM and displays the message: hhl-host-install: Insert the MontaVista Linux
Insert the target architecture CD-ROM speciÞed in the message into the CD-ROM drive and press Enter. The appropriate target platform 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 architecture CD-ROM.
26
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing or Upgrading Pro
If the upgrade is successful, you receive a message indicating upgrade is complete. In the event of a failure, review the error message and correct the problem. For additional information, see “Trouble-Shooting” on page 34.
MontaVista™ Linux® Professional Edition
27
Chapter 2: Installation Installing 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 to Pro version 3.0 for at least one LSP. To install Pro version 3.0 for the Þrst time, use the steps 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-ROM containing the desired target platform LSP. The correct target architecture CD-ROM is listed in the quick start guide for your target. You may also use the --list option of the installation tool. The label of the correct target architecture CD-ROM is displayed 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 additional LSP 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 default location, /opt/hardhat, use the command: /mnt/cdrom/bin/hhl-host-install
Warning! Do NOT change directories to the CD-ROM mount point to run the installation tool, as this will cause the tool to be unable to unmount the Þrst CD-ROM. If hhl-host-install is run while accessing the mounted CDROM, the installer will abort. If the CD-ROM is referenced from another 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 the command: /mnt/cdrom/bin/hhl-host-install --upgrade
To install (or upgrade) to an alternate location, include the --prefix
28
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing or Upgrading an Additional LSP
/mnt/cdrom/bin/hhl-host-install --prefix
Enter the name of the LSP that corresponds to the target platform hardware you wish to install. LSP names are listed in the quick start guide for your target. LSP names can also be viewed by typing ? at the prompt. A list of LSP names will be displayed and the prompt above is repeated.
All target platform packages related to the selected LSP are installed at the location selected in step 4. Packages which were previously installed as part of another LSP are 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
Chapter 2: Installation Removing Pro
Removing Pro If you installed the incorrect LSP or would like to remove your installation of Pro, use hhl-host-install. Note: For removals, the Pro CD-ROM does NOT need to be available. Once Pro is installed, 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 in a location other than the default, replace /opt in the path above and in the commands below 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 were originally installed. You may also remove the last remaining LSP. In this case, the host platform 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
You receive a message conÞrming your intentions: hhl-host-install: This operation will remove all installed
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 components that 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
Chapter 2: Installation Removing 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 components that these services may depend on are no longer present on your system.
MontaVista™ Linux® Professional Edition
31
Chapter 2: Installation Installing, Upgrading, or Removing Optional Packages
Installing, Upgrading, or Removing Optional Packages Not 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 if installed simultaneously. See “Pro Applications” on page 197 for a list of applications appearing 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 (and therefore the optional target application) you need 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 with the --package <package-name> option to 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 “Pro Applications” 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 was previously 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
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) For example, to install the optional dhcpcd package for a Pentium II target when the non-default installation directory /group1 was
32
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Installing, Upgrading, or Removing Optional Packages
previously chosen for Pro installation, you would use the following command: /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 of mutually exclusive packages you may, for example, remove a previously installed optional package from a mutually exclusive set and install an alternative package from 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 to continue. An attempt to install a package already installed, or remove a package not installed, results in an error. However, it is okay to upgrade a package that is already installed.
MontaVista™ Linux® Professional Edition
33
Chapter 2: Installation Trouble-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 automounter running, logging into a KDE or Gnome desktop and then using the su command to become 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 runs under a non-root userID. Under these conditions, the automounter will mount the distribution CD-ROM using the noexec option (implied by user), rendering the hhl-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 root login desktop session rather than using the command su root from a non-root desktop session. Another option is to disable the automounter. To disable the automounter, you need to edit the Þle /etc/fstab to either add the exec option before 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 eject the Þrst CD-ROM and installation will not proceed. Three of the most typical reasons are: •
For some desktop environments, when the automounter mounts a CD-ROM, a Þle-system browser window appears. You need to close this window to allow the CD-ROM to be unmounted by the installer.
•
If you changed directories to the CD-ROM mount point to run the installation 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 cause the CD-ROM device to be busy. You should either print this manual or make a local copy on your machine.
Unable to burn CDs Pro CD images can be downloaded via MontaVista Zone. MontaVista Software recommends burning CDs and installing from those CDs. If you are unable to burn CDs, Pro can be installed from the CD images using the --media-host or
34
MontaVista™ Linux® Professional Edition
Chapter 2: Installation Trouble-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 a command 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 you wish to install that you previously downloaded, using a loopback mount. Loopback mounts are available only on Linux host systems. Use a command 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 location of the two CD images: /mnt/prof-host/bin/hhl-host-install --install --media-host <mounted-cdimage-dir> --media-arch <mounted-cdimage-dir>
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) <mounted-cdimage-dir> is the CD image mounted on /mnt/profhost or /mnt/prof-arch. You may run the hhl-hostinstall tool from either the CD image mounted on /mnt/profhost or /mnt/prof-arch. The same installation tool is provided in both CD images. If the <prof-target-cdimage-Þle> you supply does not correspond to the correct architecture for
MontaVista™ Linux® Professional Edition
35
Chapter 2: Installation Trouble-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
Chapter 3: The Development Environment
Overview Pro contains everything you need to build an embedded Linux kernel. Full source is provided to allow for a custom kernel and for custom device drivers, as well as for application development. For more information about the Pro directory structure installed, see “Pro File-System Layout” on page 189. Included in the Pro distribution are over 280 application packages. If you do not know how to use these applications, man and info pages are available that can help. A complete list of the applications, along with a brief description and pointers to reference 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 ready to begin development. This chapter provides step-by-step instructions on how to conÞgure your development environment to allow you to easily use the tools included with 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
Chapter 3: The Development Environment Project Directories
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 you need to modify to a work directory elsewhere on your host. We make this recommendation for the following reasons: •
It allows you to easily return to the default conÞgurations provided by MontaVista Software.
•
The /opt/hardhat/devkit/<architecture>/ <processor>/target/ directory is used by the MontaVista Target 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 steps below: 1.
Create project directories.
2.
Populate your project directories with copies of the default Þles from MontaVista 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 a work directory structure such as the following: my_work_directory /mykernel /myapplication /myfilesystem
The mykernel directory can be used for kernel development. The myapplication directory can be used for application development. The myfilesystem directory is where you can integrate your Þle system hierarchy and your 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 project directories. The sections below describe what we recommend each project directory contain.
mykernel In this directory, you should place a copy of your development kernel. How you copy the development kernel over depends on whether you are using Target ConÞguration
38
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Project Directories
Tool (TCT) (recommended), or another utility, such as make menuconfig, for your kernel development. TCT. If you are using TCT, when you create your TCT project directory, select the mykernel directory to save your project. TCT will automatically copy everything you need for kernel and Þle-system development to the mykernel directory. make menuconÞg. If you are using another tool, such as make menuconfig, use the following commands to copy everything in the appropriate linux directory in the kernel source tree to your mykernel directory: cd my_work_directory/mykernel cp -a /opt/hardhat/devkit/lsp/
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 another method for copying the Þles over, be sure to include options for copying symbolic linking and permissions.
myapplication Use this directory to build your application. At this time, there is nothing that needs to be copied from the Pro distribution to your application work directory for you to begin development. If you are using KDevelop, you need to specify this directory when setting up your project.
myÞlesystem In this directory, you will eventually want to create a sub-directory for each of your test Þle systems. The Þle system we recommend you start with is a copy of the target’s default root Þle system directory. Other Þle systems you will want to test are those that 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 Þles are 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 convenient location for testing your application on the target.
MontaVista™ Linux® Professional Edition
39
Chapter 3: The Development Environment Running Pro Applications and Tools
Running Pro Applications and Tools Pro includes over 280 application packages. Applications are classiÞed as “crossdevelopment applications,” “host applications,” or “target applications.” Cross-development applications are tools that are run on the host but produce output intended to run on the target. In general, the cross-development applications are compilers, 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 compatible version of TFTP. For the list of host applications, see “Host Application Packages” on page 200. Target applications are intended to be used only on the corresponding architecture target. The Pro distribution contains pre-compiled and pre-packaged versions of these application packages so that RPM can be used to install them on the target. For development, we recommend that NFS be used to provide the target root. The Þle system served by NFS is considered part of the target system, and therefore contains only target application packages (i.e., “host” and “cross-development” packages are not installed into this NFS portion of the Þle system). For the list of target applications, see “Target Application Packages” on page 204.
40
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Running Pro Applications and Tools
The chart below shows the full installation paths for the Pro applications and tools. If you installed Pro using relocation, replace /opt in the paths listed below with the path you used. Applications Target
Path 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
Crossdevelopment
/opt/hardhat/devkit/<architecture>/<processor>/bin
To run any of Pro applications, update your executable search path to include the Pro applications. 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 the application start command at the host or target system prompt. For help on any of the applications, see the man or info page for that application. For more information, see “Accessing man and info Pages” on page 44.
MontaVista™ Linux® Professional Edition
41
Chapter 3: The Development Environment Running Pro Applications and Tools
Note: Cross-development applications contain a preÞx indicating the target architecture and processor. For a list of the preÞxes, see “Cross-Development Application PreÞxes” on page 42. For example, to update your executable search path to include the Pro host applications 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)
CrossDevelopment Application PreÞxes
Cross-development applications use a preÞx that indicates the architecture and processor in the application’s start command. For example, to run GCC to compile code 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 CPU architecture and processor types. Architecture and Processor
42
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
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Running Pro Applications and Tools
Architecture and Processor
Prefix
Example
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
MontaVista™ Linux® Professional Edition
43
Chapter 3: The Development Environment Accessing man and info Pages
Accessing man and info Pages Linux has fairly extensive online documentation. Most of the applications included with Pro have man and/or info pages available. Info pages are online manuals for the given application. A typical man page provides a description of the application and its options, 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 the chart below. If you installed Pro using relocation, replace /opt in the paths listed below with the path you used.
Applications
Path
Target
/opt/hardhat/devkit/<architecture>/<processor>/target/ usr/share/man
Host
/opt/hardhat/host/man
Cross
/opt/hardhat/devkit/<architecture>/<processor>/man
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 search path 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 for the host applications for bash, use the command: export MANPATH=/opt/hardhat/host/man:$MANPATH
44
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Accessing 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 the following command at the host or target system prompt: man
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 man pages are displayed, enter the command: man -aw
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 for man. 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 the chart below. If you installed Pro using relocation, replace /opt in the paths listed below 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
Chapter 3: The Development Environment Accessing man and info Pages
Viewing info pages To view info pages for any of the Pro applications, update your executable search path to 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 for the 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 the following command at the host or target system prompt: info
For example, to view the info page for bash, enter the command: info bash
46
MontaVista™ Linux® Professional Edition
Chapter 3: The Development Environment Accessing man and info Pages
Additional information Additional information about info pages can be obtained by reading the info page for info. To view the info page for info, enter the command: info info
MontaVista™ Linux® Professional Edition
47
Chapter 3: The Development Environment Other 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:
48
•
/opt/hardhat/devkit/<architecture>/ <processor>/doc
•
/opt/hardhat/host/doc
•
/opt/hardhat/devkit/lsp/
MontaVista™ Linux® Professional Edition
Chapter 4: Target ConÞguration and Boot
Overview Once you have installed Pro on your host machine and conÞgured your development environment, 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” on page 50
•
“Booting the Target with a Custom Kernel” on page 52
•
“Using Minicom” on page 54
MontaVista™ Linux® Professional Edition
49
Chapter 4: Target Configuration and Boot Booting 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 Software provides a quick start guide. The quick start guides contain step-by-step instructions for booting Pro on the target for a cross-compilation development environment. For instructions on how to install Pro for local-compilation development on an IA-32/x86 target, see Using MontaVista Linux Professional Edition for Local Compilation. Copies of the Pro quick start guides and the local-compilation manual can be found on the “Pro Host Binaries” CD-ROM in the /docs/quickstarts directory. In addition, as updates are made, the latest versions will be available on MontaVista Zone. In general, booting the target for cross-compilation development consists of the following steps: Warning! These steps are generic. For step-by-step instructions for your target, see the Pro quick start guide for your target. 1.
Hardware setup. This involves connecting the target to the host using a serial connection and connecting the target to a LAN. Some targets also require a speciÞc power supply setup or Abatron BDI setup. For others, hardware setup may also include changing DIP switches or installing EEPROMS.
2.
Minicom (or other terminal emulation program) conÞguration. You need to use a terminal emulation program such as Minicom to communicate with your target. For step-by-step instructions on using Minicom, see “Using Minicom” on page 54. The parameters for communicating with your 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 host IP address. Some targets also require you to set the connection speed.
4.
Host conÞguration. Many of the targets use a network boot. All targets mount their root Þle system via NFS. Depending on the Þrmware used by your target, you’ll need to conÞgure all or some of the following host services: 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, MontaVista Software provides host manuals. These manuals provide host requirements, step-by-step instruction on how to conÞgure the required host services, and notes on using that host for development. Host manuals are available for Solaris, SuSE, and Mandrake. Copies of the Pro host manuals can be found on the “Pro Host Binaries” CD in the / docs/hostmanuals directory. In addition, as updates are made, the latest versions will be available on MontaVista Zone.
50
MontaVista™ Linux® Professional Edition
Chapter 4: Target Configuration and Boot Booting the Target with the MontaVista Supplied Kernel
5.
Booting the target. To boot the target, the Þrmware often requires a command to begin the booting sequence. The commands are Þrmware speciÞc.
6.
Once Linux boots, you are placed at a login prompt:
7.
At this point, you can login as root with no password. You are placed at a bash shell prompt. Note: We recommend that you change the root password as soon as possible.
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 to work. Once you have proven that the target boots, you can begin development. Note: In the chapter “The Development Environment” on page 37, we recommended creating a directory called “myfilesystem” as a location for doing Þle-system development. We recommend that you NFS export this directory in addition to the default system created by MontaVista Software. By exporting the Þle-system directory as NFS, you can test your environment on the target before spending the development time to reduce the Þle-system size or adding the Þle system to ßash. In general, you will want to continue using the NFS-mounted root Þle system until Þnal deployment. For more information about how to NFS export an additional directory, see “How to NFS export your Þle-system project directory” on page 53.
MontaVista™ Linux® Professional Edition
51
Chapter 4: Target Configuration and Boot Booting 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 the system.map Þle in the top level of the Linux tree. For compressed images, 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 the kernel image in /tftpboot to the new kernel image.The image name and 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 directory of the local system for your target. Loadable module are typically located in /lib/modules. If you don’t already have a directory for your modules, create one by using the command: mkdir /
•
Copy your modules to the directory you just created. Use the command: cp -a /<module>
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) <module> is the full path and name of the module you wish to include. 3.
Add a line in the /etc/rc.sysinit Þle on the target to insmod the module. See the man page for insmod for information about use and syntax.
4.
Complete the steps listed in the quick start guide for your target using the new kernel image and path, rather than the default kernel images and paths listed in the manual. Note: The quick start guide for your target includes information about how to NFS export the target’s default root Þle system directory (/opt/hardhat/devkit/<architecture>/<processor>/ target/). In the chapter “The Development Environment” on page 37, we recommended creating a directory called “myfilesystem” as the location for Þle-system development. We recommend that you NFS export this directory in addition to the default system created by MontaVista Software. By exporting the Þle system directory as NFS, you can test your environment on the target before spending the development time to reduce the Þle-system size or adding
52
MontaVista™ Linux® Professional Edition
Chapter 4: Target Configuration and Boot Booting the Target with a Custom Kernel
the Þle system to ßash. In general, you will want to continue using the NFS-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 can be exported as the root Þle system. In addition to conÞguring NFS, if you would like to make a particular directory the target’s root Þle system directory, you also need to reconÞgure DHCP. To specify that a directory should be the root Þle system, follow the instructions in the quick start guide (or appropriate host manual, if you are not using a Red Hat host) to conÞgure DHCP. Be sure to replace the line /opt/ hardhat/devkit/<architecture>/<processor>/target/ in the DHCP conÞguration Þle with the path to the directory you want to use for the root Þle system.
MontaVista™ Linux® Professional Edition
53
Chapter 4: Target Configuration and Boot Using Minicom
Using Minicom Minicom is a terminal emulation and modem interface program included in most Linux 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: Filenames and paths File transfer protocols Serial port setup Modem and dialing Screen and keyboard Save setup as dfl Save setup as.. Exit Exit from Minicom
2.
Select Serial port setup and set the options for your target. The quick start guide for your target contains the parameters you need to set to be able to communicate with your target. Note: The serial device values given are typical. They can change depending 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.
A B C D E F G H I J
-
Init string ......... Reset string ........ Dialing prefix #1.... Dialing suffix #1.... Dialing prefix #2.... Dialing suffix #2.... Dialing prefix #3.... Dialing suffix #3.... Connect string ...... No connect strings ..
K L M N O
-
Hang-up string ...... Dial cancel string .. Dial time ........... Delay before redial . Number of tries .....
ATDT ^M ATDP ^M ATX1DT ;X4D^M CONNECT NO CARRIER NO DIALTONE ^M 45 2 10
Q R S T
-
BUSY VOICE Auto bps detect ..... Modem has DCD line .. Status line shows ... Multi-line untag ....
P - DTR drop time (0=no). 1 Change which setting?
54
MontaVista™ Linux® Professional Edition
(Return or Esc to exit)
No Yes DTE speed No
Chapter 4: Target Configuration and Boot Using Minicom
Start 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.
When you enter Minicom again, you are able to communicate with your target by using the command: minicom
Note: You may need to initiate a board hardware reset after restarting Minicom to successfully 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.
Help
Press Enter to exit.
For help using Minicom, complete the following step: 1.
Use the following command: control-A Z
MontaVista™ Linux® Professional Edition
55
Chapter 5: Target ConÞguration Tool (TCT)
Overview Now that you have Pro installed and your target booted, you are ready to begin development of your embedded application. To help you right-size the Linux kernel and create an optimal Þle system, MontaVista Software provides Target ConÞguration Tool (TCT). This GUI-based utility enables you to select only needed modules and drivers for inclusion in kernel builds, allowing bootable footprints scaled below 500K. Using TCT avoids the drudgery of hand-editing conÞguration and make Þles while managing dependencies among components. TCT also lets you choose pre-built packages for inclusion in your Þle system, including system binaries and data. As the base for kernel and Þle-system development, TCT uses the Þles and conÞgurations provided in the reference LSP selected for your project. By starting with the default system provided in the LSP, you can greatly reduce your development time, 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 system package selections. By allowing you to maintain multiple conÞgurations, TCT allows you 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
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 create a 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 Pro applications. Instructions on how to run Pro applications can be found in “Running Pro Applications and Tools” on page 40. The Project Manager window appears:
Create a New Project
58
To create a new project, complete the following steps: 1.
Click the New Project button in the right-hand pane of the Project Manager window.
MontaVista™ Linux® Professional Edition
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 must have a unique name.
•
Directory... This is the directory where the project is stored. If you click on the Directory... button, a Directory Selection dialog box appears. From there, you can browse to and choose an empty directory you already created or click the New Directory button to create 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 select an LSP. Selecting an LSP ensures that the correct default target directory and cross-compilers are used by TCT for your target board. In addition, by selecting an LSP, you have a kernel that is known to boot on the reference board as a starting point for your development.
•
If you are using a custom kernel, make sure Use Custom Kernel is selected. Note: If you do not select the Use Custom Kernel option, TCT assumes 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
Chapter 5: Target Configuration Tool (TCT) Starting TCT
A project directory is created, and if you are using a custom kernel, the kernel is copied to the new directory. Copying the kernel can take some time (there is no progress indicator).
Open a Project
Remove 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 Open Project button in the right-hand pane of the Project Manager window.
•
Or simply double-click on the name of the project in the left-hand pane of the Project Manager window that you want to open.
To remove an existing project, complete the following step: 1.
Highlight the project you want to remove, then click the Remove Project 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 to remove these Þles from your system, you must do so manually.
60
MontaVista™ Linux® Professional Edition
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. For each 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. You can 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
Chapter 5: Target Configuration Tool (TCT) TCT Project Menus
Once selected, a conÞguration selection dialog box appears. Select the conÞguration you 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 .cfg extension.
Close ConÞg Select this option to close the conÞguration that you are viewing without saving changes.
Build Target Select this menu option to build the kernel and Þle system for your target.
62
MontaVista™ Linux® Professional Edition
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 easy identiÞcation. The build log is also stored in the project directory.
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. You can scroll through the status messages to Þnd out what happened. Click Done when you are Þnished.
MontaVista™ Linux® Professional Edition
63
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 set options for the Þnal build using the View menu.
Kernel ConÞgure This view can be used to change kernel conÞguration parameters. The interface for editing the conÞguration is the same as when using make xconfig in the Linux source 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Þcally stated on the MontaVista Zone page for your target are supported.
64
MontaVista™ Linux® Professional Edition
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. The packages in a selected group are displayed in a hierarchical manner in the pane on the right. When an arrow pointing to the right is displayed next to the name of a package or 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 it again to hide the subcomponents. For more information about how to list which packages are in which group, see “The targetpkg Utility” on page 73. Warning! The checkboxes only show the packages you selected. If a package has a dependency on another package, that package is automatically installed with the selected package; however, the check box for that package remains unchanged. At the bottom of the Package Selector view are two values - Total size and Stripped size. •
Total Size is the total size of the packages selected.
•
Stripped Size is the total size of the packages selected once they have been ‘stripped’ of all symbol information.
Using the Target Options view, you can decide if you want to strip the binaries before they 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
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 Options This category always includes the option to Strip Binary Files.
•
Install Kernel Files This category is for custom kernels only. The options displayed here are different for each kernel. For most LSPs, these options include the type of kernel images to build and place in the Þle system tar archive created when you build the target. You want to make sure to select the kernel image type required for your target. The Kernel Modules option is almost always present, and it is selected by default – any modules that are conÞgured by the kernel conÞguration selections will be installed. No options are available when using a pre-built kernel.
•
66
Filesystem Image TAR Þle name: Use this Þeld to enter the Þle name that you would like the tar archive saved as. The default name is fsimage.tar. If you are saving multiple conÞgurations, to prevent overwriting an older conÞguration, make sure you change this Þle name.
MontaVista™ Linux® Professional Edition
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 Info menu.
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
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 the following TCT activities:
Create a ConÞguration File
•
“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
You can use TCT to create a target conÞguration Þle. A target conÞguration Þle contains the options you have selected for your target Þle system, the options selected for your custom kernel conÞguration, and options regarding how to build the target kernel 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 make menuconfig or by running make xconfig independent of TCT are NOT stored in 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 or build 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 new conÞ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 .cfg extension.
68
MontaVista™ Linux® Professional Edition
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 following steps: 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 TCT project. (See “Starting TCT” on page 58.) Warning! Changes made to the kernel conÞguration using another tool such as make menuconfig or by running make xconfig independent of TCT are NOT stored in your project’s conÞguration Þle. To create/edit a new kernel conÞguration for your project, complete the following steps: 1.
Open your project and the conÞguration you want to edit. (See “Starting TCT” 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-time enhancements, standard devices, or Þle-system types, see “Linux Kernel Development” on page 75. Note: While many features are available for conÞguration, only features speciÞcally stated on the MontaVista Zone page for your target are supported.
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
Chapter 5: Target Configuration Tool (TCT) Using TCT
The kernel options are now saved in the open conÞguration Þle. TCT does not build the kernel until the Build Target option from the File menu is selected. For more information, 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 product determines the size and type of Þle system, which in turn dictates how many applications can be included. You should be aware of the type of Þle system you want to use in your deployed product before creating the Þle-system hierarchy, as different Þle-system types have different constraints. The section “Select a Deployment FileSystem Type” on page 145 has some information about the features and limitations of each 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 “Starting TCT” 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 on the left. For more information about how to list which packages are in each 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. (Also in 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 automatically selects a useful subset of its associated subcomponents. You may also select or deselect any of the subcomponents if you wish to control the selections at a Þner level. When you select a package, the Package Selector reports any conßicts with other packages already selected. Warning! The checkboxes only show the packages you selected. If a package has a dependency on another package, that package is automatically installed with the selected package; however, the check box for that package remains unchanged. Note: At the bottom of the Package Selector view are two values - Total size and Stripped size. As size is a major consideration for many
70
MontaVista™ Linux® Professional Edition
Chapter 5: Target Configuration Tool (TCT) Using TCT
embedded development projects, pay attention to these values as you build your Þle system. 5.
Select Save ConÞg from the File menu to save your changes to the current 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 more information, 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 current open conÞguration, complete the following steps: 1.
From the View menu, select Target Options. The Target Options window appears.
2.
Select the build options you want to use. Be sure to change the name of the Þle-system image, or you may overwrite a previous image. For more information about the options available, see “Target Options” on page 66. Note: You should select the kernel image format you need for your target in this screen. If you do not, you will need to convert the kernel image to the correct format before booting.
3.
Select Save ConÞg from the File menu to save your changes to the project 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 in red text for easy identiÞcation. This build log is also stored in the project directory. 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 this point you can scroll through the status messages to Þnd out what happened.
5.
Click Done when you are Þnished.
The build process creates a tar archive of the Þle system (and kernel) in your project directory. See “Using the Tar Archive Created by TCT” on page 72 for more information 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 make menuconfig or by running make xconfig independent of TCT were NOT stored in your project’s conÞguration Þle, and therefore not built in the kernel.
MontaVista™ Linux® Professional Edition
71
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 project directory. The tar archive contains: •
a Þle-system hierarchy with the applications and libraries you selected
•
kernel images – depending on the selections you made in the Target Options screen, there may be multiple kernel images of different formats
The tar archive must be extracted for use for kernel development or Þle-system development. 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 you created for your Þle system.
3.
Use GNU tar to untar the Þle-system tar archive into your Þle-system directory. For example, to untar the Þle project1.tar into the directory 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 and group 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 Target Options screen, you should have a kernel image of the correct type to boot your target.
•
If your CPU or board Þrmware uses an image type not available on the Target Options screen, or you did not select the image type you need, 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 a Custom Kernel” on page 52.
72
MontaVista™ Linux® Professional Edition
Chapter 5: Target Configuration Tool (TCT) The targetpkg Utility
The targetpkg Utility Included with TCT is a command-line utility called targetpkg. This utility allows you to list the TCT groups with the packages and Þles in the groups. To use targetpkg, you need to update your executable search path to include the Pro applications. Instructions on how to run Pro applications can be found in “Running Pro Applications and Tools” on page 40.
Usage
Use of the targetpkg utility is described below. targetpkg [-f] <architecture>_<processor>
targetpkg accepts the following option: •
Examples
-f List all Þles. By default, targetpkg only lists the packages.
If you want to see all of the packages listed in TCT for a PowerPC 8xx target, you would use the command: targetpkg ppc_8xx
You would see output similar to the following: admin admin web devel doc ...
adduser anacron apache apache-dev apache-html_manual
In the example above, the Þrst column is the TCT group and the second column is the package. If you want to see all of the packages and Þles listed in TCT for a PowerPC 8xx target, you would use: targetpkg -f ppc_8xx
You would see output similar to the following: admin admin admin admin admin ...
adduser/base adduser/base adduser/base adduser/base adduser/base
/etc/adduser.conf /etc/deluser.conf /usr/lib/perl5/AdduserCommon.pm /usr/sbin/adduser /usr/sbin/deluser
In the example above, the Þrst column is the TCT group, the second column is the package, and the third column is the Þle.
MontaVista™ Linux® Professional Edition
73
Chapter 6: Linux Kernel Development
Overview The kernel binary is at the core of every MontaVista Linux execution. It handles scheduling, resource allocation, and use of programs. Pro provides you with two kernels: an LSP-speciÞc kernel and a generic kernel. The LSP kernel (with MontaVista Software patches) is built speciÞcally for the supported reference boards. MontaVista recommends that you use the LSP kernel for all development. The sources for this kernel are installed automatically when you install Pro and can be found in: /opt/hardhat/devkit/lsp/
“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
Chapter 6: Linux Kernel Development Building 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 GUIbased tool that provides you with the ability to easily choose kernel options and select target Þle system packages. You can also use TCT to manage kernel builds and to control options such as whether target binaries are stripped. In addition, TCT supports multiple 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 make menuconfig or by running make xconfig independent of TCT are NOT stored in 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 following steps: 1.
Copy everything in the appropriate linux directory in the kernel source tree to the directory where you wish to build the new kernel. Use the command: cp -a /opt/hardhat/devkit/lsp/
(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 upgrading Pro. For that reason, we strongly recommend that you copy everything to a build directory, such as mykernel. For example: cp -a /opt/hardhat/devkit/lsp/
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) 2.
Change to the directory containing your copy of the kernel. For example: 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
Chapter 6: Linux Kernel Development Building and Configuring the Kernel
make menuconfig
Use this command to select conÞguration options from hierarchical groups. To enable an option using make menuconfig, place an asterisk (*) 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 CPU options, make menuconfig will not correctly conÞgure the kernel. make xconfig
This is a mouse-driven conÞguration tool. To enable an option, click the check box for “yes” next to the option you wish to enable. Note: To run any of the Pro tools, you need to update your executable search path to include the Pro applications and tools. Instructions on how to run Pro tools, can be found in “Running Pro Applications and Tools” on page 40. Note: While many features are available for conÞguration, only features speciÞcally stated on the MontaVista Zone page for your target are supported. Note: If you intend to use loadable kernel modules, you must ensure that Loadable module support is enabled in your conÞguration. For more information about kernel modules, see “Enabling Loadable Kernel Modules” on page 80. 4.
Remove old kernel images, dependency Þles, or other old Þles that may disrupt 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, you do not need to do anything.
MontaVista™ Linux® Professional Edition
77
Chapter 6: Linux Kernel Development Building 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 the new kernel image to the appropriate location for your target to replace the default kernel image. For example, if you were to use a PowerPC 8xx target, you would use the command: ppc_8xx-objcopy -O srec vmlinux vmlinux.srec
For example, if you were to use a MIPS ßoating point little-endian target, 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 littleendian target, you would use the command: arm_920t_le-objcopy -S -O srec compressed/vmlinux vmlinuz.srec
-R
.stack
arch/arm/boot/
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) or arm_720t_le-objcopy -S -O srec compressed/vmlinux vmlinuz.srec
-R
.stack
arch/arm/boot/
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) 8.
If you conÞgured any of the parts of the kernel as a module and enabled Loadable 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 is required if you enabled or disabled any modules. If you do not recompile the modules, you will receive “unresolved symbols” errors during or after kernel boot. 9.
Boot the target. For instructions on how to boot the target with your new kernel, see “Booting the Target with a Custom Kernel” on page 52.
For more information about conÞguring and building the kernel, see the README Þle and the Þles in the Documentation subdirectory in the kernel source directory. Warning! Changes made to the kernel conÞguration using tools such as make menuconfig or by running make xconfig independent of TCT are NOT stored in your TCT project’s conÞguration Þle, and therefore will not be built in the kernel
78
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building and Configuring the Kernel
created by TCT. If you did not use TCT for your kernel development but did use TCT for your Þle-system development, ignore the kernel generated by TCT.
MontaVista™ Linux® Professional Edition
79
Chapter 6: Linux Kernel Development Enabling Loadable Kernel Modules
Enabling Loadable Kernel Modules Rather than having all device drivers built into the kernel, the Linux kernel supports loadable modules – that is, modules that can be inserted or removed from memory at runtime. The advantage of loadable kernel modules is that you do not need to rebuild the kernel to test or enable a new device. When building your own custom device driver, we recommend that you Þrst write and test your device driver as a loadable kernel module (see “Building Custom Device Drivers” on page 88). For that to work, you need to ensure that support for loadable modules has been enabled in the kernel. Loadable kernel modules is on by default in most LSPs. To enable loadable kernel modules, complete the following steps: 1.
Start make menuconfig or make xconfig. The latter can be run on 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 and ConÞ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 those applications.
80
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling 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 in improving the real-time performance characteristics of the Linux kernel. This approach to real-time Linux doesn't alter the APIs of the programming model. By leveraging the inherent capabilities of the kernel, changes required of applications that utilize these real-time performance improvements are minimized. MontaVista Software engineering efforts into benchmarking and improving the realtime performance of the Linux kernel have resulted in the following improvements to the kernel:
MontaVista RealTime Scheduler
•
“MontaVista Real-Time Scheduler” on page 81
•
“Preemptible Kernel” on page 82
The MontaVista Real-Time Scheduler (RTS) is a supplemental scheduler for the Linux kernel that takes scheduling custody of real-time processes. The MontaVista Real-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 dispatch times of real-time tasks. Non-real-time (SCHED_OTHER) tasks are handled in a fashion similar to the standard scheduler; however, the management of the time slice calculation is modiÞed to be much faster while having the same end result.
Support The scheduler is available on all supported architectures; including Symmetric Multiprocessing (SMP) Systems. Check the MontaVista Zone page for your target for information 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 by default. To enable the MontaVista Real-Time Scheduler, complete the following steps: 1.
Start make menuconfig or make xconfig. The latter can be run on its own or through TCT.
2.
Depending on the target architecture, select Processor type and features or Platform support.
3.
Enable Real Time Scheduler.
4.
Enter a value for the Maximum Priority? option. This option allows you 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
Chapter 6: Linux Kernel Development Enabling 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 2047 are changed to 2047. The default is set to 127, and in most cases, this is what you would use. 5.
Save your changes.
6.
Rebuild the kernel, using TCT or the procedure in “Building and ConÞguring the Kernel” on page 76.
The MontaVista Real-Time scheduler is now enabled. Warning: The MontaVista Real-Time Scheduler does not honor the allowed_cpus member of the task_struct; thus, it will not honor any attempt to 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 cause performance degradation.
Additional information The MontaVista Real-Time Scheduler is an open-source project and it is hosted at: •
Preemptible Kernel
http://rtsched.sourceforge.net/
The Preemptible Kernel (CONFIG_PREEMPT) option reduces the latency of the kernel when reacting to real-time or interactive events by allowing a low-priority process to be preempted, even if it is in kernel mode executing a system call. This feature allows applications that need real-time response – such as audio and other multimedia applications – to run more reliably, even when the system is under an increased load due to other lower-priority processes.
Features The new preemption model allows the kernel to be preempted any time it is not locked, which is very different from the model where preemption is actively requested by the currently executing code. Using the new model, when an event occurs causing a higher priority task to be executable, the system will preempt the current task and run the higher priority task. In the following instances, preemption should not occur, and the Preemptible Kernel option does not allow it:
82
•
while handling interrupts
•
while doing “bottom half” processing -- bottom half processing is work that an interrupt routine needs to do, but that can be done at a more relaxed pace
•
while holding a spinlock, writelock, or readlock
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling Real-Time Performance Enhancements
These locks exist in the kernel to protect it from other processors in Symmetric Multiprocessing (SMP) Systems. While these locks are held, the kernel is not preemptible for re-entrancy or data protection reasons (just as in the SMP case). •
while the kernel is executing the scheduler itself -- the scheduler is charged with executing the “best” task, and if it is engaged in making that decision, it should not be confused by asking it to give up the processor
At all other times, the MontaVista algorithm allows preemption. Also, whenever the system exits from one of the above states, it tests to see if preemption is called for. If so, the current task is preempted.
Support Check the MontaVista Zone page for your target for information about support for this 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 can be 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 and ConÞ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 is experimental.
MontaVista™ Linux® Professional Edition
83
Chapter 6: Linux Kernel Development Enabling Standard Devices
Enabling Standard Devices Pro 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-
Framebuffer Support
Framebuffer provides bitmap graphics for running a windowing system.
Support Check the MontaVista Zone page for your target for information about support for this 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 the SVGA_MODE variable. To set the SVGA_MODE variable, change the SVGA_MODE variable setting from NORMAL to what is appropriate for your setup. Read /opt/hardhat/devkit/lsp/
84
-DSVGA_MODE=0x301
2.
Start make menuconfig or make xconfig. The latter can be run 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.
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling Standard Devices
7.
Rebuild the kernel, using TCT or the procedure in “Building and ConÞ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 for this 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 run on 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 and ConÞguring the Kernel” on page 76. To verify that videocard support has been enabled, load and boot the new kernel on the target. If you see a penguin in the upper left-hand corner of your target screen, you have succeeded.
MontaVista™ Linux® Professional Edition
85
Chapter 6: Linux Kernel Development Enabling Standard Devices
PS/2 Keyboard and Mouse Support
Support Check the MontaVista Zone page for your target for information about support for this 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 run on 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 and ConÞguring the Kernel” on page 76.
7.
On the target, ensure that you have a psaux device. Use the following command to list the devices: ls /dev/psaux
If you do not have a psaux device, use the following command to create one: mknod /dev/psaux c 10 1
For more information about creating standard device nodes, see “Create Standard Device 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
Chapter 6: Linux Kernel Development Enabling Standard Devices
Sample Startup/Kill Scripts. Startup and kill scripts can be used rather than the gpm daemon. 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=ps2 device=/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.pid GPM=/usr/sbin/gpm CFG=/etc/gpm.conf test -x $GPM || exit 0 if [ "$(id -u)" != "0" ] then echo "You must be root to start, stop or restart gpm." exit 1 fi cmdln= 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"; fi fi gpm_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 1 esac exit 0
MontaVista™ Linux® Professional Edition
87
Chapter 6: Linux Kernel Development Building Custom Device Drivers
Building Custom Device Drivers While there are hundreds of drivers available for Linux, you may Þnd that the exact driver you need does not exist for your device. In this case, you need to either write your own driver or simply modify a similar driver. Whether you are writing a new driver or modifying an existing driver, you should write and test your driver in an incremental fashion. By working in increments, you can easily track your progress and isolate bugs. A test program, developed in lockstep 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 sample driver outlined in this section, the Þrst steps to developing the driver are to write and test 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 much easier to test each section of driver code as you write it. 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 the driver works, you can compile the driver 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 the particulars for building a device driver are dependent on the device, Linux device drivers have many common features. There are hundreds of examples available in /opt/hardhat/devkit/lsp/
“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, almost everything shown in the example driver is required in a PCI-device driver as well.
88
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building 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 a kernel module), create the /dev node, and launch a test program. The test program should be written as you write your driver to test each new piece of functionality. Your kernel must have loadable kernel module support enabled. See “Enabling Loadable Kernel Modules” on page 80 for more information. Refer to the appropriate man and info pages for details on each of these operations. Sample load module and test program script #!/bin/sh # Insert mydriver and run the test program # mknod /dev/mydriver c 120 0 insmod mydriver.o ./test_mydriver
First, the mknod command creates a character (c) device entry in the /dev Þle system. The driver will use major device 120, one of the numbers reserved for experimental use. The minor device number, 0 in the above example, will be passed to the driver each time the driver is used, and has no meaning other than what the driver makes of it. Note: If the driver (kernel module) is going to allow Linux to assign the major device number, insmod must be executed before mknod, and some additional shell programming will be needed to extract the answer from /proc/devices before mknod can be executed. (Finally, it is possible to do the mknod(2) operation in the driver itself.) Next, assuming the driver (kernel module) has been compiled as mydriver.o, the insmod command inserts (loads) the driver into the running system. Within the driver (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 current directory – hence the “./” preÞx – this program tests the driver by issuing typical I/O calls and checking the results. The test program should also test boundary conditions as well as verify the error-checking in the driver itself. For example, device drivers must validate user-space addresses. Failure to do so could result in a system panic. The test program should, therefore, attempt some operations using invalid addresses and verify that the driver returns the proper error status. It is not uncommon for a test program to be several times larger than the driver being tested.
MontaVista™ Linux® Professional Edition
89
Chapter 6: Linux Kernel Development Building Custom Device Drivers
When a problem is detected in the driver source code, the driver must be removed from the system, the error must be corrected, and the driver must then be recompiled and reloaded. For consistent results, a removal script, such as the following, should be used: Sample remove module script #!/bin/sh # Remove mydriver # rmmod mydriver rm -f /dev/mydriver
First, the removal script undoes the insertion. Note that the driver's name no longer carries 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 will be 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 is ready to be tested again, expect an error message when the mknod command is executed because the /dev/mydriver node is still present from the previous life of the system.
Code the Kernel Portions of the Driver
While writing and testing the driver, the kernel module provides a carrier for loading and unloading the device driver. As such, the kernel module should be written and debugged Þrst. Once it can be inserted and removed at will, coding of the driver can begin. For this to work, your kernel must have loadable kernel module support enabled. 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 the driver works, you can compile the driver as you desire – as a loadable module or as part of the kernel. Below is a very simple kernel module example: Sample kernel module #include
90
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
The three #include statements are all required. The linux/init.h header Þle contains, 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 later built 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 more information about running the cross-compiler for your target, see “Running Pro Applications and Tools” on page 40. The following describes the other options used: •
The -c option tells the compiler to generate the object Þle from mydriver.c, but to proceed no farther.
•
The -DMODULE option is needed when compiling a kernel module Some compilers do not, by default, generate reentrant code. For device drivers, this is a necessity. Note: If you are compiling your driver as part of the kernel rather than as a module, you would use the -DKERNEL option in place of the -DMODULE option.
•
The -I <path-to-kernel>/include instructs the compiler to use the kernel include Þles (rather than user-space Þles.) Replace <path-to-kernel> with the proper path where the kernel source code used to build the kernel image used on the target board.
•
The -nostdinc option ensures that the compiler does not pick up any user-space paths.
•
The -Wall option instructs the compiler to issue all relevant warnings. Tracking down the source of these and carefully implementing the proper correction is very important when working in the kernel, much more so than in user-space programs.
•
The -O option turns on compiler optimizations. For user-space programs, this is a good idea. For code that will execute in the kernel, however, it is required.
At this point, the kernel module should be compiled and the load and unload scripts tested. 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
Chapter 6: Linux Kernel Development Building 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 and tested. 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 the corresponding read routine. Once write is Þnished, it can often be copied and pasted into 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(). This system operation registers the fact that a new driver is present in the system, which should be done when the driver (kernel module) is loaded. The driver's initialization routine 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. This particular operation is used in practically every driver in Linux. There are hundreds of examples beneath the drivers directory. Look for a directory named drivers in /opt/hardhat/devkit/lsp/
From the results, pick a directory and grep for the “register_chrdev” string. There are two basic ways of using register_chrdev(): assigning a major device number, or letting Linux assign one. The Þrst argument in register_chrdev() may contain either a non-zero number, or zero. A non-zero number tells Linux what major device number to use. Linux will return success (0) or failure (non-zero). Conversely, coding a zero as the Þrst argument to register_chrdev() asks Linux to automatically assign an unused major device number to the driver. In that
92
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
case a return value of non-zero means success and the returned value is the assigned major device number. Should Linux return a zero, however, there are no major device numbers available, and the register_chrdev() operation has failed. The second argument to register_chrdev() is the driver's name. Although it could be anything, for consistency, it is a good idea to make this name the same as the name used in the /dev Þle system. The Þnal argument is the name of a structure containing pointers to the driver entry points. 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 structure deÞ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 they will, 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 driver initialization routine, and, conversely, the unregister_chrdev() call is the only function required to be in the driver remove routine. There are other system operations commonly found in the initialization code of device drivers. These are ioremap(), tasklet_init() and, quite often, the operations needed to reset the hardware device being controlled. ioremap() programs the processor's address translation unit (or discovers the previously programmed address) for the hardware device the driver is controlling. For portability, it is important to recognize that the return from ioremap() is an “I/O Space Address,” which is not necessarily accessible by a direct memory reference. Special functions are provided for all I/O space address references. Drivers that dereference these pointers directly will not be portable and may also suffer byte-order problems. tasklet_init() initializes the structure used to trigger a tasklet which, in most drivers, is used for the post-processing of an interrupt. (Earlier Linux implementations provided “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 bottomhalves and soft IRQs and should use tasklets.) For both ioremap() and tasklet_init(), refer to examples in the Linux driver source Þles. Finally, if an ioremap() is coded in the driver initialization routine, an iounmap() should probably be written into the remove routine. There is no counterpart to tasklet_init(). Testing the initialization and remove routines. With the initialization and remove routines coded, this is a good point to test the driver 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
Chapter 6: Linux Kernel Development Building Custom Device Drivers
The above command displays the current registry of major device numbers and names known to Linux. If run after loading the driver, by Þnding the driver's name in the output 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 number of different types of devices, and the different ways in which they may be installed and used with Linux. Therefore, it may be useful to examine several drivers and compare the approaches implemented in them with the suggestions herein. The Open routine in a device driver often associates an external hardware interrupt with a piece of code in the driver, the ISR or Interrupt Service Routine. The request_irq() function provides this service. Before it can be used, however, the driver must determine which IRQ (Interrupt ReQest number) it should use. Depending on the hardware design and the device's capabilities, there are several techniques to choose from. First, the device may simply be hard-wired with a particular IRQ number. This is often true of on-board devices that are soldered in place. For these devices, the hardware designer may have made the selection of IRQ number and documented the answer in the hardware reference materials. If the device is PCI-based, however, the device will have been programmed in the PCI subsystem or possibly earlier, in BIOS if present, or in a comparable part of the system’s initialization code. For PCI-based devices, the PCI subsystem will know the IRQ number. Again, refer to the Linux sources for the most reliable answer. Locate a device driver containing both a call to request_irq() and also a call to, for example, pci_enable_device(). Another technique is probing for an IRQ number. The kernel routines probe_irq_on() and probe_irq_off() are used, in sequence, to determine what IRQ number a particular device is using. In between those two operations, the device driver is expected to do something to the device to provoke an interrupt. Linux monitors the unused IRQ lines and returns the IRQ number when probe_irq_off() is called. Although useful in some environments, probing may exhibit some undesirable behavior in some systems. It should, therefore, be avoided if possible. Note: Examination of the sources for Linux drivers will reveal a dozen or more additional techniques. Choose one appropriate for the hardware you are using. The IRQ number is the Þrst argument to request_irq(). The second argument is the name of the function to be executed in the interrupt context. This is the driver's ISR. Note: It is important to note, throughout the driver, the context of execution of a particular function. Interrupt Service Routines execute in the interrupt context. Most
94
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building 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 be considered a third type of context. Of these, the portions of a driver that execute in the process context can be interrupted by tasklets and interrupts, tasklets themselves can be interrupted by interrupts, and in some cases, interrupts can even be interrupted by other interrupts. This is what the -D_REENTRANT ßag is for when compiling a driver. And, this is what things like kernel MUTEXes, spin locks and interrupt masking are designed to help a driver handle. If these are new concepts, a careful and thorough study of these topics is recommended and, unfortunately, is much more than can be dealt with here. The third argument to request_irq() is a group of ßags that may be OR'd together. These include whether or not the driver is a “fast” or “slow” interrupt handler, is willing to share the IRQ with other drivers, and whether or not interrupts from the device tend to occur at random times. The relevant ßags are SA_INTERRUPT (a “Fast” handler), SA_SHIRQ (the driver will “share” the IRQ line), and SA_SAMPLE_RANDOM (interrupts occur at random times). The converse of each ß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 the capabilities of the hardware, “slow” interrupt handlers execute with interrupts other than their own re-enabled. This allows for the nesting of other (often “higher priority”) 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 probable choice. The name used with request_irq() will be displayed through the /proc/interrupts interface that shows how many interrupts have occurred at each IRQ number. And the Þnal argument to request_irq() is any value of use to the driver. This value will be passed to the driver's interrupt service routine whenever an interrupt occurs. It is often used to pass a pointer to some driver control structure needed at interrupt time. The Þnal item needed in the driver's open routine is the MOD_INC_USE_COUNT macro. This increments a counter and is used to determine when a module may be unloaded. A corresponding MOD_DEC_USE_COUNT should, therefore, appear in the release routine, which should also include a free_irq() call to release the IRQ number. It may also be a good idea to disable the device or otherwise prevent it from generating interrupts in the future. With the open and release handlers coded and compiled, the test program can be enhanced to test the new entry points. In the test program, open(“/dev/ mydriver”,...) will return a Þle descriptor. Prior to that, however, the driver entry point will be executed. The driver must, therefore, return success (0) if everything is working. On the other hand, if the request_irq() or other operation
MontaVista™ Linux® Professional Edition
95
Chapter 6: Linux Kernel Development Building Custom Device Drivers
fails, the driver’s open routine should return an appropriate error number. Examine various driver sources and note the methods used. They are relatively straightforward and common across many drivers. At this point, all the test program can do is open() and close() the driver. But these should cause the driver's corresponding entry points to execute. If desired, a few printk()s could be placed throughout these routines in the driver to verify operation.
Write to a device The write and read portions of the driver will be handled and tested separately, and they should probably be coded and debugged in that order: write before read. This is simply because it is easier to code a test program that makes up random data to be written to a device than it is to cause a device to make readable data available. Testing is 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 the existing data and the number of bytes therein. The address the program speciÞes, and which is passed to the driver, is a user-space address. That area of memory, including various portions or all of it, might not be resident in RAM at the time the I/O call is issued. The driver, therefore, must not attempt to touch the user-speciÞed data directly. 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 this purpose. The buffer must be large enough to hold the maximum size write (or read) to be handled by the driver. In many cases this means very large writes (and reads) will actually 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's initialization routine may be selected for this operation. The difference between these two depends on how many kernel-space buffers will be needed by the driver. The driver initialization routine is executed once. The open routine, on the other hand, is executed once for each minor device that is opened. Drivers supporting multiple minor devices and needing a kernel-space buffer for each such device may do the kmalloc() operation in the open routine, and the corresponding kfree() in the release routine. When a user program issues a write operation, the device driver's write handler must copy the data from user space to kernel space. The copy_from_user() function provides 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 paged out, the copy_from_user() function will initiate a page-in operation and put the current operation to sleep until it completes. This means that the driver's write routine may be put to sleep during the copy_from_user() operation. Note: Sleeping is perfectly acceptable in a process (or thread) context. It is not allowed; however, in an interrupt or tasklet context. Since different portions of the device driver will execute in different contexts, it will be important to remember what is and is not allowed in each part of the driver.
96
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
In addition to coping with page faults, copy_from_user() will also validate the user-space addresses over the entire range of indicated addresses. If the user program speciÞes an invalid address, or if the user-space buffer beginning address is valid but the length extends into forbidden space, copy_from_user() will return a nonzero value to the driver. The driver is then obligated to return -EFAULT to the user program. This will probably result in a segment violation signal to the requesting process, typically a fatal event. Arguments to copy_from_user() are straightforward: kernel-space destination address, user-space source address, and number of bytes. Two of these values, userspace 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 kernelspace buffer, is then transferred to the I/O device. Sometimes this is a copy from kernel-space to I/O-space, memcpy_toio(), or, in the case of a device that handles only a single byte, “word” (two bytes) or “longword” (four bytes) at a time, writeb(), writew(), and writel(). In cases where the device is capable of fetching the contents of system memory, the appropriate memory address must be programmed into the device. Because devices are assumed to exist in I/O space which may be different from the processor's memory space, the kernel-space address must be 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. Physical addresses 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 data transfer. These calls access the system's I/O space: the pointers to the I/O device should be the value returned by the ioremap() call in the driver's initialization routine, or some offset. If a delay occurs between starting the data transfer and when it completes, the process is typically put to sleep by having the driver call interruptible_sleep_on(). Later, if an interrupt occurs at the end of the data transfer, the driver's ISR or tasklet can issue the corresponding wake_up_interruptible() operation. When that occurs, the driver will reawaken at the line of code immediately after the interruptible_sleep_on(). Some drivers provide one or two common variants; however, instead of waiting for the operation to complete, some drivers may support O_NONBLOCK operation. When an application program requests an O_NONBLOCK operation, it is asking for the driver to complete the transfer of data from user space immediately and to allow the program to continue running without possibility of sleep. In other words, the driver should copy the data from user space, start the data transfer with the I/O device, but then immediately return from the write routine. Later, when the I/O completion interrupt occurs, the ISR (or tasklet) must be smart enough to know if it should not do the wake_up_interruptible() call, since no one is sleeping. In addition, the driver must also know that the device is busy. If an additional O_NONBLOCK operation is requested while the device is busy, the -EBUSY status should be returned. The -EBUSY status tells the application program that the non-blocking operation was not possible.
MontaVista™ Linux® Professional Edition
97
Chapter 6: Linux Kernel Development Building Custom Device Drivers
The second alternative is the FASYNC operation. This is similar to O_NONBLOCK except that in the former case, the application program cannot know when the data transfer to the external device has been completed. FASYNC operation, on the other hand, asks the driver to send a signal to the process. Driver support of FASYNC is usually 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 its hardware device is causing an interrupt. Drivers for devices that “share” IRQ lines may be called with a different device on the same IRQ line that is requesting an interrupt. Therefore, drivers must check to see if their device is generating an interrupt. If not, the ISR should simply return to Linux. If the driver's device is causing an interrupt, then the question becomes, why? And once 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 we wait too long
•
defer as much work as possible into a tasklet probably by adding entries to a queue of work to be done (the kernel's list_head manipulating routines may be particularly useful)
•
use tasklet_schedule() to cause the tasklet to execute at some later time
When should everything be done in the ISR and when should a tasklet be used are good questions with no clear answers. It is probably safe to say that if deferring the work takes longer than doing it, then a tasklet is not warranted. On the other hand, if the work is complex and may involve a backlog or transactions, then a tasklet is a good 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 Linux returns to the execution of any process. Tasklets are, therefore, a third type of “things that can execute code” and, in importance, they fall between hardware interrupts and processes. The content of the ISR and tasklet, if any, depends on the I/O device and the type of execution (O_NONBLOCK, FASYNC, etc.) desired by the application program, and by the designer. SufÞce it to say that these considerations and the discussion in the section “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 were transferred, and return that count.
98
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
With the driver write routine coded and ready to be tested, the test program must be modiÞed. Here's where things start to get involved in the test program. There are several questions to be answered. First, what types of data are acceptable to the device? What lengths of data are allowed? Does the driver support O_NONBLOCK operation? Does it support the FASYNC style of transfer? Of course, all the permitted combinations must be tested. Additionally, various combinations of illegal and nonsensical operations must also be attempted. In all cases, the value returned from the driver must be compared to see if the driver is giving the correct response. This is also the time to begin stressing the driver to see if it continues to behave well under load. Depending on the driver, the use of a kernel MUTEX may be required. These are initialized with init_MUTEX() and then manipulated with down_interruptible() and up(), and occasionally with plain down(). A kernel MUTEX is used in a driver to prevent multiple processes (or threads) from using critical portions of the driver at the same time. When one process successfully executes the down_interruptible() operation, any subsequent process reaching that same point will be put to sleep until the Þrst process executes the corresponding up() operation. Note that as before, ISRs and tasklets are not allowed to 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, including down_interruptible() as well as interruptible_sleep_on() and its variants, special handling is needed immediately thereafter. These kernel operations are “interruptible” in the sense that a signal could be sent to the process while it is sleeping, 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 two signals and noting their precise meaning. Also note that when a data transfer is initiated and the process is put to sleep, in most devices there will be an interrupt to let the driver know the I/O has been completed. If the 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 case as the “sleep queue” is presumed to be empty. Depending on the driver and the application, this behavior and its consequence should be carefully considered. And Þnally, there is another potentially larger problem. If an application program asks a driver to transfer data to a device, and then a signal causes that application program to be terminated, should the driver Þnish transferring the data? And what about when a 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 where the 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 is driver-speciÞc and application-speciÞc. You need to decide based on your driver and application needs.
MontaVista™ Linux® Professional Edition
99
Chapter 6: Linux Kernel Development Building Custom Device Drivers
Read from a device At this point, the driver's write routine should be 100% functional. It should be fairly well tested under normal, stress, and abusive conditions. It should handle bad pointers from users, deal with reentrancy issues using MUTEXes, and be fully coordinated with the driver's ISR and tasklet. As needed, it should handle normal, non-blocking and asynchronous writes. To code the read routine, copy the core of the write routine and paste it into the read function. Once there, review the sequence of events and make any necessary adjustments. For example, instead of copy_from_user(), the read routine uses the copy_to_user() function. Since the data to be read won't be available until near the end of the read routine, the call should probably move to the end of the read handler. In the case of a normal (sleeping) data transfer, the copy_to_user() function would belong shortly after the interruptible_sleep_on(). In that case, the device interrupt would essentially mean “the data is now ready in the kernel buffer.” Other details of the read handler in the device driver should be relatively obvious. As with 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 test program for the read routine. Other issues to be tested may involve the concurrency of reads and writes to the same device at the same time. There is no absolute rule here. It depends on what your driver is supposed to be capable of supporting. With some hardware devices, only one read or one write can be performed at any instant. The driver should take this into account, therefore, and serialize use of the device accordingly. But if the device supports reading and writing at the same time, the driver 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 Þrst doesn'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 data variables or device control registers that might also be accessed or manipulated in the interrupt or tasklet context should be considered a critical region. The classic method of ensuring integrity of the data is to simply preclude a change of context. This is most easily done by disabling (blocking) all hardware interrupts. Use the save_flags(); cli(); sequence to Þrst save the current state of the interrupt mask and then set it into the disabled state and, later, use restore_flags() to restore the former setting. Using this sequence is “safe” no matter what the interrupt state is at the beginning. It will always set it back to the correct value. Testing for reentrancy problems is difÞcult. Although it is theoretically possible to test a driver for all possible cases, in practice, the hardware is usually not available to try all combinations. Instead, most drivers are subjected to long-running stress tests with randomized data and timings. The hope is that, given enough time and enough random variation, all the bugs will eventually be found.
100
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Building Custom Device Drivers
For the test program, this means that all of the foregoing tests must be repeated thousands and thousands of times, meticulously checking each and every operation for proper behavior. Multi-threading in the test program is a common way of achieving a high degree of parallelism but, if overdone, can drive the system so hard that 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 multiple application programs to execute in true concurrent fashion. In those systems, one application program may call a device driver at exactly the same time as a different application program on another processor calls the exact same driver. The previously described MUTEX will adequately handle this case, but what if one processor is initiating a data transfer and, nanoseconds later, the device causes an interrupt and the hardware decides to allow a different processor handle the interrupt? In that case, the driver's ISR and read/write handler will both be executing, literally at the exact same time. If they both access a common data structure at the same time, the data could easily be corrupted. The situation above demonstrates the need for spin locks. A spin lock is a bit that is either on (locked) or off (unlocked). The processor provides some basic mechanism for testing and setting these bits, and Linux provides well-documented and portable interfaces 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, a driver 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 acquires a spin_lock but also disables interrupts on the local processor. The corresponding spin_unlock_irqrestore() is then used later to undo both the spin lock and the processor's interrupt mask. Finally, because spin locks may cause other processors to “spin in their tracks,” their use should be as rare and for as brief a period of time as possible. Study of the source code to other drivers will show that, in most cases, spin locks are rarely held for longer 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 test program, developed in lock-step with the coding of the driver, can be used to test each piece. As the driver gains in capability, the test program is similarly enhanced to thoroughly probe the driver and verify proper operation. This includes giving the appropriate 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 and the driver's kernel module “carrier.” The associated kernel module initialization and removal routines are tested at this initial stage.
MontaVista™ Linux® Professional Edition
101
Chapter 6: Linux Kernel Development Building Custom Device Drivers
Then, the driver's initialization and prepare to be removed functions are coded and tested. These include the Þrst use of the kernel via the register_chrdev() and unregister_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 interrupt handler and, if necessary, the driver's tasklet. To test the new code, the test program is enhanced to include normal (legal) writes as well as writes specifying invalid addresses and other illegal operations the driver is supposed to catch. The test program veriÞes that the driver not only catches the errors, but also returns the proper indication. When the write handler is Þnished, it is copied into the read handler and, after some fairly minor adjustments, it is ready to be tested. The test program is modiÞed accordingly and run. Issues of reentrancy abound. Kernel MUTEXes, spin locks and interrupt masking must all be used in various places and combinations. Testing becomes less certain of Þnding all problems and “long duration stressing” is often used in partial compensation. The main driver entry points have been sketched out here. The driver's handlers for open(), close(), read() and write() are almost complete. However, most drivers will also include handlers for ioctl() and others. Many will also provide interfaces for poll(), mmap(), media_change(), revalidate() and several others. And, practically every one of these will have only a passing similarity from one driver to the next.
Additional Information
The best information on Linux device drivers are the hundreds of Linux device drivers, all of which are provided in source form in: •
/opt/hardhat/devkit/lsp/
In addition, there are many good books that provide details on building Linux device drivers. Note: MontaVista Software does not endorse the book listed below. The following example is provided for your convenience only. Linux Device Drivers (Nutshell Handbook), Second Edition, Alessandro Rubini, Andy Oram (Editor). Sebastopol, California: O'Reilly & Associates ISBN: 1565922921
102
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Enabling File Systems
Enabling File Systems The Linux kernel supplies Þle-system services for a of variety Þle-system types. File systems 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 system support on your target. As part of deployment (see “Deployment” on page 171), you need to build a Þle system for your embedded system. Building a Þle system requires, among other things, 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 for JFFS), see: •
“ConÞguring the Kernel to Be Stand-Alone and to Enable a Deployable Root File System” on page 173
MontaVista™ Linux® Professional Edition
103
Chapter 6: Linux Kernel Development Debugging the Kernel
Debugging the Kernel Pro provides a number of tools and conÞguration Þles that can be used to debug the kernel. The tools and conÞguration Þles are:
KGDB
•
KGDB
•
Linux Trace Toolkit (LTT)
•
Abatron BDI2000 ConÞguration Files
KGDB is a debugging tool that can be used to debug the Linux kernel. Using KGDB is most practical when you are implementing kernel device drivers and other similar functions. 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 is not on by default in the kernel; however, the ability to turn on KGDB is there for each kernel. 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. To enable kernel debugging, complete the following steps:
104
1.
Start make menuconfig or make xconfig. The latter can be run on its own or through TCT.
2.
Depending on the target architecture, select Kernel Hacking or Kernel Debugging.
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Debugging the Kernel
3.
Enable GDB stub kernel debug or KGDB.
4.
The makefile in the same directory where .config for the kernel resides 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 GDB for symbolic debugging. Removing the –fomit-frame-pointer allows the capability to do stack traces and walkbacks. 5.
Rebuild the kernel, using TCT or the procedure in “Building and ConÞ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 the target with the new kernel, see “Booting the Target with a Custom Kernel” on page 52.
Set up GDB to debug the kernel Now that everything is set to debug the kernel, it is necessary to connect to it using GDB. To connect to the target using GDB, complete the following steps: 1.
Terminate the Minicom (or other terminal emulator) connection to target.
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. A copy 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
The file command loads the symbols for the kernel into GDB to enable symbolic debugging. By being in the correct directory, the full source is also available for display.
MontaVista™ Linux® Professional Edition
105
Chapter 6: Linux Kernel Development Debugging the Kernel
Note: The kernel binary image Þle to download into GDB is located in the top-level directory of the tree used to build the kernel, and it is usually 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.
7.
Enter a breakpoint command at the address or function where debugging should begin. There are two convenient places to set breakpoints. They are: •
b panic This is the entry point to panic routines. This traps all panics to GDB.
•
b sys_sync By entering a sync command, the system will go to the breakpoint for sys_sync.
Enter continue to start the kernel running again.
GDB is now running and in control of the kernel. It will stop at the breakpoint entered above. This allows for examining variables and watching how the code ßows.
Additional information For more information about using KGDB and kernel debugging, see the following help document on MontaVista Zone (http://support.mvista.com/content/Kernel).
106
MontaVista™ Linux® Professional Edition
Chapter 6: Linux Kernel Development Debugging the Kernel
Linux Trace Toolkit (LTT)
LTT provides a general-purpose event logging and analysis system, with many useful pre-deÞned events. The pre-deÞned events are in the areas of:
•
system calls
•
Þle-system management
•
traps
•
timer management
•
interrupts
•
memory management
•
scheduler
•
socket communications
•
kernel timer
•
SystemV IPC
•
soft IRQ management
•
communications
• •
process management
network device management
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 received for 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 for Solaris. For all hosts, the LTT tracevisualizer data analysis tool is linked in statically to avoid an install-time dependency on some graphics packages, such as glib, XFree86-libs, and gtk+. This results in problem using some GTK themes. These problems depend on 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.
MontaVista™ Linux® Professional Edition
107
Chapter 6: Linux Kernel Development Debugging the Kernel
•
Remove ~/.gtkrc (you might want to save a copy).
•
The hhl-host-ltt-dynamic package contains a version of the tracevisualizer data analysis tool that is linked with shared libraries. Remove the hhl-host-ltt-0.9.5a package and install the hhl-host-ltt-dynamic-0.9.5a package available on the Pro distribution CD-ROMS. To remove the hhl-host-ltt-0.9.5a package, use the command: rpm -e
hhl-host-ltt-0.9.5q-mvl3.0.5
To install the hhl-host-ltt-dynamic-0.9.5a package, use the command: rpm -Uhv --ignorearch mvl3.0.5
hhl-host-ltt-dynamic-0.9.5q-
(ENTER THE ABOVE COMMAND AS A SINGLE LINE.) Note:
Additional information For more information about what LTT does and how to use it, see the LTT reference manual 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 solely through the stable on-chip debugging services. This debugging mode runs even when the target system crashes, and it enables you to continue investigating the cause of the crash. Host-to-BDI communication uses the standard GDB remote protocol, as in the diagram below:
Serial Connection
Host
(Optional for console)
LAN
AbatronBDI2000 (Functions as a GDB server)
108
MontaVista™ Linux® Professional Edition
Target
BDM/JTAG
Chapter 6: Linux Kernel Development Debugging 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 network capability
•
supports built-in on-board programming of ßash memories
•
supports internal break register (allows debugging of code running out 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 LSPs for which we support the use of the Abatron BDI2000 debugger. Check the MontaVista Zone page for your target for information about support for this feature on your target.
MontaVista™ Linux® Professional Edition
109
Chapter 6: Linux Kernel Development Debugging 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 to follow 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 that contains bdisetup.zip.
3.
Copy the .cnf and .def Þles that came with the BDI2000 into the directory that your TFTP server gives access to. If a .cnf Þle came with 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 and then make a copy of the Þle. Edit the copy to change the conÞguration values to Þt your particular environment. You will want to refer to the BDI2000 documentation for more details. You will need the name of this Þle in Step 8.
4.
Connect your BDI2000 to your host with a serial cable, the network with a LAN cable and then connect its power. Do NOT connect the BDI2000 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 -u option. The defaults for the options can be determined by looking in the source, but it is probably easier to just specify all options. The application 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 BDI2000 from the Þles in the current directory using the serial port /dev/ttyS1 running at 38400 baud. The Þrmware and logic that is loaded is for a PPC400 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, and the IP address of your gateway. The conÞguration Þle should be the name 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
Chapter 6: Linux Kernel Development Debugging the Kernel
9.
Make sure that the Þrmware is programmed correctly and then tell the BDI2000 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 LED should no longer be blinking on the BDI2000 and you should be able to telnet to it. When you telnet to the BDI2000, it will show a help screen and then report that it is waiting for the target Vcc. 10. Make sure that your target's power is turned off. You can then connect the JTAG or BDM ribbon cable between your target and the BDI2000. Turn on the target's power. If all is well, the BDI2000 resets and initializes the target with no errors. You are now ready to start using the BDI2000. Using the telnet interface, you can do such 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 apparent when you start using it as a gdbserver. You will be able to debug boot code, the kernel, drivers, and modules. If you compile your code with -ggdb and use ddd, you will 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
Chapter 7: Application Development
Overview There are a variety of ways to build your application using Pro. You can build the application on the host using KDevelop (a C/C++ IDE) or the command-line crosscompilers included with Pro. Whether you use KDevelop or the command-line tools, we recommend that you do NOT work directly in the /opt/hardhat/devkit tree. Rather, you should create a build directory for your work (for example, myapplication) Once you have written and compiled your program, you should copy 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 the target for testing. When choosing a location for your application in the target Þle system, we recommend following the Filesystem Hierarchy Standard (FHS). For more information, see http://www.pathname.com/fhs/. Note: You can also write and debug programs directly on the target using the targetspeciÞc command-line compilers. This chapter provides examples of writing simple programs and information on how to 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
Chapter 7: Application Development Building 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, KDevelop provides: •
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 selected project type, Þle templates and appropriate includes and libraries are 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 as Compiler, Linker, automake and autoconf. MontaVista Software has customized KDevelop for use in the cross-development environment. See “MontaVista Customizations” on page 115 for more information. The KDevelop documentation set includes The User Manual to KDevelop and The KDevelop Programming Handbook. Both of these manuals are part of the KDevelop distribution and are also available via MontaVista Zone. While fairly complete, the KDevelop documentation does not cover using KDevelop in a cross-development environment. The sections below provide information about the customizations MontaVista Software made to KDevelop, as well as information about how to use KDevelop in the cross-development environment.
114
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
MontaVista Customizations
KDevelop 2.0.1 was used as the base for the Pro distribution. MontaVista customizations include: •
Menu Bar changes: •
Project-> New (New Project Wizard). Provides a “Target Non-Graphic” major project type as a starting point for target cross-development. “Non-graphic” means that support is not provided for a graphical environment (X11, Qt/Embedded, KDE, or Gnome) on the target.
•
Tools: Provides DDD (debugger) and TCT (Target ConÞguration Tool) entries if those components are installed as part of Pro. (TCT and DDD are installed by default with Pro.)
•
Options->Tools... Includes DDD and TCT entries.
•
Help->MontaVista Support: Provides direct access to MontaVista Zone via a Web browser.
•
KDevelop senses which cross-development environments are installed in /opt/hardhat/devkit. This allows projects to be deÞned either for the development host (normal, natively hosted development) or for any of the cross-development targets. Various menus and options throughout KDevelop were adjusted for this option.
•
The second pane of the Application Wizard presents a Target pulldown menu that allows you to select either Development Host for natively-hosted development (using the host system's own toolchain) or one of the MontaVista architecture/processor strings for cross-development using the appropriate toolchain for your target.
•
The Compiler Options pane has been changed to include a Target Arch/Proc pull-down. This initially shows the target chosen during project creation. Clicking this pull-down and changing the selection redeÞnes the project for a new target. Selecting Development Host converts the project from cross-development to natively-hosted development.
•
The Þeld Pro Development Kit shows the root of the Pro crossdevelopment tree. This value is set based on the installed location of Pro (typically /opt/hardhat/devkit.) Replace the value of this Þeld if the development kit has been moved. (Warning: Pro cannot be relocated after installation and any attempts to do so will break the development environment; however, this option may be useful for customers who have multiple products installed.)
•
Under the Build menu, the options Execute and Execute with Arguments can only be used for natively hosted projects. Because
MontaVista™ Linux® Professional Edition
115
Chapter 7: Application Development Building Programs Using KDevelop
these menu items run the application on the local host system, when a cross-development project is deÞned, these menu items are disabled. Cross-development binaries must be moved to the target system and run and debugged remotely. •
Under the Debug menu, the options Start and Start (other)... start the debugger. If DDD is installed for cross-development, the debugger is conÞgured to be DDD for the current target. For example, if the project target is set to arm_sa_le, by default, the debugger is deÞned to be: ddd --debugger arm_sa_le-gdb
The default value can be overridden by selecting KDevelop Setup from 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 the architecture-speciÞc debugger; instead, it uses the options speciÞed in the Options->Tools... conÞguration. If you intend to use DDD via the 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 installation of Pro. Note: Many host distributions have a version of KDevelop already installed. The version 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, you may see some look-and-feel and desktop interaction differences when running the MontaVista provided KDevelop. These differences are most noticeable when running in a non-KDE desktop (Gnome, CDE, OpenWindows, Motif). For a KDE desktop older 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 that when 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 MontaVista provided KDevelop. For example, if the “File Browsing Preferences” were changed via the control panel, those changes would not affect the MontaVista provided KDevelop. In general, the MontaVista provided KDevelop is isolated from the desktop, since its main purpose is to build tools for the target.
116
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building 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 host versions 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 the full path when starting the MontaVista provided KDevelop. Alternatively, the PATH variable must be set to give priority to the Pro host tools. The base system installs KDevelop into /usr/bin or /opt/kde2/bin while Pro installs by default into /opt/hardhat/host/bin.
Use KDevelop for CrossDevelopment
The sections below provide an example of how to use KDevelop in the crossdevelopment 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 userinterface
•
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 starting KDevelop 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 erases the “recently opened project” list. KDevelop project deÞnitions and directories are not disturbed. Following setup, you need to open existing projects by explicitly selecting Open... from the Projects menu. You may also change some (but not all) settings established without re-starting in setup mode by selecting KDevelop Setup... from the Options menu.
MontaVista™ Linux® Professional Edition
117
Chapter 7: Application Development Building Programs Using KDevelop
Creating a new cross-development project To create a new project that will use the cross-compilers for your target, 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 Target Non-Graphic major project type, select either C or C++. The Target Non-Graphic major project type is a starting point for target cross-development. The target is assumed to only contain the Pro development environment, and support is not provided for a graphical environment (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.
118
Select Next to move to the next screen.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
5.
Fill in the Þelds in the Generate settings panel. The examples in this manual use mynewproject as the application project directory name.
6.
From the Target pull-down menu, select the architecture/processor type of your target board. Note: KDevelop automatically detects which architecture/processor types have been installed as part of previous Pro installations. Only the architecture/processor types installed, along with the native host option, are available. Note: Only one architecture/processor type can be selected at a time, so a single project cannot simultaneously be built for multiple architecture/ processor types. For team development, all developers share the same project metadata and therefore must use the same architecture/processor type.
7.
Select any additional features that you need for your project, such as API-Documentation or GNU-Standard-Files.
MontaVista™ Linux® Professional Edition
119
Chapter 7: Application Development Building 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 control system, select CVS from the pull-down menu and enter the information about your repository in the VCS Support Þelds. If you are using a nonlocal 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 to create 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 required makeÞles. You can now write your application. Note: Following initial deÞnition of a project, the target may be changed at any time by selecting Options from the Project menu. If any project options are changed, the project will be reconÞgured upon closing the Project->Options menu. If the development target was changed, the project will be reconÞgured to use the new development toolchain; however, the project is not rebuilt for the new architecture
120
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
until you select Rebuild from the Build menu. Source code that is not written in an architecture-independent manner remains unchanged, and if the target is changed, the code 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, select Custom project.
3.
Continue to use the Application Wizard just as you would for any new project. (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 browse through the Þle system and select the source code and makeÞle you want 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 process will use (that is, the one you imported).
MontaVista™ Linux® Professional Edition
121
Chapter 7: Application Development Building 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 the Classbrowser, Classtools, and Þle views to help you easily view and edit your project source Þles. For typical application development you might see a screen similar to the one below:
Once you have written your application, you can build your application by selecting Rebuild from the Build menu. Note: The Build menu commands Execute and Execute with Arguments can only be used for natively-hosted projects. Because these menu items run the application on the local host system, when a cross-development project is deÞned, these menu items are disabled. Cross-development binaries must be moved to the target system and must be run and debugged remotely.
122
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
Moving the application to the target Cross-development binaries must be moved to the target system and then run or debugged remotely. If you followed the steps listed in the quick start guide for your target, you will have NFS exported the default root Þle system (/opt/hardhat/ devkit/<architecture>/<processor>/target). We recommend that you NOT work directly in the /opt/hardhat/devkit tree. Rather, you should create a directory for your Þle system (for example, my_work_directory/myfilesystem) that contains a copy of the default target Þle system or the Þle-system you are developing. You should then NFS export your custom Þle system directory as the root Þle system on your target. See “How to NFS 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 to the target’s Þle system (/my_work_directory/myfilesystem), where it can be run and debugged (recommended). When choosing a location for your application in 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 any associated data Þles to the cross-development Þle-system tree. To use KDevelop for this purpose, complete the following steps: 1.
In your project’s makeÞle, specify the location where you wish to move the executable. For example, you could move the application to a work directory 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 write access to the directory (or to the target subtree in general) speciÞed. 2.
From the Build menu, select Install. KDevelop performs a make install which moves the executable and any associated data Þles to the cross-development Þle-system tree that you speciÞed in the project makeÞle.
Your application can now be run and debugged on the target.
MontaVista™ Linux® Professional Edition
123
Chapter 7: Application Development Building Programs Using KDevelop
Debugging an application For cross-development, the debugger is conÞgured to be DDD for the current project target, 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 is deÞned to be: ddd --debugger arm_sa_le-gdb
Note: This default can be overridden by selecting KDevelop Setup from the Options menu. To debug the current open application, complete the following steps: 1.
From the Options menu, select KDevelop Setup to set the options used by 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 debugger checkbox is not checked) that is not useful for remote debugging and is not supported by MontaVista Software. Since DDD was installed as part of Pro, KDevelop detects it and automatically selects Use external debugger and predeÞnes the Select debug command Þeld to ddd. Note: Although the command line is shown as ddd, the actual command line used is the following:
124
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
ddd --debugger gdb
for native host development deÞned projects
In the cross-development environment, DDD establishes a connection to a remote debugging stub, usually gdbserver, via a serial or TCP connection. Since the location and type of connection to the target is not known, you must set those options. One of the options related to remote debugging over a serial line is: •
-b <speed>
to set the line speed for a serial connection from GDB to gdbserver To add user options, enter the options into the Select debug command Þeld following ddd. For example, to set the line speed for remote debugging 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
You should see output similar to the following: Process dispbmp created; pid = 18
More information about DDD and GDB can be found in “Debugging Programs Using GDB and DDD” on page 132. 7.
In KDevelop, run the debugger. From the Debug menu, select Start or Start (other)... This launches DDD using the options speciÞed.
8.
DDD creates a window with two panes. The lower, smaller pane provides a work space for direct entry of GDB commands and viewing GDB responses.
MontaVista™ Linux® Professional Edition
125
Chapter 7: Application Development Building Programs Using KDevelop
•
To connect to the remote debugging stub using a TCP connection, enter: target remote
where
•
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 system being debugged. This connection will run at the serial-line speed speciÞ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 to run 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. Executable and Menu Text should contain the correct information by default.
3.
In the Arguments Þeld, enter: --host
where
126
4.
Ensure that the box Capture output is checked.
5.
Click the Replace button.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building Programs Using KDevelop
6.
Click the OK button.
You may now run DDD with remote debugging on your executable by selecting DDD from the Tools menu.
Help
You can access MontaVista Zone from inside KDevelop by selecting MontaVista Support from the Help menu. For more information about MontaVista Zone, see “MontaVista Zone” on page 11. A supported Web browser must be available in the desktop execution environment to view the content. For Linux systems, supported browsers include Konqueror (KDE 2), Netscape (netscape-communicator), and Mozilla. For additional information about using GDB and DDD, see the GNU manuals for those applications. The GNU GDB and DDD manuals are available on MontaVista Zone.
MontaVista™ Linux® Professional Edition
127
Chapter 7: Application Development Building 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 your programs rather than the KDevelop IDE. When using the command-line compilers to build 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 a my_work_directory/myapplication directory for your application development and a my_work_directory/myfilesystem directory for your Þle-system development. These directories will be used in all examples below. We also recommended that you NFS mount the myfilesystem directory on the target for testing. It is assumed in the examples below that the myfilesystem directory contains your target Þle system and that it is NFS-mounted as the target’s root Þle system. For all of these examples, the user’s executable search path has been updated to include 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 is 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, write your program. For this example, we’ll use the simple “hello world” program saved as hello.c. #include <stdio.h> main(int argc, char **argv) { printf("hello world\n"); }
2.
Using the cross-development tools included with Pro, on the host, build the 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 using gcc, 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/
128
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Building 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: ./hello hello world
Example of a C++ Program
The following is an example of a simple C++ program on a PowerPC 8xx target. Bold is 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, write your program. For this example, we’ll use a simple “hello” program saved as hello.cc. #include
2.
Using the cross-development tools included with Pro, on the host, build the 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 using g++, 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: ./hello hello 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
MontaVista™ Linux® Professional Edition
129
Chapter 7: Application Development Building Programs Using GCC and G++
130
•
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
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Using Threads
Using Threads For building multi-threaded applications, Pro provides LinuxThreads. LinuxThreads is an implementation of the POSIX threading library speciÞcation IEEE 1003.1c. LinuxThreads implements a 1:1 threading model, allocating one kernel thread for each user-space thread created by the program. LinuxThreads is the standard Linux threading library. To use LinuxThreads in your application, you need to do the following: •
Use #include
•
Add -lpthread to your application's compilation options to link against 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
Chapter 7: Application Development Debugging Programs Using GDB and DDD
Debugging Programs Using GDB and DDD Pro provides a number of tools for debugging code; however, the main troubleshooting tool available for debugging application code is currently GDB. GDB is a command-line debugger that allows you to step through code, set break points, and print 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 the execution of the program being debugged
•
a client that runs on the host and provides a command interface and access 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 being debugged 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 catch bugs: •
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 to experiment with the effects of a change
Pro also includes the program DDD. DDD is a graphical front-end for Linux debuggers, including the GDB debugger. Using DDD with GDB, it is possible to point and click through debugging an application program. You can use GDB to debug programs written in C, C++, and assembly. Examples follow 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 to include the Pro applications. For information on how to update your path, see “Running Pro Applications and Tools” on page 40.
Additional Documentation
132
For additional information about using GDB and DDD, see the GNU manuals for those applications. The GNU GDB and DDD manuals are available via MontaVista Zone.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Debugging Programs Using GDB and DDD
Example of Using GDB
Following is an example of using GDB to debug a Pentium III target system. In the default 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 to strip programs to save space on the target, and doing so prevents the GDB client from accessing symbol information. Note: When working with a stripped binary on the target, the host requires a nonstripped 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’s usr/bin directory, you can begin debugging in the target environment, as in the example below. Bold indicates user input.
On the GDB server command line, 2345 is the network port number on which the server waits for a connection from the client. This can be any available port number on 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 name and the port is 2345, you can begin debugging in the host environment as shown in the 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 you are welcome to change it and/or distribute copies of it under certain conditions. Type "show copying" to see the conditions. There is absolutely no warranty for GDB. Type "show warranty" for details. This GDB was configured as "--host=i686-pc-linux-gnu --target=i686linux". (gdb) target remote Voyager:2345 Remote debugging using Voyager:2345 0x3000ffbc in ?? () (gdb)
MontaVista™ Linux® Professional Edition
133
Chapter 7: Application Development Debugging 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 III target system. In the default conÞguration for Pro for Pentium III, 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 to strip programs to save space on the target, and doing so prevents the GDB client from accessing symbol information. Bold indicates user input. Note: When working with a stripped binary on the target, the host requires a nonstripped 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 a connection from the client. This can be any available port number on the target. 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. Use the 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 console similar to the following: Remote debugging using Voyager:1000
Voyager is the machine name and the port is 1000. You can now begin debugging in the host environment using the interface provided by DDD.
134
5.
Set a breakpoint on main by double clicking or entering on the command line: b main
6.
Click the cont button.
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Debugging 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 call fork(), vfork(), and execve(). To stop execution when the debugged program calls fork, vfork, or exec respectively, 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 the default), 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
Chapter 7: Application Development Debugging Multi-Threaded Applications
Debugging Multi-Threaded Applications With 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 about threads: •
Threads in Linux are not child processes of the creator thread – all threads 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 particular thread and to set a break point. There are two ways to set a break point with threads using DDD:
Additional Information
•
You can specify the address of the break point and the thread number.
•
Or you can attach to the thread and then set the break point.
There are several good sources of information about threads available. Note: MontaVista Software does not endorse any of the books or Web sites (other than our own) listed in this section. Examples are provided for your convenience only.
Books Pthreads Programming. by Bradford Nichols, Dick Buttlar and Jacqueline Proulx Farrell. O'Reilly & Associates, 1996 ISBN: 1565921151 POSIX
Web Sites The Linux Threads FAQ on MontaVista Zone http://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
Chapter 7: Application Development Additional Tools for Programming and Debugging
Additional Tools for Programming and Debugging The following tools have been found to be valuable time-savers in developing and debugging Linux applications. Many of these applications are free-source and available 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 answer questions 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: •
cßow
http://www.ziplink.net/~felaco/cbrowser/
cflow reads a list of source Þles and prints a graph of the program's function call hierarchy. Called functions are indented with respect to their calling functions. cflow can be downloaded from: •
cscope
http://metalab.unc.edu/pub/Linux/devel/lang/c/!INDEX.short.html
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
Chapter 7: Application Development Additional Tools for Programming and Debugging
cscope builds a symbol database that can be searched for the answers to those questions. It searches the database and displays a window of the Þles, which can then be opened in your favorite editor. cscope can be downloaded from: •
dmalloc
http://cscope.sourceforge.net
dmalloc is a memory allocation debugger that supports both C++ and threading. dmalloc is part of the Pro distribution. More information about how to use dmalloc 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 the executed process and the signals that are received by that process. ltrace is part of the Pro distribution. More information about how to use ltrace can be found by reading the man page for ltrace.
mtrace
There is a feature of the GNU C Library called mtrace. Using this feature allows you to detect memory leaks caused by unbalanced malloc and free calls. mtrace is implemented as a function call to turn on tracing. When implemented, mtrace creates a log Þle of addresses malloc'd and free'd. A perl script is used to display the log Þle listing only the unbalanced combinations and, if the source Þle is available, 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 C Library: •
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 and view the Memory Allocation section. In particular, within the Memory Allocation section, see the section on Allocation Debugging. Information on mtrace was the April 2001 Tip and Trick article on MontaVista Zone (http://support.mvista.com/content/TipArchive/april2001.html), which included sample programs and scripts.
138
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Additional Tools for Programming and Debugging
strace
strace is a focused debugging tool for tracing system calls and signals by intercepting and recording system calls called and received by a process. strace is part of the Pro distribution. More information about how to use strace can 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 that is easy to read. It is easy to Þgure out which assembly code each C-source line generated. Color is used to make the output easier to read. showasm can be downloaded from MontaVista Zone.
MontaVista™ Linux® Professional Edition
139
Chapter 7: Application Development Using AltiVec™ Technology by Motorola
Using AltiVec™ Technology by Motorola AltiVec™ technology provides general-purpose processing for PowerPC microprocessors while concurrently addressing high-bandwidth data processing and algorithmic-intensive computations in a single-chip solution. Using AltiVec technology can:
Features
Limitations
•
provide multichannel modems, echo cancellation equipment, and base-station processing
•
enable encryption methods optimized for the SIMD processing model
•
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 3D graphics, etc.)
When using Motorola's AltiVec technology with Pro: •
assembler supports AltiVec instructions -- allows user applications to be written with in-line assembly AltiVec code
•
the Kernel and C Library support saving and restoring AltiVec registers
•
the C library supports the use of setjmp and longjmp in combination with AltiVec code
No direct support is available for AltiVec C extensions. MontaVista Software is evaluating these extensions. The kernel currently ignores VRSAVE and saves all registers when switching between two user tasks running AltiVec code. These actions:
140
•
may hide errors when using VRSAVE in user code
•
may cause problems in the future if optimizations to use VRSAVE to determine which registers to save and restore are implemented in the kernel
MontaVista™ Linux® Professional Edition
Chapter 7: Application Development Using 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
Chapter 8: System Integration
Overview Once you have Þnished developing your kernel and application, you are ready to begin deployment of your embedded application. The Þrst thing you need to do is integrate your system components (the kernel and the application) in a test environment. The steps listed below are guidelines. You may need to change the order of integration, depending on the type of Þle system you have or other development needs. 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
Chapter 8: System Integration Overview
Once you have completed the steps above, you should have a system that appears as follows: User-Space Configs
Local Network Pro --------------Red Hat 7.3
Custom Apps NFS Root File System
Custom Kernel
Target File System
Serial
................... .................. Target Host
144
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Creating Your File-System Hierarchy
Creating Your File-System Hierarchy Once you are satisÞed with your kernel and application, you need to determine which additional libraries and applications are required to support your application so that you 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 by MontaVista that you need in your embedded system.
3.
Add your custom applications to the Þle system hierarchy created by TCT.
Guidelines on how to complete the above steps are included in the sections below.
Select a Deployment FileSystem Type
Knowing which ßash, memory, and disk drive provided by the board in your product will determine the size and type of your Þle system, which in turn will dictate how many applications can be included. You should know the type of Þle system you want to 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 target boards 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 such as CramFS. In addition, MontaVista Software also provides a tool for reducing the size 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 wider range of choices. One choice is ReiserFS, a journaling Þle system, which can be a good choice if your embedded application will need to be turned on and off on a regular 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 of XFS include quick journaling recovery, fast transactions, high scalability, and excellent bandwidth. MontaVista Software supports the following Þle system types: •
CramFS
•
EXT2 and EXT3
•
Journaling FLASH Filesystem (JFFS)
•
ReiserFS
•
XFS
MontaVista™ Linux® Professional Edition
145
Chapter 8: System Integration Creating Your File-System Hierarchy
Not all of the Þle systems listed in this section can be used with all target boards. To help you decide which Þle system you want to use, here are some notes about the features and limitations for each Þle-system type. In addition, check the MontaVista Zone 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 than 16MB, 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 created along 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 in conjunction with another Þle system and can be used with MTD (Memory Technology Device). Check the MontaVista Zone page for your target for information about 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 using CramFS 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 and CD-ROM drives. EXT2 supports up to 4 Terabyte Þle system sizes and Þle name sizes of up to 255 characters. EXT3 is the latest version of the EXT Þle system. Two big improvements included in EXT3 are support for access control lists (ACLs) conforming to Posix Semantics (IEEE 1992), and journaling (automatic recovery when the Þle system is remounted). EXT2 is supported on all Pro architectures. EXT3 is experimental; however, it is available for all Pro architectures. Check the MontaVista Zone page for your target for 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
Chapter 8: System Integration Creating Your File-System Hierarchy
Journaling FLASH File System (JFFS) The Journaling Flash Filesystem (JFFS) was developed by Axis Communications in Sweden. JFFS: •
provides a Þle system directly on ßash, rather than emulating a block device
•
is designed for use on ßash-ROM chips and it recognizes ßashROM 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 times erase_sector_size times the number of ßash chips that is required for garbage collection. JFFS has some limitations. It doesn’t do garbage collection incrementally, and it blocks read during the garbage collection erase sectors, which may last for several seconds. In some cases, JFFS has failed after consecutive power cycles during writes to the ßash. JFFS2 is the next version of JFFS. JFFS2 provides improved wear-levelling and garbage-collection performance; improved RAM footprint and response to systemmemory pressure, improved concurrency and support for suspending flash erases; marking of bad sectors with continued use of the remaining good sectors, thus enhancing the write-life of the devices; native data compression inside the file system design; and support for hard links. Check the MontaVista Zone page for your target for information about support for this 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, the supplied MTD Utilities (in /usr/sbin), and some frequently asked questions about JFFS and MTD.
•
http://developer.axis.com/software/jffs/
•
http://www.linux-mtd.infradead.org/
MontaVista™ Linux® Professional Edition
147
Chapter 8: System Integration Creating Your File-System Hierarchy
•
ftp://ftp.uk.linux.org/pub/people/dwmw2/mtd/cvs/mtd/mtd-jffsHOWTO.txt
ReiserFS ReiserFS is a journaling Þle system. The main beneÞt of ReiserFS is that there is no need for a lengthy Þle-system check (fsck) when the system is rebooted. During normal operation, ReiserFS logs all changes to Þle-system structure (metadata) to a special 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 for non-journaling Þle systems. The ReiserFS journal area is currently Þxed in size at 30 megabytes. This makes ReiserFS unsuitable for Þle systems that are less than about 100 megabytes in size. ReiserFS is currently supported on all Pro architectures. Check the MontaVista Zone page 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/Þlesystemsblock.html
XFS XFS is a journaling Þle system developed by SGI and used in IRIX operating system from SGI. XFS combines advanced journaling technology with full 64-bit addressing and scalable structures and algorithms. The main features of XFS include quick journaling recovery, fast transactions, high scalability, and excellent bandwidth. XFS provides the following beneÞts:
148
•
sub-second Þle system recovery after crashes, which means no long fscks 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 per directory)
•
two terabyte Þle system limit is due to the Linux block device I/O layer
•
extremely scalable using Btrees extensively to support large and/or sparse Þles and extremely large directories
•
resizing
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Creating 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 block addressing limitation effectively limiting the maximum Þle system size to 137 GB
SGI XFS is currently supported on all Pro architectures. Check the MontaVista Zone page for your target for information about support for this feature on your target. Additional information about SGI XFS is available at: •
XFS FAQ http://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 on MontaVista 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 a dependency on another package, that package is automatically installed with the selected package. TCT will also tell you the size of your Þle system. Once you have selected 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 a dependency on another package, that package is automatically installed with the selected 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 include in your Þle system.
2.
Use TCT to build the Þle system. TCT creates a tar-archive of the Þle system.
MontaVista™ Linux® Professional Edition
149
Chapter 8: System Integration Creating 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 to a build directory (for example, myfilesystem), the next step is to add you application. Copy your application to where you want it to reside in the target Þle system. The default Þle system layout of the target follows the Filesystem Hierarchy Standard (FHS). When deciding where to place your application, we recommend that you follow the FHS guidelines. For more information, see: •
150
http://www.pathname.com/fhs/
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Booting 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 boot the target with the new kernel and NFS-mount your Þle system. The kernel is either the one you modiÞed for your embedded application, or, if you chose not to modify the kernel, it is the default kernel supplied by MontaVista Software. If you used TCT to develop your kernel, your kernel image is included in the tar archive created by TCT. 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 the Target with a Custom Kernel” on page 52. Note: The instructions include NFS mounting the target’s root Þle system. By exporting the Þle system directory as NFS, you can test your environment on the target before spending the development time to reduce the size of the Þle system or adding the Þle system to ßash.
MontaVista™ Linux® Professional Edition
151
Chapter 8: System Integration Configuring the User-Space Environment
ConÞguring the User-Space Environment Once you have installed Pro and completed your kernel, application and Þle-system development, and you have exported the Þle-system directory as NFS, the next step in system integration is to tailor your target’s user-space environment to your application. While we cannot anticipate the particulars of every situation, some examples of common setups are provided below. This section contains information about the following conÞguration settings and tools:
Enable Run-Level Services (Startup Scripts)
•
“Enable Run-Level Services (Startup Scripts)” on page 152
•
“ConÞgure the Target for Serial Console or Virtual Terminal” on page 156
•
“Create Standard Device Nodes” on page 158
•
“Add Shells” on page 158
•
“Start PCMCIA” on page 160
•
“ConÞgure Networking” on page 160
initdconfig is used to enable run-level services for initscripts. For more information 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 Applications and Tools” on page 40 for more information about how to update your executable path to easily run this script and how to access man and info pages. The following is the command line help for initdconfig: Usage: initdconfig initdconfig initdconfig initdconfig initdconfig initdconfig
Levels - S 0 1 2 3 4 5 6
--add
Startup halt Single User Multiuser (No networking) Normal/Multiuser (w/ networking) reserved for local use (same as 3) xdm or equiv graphic login reboot
Note: The levels indicated in the help are guidelines. They are not hard and fast rules.
152
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 similar to this:
mountfs umountnfs.sh urandom ifupdown cron anacron
0:on 0:on
6:on 6:on
S:off S:on 2:off 2:off
3:off 3:off
4:off 4:off
5:off 5:off
In the above example: •
The initscripts, umountfs and umountnfs.sh execute in run levels 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, and 5. 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
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 the command: initdconfig [--level
For example, if you want cron to only run in levels 3 and 4, use the command: initdconfig --level 34 cron on
MontaVista™ Linux® Professional Edition
153
Chapter 8: System Integration Configuring the User-Space Environment
Disabling an initscript To disable an initscript in all run levels (speciÞed by the initscript) use the --del option, followed by the initscript name. Use the command: initdconfig --del
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 the command: initdconfig [--level
For example, if you want to disable the run levels 3 and 4 for cron, use the command: initdconfig --level 34 cron off
Note: The reset option (in place of on/off) Þrst turns the run levels off and then turns them 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 created by 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.d directory. The symbolic links are named SXXname or KXXname. Here is what each component 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 the initscripts 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 the scripts in /etc/rc.d/rcS.d. Once those scripts have been started, control is returned to sysvinit. When run levels change, /etc/init.d/rc is run with the argument of the new run level. This script is responsible for stopping all of the services beginning with a K at the speciÞed run-level and higher-numbered run levels and starting all of the services beginning with an S at the speciÞed run level and lower-numbered run levels.
154
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 the following 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 by the initdconfig program. Starting run levels may be any combination of S, 0, 1, 2, 3, 4, 5, and 6. The starting run level implies the stopping run level. If you specify S as the starting run level then the stopping run levels are automatically 0 and 6. If you specify 0, 1, 2, 3, 4, 5, or 6 then 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 stop processes. If there are two items with the same start/stop priority there is no guarantee to 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. For example, 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 is never started, but stops in run levels 0 and 6. The /etc/init.d/skeleton example also shows the parameters most initscripts contain: •
start starts the item
•
stop stops the item
•
reload reloads the item if possible (usually by sending a SIGHUP)
MontaVista™ Linux® Professional Edition
155
Chapter 8: System Integration Configuring the User-Space Environment
•
ConÞgure the Target for Serial Console or Virtual Terminal
restart and force-reload should stop and then restart the daemon (force-reload is only implemented if reload is implemented.)
The /etc/inittab Þle on your target is used to conÞgure the target for use with a serial console or virtual terminal. Once the target has been booted, edit the /etc/inittab Þle to reßect the setup you are using (serial console or virtual terminal.) Example Þles are included in the Pro distribution for both virtual terminals (video consoles) and serial consoles. Comments are included in the example Þles to help you determine 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 by adding a “#” at the beginning: con:2345:respawn:/sbin/getty console
3.
Enable the correct console for your system by uncommenting the line for 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 serial port, you need to uncomment one of the following lines (depending on which serial port 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 on ttySA0 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 also wish 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
Chapter 8: System Integration Configuring 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 Runlevel 1 is Runlevels 2-5 Runlevel 6 is
halt. single-user. are multi-user. reboot.
l0:0:wait:/etc/init.d/rc 0 l1:1:wait:/etc/init.d/rc 1 l2:2:wait:/etc/init.d/rc 2 l3:3:wait:/etc/init.d/rc 3 l4:4:wait:/etc/init.d/rc 4 l5:5:wait:/etc/init.d/rc 5 l6: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 start pn::powerfailnow:/etc/init.d/powerfail now po::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: #
MontaVista™ Linux® Professional Edition
157
Chapter 8: System Integration Configuring 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 creates device 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 the how 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 the target, 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 following commands: cd /dev ./MAKEDEV fb
To create all of the normal audio device nodes, on the target, enter the following commands: cd /dev ./MAKEDEV audio
Add Shells
shellconfig is used to add shells to the /etc/shells Þle and to set the symbolic 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 Applications and Tools” on page 40 for more information about the how to update your executable path to easily run this script and how to access the man and info pages for this application. The following is the command line help for shellconfig: Usage: shellconfig shellconfig shellconfig shellconfig shellconfig
--add
If you are using shellconfig as a cross-development application, you need to use the architecture and processor preÞx in the commands in the following sections (<architecture-prefix>-shellconfig).
158
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 similar to the following: Name Priority /bin/ash: 10 /bin/ash.static: 11 /bin/bash: 1 /usr/bin/sash: 50 /bin/sh is linked to /bin/bash.
POSIX Shell (sh) yes yes yes yes
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, and is 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 adding a shell with --add, the
Removing a shell You can remove a shell from the conÞguration Þles with the --del option. You may list as many shells on the command line as you want and each of them will be removed from the list. When deleting a shell, the
MontaVista™ Linux® Professional Edition
159
Chapter 8: System Integration Configuring the User-Space Environment
Start PCMCIA
Pro provides pre-built PCMCIA. Check the MontaVista Zone page for your target for information about support for this feature, along with information about the cards tested and enabled with your LSP. Note: If your application requires a type of card not tested or enabled by MontaVista Software, you need to enable the PCMCIA driver in the kernel conÞguration and rebuild the kernel. For more information about rebuilding the kernel, see “Building and ConÞguring the Kernel” on page 76. Once PCMCIA is enabled in the kernel, to start PCMCIA, on the target, enter the following command: /etc/init.d/pcmcia start
The above command loads the card services modules and starts the cardmgr daemon. To start PCMCIA at boot, use the utility initdconfig either on the host or the target. (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 the loopback device by default. An entry for eth0 is not necessary, because the LSPs enable the auto IP option in the kernel. When you are ready to build a stand-alone system for deployment, you may wish to use a different conÞguration. Pro includes Internet Protocol Version 6 (IPv6). The sections below provide information about IPv6, an example to show how to set-up a minimal network using either IPv4 or IPv6, and information about MontaVista Net (a PCI-based back-panel communication product).
IPv6 Internet Protocol Version 6 (IPv6) is the next generation of the internal protocol and is beginning to replace the more standard IPv4. IPv6 adds many improvements over IPv4 in areas such as routing, network autoconÞguration, security, and scalability. The most signiÞcant change is that IPv6 uses 128bit address space (4 times longer than IPv4) allowing for more available addresses. Note: Some IPv6 speciÞcations are NOT supported. For more information, see MontaVista Zone.
Enabling IPv6 IPv6 is enabled as a module by default.
160
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring 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 run on 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 and ConÞ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 will not be served. The following list contains the target utilities included with Pro that can be used with IPv6:
•
apache
•
netkit-rsh
•
atm
•
ping
•
bsd-Þnger
•
proftp
•
inetd
•
radvd
•
iproute
•
sendmail
•
libinet6
•
sysklogd
•
linux-ftpd
•
tcpdump
•
netkit-base
•
tcp-wappers
•
netkit-ftp
•
ucd-snmp
•
netkit-telnet
•
xinetd
•
net-tools
MontaVista™ Linux® Professional Edition
161
Chapter 8: System Integration Configuring 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/Work station would. This example assumes that you have networking enabled in the kernel and that you have loaded the appropriate packages. As an incomplete list, these packages 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:
162
•
/etc/hostname
•
/etc/hosts/
•
/etc/services
•
/etc/inetd.conf
•
/etc/nsswitch.conf
•
/etc/resolv.conf
•
/etc/network/interfaces
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Configuring the User-Space Environment
The above Þles have the following format: /etc/hostname test.mvista.com
/etc/hosts #IPv4 Address 127.0.0.1 192.168.2.202 192.168.2.190
localhost test.mvista.com rootnfs.mvista.com
#IPv6 addresses ::1 3ffe:305:1002:8010::1
localhost.localdomain test rootnfs
ipv6-localhost test.mvista.com
ipv6-loopback test
/etc/nsswitch.conf passwd: files group: files hosts: files networks: files ethers: files protocols:files rpc: files services: files
/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 the hosts: entry in the /etc/nsswitch.conf Þle above. domain mvista.com search mvista.com nameserver 192.168.14.10 nameserver 192.168.14.38
/etc/network/interfaces Use the examples provided in the /etc/network/interfaces Þle to create an entry like the following to set up each Ethernet interface: #IPv4 Addresses auto eth0 iface 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 addresses auto eth0 iface eth0 inet6 static address 3ffe:305:1002:8010::1 netmask 64
MontaVista™ Linux® Professional Edition
163
Chapter 8: System Integration Configuring the User-Space Environment
MontaVista Net MontaVista Net is a PCI-based back-panel communication product. MontaVista Net can be used in one of two ways: •
to off load conventional Ethernet interfaces for transactions between processors in the same chassis
•
as a complete replacement for Ethernet – this option allows Peripheral Processors to boot from ßash and remote mount the root Þle system via NFS, through the MontaVista Net back-panel interface
Instructions for conÞguring and using MontaVista Net can be found on MontaVista Zone.
164
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Testing Your Environment
Testing Your Environment At this stage in your application’s development, you should fully test your application. Because every project is different and has different requirements on the system, how you test your project is up to you. We do, however, recommend that you do incremental tests. By starting with a system that works, when you reduce the Þlesystem size you can more easily determine which libraries and applications are still needed by your application. We also highly recommend doing complete testing before you reduce the size of your Þle system, as in many cases, doing so will remove the symbol information required for proper debugging.
MontaVista™ Linux® Professional Edition
165
Chapter 8: System Integration Reducing 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 reduce the 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 to determine which components of supported shared libraries are required by the included executables and shared libraries. LOT then rebuilds the supported shared libraries so they contain only the required code, which often results in a signiÞcant size reduction. Because LOT removes symbols used for debugging, it is important that you test and debug 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 a shared library to be supported for use with LOT, the library packages containing detailed information about the contents of the library must be installed on the host machine. Currently, two libraries distributed with Pro have the detailed optimization information. They are: •
glibc
•
ncurses
The library packages containing the detailed optimization information for glibc and ncurses were installed by default when you installed Pro.
Usage LOT is a command-line tool. To run LOT, update your executable search PATH to include the Pro applications. Instructions on how to run Pro applications can be found in “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:
166
•
-s Strips the optimized libraries of all debugging information. Libraries or executables in the speciÞed tree that do not have the required optimization information are not stripped.
•
-d <destree> SpeciÞes the base of the Þle hierarchy where the resulting
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Reducing the Size of Your File System
optimized libraries will be placed. This directory must be a directory 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 is required.
We recommend that the target directory be a separate tree that you have built. When using LOT, you should work in a project directory created for building your Þle system. In the section “Project Directories” on page 38, we recommend creating a my_work_directory/myfilesystem directory for your Þle-system development. We also recommended that you NFS-mount the myfilesystem directory on the target for testing. It is assumed in the example below that the myfilesystem directory contains your target Þle system, and that it is NFSmounted as the target’s root Þle system. One good way to build the target directory is to untar the Þle-system tar archive created 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 will be on the target (this includes your applications). We make this recommendation because if a destination tree is not speciÞed, the optimizer writes over the full versions of the libraries. If your <srctree> is in the /opt/hardhat tree, the library packages 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 directory hierarchy to be optimized is my_work_directory/myfilesystem/fs-1. The directory mylib contains the bash shell executable. The directory fs-1/lib contains the libraries for glibc that have the required detailed optimization information and the libraries for myprogram that do not. The directory fs-2 is where 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
Chapter 8: System Integration Reducing the Size of Your File System
168
•
The Þle tree under fs-1 is scanned for executables and shared libraries. Standard library search rules are used, so shared libraries should be located in the same relative directory as they will be on the target.
•
For each shared library that contains the detailed optimization information (glibc in this example), LOT: •
determines which symbols and code are required
•
removes the symbols not required (along with the associated code)
•
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 required optimization information (myprogram and bash shell, in this example) LOT simply determines which symbols are required. These Þles are left in myfs unchanged (that is, not stripped and not copied to fs-2).
•
The same directory structure used in fs-1 is used in fs-2
MontaVista™ Linux® Professional Edition
Chapter 8: System Integration Profiling Your Embedded Application
ProÞling Your Embedded Application Once you have completed development of your environment, you should use proÞling tools to evaluate the project performance and to look for memory leaks, etc. Tools such as Linux Trace Toolkit (LTT) and mtrace, among others, are provided with Pro to help with proÞling your application. In addition, other tools that could not be distributed with Pro, such as netperf, are available via MontaVista Zone.
MontaVista™ Linux® Professional Edition
169
Chapter 9: Deployment
Overview Once you have completed development of your embedded project, you will want to disconnect the target from its reliance on the host and create a stand-alone environment 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. Other conÞgurations that have been used involve using Compact Flash, RAW ßash or SCSI conÞgurations. Because on-board ßash and IDE solutions are most common, this manual provides information about deployment in those conÞgurations. When you are ready to create a deployment candidate, you may wish to discuss your deployment strategy with the MontaVista representative assigned to your account. A stand-alone target may appear as in the diagram below: User-Space Configs
Custom Apps Local Root File System
Custom Kernel
.................. ................... Target
MontaVista™ Linux® Professional Edition
171
Chapter 9: Deployment Overview
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 Deployable Root 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. Once completed, you should have a suitable candidate for deployment. Note: Because there are so many differences between the supported targets and embedded projects, these steps are generic. Your target may not follow these steps exactly as listed and you may need to perform additional steps to enable other functionality. For some hints on trouble-shooting, see “Trouble-Shooting Deployment” on page 187.
172
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Configuring 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 and to enable a deployable root Þle system. The kernel supplied by MontaVista Software sends BOOTP queries and NFS mounts the root Þle system. In this conÞguration, the kernel cannot be run as a system that is stand-alone (that is, without a host or network connection). For deployment, you need to rebuild the kernel to be stand-alone. To rebuild the kernel for a stand-alone conÞguration and to enable a deployable Þle system, complete the following steps: 1.
Start make menuconfig or make xconfig. The latter can be run 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 the desired 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 using MTD 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
Chapter 9: Deployment Configuring 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 and you need to use MTD (Memory Technology Device), ensure that MTD has been enabled in the kernel. For targets that support MTD, MTD should be enabled by default in the kernel supplied by MontaVista Software. If you are using a custom kernel or a target for which MontaVista Software does not yet support MTD, 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 embedded system. For more information about the options to select for each of the supported Þ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 are using 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 the module. See the man page for insmod for information about use and syntax. Another option is to use modprobe rather than insmod. See the man page for modprobe for information about use and syntax. 14. Rebuild the kernel, using TCT or the procedure in “Building and ConÞ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 Þle system. This manual only covers creating a root Þle system for your target. Additional conÞguration not included in this manual is required if you intend to use multiple Þle systems and/or have some Þle systems built as modules. Warning! Do NOT boot the new kernel yet! The next step in the deployment process is to transfer your Þle system to the target. The reason we recommend rebuilding the kernel Þrst is that in many cases, you can transfer your kernel to the target system inside of a Þle-system image.
174
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Configuring 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 been enabled: •
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 options under Filesystems is enabled: •
Journaling FLASH Filesystem (JFFS)
EXT2 File System support or EXT3 File System support
To use JFFS or JFFS2, ensure that the following options are enabled: •
MTD. For targets that support MTD, MTD should be enabled by default in the kernel supplied by MontaVista Software. If you are using a custom kernel or a target for which MontaVista Software does not yet support MTD, information about how to enable MTD is 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: JFFS debugging 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 to work. These devices should be included automatically with the target LSPs that support the ßash driver. Ensure that these devices are present. For more information about 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 found or not. Also, after boot-up, the command cat /proc/mtd can be used to see the details 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 have ReiserFS compiled into the kernel (that is, not as a module). ReiserFS can be built as
MontaVista™ Linux® Professional Edition
175
Chapter 9: Deployment Configuring 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 the whole kernel and not just the module! Because interfaces to the Þle system are changing quickly and often, bugs due to recompiling only the module can appear. Such bugs can be cryptic and difÞcult to resolve.
XFS
MTD
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/
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 not yet fully supported. If the board only has one ßash that you want MTD support on and you only need one MTD device and the chip is CFI (Common Flash Interface) compliant, to enable MTD 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 the MontaVista LSP for your board enables MTD/JFFS, use the settings that are already in the conÞg Þle. Otherwise, this information should be available via the board's memory map and other documentation.
Note: “One ßash” means one or more ßash chips linearly mapped into the address space. They can be organized as x8, x16 or x32 wide memory interfaces using one or more 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 a single ßash type, you also need to create a mapping Þle to describe the ßashes and their partitions (devices) on the board. See the “The following is an example of a mapping Þle.” on page 177 for an example.
176
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Configuring 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 #include #include #include #include #include #include #include
#if defined(CONFIG_MIPS_ITE8172) || defined(CONFIG_MIPS_IVR) #include
MontaVista™ Linux® Professional Edition
177
Chapter 9: Deployment Configuring 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 matches your ß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
Chapter 9: Deployment Creating 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 the target. 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 to complete the following steps: 1.
For some conÞgurations, the Þle-system image may contain the kernel image along with the Þle system. Including the kernel in the Þle-system image is typical of systems that boot from an IDE. Separate transfer is more typical of systems that boot from on-board ßash. If your conÞguration needs the kernel included in the Þle-system image, add a copy 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 transfer that image to the target.
CramFS
CramFS is a read-only Þle system, so unlike other Þle systems, it must be created along 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. Host and 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
You now have a CramFS image that can be easily transferred to the target. 2.
Make sure your ßash is erased.
MontaVista™ Linux® Professional Edition
179
Chapter 9: Deployment Creating a File-System Image
3.
Assuming you used MTD, copy the CramFS image to your ßash. For example: 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 ßash depends 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 not available. Note: CramFS can be used in conjunction with another type of Þle system. If the CramFS Þle system is not the root Þle system, mount the Þle system on the block device where it will be used. (This method is useful for testing the Þle system.) On the target, 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 are using 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 the command above. 3.
Make sure your ßash is erased.
4.
Assuming you used MTD, copy the JFFS image to your ßash. For example: 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 without putting a Þle system on it. This will let you Þll the device interactively under your shell control (that is, copy stuff to the mounted directory).
180
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Creating a File-System Image
The steps above assume that MTD has been enabled in the kernel. MTD is enabled by default 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 create and populate an EXT2/EXT3 Þle system for deployment, complete the following steps: 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/
Mount the new partition. mount /dev/
<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 to contain. Make a tar archive of the Þle-system hierarchy that you created during system integration, move the archive to the new location, and untar the archive. For example, to move the Þle system in the NFS-mounted directory my_work_directory/myfilesystem to the new location, on the target, 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
Chapter 9: Deployment Creating a File-System Image
If desired, convert the EXT2 Þle system to an EXT3 Þle system. To convert your EXT2 Þle system to EXT3, you need to use the tune2fs utility to add a journal to your existing EXT2 Þle system. To add journaling to an EXT2 Þle system created on the 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 matching lines.
Note: To prevent the Þle system from being mounted as EXT2, you need to use initrd to boot the target.
ReiserFS
Assuming you are using an IDE device to store your kernel and Þle system, to create and 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/
Mount the new Þle system. Use the following command: mount /dev/
<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.
182
Populate your target’s Þle system with everything that you want it to contain. Make a tar archive of the Þle-system hierarchy that you created during system integration, move the archive to the new location, and untar the archive.
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Creating a File-System Image
For example, to move the Þle system in the NFS-mounted directory my_work_directory/myfilesystem to the new location, on the target, 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 a ReiserFS Þle system as the root Þle system.
XFS
Assuming you are using an IDE device to store your kernel and Þle system, to create and 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/
Mount the new Þle system. Use the following command: mount /dev/
<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 to contain. Make a tar archive of the Þle system hierarchy that you created during system integration, move the archive to the new location, and untar the archive.
MontaVista™ Linux® Professional Edition
183
Chapter 9: Deployment Creating a File-System Image
For example, to move the Þle system in the NFS-mounted directory my_work_directory/myfilesystem to the new location, on the target, 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
Chapter 9: Deployment Setting 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 edit this Þle to ensure that the Þle systems you are using are available. You also need to edit 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. #/etc/fstab #device #
directory
/dev/hda6 /dev/hda1 proc /dev/hda5
Sample 2
type
/ /boot /proc swap
ext3 ext3 proc swap
options defaults defaults defaults defaults
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 # /dev/md1 /dev/md0 proc
directory
type
options
/ /boot /proc
ext3 ext3 proc
defaults,errors=remount-ro defaults,errors=remount-ro defaults
dump pass 0 0 0 0 0 0
MontaVista™ Linux® Professional Edition
185
Chapter 9: Deployment Booting 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 vendor documentation for more information about using the board’s Þrmware or for information about hardware conÞgurations. If you have additional questions about how to conÞgure and boot a particular target for deployment, contact your MontaVista representative. Booting the target, usually consists of the following steps: 1.
Hardware setup. Hardware setup may include changing DIP switches or shorting jumpers to permit the board to boot from ßash. Hardware changes are target speciÞc.
2.
Minicom (or other terminal emulation program) conÞguration. You need to use Minicom to communicate with your target. You should use the same communication parameters that you used during development.
3.
Target conÞguration. The Þrmware on the target may need to be conÞgured for booting from ßash or booting from an IDE. The commands are Þrmware speciÞc.
4.
If the kernel was not included in the Þle-system image, transfer the kernel to a storage device on the target. Typically, this is a ßash device or an IDE. The commands for transferring the kernel are Þrmware speciÞc.
5.
Booting the target. To boot the target, the Þrmware often requires a command to begin the boot sequence. The commands are Þrmware speciÞc.
You should now have a system that is a suitable candidate for deployment. If your target 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-Shooting Deployment” on page 187.
186
MontaVista™ Linux® Professional Edition
Chapter 9: Deployment Trouble-Shooting Deployment
Trouble-Shooting Deployment Corrupt File System
If you would like to check the integrity of your Þle system, use one of the following commands: For an EXT2/EXT3 Þle system, use the fsck utility. Run the following command: fsck /dev/
For a ReiserFS Þle system, use the resierfsck utility. Run the following command: resierfsck /dev/
MontaVista™ Linux® Professional Edition
187
Appendix A: Pro File-System Layout
Overview There are two main components to the Þle-system layout used for Pro: the crossdevelopment environment layout and the target layout. The cross-development environment file-system layout was created with several goals in mind: Pro components must be self-contained, traditional RTOS cross-development layout is needed, 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
Appendix A: Pro File-System Layout Base Directories
Base Directories All of the Þles that make up the Pro cross-development environment are located inside of a single hardhat directory. This directory, by default, resides in the /opt directory on the host machine’s Þle system. Contents of Base Directories /opt /hardhat
Description Default installation directory. Pro is fully contained in this directory. By default, the /hardhat directory is installed within the /opt directory.
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 to replace /opt in all path names in this manual with the directory that you used.
190
MontaVista™ Linux® Professional Edition
Appendix A: Pro File-System Layout /hardhat Directory
/hardhat Directory The hardhat directory contains two directories that are used to segment the crossdevelopment tools into two categories: cross tools and host tools. Contents of /hardhat Directory
Description
/devkit
Contains cross tools and Linux kernel source code.
/host
Contains host tools.
More information about the tools included can be found in “Pro Applications” on page 197.
MontaVista™ Linux® Professional Edition
191
Appendix A: Pro File-System Layout /devkit Directory
/devkit Directory The /devkit directory contains one directory for each installed architecture family, a /kernel directory and an /lsp directory. Contents of /devkit Directory
Description
/kernel
Generic Linux kernel source code and related items.
/lsp
Board speciÞc Linux kernel source code and related items.
/arm, /mips, /ppc, /sh, /x86, etc.
Architecture family directories.
/kernel Directory
The /kernel directory contains one or more versions of the MontaVista Software uniÞed kernel. The kernel source located in this directory is generic and not speciÞc to any target board. The directory may also contain related items, such as functionality patches. This kernel is for reference only. We strongly recommend that you use the kernel located in the /lsp directory that was created speciÞcally for your reference board.
/lsp Directory
The /lsp directory contains directories for each reference board LSP installed. The board directory contains a conÞgured Linux kernel source for that board. The board directory may also contain board-speciÞc patches, bootloader source code, documentation and control Þles. An example of the /lsp layout for the embeddedplanet-ep8260-ppc_82xx LSP is given below: Sample Contents of an /lsp Directory /embeddedplanet-ep8260-ppc_82xx
Architecture Family Directories
192
Description LSP directory name. In this case, the LSP directory name is for the Embedded Planet EP8260 target board.
/desc
Target ConÞguration Tool (TCT) conÞguration Þle.
/linux-2.4.17_
ConÞgured Linux kernel source.
/README
LSP readme Þle.
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 the processor types for each architecture family. The various architecture family directories are used to group all of the processor-speciÞc cross-development tools and associated target Þles.
MontaVista™ Linux® Professional Edition
Appendix A: Pro File-System Layout /devkit Directory
An example of the ppc architecture family is given below: Sample Contents of an Architecture Family Directory
Description
/devkit
By default, the architecture family directory is installed in the /devkit directory.
/ppc
Architecture family directory name. In this case, the architecture family name is for the PowerPC processor type.
/405, /7xx, /74xx, /8xx, /82xx
Processor directory names.
Some architecture families, such as the MIPS architecture, use a different naming scheme:
Sample Contents of the MIPS Architecture Family Directory /devkit
Description By default, the architecture family directory is installed in the /devkit directory.
/mips
Architecture family directory name. In this case, the architecture family name is for the MIPS processor type.
/fp_be /nfp_be, /fp_le, /nfp_le
Processor directory names.
When the processor version does not adequately describe a given architecture, the architecture is listed by floating point and endian. The architecture and processor directories contain the cross-development tools. These tools are run on the host and are tailored to a specific target. The structure of the <processor> directory is listed below: Processor Directory Structure
Description
<architecture>
The architecture family directory. By default, the <processor> directory is installed in the architecture family directory.
<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
Appendix A: Pro File-System Layout /devkit Directory
Processor Directory Structure
Description
/lib
Host libraries.
/man
man pages.
/share
Program data Þles.
/var
Program data Þles.
<architecturecanonical-name> /target
Used by GNU tools.
Full target Þle system, build/run-time libraries, etc. This directory can be NFS-mounted on the target.
/bin Directory
The /bin directory contains the various cross-development tools. These tools include the cross-compiler, assemblers, debuggers, etc. It may also include target configuration tools, and other target-specific items.
/etc Directory
The /etc directory contains user-changeable 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 /home directory first, and then in the /etc directory.
/include and /lib Directories
Both the /include and /lib directories contain Þles used to develop additional cross-development tools. The Þles in these directories are designed to build software for the host architecture.
/doc, /info, and /man Directories
The /doc, /info and /man directories contain various pieces of documentation for the cross-development tools. The /info and /man directories contain GNU information and Linux manual pages, respectively. The /doc directory contains pieces of documentation that cover the entire package that was installed. This documentation includes license information, notes, FAQs, and other pieces of documentation taken from a package’s source code.
/share and /var Directories
The /share and /var directories are analogous to the /usr/share and /var directories in a standard Linux Þle system. These may be used for internationalization and other data Þles required by a cross-development tool.
194
MontaVista™ Linux® Professional Edition
Appendix A: Pro File-System Layout /host Directory
/host Directory The /host directory contains various tools and applications that are to be run on the host system and are target independent. While these tools are target independent, they are required to assist in software development. This directory contains several subdirectories: Contents of the /host Directory /host
Description 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.
The structure and purpose of these directories is similar to the cross-development tools listed above.
/bin Directory
The /bin directory contains the host tools. Programs in these directories aid in generic system development. These tools may include programs to augment a host’s environment.
/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 home directory first, and then in the /etc directory.
/include and /lib Directories
Both the /include and /lib directories contain Þles used to develop additional host tools. The Þles in these directories are designed to build software for the host architecture.
/doc, /info, and /man Directories
The /doc, /info and /man directories contain various pieces of documentation for the cross-development tools. The /info and /man directories contain GNU information and Linux manual pages, respectively. The /doc directory contains pieces of documentation that cover the entire package that was installed. This documentation includes license information, notes, FAQs, and other pieces of documentation taken from a package’s source code.
MontaVista™ Linux® Professional Edition
195
Appendix A: Pro File-System Layout /host Directory
/share and /var Directories
196
The /share and /var directories are analogous to the /usr/share and /var directories in a standard Linux Þle system. These may be used for internationalization, and for other data Þles required by a cross-development tool.
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications
Overview Pro includes over 280 application packages. Applications are classiÞed as “crossdevelopment applications,” “host applications,” or “target applications.” Cross-development applications are tools that are run on the host but produce output intended to run on the target. In general, the cross-development applications are compilers, 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 compatible version of TFTP. For the list of host applications, see “Host Application Packages” on page 200. Target applications are intended to be used only on the corresponding architecture target. The Pro distribution contains pre-compiled and pre-packaged versions of these application packages so that RPM can be used to install them on the target. For development, 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 therefore contains 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 of target applications, see “Target Application Packages” on page 204. Note: man and/or info pages are available for many of the applications included. man pages for target applications are not available when using a Solaris host. For more information about using man and info pages, see “Accessing man and info Pages” on page 44.
MontaVista™ Linux® Professional Edition
197
Appendix B: Pro Applications Cross-Development Application Packages
Cross-Development Application Packages The chart below lists the cross-development applications included in the Pro distribution, along with some notes about the applications. Applications are installed by default unless marked as optional in the “Notes” column. Optional applications can 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 (other than our own) listed in this section. Examples are provided for your convenience only. Application Package binutils
Version 2.11.2
Notes Installed: Default Description: Cross version of binutils.
Reference Books and Web Sites http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
bootldr-assabet
2.13.2
Installed: Default for StrongARM targets Description: Bootloader for the Intel® Assabet target.
cross-<architectureprefix>-libtool
1.3.5
Installed: Default Description: Cross version of libtool for a given target architecture. Provides the utility libtoolize. If you are building an open-source package using libtool, you need to run the libtoolize utility in this package before building the application 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 given target architecture.
Using and Porting the Gnu Compiler Collection Gcc Richard Stallman iUniverse.com ISBN: 059510035X
Version change from the Pro 2.1 distribution http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 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
Appendix B: Pro Applications Cross-Development Application Packages
Application Package gdb
Version 5.1
Notes Installed: Default Description: Cross version of gdb for a given target architecture.
Reference Books and Web Sites Debugging with GDB: The GNU Source-Level Debugger Richard M. Stallman, Roland H. Pesch Universe.com ISBN: 0595149197 http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 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 given target architecture.
hardhatutils
1.14
Installed: Default
ksymoops
2.4.3
Installed: Default
ldd
1.0
Description: Various utilities.
Description: Kernel crash dump analyzer. Installed: Default Description: Cross version of ldd for a given target architecture. linux86
0.15.4
Installed: Default (x86 only) Description: Real-mode linker and assembler for x86.
MontaVista™ Linux® Professional Edition
199
Appendix B: Pro Applications Host Application Packages
Host Application Packages The chart below lists the host applications included in the Pro distribution along with some notes about the applications. Applications are installed by default unless marked as optional in the “Notes” column. Optional applications can 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 (other than our own) listed in this section. Examples are provided for your convenience only. Application Package autoconf
Version 2.13
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: Creates scripts to conÞgure source code packages using templates.
automake
1.4p4
Installed: Solaris hosts only Description: Automatically creates makeÞle.in’s from makeÞle.am’s.
bash
2.05a
binutils
2.10.91.0.2
Installed: Solaris hosts only Description: Bourne-Again shell Installed: Solaris hosts only Description: Solaris version of binutils.
http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
bison
1.28
Installed: Solaris hosts only Description: GNU Project parser generator (yacc replacement)
bzip2
1.0.2
cetools
0.3
Installed: Solaris hosts only Description: A block-sorting Þle compressor Installed: Default Description: Set of tools used to convert Microsoft® bootable binary images
db
3.2.9
ddd
3.3.1
Installed: Solaris hosts only Description: Database access methods Installed: Default Description: Data Display Debugger – a graphical front end to GDB
ethload
1.2
Installed: Default Description: Used to load a Microsoft® bootable binary image via the bootme protocol
filesystem
2.0
Installed: Default Description: Host-based Þle-system development kit
fileutils
4.1
Installed: Solaris hosts only Description: File utilities
200
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications Host Application Packages
Application Package
Version
findutils
4.1.7
flex
2.5.4
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: Find utilities Installed: Solaris hosts only Description: A a tool for generating programs that perform pattern-matching on text
gawk
3.1.0
Installed: Solaris hosts only Description: The GNU Project's implementation of the AWK programming language
gcc
2.95.3
Installed: Solaris hosts only Description: Solaris version of gcc
Using and Porting the Gnu Compiler Collection Gcc Richard Stallman iUniverse.com ISBN: 059510035X http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
gettext
0.10.35
grep
2.4.2
Installed: Solaris hosts only Description: GNU internationalization utilities Installed: Solaris hosts only Description: Used to print lines matching a pattern
gzip
1.2.4
hardhatutils
1.14
Installed: Solaris hosts only Description: Used to compress or expand Þles Installed: Default Description: Miscellaneous utilities used by Pro applications
jflash-assabet
1.2
kdelibs
2.2.1
kdevelop
2.0.1
Installed: Default Description: Flash tool for the Intel® Assabet Installed: Default Description: KDE library used by KDevelop Installed: Default Description: C and C++ integrated development environment
ldd
1.0
Installed: Default Description: Prints the shared libraries required by each program speciÞed on the command line
lesstif
0.92.6
Installed: Default Description: motif-like library required for ddd
libtool
1.3.5
ltt
0.9.5a
Installed: Solaris hosts only Description: Generic library support script Installed: Default Description: Linux Trace Toolkit Version change from the Pro 2.1 distribution
The LTT Reference manual is distributed with the LTT package and once installed, can be found in /opt/hardhat/ host/doc/hll-host-ltt-0.9.5a/ index.html.
MontaVista™ Linux® Professional Edition
201
Appendix B: Pro Applications Host Application Packages
Application Package
Version
m4
1.4
make
3.79.1
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: The GNU macro processor Installed: Solaris hosts only Description: GNU make utility to maintain groups of programs
http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
minicom
1.83.0
mkcramfs
2.4.16
Installed: Solaris hosts only Description: Host-to-target communication tool. Installed: Default Description: Used to make a cramfs Þle-system image
modutils
2.4.13
ncurses
5.2
Installed: Solaris hosts only Description: Linux module utilities Installed: Solaris hosts only Description: The ncurses library routines give the user a terminal-independent method of updating character screens with reasonable optimization
patch
2.5.4
Installed: Solaris hosts only Description: Used to apply a diff Þle to an original
pcmcia-cs
3.1.30
perl
5.6.1
Installed: Default Description: PCMCIA card services Installed: Solaris hosts only Description: Practical Extraction and Report Language
platformtest
0.1.2
Installed: Default Description: ConÞguration utilities and scripts for compiling Pro sources
python
2.0
qt
2.3.1
Installed: Solaris hosts only Description: Required for TCT 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 that can 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 scripts for compiling Pro sources
sed
3.02
shellutils
2.0.11
Installed: Solaris hosts only Description: A stream editor Installed: Solaris hosts only Description: Various shell utilities
202
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications Host Application Packages
Application Package tar
Version 1.13.19
Notes
Reference Books and Web Sites
Installed: Solaris hosts only Description: The GNU version of the tar archiving utility
tcl
8.3.2
texinfo
4.0b
tftp-hpa
0.17 and 0.31
Installed: Solaris hosts only Description: Tcl scripting language Installed: Solaris hosts only Description: GNU Documentation system 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
tsload
1.0.0
zlib
1.1.3
Installed: Solaris hosts only Description: TK scripting language Installed: Default Description: Bootloader for various targets Installed: Solaris hosts only Description: A compression and decompression library
zsrec
1.0
Installed: Default Description: Needed S-Records format
to
produce
Motorola
MontaVista™ Linux® Professional Edition
203
Appendix B: Pro Applications Target Application Packages
Target Application Packages The chart below lists the target applications included in the Pro distribution along with some notes about the applications. Applications are installed by default unless marked as optional in the “Notes” column. Optional applications can 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 (other than our own) listed in this section. Examples are provided for your convenience only. Application Package adduser
Version 3.24
Notes
Reference Books and Web Sites
Installed: Default Description: Allows users to be added to group or password Þles
anacron
2.3
Installed: Default Description: A cron-like program that can run jobs lost during downtime Requires cron
apache
1.3.20
Installed: Default Description: The most widely used Web server on the Internet
ash
0.3.8
Apache: The DeÞnitive Guide Ben Laurie, Peter Laurie, Robert Denn (Editor) O'Reilly & Associates ISBN: 1565925289
Installed: Default Description: A smaller version of the Bourne shell (sh). Functionality of interest: sh, ash.static
at
3.1.8
aumix
2.7
autoconf
2.13
Installed: Default Description: Job spooling tools Installed: Default Description: Sound utility Installed: Default Description: A GNU tool for automatically conÞguring source code
autofs
3.1.7
GNU Autoconf, Automake, and Libtool Gary V. Vaughan, Ben Elliston, Tom Tromey, Ian Lance Taylor New Riders Publishing ISBN: 1578701902
Installed: Default Description: A tool for automatically mounting and unmounting Þle systems
automake
1.4p4
Installed: Default Description: A GNU tool for automatically creating makeÞles
base-files
2.1.PRO
base-passwd
3.2.0
Installed: Default Description: Contents of /etc directory Installed: Default Description: Default password and group Þle
204
MontaVista™ Linux® Professional Edition
GNU Autoconf, Automake, and Libtool Gary V. Vaughan, Ben Elliston, Tom Tromey, Ian Lance Taylor New Riders Publishing ISBN: 1578701902
Appendix B: Pro Applications Target Application Packages
Application Package bash
Version 2.05a
Notes
Reference Books and Web Sites
Installed: Default Description: A GNU Bourne Again shell (bash)
bind
9.1.3
Installed: Default Description: A DNS (Domain Name System) server
bind
1.28
Advanced Bash-Scripting Guide Mendel Cooper http://linuxdoc.org/LDP/abs/ html/index.html DNS and BIND (4th Edition) Paul Albitz, Cricket Liu O'Reilly & Associates ISBN: 0596001584
Installed: Default Description: The most widely used DNS server on 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 GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995;however it does contain a good introduction to GNU programming.
bison
1.28
Installed: Default Description: A GNU general-purpose parser generator
bonnie++
1.92
Installed: Default Description: Hard disk bench marking suite Minor revision update from HHL 2.0
bootldr-assabet
2.13.2
bridge-utils
0.9.3
Installed: Default Description: Bootloader for the Intel® Assabet Installed: Default Description: Utilities to conÞgure the Linux networking bridge interface
bsd-finger
0.17
busybox
0.60.2
Installed: Default Description: Finger client and server Installed: default Description: Multi-call replacing mount, etc.
binary
capable
of
Because this package is a multi-call binary, calling it via a different name changes the functionality. For example, “ln -s busybox ls; ls” will call busybox with the name ls and cause busybox to “act” like ls. To automatically activate the links, use TCT to create your Þle system. bzip2
1.0.2
checker
0.9.9.1
Installed: Default Description: A Þle-compression utility Installed: Default - IA-32/x86 only Description: GNU version of a Purify (memory leak checker) tool
console-data
1999.08.29
Installed: Default
console-tools
0.2.3
Installed: Default
Description: VGA console fonts
Description: Tools for conÞguring the console
MontaVista™ Linux® Professional Edition
205
Appendix B: Pro Applications Target Application Packages
Application Package
Version
cpio
2.4.2
cprof
1.0.1
cproto
4.6d
Notes
Reference Books and Web Sites
Installed: Default Description: A GNU archiving program Installed: Default – IA-32/x86 only Description: Thread-safe proÞler Installed: Default Description: Generates function prototypes and variable declarations from C code
cracklib
2.7
Installed: Default Description: processing
cron
3.0p11
Library
needed
for
password
Installed: Default Description: Manages system resources and launch events/tasks
db
3.2.9
devfsd
1.3.11
Installed: Default Description: Berkeley db Installed: Default Description: Dynamic dev directory daemon. It automatically 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
dhcpcd
1.3.19p|5
Installed: Default Description: A DHCP client
diff
2.7
Installed: Default Description: Creates source patches. Includes
cmp dmalloc
4.8.2
dnrd
2.1.0
dump
0.4b23
e2fsprogs
1.22
Installed: Default Description: Debug memory allocation utility Installed: Default Description: Domain name relay daemon Installed: Default Description: File-system backup and restore Installed: Default Description: Programs for backing up and restoring Þle systems
ed
0.2
editline
1.12
Installed: Default Description: A line-oriented text editor Installed: Default Description: A BSD licensed for the “readline” functionality
206
MontaVista™ Linux® Professional Edition
The DHCP Handbook: Understanding, Deploying, and Managing Automated ConÞguration Services Ted Lemon, Ralph E. Droms Pearson Higher Education ISBN: 1578701376 The DHCP Handbook: Understanding, Deploying, and Managing Automated ConÞguration Services Ted Lemon, Ralph E. Droms Pearson Higher Education ISBN: 1578701376
Appendix B: Pro Applications Target Application Packages
Application Package eject
Version 2.0.2
Notes
Reference Books and Web Sites
Installed: Default Description: A program that ejects removable media using software control
exim
3.34
Installed: Default Description: Local mail handler Required by cron
expect
5.32.2
Installed: Default Description: A program that “talks” to other interactive programs based on a script
fbgetty
0.1.4
Installed: Default Description: Framebuffer getty program for simple graphical environments.
fbset
2.1
Installed: Default Description: Tools for managing a framebuffer's video mode properties
file
3.33
filesystem
2.0
Installed: Default Description: A utility for determining Þle types Installed: Default Description: The basic directory layout for a Linux system
fileutils
4.1
Installed: Default Description: The GNU versions of common Þlemanagement utilities Functionality 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 (text pattern recognizers)
gawk
3.1.0
Installed: Default Description: The GNU version of the awk text processing utility
gbdm
1.7.3
GAWK: The GNU AWK User's Guide Arnold Robbins Free Software Foundation ISBN: 1882114272
Installed: Default Description: A GNU set of database routines which use extensible hashing
gcc
3.2.1
Installed: Default Description: Various compilers Objective-C, Chill, etc.)
(C,
C++,
Using and Porting the Gnu Compiler Collection Gcc Richard Stallman iUniverse.com ISBN: 059510035X
Version change from the Pro 2.1 distribution http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995;however it does contain a good introduction to GNU programming.
MontaVista™ Linux® Professional Edition
207
Appendix B: Pro Applications Target Application Packages
Application Package gdb
Version 5.1
Notes Installed: Default Description: A GNU source-level debugger for C, C++ and Fortran
Reference Books and Web Sites Debugging with GDB: The GNU Source-Level Debugger Richard M. Stallman, Roland H. Pesch Universe.com ISBN: 0595149197 http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 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 Þle systems
gettext
0.10.35
Installed: Default Description: GNU libraries and utilities for producing multi-lingual messages
glib
1.2.10
glibc
2.2.5
Installed: Default Description: A library of handy utility functions. Installed: Default Description: The GNU libc libraries Functionality of interest: ldd, ldconfig Version change from the Pro 2.1 distribution
gpm
1.19.6
Installed: Default Description: A mouse server for the Linux console
grep
2.4.2
Installed: Default Description: The GNU versions of grep pattern matching utilities
groff
1.17.2
gzip
1.2.4
Installed: Default Description: A document formatting system Installed: Default Description: The GNU data compression program Functionality of interest: gzip, gunzip, zcat
hardhatutils
1.14
Installed: Default Description: Contains various utilities for administrating a machine, for example initdconfig and shellconfig The package hardhatutils-which is optional. The package name is hhl<architecture>_<processor>hardhatutils-which
hdparm
3.9a
Installed: Default Description: A utility for displaying and/or setting hard disk parameters
hostname
2.09
Installed: Default Description: Sets system host name Required by initscripts
208
MontaVista™ Linux® Professional Edition
Grep: Searching for a Pattern Alain Magloire iUniverse.com ISBN: 0595100392
Appendix B: Pro Applications Target Application Packages
Application Package
Version
ifupdown
0.6.4
ilmtk
0.2
ipgrab
0.8.2
Notes
Reference Books and Web Sites
Installed: Default Description: Enables/disables network interfaces Installed: Default Description: Interrupt Latency Toolkit Installed: Default Description: Network debugging tool similar to tcpdump
iproute
2.2.4
Installed: Default Description: Enhanced IP routing and network device conÞguration tools
iptables
1.2.2
Installed: Default Description: Used to set up kernel packet Þltering rules Revision update from HHL 2.0
jed
B0.99.12
Installed: Default Description: A fast, compact editor based on the S-Lang screen library The package jed-rgrep is optional. The package name is hhl-<architecture>_<processor>-jed-rgrep
kernel
Installed: Default Description: The Linux kernel (the core of the Linux 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 the kernel)
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.1e style “capabilities”
libelf
0.7.0
Installed: Default
libjpeg
6b
Installed: Default Description: A library for manipulating JPEG image 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 manipulating PNG image format Þles
for
MontaVista™ Linux® Professional Edition
209
Appendix B: Pro Applications Target Application Packages
Application Package libtiff
Version 3.4
Notes Installed: Default Description: A library of functions manipulating TIFF image format Þles
libtool
1.3.5
Reference Books and Web Sites for
Installed: Default Description: The GNU libtool, which simpliÞes the use of shared libraries If you are building an open-source package using libtool, you need to run the command: <architecture-prefix>_libtoolize --force --copy before building the application to ensure that the proper libtool control Þles are used.
libungif
4.1.0b1
Installed: Default Description: A library for manipulating GIF format image Þles
libwww
5.2.8
lilo
22.1
Installed: Default Description: HTTP library of common code Installed: Default - IA-32/x86 only Description: The boot loader for Linux and other operating systems
linux-ftpd
0.17
Installed: Default
linux86
0.15.4
Installed: Default – IA-32/x86 only
Description: Version of ftp
Description: Required to build and run lilo – real-mode tools linuxinfo
1.1.7
lm_sensors
2.5.4-p10
logrotate
3.5.7
Installed: Default Description: Displays basic system information Installed: Default Description: Hardware monitoring tools Installed: Default Description: Rotates, compresses, removes and mails system log Þles
lpr
0.50
lprng
3.7.4
Installed: Default Description: Print utility 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 a Linux/UNIX system
ltrace
0.3.10
Installed: Default Description: Tracks runtime library calls from dynamically linked executables This application is NOT available on MIPS nor SuperH targets.
210
MontaVista™ Linux® Professional Edition
GNU Autoconf, Automake, and Libtool Gary V. Vaughan, Ben Elliston, Tom Tromey, Ian Lance Taylor New Riders Publishing ISBN: 1578701902
Appendix B: Pro Applications Target Application Packages
Application Package ltt
Version 0.9.5a
Notes
Reference Books and Web Sites
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 cursoraddressable, character-cell display devices
m4
1.4
mailx
8.1.2
Installed: Default Description: The GNU macro processor Installed: Default Description: The /bin/mail program for sending e-mail messages
make
3.79.1
Installed: Default Description: A GNU tool which simpliÞes the build process for users
http://www.oreilly.com/ catalog/prognu/ Programming with GNU Software ISBN 1-56592-112-7 Note: This documentation is from 1995; however, it does contain a good introduction to GNU programming.
makedev
2.3.1
Installed: Default Description: A program used for creating the device Þles in /dev
man-db
2.3.19
man-pages
1.38
memstat
0.2
mgetty
1.1.26
Installed: Default Description: man program Installed: Default Description: man page contents Installed: Default Description: Utility to query free memory Installed: Default Description: A getty replacement for use with data and fax modems
mingetty
0.9.4
Installed: Default Description: A compact getty program for virtual consoles only
minicom
1.83.0
Installed: Default Description: A text-based modem control and terminal emulation program
mkcramfs
2.4.16
Installed: Default Description: Used to make CRAMFS Þle-system images
modutils
2.4.13
Installed: Default Description: Linux module utilities such as modprob and insmod
mtd-utils
2.4.16_1.16
nana
2.5
Installed: Default Description: Utilities for MTD Installed: Default Description: Debugging library
MontaVista™ Linux® Professional Edition
211
Appendix B: Pro Applications Target Application Packages
Application Package
Version
nano
1.0.3
ncurses
5.2
Notes
Reference Books and Web Sites
Installed: Default Description: Pico editor replacement Installed: Default Description: termcap
net-tools
1.60
Replaces
libtermcap
and
Installed: Default Description: The basic tools for setting up networking, such as route and ifconfig
netbase
4.06
Installed: Default Description: Provides network infrastructure control Þles
netkit-base
0.10
Installed: Default Description: Network utilities Functionality of interest: inetd, ping
netkit-ftp
0.17
netkit-ntalk
0.17
netkit-routed
0.17
Installed: Default Description: FTP client - minimal functionality Installed: Default Description: Talk utility Installed: Default Description: Route daemon that feeds routes into kernel
netkit-rsh
0.17
Installed: Default Description: Remote shell. Needed for remote access
netkit-rusers
0.11
Installed: Default
netkit-rwall
0.17
Installed: Default
Description: User daemons for remote who, etc.
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
nfs-user-server
2.2beta47
Installed: Default
nfs-utils
0.3.2
Description: Telnet client and daemon
Description: User space NFS servers Installed: Default Description: NFS utilities and daemons for the kernel NFS server
supporting
The package nfs-kernel-server is optional. The package name is hhl-<architecture>_<processor>-jnfs-kernelserver nis
3.9
Installed: Default Description: Network information server items such as ypbind
212
MontaVista™ Linux® Professional Edition
Appendix B: Pro Applications Target Application Packages
Application Package ntp
Version 4.0.99g
Notes
Reference Books and Web Sites
Installed: Default Description: Synchronizes system time using the Network Time Protocol (NTP)
nvi
1.79
Installed: Default Description: Small embedded vi – useful for demonstrating embedded target functionality
openssh
3.0.2p1
Installed: Default Description: OpenSSH free Secure Shell (SSH) implementation
openssl
0.9.6c
Installed: Default Description: Secure Sockets Layer Toolkit
p2linux
0.2
pam
0.72
Installed: Default
SSH, the Secure Shell: The DeÞnitive Guide Daniel J. Barrett, Richard Silverman O'Reilly & Associates ISBN: 0596000111 SSL & TLS Essentials: Securing the Web Stephen A. Thomas John Wiley & Sons ISBN: 0471383546 http://support.mvista.com/ content/AppInfo/
Description: Wind River pSOS® to Linux tool kit Installed: Default Description: A security tool which provides authentication 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, for modifying and upgrading Þles
pciutils
2.1.8
pcmcia-cs
3.1.30
perl
5.6.1
Installed: Default Description: Linux PCI utilities Installed: Default Description: PCMCIA Daemon Installed: Default Description: The Perl programming language
pidentd
3.0.12
Programming Perl (3rd Edition) Larry Wall, Tom Christiansen and Jon Orwant O'Reilly & Associates ISBN: 0596000278
Installed: Default Description: An implementation of the RFC1413 identiÞcation server
portmap
5beta
Installed: Default Description: A program which manages RPC connections
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 processing program
MontaVista™ Linux® Professional Edition
213
Appendix B: Pro Applications Target Application Packages
Application Package procps
Version 2.0.7
Notes
Reference Books and Web Sites
Installed: Default Description: Utilities for monitoring your system and the processes on your system Functionality of interest: top, free, ps
psmisc
20.1
Installed: Default Description: Utilities for managing processes on your system
pump
0.8.3
Installed: Optional Package Name: hhl-<architecture><processor>-pump Description: A BOOTP and DHCP client for automatic IP conÞguration
pxelinux
1.62
python
2.0
Installed: Default Description: Used to facilitate a PXE boot Installed: Default Description: An interpreted, interactive objectoriented programming language
Programming Python Edition) Mark Lutz O'Reilly & Associates ISBN: 0596000855
Required for using TCT quota
2.00
Installed: Default Description: System administration tools for monitoring users' disk usage
rarpd
98.11.07
rdate
1.3.0
Installed: Default Description: The RARP daemon Installed: Default Description: Tool for getting the date/time from another machine on your network
readline4
4.1
Installed: Default Description: Library for standard line input manipulation. Required by bash
reiserfsprogs
3.x.1b
rp-pppoe
3.3
Installed: Default Description: Reiserfs utilities Installed: Optional Description: PPP on Ethernet Package name: hhl-<architecture>_<processor>-rp-pppoe
rpm
4.0
Installed: Default Description: Customized Red Hat Package Manager
rstatd
3.03
rsync
2.3.2
Installed: Default Description: Kernel stats daemon Installed: Default Description: A program for synchronizing Þles over a network
rtsched-utils
0.1
Installed: Default Description: Real-Time Scheduler utilities
214
MontaVista™ Linux® Professional Edition
Maximum RPM (RPM) Ed Bailey Sams ISBN: 0672311054
(2nd
Appendix B: Pro Applications Target Application Packages
Application Package samba
Version 2.2.1a
Notes Installed: Default Description: A collection of programs that implements the Server Message Block (commonly abbreviated as SMB) protocol for UNIX systems
sash
3.4
Reference Books and Web Sites Using Samba (O'Reilly System Administration) Robert Eckstein, David Collier-Brown O'Reilly & Associates ISBN: 1565924495
Installed: Default Description: A statically linked shell, including some built-in basic commands
sed
3.02
sendmail
8.11.6
Installed: Default Description: A GNU stream text editor Installed: Optional Description: A widely used Mail Transport Agent (MTA). MontaVista Software does not provide a default conÞguration Þle
Sendmail Bryan Costales, Eric Allman O'Reilly & Associates ISBN: 1565922220
Package Name: hhl-<architecture><processor>-sendmail setserial
2.17
shadow
20000902
shellutils
2.0.11
Installed: Default Description: A utility for conÞguring serial ports Installed: Default Description: Shadow password utilities Installed: Default Description: Set of POSIX scripts for shell functionality Functionality of interest: FALSE, TRUE, pwd, sleep, uname Includes date The package shellutils-hostname is optional. The package name is hhl-<architecture>_<processor>-shellutilshostname
slang
1.4.4
Installed: Default Description: Multi-platform programmer’s library
socket
1.1
Installed: Default Description: Creates an endpoint for communication and returns a descriptor
squid
2.4.6
Installed: Default Description: Internet Object Cache a.k.a Web Proxy
stat
2.5
Installed: Default Description: A tool for Þnding out information about a speciÞed Þle
strace
4.3
Installed: Default Description: Tracks and displays system calls associated with a running process
sudo
1.6.5pl
Installed: Default Description: Allows restricted root access for speciÞed users
sysklogd
1.3.31
Installed: Default Description: System logging and kernel message trapping daemons
MontaVista™ Linux® Professional Edition
215
Appendix B: Pro Applications Target Application Packages
Application Package
Version
systune
0.5.3
sysutils
1.3.8.1
sysvinit
2.78
tar
1.13.19
tcl
8.3.2
Notes
Reference Books and Web Sites
Installed: Default Description: Kernel tuning utility and scripts Installed: Default Description: Miscellaneous system tools Installed: Default Description: Functionality of interest: init Installed: Default Description: A GNU Þle-archiving program Installed: Default Description: Tcl scripting language
tcp-wrappers
7.6
Practical Programming in Tcl and Tk Brent B. Welch Prentice Hall PTR ISBN: 0130220280
Installed: Default Description: A security tool which acts as a wrapper for TCP daemons
tcpdump
3.6.2
texinfo
4.0b
Installed: Default Description: A network trafÞc monitoring tool Installed: Default Description: Tools needed to create Texinfo format documentation Þles
textutils
2.0
Installed: Default Description: A set of GNU text Þle modifying utilities.
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 TIFF image format Þles
time
1.7
Installed: Default Description: A GNU utility for monitoring a program's use of system resources
216
MontaVista™ Linux® Professional Edition
Texinfo Manual http://www.gnu.org/doc/ texinfo-manual.html
Appendix B: Pro Applications Target Application Packages
Application Package tinylogin
Version 0.80
Notes
Reference Books and Web Sites
Installed: Default Description: Multi-call binary replacing getty, passwd, etc.
capable
of
Because this package is a multi-call binary, calling it via a different name changes the functionality. For example “ln -s tinylogin ls; ls” will call tinylogin with the name ls and cause tinylogin to “act” like ls. The way tinylogin is packaged is that the main binary is in the root package. For example: hhl-ppc_7xx-tinylogin0.80.ppc_7xx.rpm The root package contains no links. Each subpackage contains links to busybox that conßict with their respective packages. For example: hhl-ppc_7xx-tinylogin-fileutils0.80.ppc_7xx.rpm would contain links to tinylogin that conßict with the real fileutils. traceroute
1.4a12
Installed: Default Description: Traces the route taken by packets over a TCP/IP network
ucd-snmp
4.2.3
Installed: Default Description: A collection of SNMP protocol tools from UC-Davis Functionality of interest: snmpd, snmp-devel, snmp-utils
usbutils
0.8
util-linux
2.11h
Essential SNMP Douglas R. Mauro, Kevin J. Schmidt O'Reilly & Associates ISBN: 0596000200
Installed: Default Description: Display info about USB devices Installed: Default Description: A collection of basic system utilities Functionality of interest: kill, mkswap, more, swapoff, swapon, umount
v2linux
0.2
http://support.mvista.com/ content/AppInfo/
Installed: Default Description: Wind River VxWorks® to Linux tool kit
vim
5.7.019
Installed: Default Description: Replaces vi
which
2.12
Vi iMproved (VIM) Steve Oualline New Riders Publishing ISBN: 0735710015
Installed: Default Description: Displays where a particular program in your path is located
wireless-tools
22+23beta3
wu-ftpd
2.6.1
xinetd
2.3.3
Installed: Default Description: Tools for wireless networking Installed: Default Description: An FTP server Installed: Default Description: A secure replacement for inetd
MontaVista™ Linux® Professional Edition
217
Appendix B: Pro Applications Target Application Packages
Application Package zebra
Version 0.92a
Notes Installed: Default Description: GNU routing daemon
zlib
1.1.3
BGP/OSPF/RIP
capable
Installed: Default Description: The zlib decompression library
218
Reference Books and Web Sites
MontaVista™ Linux® Professional Edition
compression
and
Appendix B: Pro Applications Using RSH
Using RSH RSH (Remote shell) is a Berkeley Unix networking command used to run a given command on a remote host, passing it input and receiving its output. To conÞgure RSH, complete the following steps: 1.
shell login
On the target where the command is being run, open the Þle inetd.conf for editing, and uncomment the following lines:
stream stream
2.
tcp tcp
nowait nowait
root root
/usr/sbin/tcpd /usr/sbin/tcpd
in.rshd -aL in.rlogind -a
For Pro, the setuid bit needs to be set for /usr/bin/rlogin and /usr/bin/rsh. To set the setuid bit, enter the following commands: chmod 4755 /usr/bin/rlogin chmod 4755 /usr/bin/rsh
You should see output similar to the following:
# 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
3.
In the user's home directory on the target, open the Þle .rhosts for editing, and add a line with the following format:
<userID>
For example, in the Þle /home/kbryla/.rhosts, you would add a line such as: 10.0.0.83
4.
kbryla
On the target, open the Þle /etc/hosts.equiv and edit it to allow access to the host and user. Add a line with the following format: +
For example, the Þle /etc/hosts.equiv could be:
# /etc/hosts.equiv: list of hosts and users that # are granted "trusted" r command access to your system. +
MontaVista™ Linux® Professional Edition
219
Appendix B: Pro Applications Using 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 both listening. 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 following format:
<userID>
For example, in the Þle /home/kbryla/.rhosts, you would add a line such as:
10.0.0.83
kbryla
•
Open the Þle /etc/hosts.equiv and edit it to allow access to the host and user. Add a line with the following format: +
For example, the Þle /etc/hosts.equiv could be:
# /etc/hosts.equiv: list of hosts and users that # are granted "trusted" r command access to your system. +
•
Start or restart xinetd. use the command: /etc/init.d/xinetd restart
Note: Running the command netstat -at should show that shell and login are both listening. You should now be able to use RSH.
220
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements
Notices By providing information, you understand and acknowledge that MontaVista Software, Inc. (“MontaVista Software”) is not providing legal advice to you nor does MontaVista Software endorse any particular product or any Web site, including those listed herein. The licensed software described in this publication, including all licensed material available for it, is provided to you by MontaVista Software subject to the terms of the MontaVista Software Product Subscription and Software License Agreement, or any equivalent agreement between us, and any license agreements MontaVista Software passes through to you from its licensors or suppliers. MontaVista Software, its licensors or its suppliers, may have patents, or pending patent applications, or other intellectual property rights in, or covering, the subject matter described in this publication. The furnishing of this publication does not give you any license to these patents or such other intellectual property rights of MontaVista Software or its licensors or suppliers, except as may be provided in a separate license agreement relating to the particular licensed software. Any references in this publication to non-MontaVista Software Web sites are provided for your convenience only and do not, in any manner, serve as an endorsement by MontaVista Software of such Web sites or their content. Information contained in such Web sites are not under the control of MontaVista Software, Inc., nor are they part of the materials for this MontaVista Software product. MontaVista Software is not responsible for any changes or updates to such sites and your use of any such Web sites 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 vary signiÞcantly. Some measurements may have been made on development-level systems and MontaVista Software makes no guarantee that these measurements will be 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 applicable data for your speciÞc environment. This publication may also contain sample
MontaVista™ Linux® Professional Edition
221
Appendix C: Notices and License Agreements Notices
application programs in source language, which illustrate programming techniques on various operating platforms. These examples have not been thoroughly tested under all conditions and MontaVista Software, therefore, cannot guarantee or imply reliability, serviceability, or function of such programs. You may copy, modify and distribute these sample programs subject to the license agreements and copyright notices accompanying such sample application programs. This publication may contain examples of data and reports used in daily business operations. To illustrate them as best as possible, the examples may include references to Þctional characters, companies, brands and/or products. MontaVista Software's use of such named Þctitious characters, companies, brands and/or products is for illustration only. Any similarity to actual persons, companies, brands, products or business enterprises is unintentional and entirely coincidental.
222
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements License Agreements
License Agreements MontaVista™ Linux® Professional Edition is licensed, not sold, to you under the terms of the MontaVista Product Subscription and Software License Agreement, or any equivalent agreement between us.
MontaVista™ Linux® Professional Edition
223
Appendix C: Notices and License Agreements Target Configuration Tool End User License Agreement
Target ConÞguration Tool End User License Agreement IMPORTANT-READ CAREFULLY: This MontaVista Software, Inc. End-User License Agreement (“EULA”) is a legal agreement between you (either an individual or a single entity) and MontaVista Software, Inc. for the MontaVista Software, Inc. software product identiÞed above, which includes computer software (binary and source) and may include associated media, printed materials, and “online” or electronic documentation (“Software Product”). By installing, copying, or otherwise using the Software Product, you agree to be bound by the terms of this EULA. If you do not agree to the terms of this EULA, do not install or use the Software Product. If applicable, you may return it to your place of purchase for a full refund of any separate fees paid for the Software Product. MontaVista Software, Inc. shall be referred to in this EULA as “Licensor.” Any third party software that is provided with the Software Product includes such third party’s license agreements (in either electronic or printed form) (including the GNU General Public License) for use at your option. If you choose to use such software, then such use shall be governed by such third party license agreements and not by this Agreement. The Software Product is protected by copyright laws and international copyright treaties, as well as other intellectual property laws and treaties. The Software Product is licensed, not sold. LICENSE GRANT. Licensor grants you a non-exclusive and non-transferable license to use the Software Product and accompanying documentation (“Documentation”), subject to the limitations below. This license grant is subject to the payment of applicable license fees. Unless you have purchased a product subscription for the Software Product, the license granted under this Agreement does not grant you any right to any enhancement or update to the Software Product. LIMITATIONS ON USE; NO REDISTRIBUTION. With respect to the Software Product, you may not, and may not authorize any third party to: (1) distribute to any third party the source code of the Software Product or any modiÞcations or derivative works thereof, or any copies of the Documentation; (2) rent, lease, grant a security interest in, or otherwise transfer rights to the Software Product; or (3) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols or labels 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 a period of ninety (90) days from the date of acquisition, the Software Product, if operated as directed, will substantially achieve the functionality described in the Documentation. Licensor does not warrant, however, that your use of the Software Product will be uninterrupted or that the operation of the Software Product will be error-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) to advise you how to achieve substantially the same functionality with the Software Product as described in the Documentation through a procedure different from that set forth in the Documentation; or (iii) for individual consumers, if the above remedies are impracticable, to refund the license fee you paid for the Software Product separate
224
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements Target Configuration Tool End User License Agreement
and apart from other products, if any such separate fee was paid for the Software Product, minus a reasonable allowance for the time you have used the Software Product. Only if you inform Licensor of your problem with the Software Product during the applicable warranty period and provide evidence of the date you purchased a 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 the Software Product by you during the warranty period; (2) if the media is subjected to accident, 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 conjunction with hardware or software other than the unmodiÞed version of hardware and software with which the Software Product was intended to be used as described in the Documentation. NO OTHER WARRANTIES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, LICENSOR DISCLAIMS ALL OTHER WARRANTIES AND CONDITIONS, WHETHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OR MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT, WITH REGARD TO THE SOFTWARE PRODUCT, AND THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES. THIS LIMITED WARRANTY GIVES YOU SPECIFIC LEGAL RIGHTS. YOU MAY HAVE OTHERS, WHICH VARY FROM STATE/JURISDICTION TO STATE/JURISDICTION. TITLE. Title, ownership, and intellectual property rights in the Software Product and Documentation shall remain in Licensor. You acknowledge such ownership and intellectual property rights and will not take any action to jeopardize, limit or interfere in any manner with Licensor’s ownership of or rights with respect to the Software Product and Documentation. The Software Product and Documentation are protected by copyright and other intellectual property laws and international treaties. TERMINATION. This EULA and the license granted hereunder will terminate automatically if you fail to comply with the conditions described herein. Upon termination, you must destroy all copies of the Software Product and Documentation. Your obligations to pay accrued charges and fees shall survive any termination of this EULA. EXPORT CONTROLS. The Software Product is subject to the regulations of the United States government and agencies thereof, including the Bureau of Export Administration. None of the Software Product of underlying information or the underlying information or technology may be downloaded or otherwise exported or reexported into prohibited countries (including Cuba, Iraq, Libya, Sudan, North Korea, Iran, Syria or any other country to which the United States has embargoed goods). By downloading or using the Software Product, you agree that you are not located in, under the control of, or a national or resident of any such country. LIMITATION OF LIABILITY. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW, IN NO EVENT SHALL LICENSOR BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT, OR CONSEQUENTIAL DAMAGES WHATSOEVER (INCLUDING, WITHOUT LIMITATION, DAMAGES FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, OR ANY OTHER PECUNIARY LOSS) ARISING OUT OF THE
MontaVista™ Linux® Professional Edition
225
Appendix C: Notices and License Agreements Target Configuration Tool End User License Agreement
USE OF OR INABILITY TO USE THE SOFTWARE PRODUCT OR THE PROVISION OF OR FAILURE TO PROVIDE SUPPORT SERVICES, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. IN ANY CASE, LICENSOR’S ENTIRE LIABILITY UNDER ANY PROVISION OF THIS EULA SHALL BE LIMITED TO THE AMOUNT ACTUALLY PAID BY YOU SEPARATELY FOR THE SOFTWARE PRODUCT. BECAUSE SOME STATES AND JURISDICTIONS DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY, THE ABOVE LIMITATION MAY NOT APPLY TO YOU. HIGH RISK ACTIVITIES. The Software Product is not fault-tolerant and is not designed, manufactured or intended for use or resale as on-line control equipment in hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air trafÞc control, direct life support machines, or weapons systems, in which the failure of the Software Product could lead directly to death, personal injury, or severe physical or environmental damage (“High Risk Activities”). Accordingly, Licensor and its suppliers speciÞcally disclaim any express or implied warranty of Þtness for High Risk Activities. MISCELLANEOUS. This EULA represents the complete agreement concerning the license granted hereunder and may be amended only by a writing executed by both parties. THE ACCEPTANCE OF ANY PURCHASE ORDER PLACED BY YOU IS EXPRESSLY MADE CONDITIONAL ON YOUR ASSENT TO THE TERMS SET FORTH HEREIN, AND NOT ON THOSE IN YOUR PURCHASE ORDER. If any provision of this EULA is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable. All disputes relating to this EULA shall be resolved by binding arbitration in Santa Clara County, California. This EULA shall be governed by California law, excluding conßict of law provisions. The application of the United Nations Convention on Contracts for the International Sale of Goods is expressly excluded.
226
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The “Artistic License”
The “Artistic License” Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modiÞcations.
DeÞnitions: “Package” refers to the collection of Þles distributed by the Copyright Holder, and derivatives 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 been modiÞ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 the package. “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 to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) “Freely Available” means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug Þxes, portability Þxes and other modiÞcations derived from the Public Domain or from the Copyright Holder. A Package modiÞed in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed Þle stating how and when you changed that Þle, and provided that you do at least ONE of the following: •
a) place your modiÞcations in the Public Domain or otherwise make them Freely Available, such as by posting said modiÞcations to Usenet or an equivalent medium, or placing the modiÞcations on a major archive site such as uunet.uu.net, or by allowing the
MontaVista™ Linux® Professional Edition
227
Appendix C: Notices and License Agreements The “Artistic License”
Copyright Holder to include your modiÞcations in the Standard Version of the Package. •
b) use the modiÞed Package only within your corporation or organization.
•
c) rename any non-standard executables so the names do not conßict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version.
•
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) on where to get the Standard Version.
•
b) accompany the distribution with the machine-readable source of the Package with your modiÞcations.
•
c) give non-standard executables non-standard names, and clearly document the differences in manual pages (or equivalent), together with 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. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your 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 the complete Standard Version of the interpreter is so embedded. 6. The scripts and library Þles supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whoever generated them, and may be sold commercially, and may be aggregated with this Package. If such scripts or library Þles are aggregated with this Package via the so-called “undump” or “unexec” methods of producing a binary executable image, then distribution of such an image shall neither be construed as a distribution of this Package nor shall it fall under the restrictions of Paragraphs 3 and 4, provided that you do not represent such an executable image as a Standard Version of this Package.
228
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The “Artistic License”
7. C subroutines (or comparably compiled subroutines in other languages) supplied by you and linked into this Package in order to emulate subroutines and variables of the language deÞned by this Package shall not be considered part of this Package, but are the equivalent of input as in Paragraph 6, provided these subroutines do not change the language in any way that would cause it to fail the regression tests for the language. 8. Aggregation of this Package with a commercial distribution is always permitted provided that the use of this Package is embedded; that is, when no overt attempt is made to make this Package's interfaces visible to the end user of the commercial distribution. 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 products derived from this software without speciÞc prior written permission. 10. THIS PACKAGE IS PROVIDED “AS IS” AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End
MontaVista™ Linux® Professional Edition
229
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
GNU General Public License, or GNU GPL Version 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 license document, but changing it is not allowed.
Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Library General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of 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 you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of 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 they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modiÞed by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reßect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent
230
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
licenses, in effect making the program proprietary. To prevent this, we have made it clear 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 AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public 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 under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modiÞcations and/or translated into another language. (Hereinafter, translation is included without limitation in the term “modiÞcation”.) Each licensee is addressed as “you”. Activities other than copying, distribution and modiÞcation are not covered by this License; 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 work based 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 you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any 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 your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modiÞcations or work under the terms of Section 1 above, provided that you also meet all of these conditions: •
a) You must cause the modiÞed Þles to carry prominent notices stating that you changed the Þles and the date of any change.
•
b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License.
•
c) If the modiÞed program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these
MontaVista™ Linux® Professional Edition
231
Appendix C: Notices and License Agreements GNU 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 not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modiÞed work as a whole. If identiÞable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute 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 permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution 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 provided that you also do one of the following: •
a) Accompany it with the complete corresponding machinereadable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; 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 of physically performing source distribution, a complete machinereadable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or,
•
c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.)
The source code for a work means the preferred form of the work for making modiÞcations to it. For an executable work, complete source code means all the source 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 include anything that is normally distributed (in either source or binary form) with the major
232
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate 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 long as such parties remain 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 its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for 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 this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or
MontaVista™ Linux® Professional Edition
233
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to 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 a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM
234
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
(INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN 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 the public, the best way to achieve this is to make it free software which everyone can redistribute and change under these terms. To do so, attach the following notices to the program. It is safest to attach them to the start 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 is found. one line to give the program's name and an idea of what it does. Copyright (C) yyyy name of author 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 program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. 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., 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 an interactive mode: Gnomovision version 69, Copyright (C) year name of author Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. This is free software, and you are welcome to redistribute it under certain conditions; type `show c' for details.
MontaVista™ Linux® Professional Edition
235
Appendix C: Notices and License Agreements GNU General Public License, or GNU GPL
The hypothetical commands `show w' and `show c' should show the appropriate parts of the General Public License. Of course, the commands you use may be called something other than `show w' and `show c'; they could even be mouse-clicks or menu items--whatever suits your program. You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the program, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the program `Gnomovision' (which makes passes at compilers) written by James Hacker. signature of Ty Coon, 1 April 1989 Ty Coon, President of Vice This General Public License does not permit incorporating your program into proprietary programs. If your program is a subroutine library, you may consider it more useful to permit linking proprietary applications with the library. If this is what you want to do, use the GNU Library General Public License instead of this License.
236
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The 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 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. [This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.]
Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you Þrst think carefully about whether this license or the ordinary General Public License is the better 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. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things. To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it. For example, if you distribute copies of the library, whether gratis or for a fee, you must 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, you must provide complete object Þles to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them 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/or modify the library.
MontaVista™ Linux® Professional Edition
237
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modiÞed by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by 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 free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use speciÞed in this license. Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those 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 the original library. The ordinary General Public License therefore permits such linking only if the entire combination Þts its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library. We call this license the “Lesser” General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances. For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that 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 the Lesser General Public License. In other cases, permission to use a particular library in non-free programs enables a greater 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 more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating 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 the freedom and the wherewithal to run that program using a modiÞed version of the Library. 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
Appendix C: Notices and License Agreements The 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 AND MODIFICATION 0. This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General 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 be conveniently linked with application programs (which use some of those functions and data) to form executables. The “Library”, below, refers to any such software library or work which has been distributed under these terms. A “work based on the Library” means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modiÞcations and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term “modiÞcation”.) “Source code” for a work means the preferred form of the work for making modiÞcations to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface deÞnition Þles, plus the scripts used to control compilation and installation of the library. Activities other than copying, distribution and modiÞcation are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does. 1. You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; 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 your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modiÞcations or work under the terms of Section 1 above, provided that you also meet all of these conditions: •
a) The modiÞed work must itself be a software library.
MontaVista™ Linux® Professional Edition
239
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
•
b) You must cause the Þles modiÞed to carry prominent notices stating 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 charge to all third parties under the terms of this License.
•
d) If a facility in the modiÞed Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful. (For example, a function in a library to compute square roots has a purpose that is entirely well-deÞned independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.) These requirements apply to the modiÞed work as a whole. If identiÞable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library. In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.
3. You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version 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 the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.
240
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The 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 a program that is not a library. 4. You may copy and distribute the Library (or a portion or derivative of it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machinereadable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange. If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisÞes the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code. 5. A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a “work that uses 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 an executable that is a derivative of the Library (because it contains portions of the Library), rather than a “work that uses the library”. The executable is therefore covered 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 the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially signiÞcant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely deÞned by law. If such an object Þle uses only numerical parameters, data structure layouts and accessors, 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 a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6.) Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6. Any executables containing that work also fall under Section 6, whether or not they are linked directly with the Library itself. 6. As an exception to the Sections above, you may also combine or link a “work that uses the Library” with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modiÞcation of the work for the customer's own use and reverse engineering for debugging such modiÞcations. You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy
MontaVista™ Linux® Professional Edition
241
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things: •
a) Accompany the work with the complete corresponding machinereadable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable “work that uses the Library”, as object code and/or source code, so that the user can modify the Library and then relink to produce a modiÞed executable containing the modiÞed Library. (It is understood that the user who changes the contents of deÞnitions Þles in the Library will not necessarily be able to recompile the application to use the modiÞed deÞnitions.)
•
b) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy 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 the user installs one, as long as the modiÞed version is interfacecompatible with the version that the work was made with.
•
c) Accompany the work with a written offer, valid for at least three years, to give the same user the materials speciÞed in Subsection 6a, above, for a charge no more than the cost of performing this distribution.
•
d) If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above speciÞed materials from the same place.
•
e) Verify that the user has already received a copy of these materials or that you have already sent this user a copy.
For an executable, the required form of the “work that uses the Library” must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.
242
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
7. You may place library facilities that are a work based on the Library side-by-side in 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 the work 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 work based 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 that part 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 except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate 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 long as 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 derivative works. 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 the Library), you indicate your acceptance of this License to do so, and all its terms and conditions 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), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License. 11. If, as a consequence of a court judgment or allegation of patent infringement or for 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 this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.
MontaVista™ Linux® Professional Edition
243
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 12. If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 13. The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Library speciÞes a version number of this License which applies to it and “any later version”, you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation. 14. If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of 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 NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
244
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The GNU Lesser General Public License, or GNU LGPL
16. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED 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 the public, we recommend making it free software that everyone can redistribute and change. 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 attach them to the start 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 is found. one line to give the library's name and an idea of what it does. Copyright (C) year name of author This library is free software; and/or modify it under the terms Public License as published Foundation; either version 2.1 your option) any later version.
you can redistribute it of the GNU Lesser General by the Free Software of the License, or (at
This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
MontaVista™ Linux® Professional Edition
245
Appendix C: Notices and License Agreements The 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, if any, to sign a “copyright disclaimer” for the library, if necessary. Here is a sample; alter the names: Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker. signature of Ty Coon, 1 April 1990 Ty Coon, President of Vice That's all there is to it!
246
MontaVista™ Linux® Professional Edition
Appendix C: Notices and License Agreements The Modified BSD License
The ModiÞed BSD License Redistribution and use in source and binary forms, with or without modiÞcation, are permitted 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 copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3.
The name of the author may not be used to endorse or promote products derived from this software without speciÞc prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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.
MontaVista™ Linux® Professional Edition
247
Appendix D:Documentation Naming Conventions
Naming Conventions
An application name. For example bash or man.
<architecture>
Architecture family directories. For example /arm, /mips, /ppc, /sh, /sparc, /x86, etc.
<architecturecanonical-name>
Architecture family name used by GNU tools.
<architecturepreÞx>
The preÞx used for the cross-development applications to indicate the target architecture. A list of architecture preÞxes can be found in “Running Pro Applications and Tools” on page 40.
The block device where you wish to create a spare partition such as hda1. For more information about partitions, we recommend reading the man pages for parted and fdisk.
An directory where you intend to build the kernel, application, etc.
<destree>
The base of a Þle hierarchy.
A directory containing your Þle system.
MontaVista™ Linux® Professional Edition
249
Appendix D: Documentation Naming Conventions Naming Conventions
An image Þle of your Þle system.
The installation location for Pro or for an application.
The name of the kernel binary image Þle. Typically this is vmlinux.
Run levels for the conÞguration programs.
The name of the target board LSP. If the
<mount-point>
The directory where media (or Þle system) has been mounted.
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 the application 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.
The name of the target board, such as embeddedplanet-rpxlite. See the quick start guide for your target for more information about the name you should use.
250
MontaVista™ Linux® Professional Edition
Appendix D: Documentation Naming Conventions Naming Conventions
The system prompt used on the target.
<userID>
A person’s user ID.
The version number.
MontaVista™ Linux® Professional Edition
251
Glossary of Terms
API
Application Programming Interface, deÞning how programmers write source code that makes use of library or operating system facilities by accessing the behavior and state of classes and objects.
BOOT ROM
Target-resident Þrmware, executed when power is applied or the reset button is pressed on the target.
BOOTP
A standard protocol, often used in Boot ROM. BOOTP determines network conÞ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 into machine-executable programs. The term may also refer speciÞcally to the tool that translates from source to assembly language.
Cross-development
This refers to creating code on one architecture, but being able to compile it for a different architecture. An example would be to create code on a x86 host, but compiling the code so that it will run on a PowerPC or MIPS target. Though the architectures might not be the same endian or process code the same way, the GCC compiler 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 target will not run on the host.
MontaVista™ Linux® Professional
Edition
253
Debugger
A tool that allows programmers to examine and control program execution, typically for 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 embedded computer 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 on people’s right to use, copy, modify and redistribute computer programs.” The GNU Project 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 to develop a complete Unix-like operating system which is free software: the GNU system.
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. The Pro tools are installed on this system. The host system is used for compiling, linking, remote debugging and associated development activities. Sometimes referred to as the “server” system.
IDE
Integrated Development Environment, a GUI tool or a set of tools that uses GUI functionality.
JTAG
Joint Test Advisory Group, referring to a type of hardware interface that allows the testing of chips and boards within a complete system; programs running on processors with JTAG support may be controlled through the processor JTAG port.
254
MontaVista™ Linux® Professional Edition
ICE
In-Circuit Emulator
Linux
Linux is a Unix-type operating system originally created by Linus Torvalds with the assistance of developers around the world. Developed under the GNU General Public License, 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-executable programs (compiler, binary Þle converters, debugger).
Patch
A patch is a Þle that describes a source code change. It is genenerated by the diff untility and applied to the original source code with the patch utility.
PROM
Programmable Read-Only Memory, ROM that can be programmed using special equipment. 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, and temporary registers.
ROM
Read-Only Memory, non-volatile memory that can be read, but not written, by the microprocessor.
RTOS
Real-Time Operating System.
Target
A target is a reference board that you plan to use as the base for your product. Most embedded targets either don’t have an IDE drive or the drive is too small to have a full complement of tools for building kernels and applications.
TFTP
A standard protocol, possibly used by the Boot ROM, by which a system (target board) retrieves an executable Þle from another system (from the “host” system).
MontaVista™ Linux® Professional Edition
255
Toolchain
256
Informal term for the collection of programs that make up a complete set of compilation tools. Generally refering to binutils, gcc and glibc.
MontaVista™ Linux® Professional Edition
Related Documents
Monta Vista Users Guide
May 2020 42
Monta Vista Girls Soccer Schedule
May 2020 9
Mule-2.2.0-users-guide
June 2020 28
Tech 2 Users Guide
June 2020 27
Velocity Users Guide
November 2019 55