Wind River Workbench (Linux 3 Version) by Example, 3.1

Wind River Workbench (Linux 3 Version) By Example, 3.
Wind River Workbench
BY EXAMPLE
3.1
Linux 3 Version
Copyright 2009 Wind River Systems, Inc. All rights reserved. No part of this publication may be reproduced or transmitted in any form or by any means without the prior written permission of Wind River Systems, Inc. Wind River, the Wind River logo, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. Any third-party trademarks referenced are the property of their respective owners. For further information regarding Wind River trademarks, please see: http://www.windriver.com/company/terms/trademark.html This product may include software licensed to Wind River by third parties. Relevant notices (if any) are provided in your product installation at the following location: installDir/product_name/3rd_party_licensor_notice.pdf. Wind River may refer to third-party documentation by listing publications or providing links to third-party Web sites for informational purposes. Wind River accepts no responsibility for the information provided in such third-party documentation.
Corporate Headquarters Wind River Systems, Inc. 500 Wind River Way Alameda, CA 94501-1153 U.S.A. toll free (U.S.): (800) 545-WIND telephone: (510) 748-4100 facsimile: (510) 749-2010 For additional contact information, please visit the Wind River URL: http://www.windriver.com For information on how to contact Customer Support, please visit the following URL: http://www.windriver.com/support
Wind River Workbench By Example, 3.1 (Linux 3 Version) 18 Feb 09 Part #: DOC-16432-ND-00
Contents
PART I: INTRODUCTION
1 Overview ..............................................................................................
1.1 1.2 Introduction ............................................................................................................. How to Use this Guide .......................................................................................... 1.2.1 1.2.2 1.2.3 1.2.4 1.3 How is this Guide Organized? ............................................................... When is the Table of Contents Most Helpful? ..................................... What if You Just Know Your Major Role? ............................................ How Do You Set Up Your Development Environment? ....................
3
3 4 4 5 5 5 6 6 6 7 8 8 9 9 9 10
Introducing Wind River Workbench and Linux .............................................. 1.3.1 1.3.2 Cross Development Environment ......................................................... The Wind River Build System ................................................................ Layers ......................................................................................................... Standard Product Layers ......................................................................... Optional Content with Feature Templates ........................................... When to Use Layers or Templates ......................................................... Sysroots ...................................................................................................... 1.3.3 1.3.4 Accessing the Sample Projects ................................................................ Migrating Projects Forward ....................................................................
iii
Wind River Workbench By Example, 3.1 (Linux 3 Version)
1.4
Notes about Installing Workbench ..................................................................... 1.4.1 1.4.2 1.4.3 1.4.4 Installation and Licensing ....................................................................... Shared Installations .................................................................................. Building across NFS ................................................................................. Reporting Issues and Enhancements to Wind River ...........................
11 11 11 11 12 12 13 13
1.5
Finding Related Documentation ......................................................................... 1.5.1 1.5.2 Online Wind River Workbench for Linux Documentation ................ Other Online Wind River Workbench Documentation ......................
Getting Started with Workbench ........................................................ 15

2.1 2.2 2.3 2.4 2.5 2.6 2.7 Introduction ............................................................................................................. What Type of Developer Are You? ...................................................................... If You Develop Applications... ............................................................................. If You Import and Modify Source Packages... .................................................. If You Develop Middleware... .............................................................................. If You Develop or Provide Kernels... .................................................................. If You Are a Platform Integrator... ....................................................................... 15 16 16 18 19 20 21
Workbench Basics for Linux Developers .......................................... 23

3.1 3.2 3.3 Introduction ............................................................................................................. Wind River Linux Projects .................................................................................... Your Programming Environment ........................................................................ 3.3.1 3.3.2 3.3.3 Using Windows, Solaris, or Linux Hosts .............................................. Understanding the Toolchain Available to You ................................... Using Workbench and/or the Command Line .................................... 23 24 26 26 26 27
iv
Contents
3.4
Producing a File System and Kernel .................................................................. 3.4.1 3.4.2 3.4.3 Configuring Projects ................................................................................ Building the File System .......................................................................... Finding the File System and Default Kernel ........................................
27 27 28 28 28 29 29 29 30 30 31 32 32 32 33 33
3.5
Accessing the File System and Kernel on a Target .......................................... 3.5.1 3.5.2 3.5.3 Real and Simulated Targets .................................................................... Communicating with Targets ................................................................. Exploring File Systems on Targets .........................................................
3.6
Debugging and Analyzing on a Target .............................................................. 3.6.1 3.6.2 3.6.3 Debuggers ................................................................................................. Dynamic printf Statements ..................................................................... Analyzers and Profilers ...........................................................................
3.7
Productizing ............................................................................................................ 3.7.1 3.7.2 3.7.3 The Role of Your Application, Platform, or Kernel ............................. Working in a Team ................................................................................... Patching and Updating ...........................................................................
Life Cycle Development ......................................................................

4.1 4.2 4.3 4.4 4.5 4.6 4.7 Introduction ............................................................................................................. What Do You Do? ................................................................................................... Where Does Your Work Fit into the Big Picture? ............................................. Starting with a Simple Project ............................................................................. Using Pre-Built User Space Content ................................................................... Working with the File System Layout Tool ....................................................... Configuring Kernels ..............................................................................................
35
36 36 37 38 39 40 41
4.8 4.9 4.10
Debugging and Deploying ................................................................................... Optimizing ............................................................................................................... Managing Content ..................................................................................................
41 42 43
PART II: DEVELOPING PLATFORMS

5 Developing Platform Projects ............................................................ 47
5.1 Introduction ............................................................................................................. 5.1.1 5.1.2 5.1.3 5.2 Building New Platform Projectsan Overview .................................. Are You Deploying a New Platform Project? ....................................... Connecting to a Target ............................................................................. 47 48 49 49 50 51 53 53 53 55 55 56 56 57 58 60 61 61 62 62
Creating Projects Using Workbench or the Command Line .......................... 5.2.1 5.2.2 Creating Platform Projects in General ................................................... Creating an ARM Versatile Target, for Example .................................. Example Data for You to Use .................................................................. Creating the By-Example Platform Project ........................................... 5.2.3 Verifying Your Project Build ...................................................................
5.3
Building a Target File System .............................................................................. 5.3.1 5.3.2 Verifying Your Build Directory ............................................................... Building the Example ARM Versatile File System ..............................
5.4 5.5
Introducing the User Space Configuration Node ............................................ Exploring the Target File System ......................................................................... 5.5.1 5.5.2 5.5.3 5.5.4 5.5.5 Examining File Meta Properties ............................................................. Adding Files and Directories to Your File System ............................... Removing Files According to Pattern Filters ....................................... Viewing Parent Packages and Removing Packages ............................ Adding a Device .......................................................................................
vi
Contents
5.6
Using the Package Manager for RPMs ............................................................... 5.6.1 5.6.2 5.6.3 5.6.4 5.6.5 5.6.6 5.6.7 Introducing the Package Controls ......................................................... Viewing and Editing the pkglist File ..................................................... Installing Packages ................................................................................... Using Force Install .................................................................................... Installing Multi-lib Packages .................................................................. Importing Packages ................................................................................. Building Packages .................................................................................... Including Builds with Runtime Dependencies .................................... Turning Package Debugging On or Off ................................................ 5.6.8 Removing Packages .................................................................................
63 65 66 66 67 67 68 69 69 71 72 73 75 76 77 78 79 80 81 82
5.7 5.8
Creating a Project from a Package ....................................................................... Customizing Builds with Layers, Templates, and Profiles ............................ 5.8.1 Adding Templates .................................................................................... Adding Custom Templates ..................................................................... 5.8.2 Working with Layers ............................................................................... Adding Layers .......................................................................................... Reloading Changes ................................................................................... 5.8.3 5.8.4 Exporting Layers ...................................................................................... Specifying Profiles ....................................................................................
Configuring Platform Kernels ............................................................

6.1 6.2 Introduction ............................................................................................................. Configuring Wind River Linux Platform Kernels ........................................... 6.2.1 6.3 6.4 Kernel Configuration Node ....................................................................
83
83 84 85 87 87 88
Prepopulating LKM Projects ................................................................................ Adding Kernel Modules to the Platform ........................................................... 6.4.1 Creating a Custom Kernel Module ........................................................
vii
6.4.2
Moving Kernel Module Projects ............................................................
89
Feature Templates and Profiles ......................................................... 91

7.1 7.2 7.3 Introduction ............................................................................................................. Feature Templates ................................................................................................... Profile Basics ........................................................................................................... 7.3.1 7.3.2 7.3.3 7.4 Making Your Own Profile ....................................................................... Profile Hierarchy ...................................................................................... Differences between Profiles and Platforms ......................................... 91 92 93 93 93 94 94
Templates and Profiles in the Platform Project Wizard ..................................
PART III: DEVELOPING APPLICATIONS

8 If Youre an Application Developer .................................................... 97
8.1 8.2 Introduction ............................................................................................................. Creating Applications ............................................................................................ 8.2.1 8.2.2 8.2.3 8.2.4 8.2.5 8.3 Understanding Your Development Environment ............................... 97 98 99
Creating Applications in General .......................................................... 100 By Example: Building hello_world ........................................................ 100 By Example: Building Penguin .............................................................. 101 By Example: Importing Source Code for Penguin .............................. 103
Running Applications ........................................................................................... 106 8.3.1 8.3.2 By Example: Running hello_world, a Native Application ................. 106 Running Non-Native Mode Applications ............................................ 108
8.4
Changing Build Specs and Properties ................................................................ 109
viii
Contents
Sysroots, Build Specs, and Properties ............................................. 111

9.1 9.2 9.3 9.4 Introduction ............................................................................................................. 111 Importing Sysroots ................................................................................................. 112 Importing Build Specs ........................................................................................... 113 Changing Build Properties ................................................................................... 114 9.4.1 9.4.2 Configuring Project Build Properties In General ................................. 114 By Example: Putting Penguin on a Different Target ........................... 116
10
Importing Packages ............................................................................ 117

10.1 10.2 10.3 Introduction ............................................................................................................. 117 Overview of the User Space Configuration Tool ............................................. 118 Importing Classic Packages from the Installation ........................................... 119 10.3.1 10.3.2 10.4 Modifying the Makefile ........................................................................... 120 Reusing Fixes for the Package ................................................................ 120
Importing Source RPM Packages from the Web .............................................. 121 10.4.1 10.4.2 Updating the Package Spec File ............................................................. 121 Building New Packages ........................................................................... 122
10.5
Importing Wind River Linux Packages .............................................................. 123
PART IV: DEVELOPING PACKAGES

11 Patching Packages .............................................................................. 127
11.1 Introduction ............................................................................................................. 127 11.1.1 11.1.2 11.1.3 Maintaining PatchesFirst Principles .................................................. 128 Recognizing Classic Tarball Packages ................................................... 129 Recognizing SRPM Patches .................................................................... 129
ix
11.1.4 11.2
Reviewing the Quilt Menu Commands ................................................ 130
Patching and Exporting Patches to Layers ......................................................... 131 11.2.1 11.2.2 11.2.3 Patching and Exporting Classic Packages (General Steps) ................ 132 By Example: Patching and Exporting Classic Packages to a Layer .. 132 By Example: Patching and Exporting SRPM Source File to a Layer . 133
11.3
Using Quilt Basics .................................................................................................. 135 11.3.1 11.3.2 11.3.3 11.3.4 11.3.5 Configuring Quilt to Manage Patches ................................................... 135 Applying Patches ..................................................................................... 135 Importing Patches .................................................................................... 137 Creating a New Top Patch File ............................................................... 137 Viewing Patch Annotations .................................................................... 138
11.4
Patching SRPM Packages ...................................................................................... 139 11.4.1 11.4.2 Manually Patching SRPM Spec Files ..................................................... 139 Patching SRPM Source Files ................................................................... 140 Modifying SRPM Package Files ............................................................. Saving SRPM Patch Files ......................................................................... Adding the SRPM Patch .......................................................................... Saving the Updates as a Patch to the Spec File .................................... 11.4.3 11.4.4 141 141 142 143
Testing the Patches ................................................................................... 143 By Example: Viewing the SRPM Patch List .......................................... 144
11.5
Manually Patching Classic Source Files ............................................................ 144 11.5.1 11.5.2 11.5.3 11.5.4 Creating a New Top Patch File ............................................................... 144 Modifying Package Files ......................................................................... 145 Exporting a Patch ..................................................................................... 146 Testing a Patch .......................................................................................... 147
12
Managing Packages on Live Targets ................................................. 149

12.1 Introduction ............................................................................................................. 149
Contents
12.2
Working with Kernel Modules on the Target ................................................... 149 12.2.1 12.2.2 Installing Kernel Modules to the Target ............................................... 150 Removing Kernel Modules from the Target ......................................... 150
12.3
Working with RPMs on the Target ...................................................................... 151 12.3.1 12.3.2 12.3.3 Launching RPMs Straight to the Target ................................................ 151 Removing Running RPMs ...................................................................... 152 Replacing Running RPMs ....................................................................... 152
PART V: DEPLOYING TO YOUR BOARD

13 Assembling File Systems and Kernels ............................................. 155
13.1 13.2 13.3 13.4 13.5 13.6 Introduction ............................................................................................................. 155 Assembling Your File System .............................................................................. 156 Assembling Your Kernel ....................................................................................... 156 More on Build Targets ........................................................................................... 157 Adding Applications to Your File System ......................................................... 157 Collecting Your Files for Export .......................................................................... 158
14
Deploying to Targets ........................................................................... 159

14.1 14.2 Introduction ............................................................................................................. 159 Introducing Target Deployment .......................................................................... 160 14.2.1 14.2.2 14.2.3 14.3 Using a Typical NFS Target Networking Environment ...................... 160 Using an Emulated Target Environment .............................................. 160 Using a Flash Development Environment ........................................... 161
Connecting to Targets in General ........................................................................ 162 14.3.1 Defining a New Connection ................................................................... 162
xi
14.3.2 14.3.3 14.4 14.5
Connecting and Disconnecting .............................................................. 163 Modifying Connection Properties ......................................................... 164
Connecting to Emulated Targets .......................................................................... 164 Connecting with KGDB ........................................................................................ 167 14.5.1 Using Object Path Mapping .................................................................... 168 Pathname Prefix Mappings ..................................................................... 169 Basename Mappings ................................................................................ 169 14.5.2 Using Target State Refresh Page ............................................................. 169
14.6 14.7 14.8
Using Advanced KGDB Options ........................................................................ 170 Using Target Server Options ................................................................................ 171 Using the Connection Summary Page ................................................................ 172
PART VI: DEBUGGING AND ANALYZING

15 Debugging User Space ....................................................................... 175
15.1 15.2 Introduction ............................................................................................................. 175 Using the Wind River Debugger ......................................................................... 176 15.2.1 15.2.2 15.3 15.4 15.5 15.6 Creating a Remote Connection ............................................................... 177 Viewing all Running Processes .............................................................. 177
Debugging Using GDB ......................................................................................... 178 Stepping Through Your Output .......................................................................... 178 Using Dynamic printf Breakpoint Statements ................................................. 180 Sending Signals to Processes ............................................................................... 181 15.6.1 15.6.2 Configuring a Signal ................................................................................ 181 Terminating a Process .............................................................................. 182
xii
Contents
16
Debugging Kernel Space .................................................................... 183

16.1 16.2 Introduction ............................................................................................................. 184 Background Steps and Concepts ......................................................................... 185 16.2.1 16.2.2 16.2.3 16.2.4 16.2.5 16.3 Setting Up for kgdboe Between a Target and a Development Host . 186 Using agent-proxy to Cross Subnet Boundaries for kgdboe .............. 186 Mounting the Targets File System using NFS ..................................... 188 Kernels: Enabling KGDB versus Debug Builds ................................... 189 KGDB and Safe Areas when Debugging the Kernel ........................... 189
Preparing the Target for KGDB ........................................................................... 190 16.3.1 16.3.2 Option 1: Using a UDP Connection on a Non-PCD Target ................ 190 Option 2: Using a UDP Connection on a PCD Product ...................... 191 Statically Configuring KGDBOE for PCD (uclibc_small+small) ...... 191 Dynamically Configuring KGDBOE for PCD (uclibc_small+small) 191 16.3.3 Option 3: Using a Serial/Telnet Connection ........................................ 192
16.4
Connecting with KGDB from Workbench ........................................................ 192 16.4.1 16.4.2 16.4.3 16.4.4 Option 1: Making an Ethernet Connection ........................................... 192 Option 2: Making a Telnet Connection ................................................. 194 Option 3: Making a Serial Cable Connection ....................................... 195 Troubleshooting a KGDB Connection .................................................. 195
16.5
Attaching and Debugging the Kernel from Workbench ................................ 196 16.5.1 16.5.2 16.5.3 If the Compilation Unit Source Is Not Found ...................................... 196 If the Targets Terminal Is Stopped ........................................................ 197 Setting and Removing a Sample Breakpoint ........................................ 197
16.6
Debugging User-Supplied Kernel Modules ..................................................... 198 16.6.1 16.6.2 16.6.3 Building the Sample User-Supplied Kernel Module .......................... 198 Debugging a Running User-Supplied Kernel Module ....................... 199 Stepping into User-Supplied Kernel Module init from module.c ..... 200
xiii
16.6.4 16.6.5 16.6.6 16.7 16.8 16.9
Placing Breakpoints in Modules Not Yet Loaded ................................ 202 Providing Object Path Mappings to All Modules ............................... 203 Using the testmod Enhanced Sample Kernel Module ........................ 204
Creating a Custom Kernel Module .................................................................... 205 Using QEMU for KGDB Kernel Debugging .................................................... 206 Enabling and Disabling KGDB in the Kernel ................................................. 209
17
Optimizing ............................................................................................ 211

17.1 17.2 17.3 17.4 17.5 17.6 17.7 17.8 Introduction ............................................................................................................. 211 Managing File System Layout ............................................................................. 212 Profiling CPU Usage with OProfile .................................................................... 213 Analyzing Code Execution Coverage ................................................................. 213 Analyzing Memory Problems with mpatrol ..................................................... 214 Using the System Viewer ...................................................................................... 214 Improving Boot Time ............................................................................................. 215 Optimizing Footprint ............................................................................................. 215 17.8.1 17.8.2 17.8.3 17.8.4 Looking up a Packages Removal Size .................................................. 215 Looking up Packages that Require Particular Files or Directories .... 216 Looking up a Packages Dependencies ................................................. 216 Saving and Restoring Footprint Snapshots .......................................... 216 Creating a Footprint Baseline Snapshot ................................................ 216 Creating a Footprint Update Snapshot ................................................. 217 Restoring a Footprint Baseline Snapshot .............................................. 217 17.8.5 Exporting Package Dependency Information ...................................... 218
xiv
Contents
18
Analyzing Core Files ........................................................................... 221

18.1 18.2 18.3 Introduction ............................................................................................................. 221 Acquiring Core Files .............................................................................................. 222 Attaching Workbench to a Core File ................................................................... 223 Core File Analysis .................................................................................... 224 Ending the Session ................................................................................... 224
PART VII: DELIVERING YOUR PRODUCT

19 Providing Platforms and Kernels ....................................................... 227
19.1 19.2 19.3 Introduction ............................................................................................................. 227 Providing Platforms for Application Developers ............................................ 228 Exporting and Copying Sysroots ......................................................................... 229 19.3.1 19.3.2 19.3.3 Exporting Sysroots ................................................................................... 229 Copying Sysroots ..................................................................................... 230 Sysroots by Example: Adding 64-bit Multi-libs ................................... 230 Adding Available Multilibs .................................................................... 230 Adding Multilibs That Are Not Yet Available ..................................... 231 Verifying, Exporting, and Using the Multilibs Sysroot ...................... 231 19.4 19.5 Integrating Applications ....................................................................................... 232 Providing Kernels and Modules for Platforms ................................................ 232
20
Delivering Layers ................................................................................ 233

20.1 20.2 Introduction ............................................................................................................. 233 Example: Preparing Layers that Modify Kernels ............................................. 234 20.2.1 20.2.2 Creating a Project and Modifying Its Kernel Configuration .............. 234 Tailoring and Exporting a Layer ............................................................ 237
xv
20.3
Providing Layers to Teams and External Customers ....................................... 238 20.3.1 20.3.2 20.3.3 Making a Layer Available ....................................................................... 238 Telling Recipients How to Import and Use the Layer ........................ 239 By Example: Importing File System Change Lists from Layers ........ 239
PART VIII: REFERENCE

A FAQs ...................................................................................................... 243
A.1 A.2 A.3 A.4 A.5 A.6 A.7 A.8 Introduction ............................................................................................................. 245 Projects in General ................................................................................................. 246 Build Properties, Specs, Layers, and Templates ............................................... 249 Package Manager .................................................................................................... 250 Host-Related Issues ................................................................................................ 250 Application Projects ............................................................................................... 252 Debugging ............................................................................................................... 252 Troubleshooting ...................................................................................................... 253
Starting usermode-agent at Boot Time .............................................. 255

B.1 B.2 B.3 Introduction ............................................................................................................. 255 Basic Requirements ................................................................................................ 255 Writing and Placing the Script ............................................................................. 256
Workbench and Command-Line Techniques ..................................... 259

C.1 C.2 Introduction ............................................................................................................. 259 Workbench and the Command Shell Environment ......................................... 260
xvi
Contents
C.2.1 C.2.2 C.2.3 C.2.4 C.3
Setting the Environment with wrenv .................................................... 260 Setting the Environment with Workbench ........................................... 260 Executing Workbench Build Commands .............................................. 261 Executing Shell Commands in Workbench .......................................... 262
Setting the Environment Without Starting a Sub-shell .................................. 263 C.3.1 C.3.2 Exporting Environment Settings to the Current Shell ........................ 263 Extracting Environment Settings ........................................................... 264
Installing on Network Servers ............................................................ 265

D.1 D.2 D.3 D.4 Introduction ............................................................................................................. 265 Basic Considerations .............................................................................................. 266 Shared Wind River Linux Installation ............................................................... 267 Local Workbench Installation .............................................................................. 267
Glossary ................................................................................................ 269
Index .............................................................................................................. 277
xvii
xviii
PAR T I
Introduction
1 2 3 4 Overview ............................................................. 3
Getting Started with Workbench ....................... 15 Workbench Basics for Linux Developers ......... 23 Life Cycle Development ..................................... 35
1
Overview
1.1 Introduction 3 1.2 How to Use this Guide 4 1.3 Introducing Wind River Workbench and Linux 6 1.4 Notes about Installing Workbench 11 1.5 Finding Related Documentation 12
1.1 Introduction
Wind River Workbench is an integrated development environment (IDE) that lets you develop Linux target kernels and embedded applications. Workbench runs on Windows, Solaris, and Linux host operating systems, as detailed in the release notes.
1.2 How to Use this Guide

Different sections of this guide may be useful to you depending on your role in your organization, or the stage of the development process you are in.
1.2.1 How is this Guide Organized?

This guide is divided into the following parts: Part I. Introduction provides an overview of documentation, introduces Eclipse and cross-development concepts, and outlines how Workbench helps cross-development. Part II. Developing Platforms addresses platform developers, explaining how to develop platform projects and how to configure platform kernels. Part III. Developing Applications addresses application developers, who typically develop code and produce binaries, and how to use sysroots, build specs, and properties. Part IV. Developing Packages explains how to how to import local and open source packages, sources, or applications, and how to patch packages. Part V. Deploying to Your Board explains how to assemble file systems and kernels and move them to your target board, and how to use the simulator and deploy to targets. Part VI. Debugging and Analyzing explains how to debug user and kernel spaces; managing packages on a live target; analyzing code with the Indexer; profiling code; analyzing memory usage; and optimizing code with the System Viewer. It also describes briefly how to validate BSPs and how to analyze core dumps. Part VII. Delivering Your Product explains how to provide platforms and kernels to other team and product members. Part VIII. Reference describes command-line techniques, installation on network servers for shared access, and starting usermode-agent at boot time. It includes a glossary and an index.
1 Overview 1.2 How to Use this Guide
1.2.2 When is the Table of Contents Most Helpful?

The parts and chapters are arranged along the general lines of the major stages of the development of a project (see 4. Life Cycle Development):
Setup Using profiles, templates, layers, packages, and so on. Some of these are created by other people in your project. For example, someone else may develop layers and profiles that you use. Development Configuring, editing, and compiling within Workbench running on a host. Diagnosis Deploying to the target, debugging, and testing, involving both the target itself and the on-host Workbench. Optimization Using static analysis OProfile, mpatrol, and other tools such as the file system layout tool and views within Workbench to examine the footprints of your project. Delivery Providing kernels, platforms, layers, and so on for use by other project team members and/or your final customers.
If you know which areas within this life cycle apply to you, you can use the Table of Contents to locate what is relevant. Look especially for the Part divisions.
1.2.3 What if You Just Know Your Major Role?

On the other hand, if you know that youre developing, for example, applications, platforms, kernels, or layers, you can start with 2. Getting Started with Workbench Each section describes or lists the basic development tasks for a different type of developer. For each task, you can find a pointer to the most relevant sections of this guide, or, in some cases, a pointer to other documents.
1.2.4 How Do You Set Up Your Development Environment?

To become familiar with the basics of Workbench for Linux developers, read 3. Workbench Basics for Linux Developers, which tells you very briefly about:
Wind River Linux projects in general Your programming environment, toolchain, and so on Producing a file system and kernel Accessing the file system and kernel on your target
Debugging and analyzing whats on the target Making a product out of what you have done
1.3 Introducing Wind River Workbench and Linux

Workbench is an integrated development environment for creating device software to run on embedded Wind River Linux systems. Workbench is optimized for both small programs, and for very large ones with thousands of files and millions of lines of code. It includes a full project facility, advanced source-code analysis, simultaneous management of multiple targets, and a debugger with capabilities for managing multiple processes or threads on a single target or on multiple targets. Workbench and Wind River Linux have been developed in parallel to optimize development for Wind River Linux platform targets. You can use any combination of Linux command-line and Workbench GUI actions as desired.
1.3.1 Cross Development Environment

Workbench provides a cross development environment. This environment allows you to compile programs on a host machine running Workbench, to be distributed and run on generally much smaller and slower machines (target systems) that do not support the tools available on your host. Workbench allows you to edit, compile, and debug your systems on the Workbench host, and then move the resulting application, kernel, and file system to an emulated or actual target.
1.3.2 The Wind River Build System

The Wind River Linux build system is designed to create optimized runtime images suitable for embedded applications. The build systems infrastructure includes layer support, including core and Linux kernel layers. It is not a traditional binary Linux distribution.
1 Overview 1.3 Introducing Wind River Workbench and Linux
The build system has the following characteristics:
Source RPM compatible Installs and runs as a non-root user Provides complete integration with Workbench/Eclipse Enables efficient workflow and ecosystem using layers Allows a simplified board support package (BSP) model
Figure 1-1
Build System Overview
Features... Kernel Core Project Repository
sysroot Binary Kernel Binary RPMs...
Root File System Optimized Bootable Image
Layers
Project Creation Package Selection
Smudges Builder Patches Toolchain Wrappers Toolchain
File System Generator Deployable Image Generator
QEMU Simulation Hardware
Targets
Package Builder Wind River Build System
Layers
Layers provide a framework for managing device software components independently. Layers are abstractions of the Wind River Linux installation; they can be as big as a new kernel version, or as small as a single, one-line patch. The layers framework provides modular functionality, which you can modify or add to. You can then place your your modifications and additions as one or more layers on top of the core installation, with each layer contributing specific content, all without changing the core installation itself.
Layers provide both required and optional content for a target project, which allow you to: 1. 2. 3. 4. 5. Select and optimize the content first at the package level Further optimize the content to develop runtime components Generate the intermediate binaries (for example, the collection of generated RPM files from which the file system is assembled) Trim and optimize those binaries (for example, stripping out debug information or adding pre-linking) Generate the kernel and file system for the target
You can use layers to:
Add new components or modules Change the behavior of components Share configurations among members Manage change from one release to the next (for example, when migrating to the next version of a project, or up-revving to the next kernel version)
Standard Product Layers
There are four standard product layers:
The core layer contains templates, host tools, and target packages (distributions and RPMs). The kernel layer contains common kernel source and patches. The toolchain layer contains core toolchain executables and packages. The build layer lets you configure a build directory that is also a layer.
Optional Content with Feature Templates
Feature templates allow a layer to contribute many feature sets from which developers can select to further customize and extend their projects. For example, you can choose specific board, root file system (rootfs), and kernel values to include the respective board, rootfs, and kernel templates.
1 Overview 1.3 Introducing Wind River Workbench and Linux
You can also place content in optional template sub-directories, and configure your projects to add that content.
When to Use Layers or Templates
Layers and templates are optional configuration techniques you can use with Wind River Linux platform projects. You might, for example:
Use templates to cause relatively small changes at the end of the configuration process. Use layers to control larger configuration issues, such as reconfiguring and patching the kernel, modifying system files, and including one or more templates.
You may find layers useful when, for instance:
You plan to combine the work of different internal or external groups. You wish to share work with multiple projects or groups. You are making a step to a new kernel, release, or product version.
Sysroots
Sysroots can source one or more build specs for Workbench application projects. They provide the libraries, header files, and other files and directories that are essential to the infrastructure of these projects. They also provide the capability of cross building.
1.3.3 Accessing the Sample Projects

Workbench provides sample projects that you can explore on your own. This guide relies on a few of those projects to illustrate, by example, the major workflows with their associated tasks for the following types of development:
Applications User-space platforms Kernel modules
To make sure that you can access these examples, use the following steps.
1. 2. 3.
Open Workbench. Choose File > New > Example. Choose one of the following, as appropriate for what you want to develop. This guide uses the following examples in particular:
Wind River Linux Module Sample Project (version 1.4 or newer) > Next > An Example Kernel Module Demonstration Wind River Linux Application Sample > Next > The Client/Server Demonstration Program
4.
Click Finish.
1.3.4 Migrating Projects Forward

Workbench allows you to migrate runtime systems that you have produced on earlier versions. Typically, this involves:
Doing a build-all in the project to build a complete system from source. For small file systems (glibc_small or uclibc_small) that have been built in previous versions, using the templates features to migrate debugging and graphics capabilities. Specifying templates in the configure screen to specify debug and gdb templates. Using the new kernel profile templates to migrate kernels. (You still have to import kernel patches manually, to account for kernel changes.) Package makefiles that use package_RPM_DEFAULT, package_RPM_DEVEL, and package_RPM_ALL variables in place of the obsolete package_RPM_NAME. Sysroots that provide a portable application environment containing necessary library and header files as well as toolchain wrappers.
For more (and current) information about up-revving packages, see:
Wind River Linux Release Notes: Workbench Issues Wind River Linux Migration Guide: Wind River Workbench
10
1 Overview 1.4 Notes about Installing Workbench
1.4 Notes about Installing Workbench

In general, you should see the installation and licensing guides for instructions on installing Wind River products that conform to the common installation standards. Wind River uses one installation engine for all such products.
1.4.1 Installation and Licensing

The licensing system for Wind River Workbench assigns a license based on a combination of a unique machine ID and a unique name. If multiple Linux machines share the same name (such as localhost.localdomain), installation and licensing will only work on the first machine to install it. For more information, see the Wind River Linux Release Notes: Licensing.
1.4.2 Shared Installations

See the Wind River Linux Release Notes: Shared WR Linux Installations for instructions on installing Workbench and Wind River Linux on a shared NFS drive. Also, see D. Installing on Network Servers for help installing Wind River Linux and Workbench on a network server instead of locally. This allows you to reduce the number of installations, simplify maintenance, and save disk space. Note that you can also install Wind River Linux on a network server and then use a local installation of Workbench to access it.
1.4.3 Building across NFS

Wind River does not recommend NFS builds. When doing builds on NFS mounts, the file server and build machine must have synchronized clocks. If not, some package builds may fail. In addition, some operations require static inodes to be assigned to files in order to emulate special files, as well as owner and group permissions.
11
1.4.4 Reporting Issues and Enhancements to Wind River

Go to http://www.windriver.com/support to file questions, defects, and enhancements. You can also access downloads, patches, the Wind River knowledge base, the TSR (Technical Support Requests) manager, and so on. To obtain a copy of the Standard Support Users Guide, see: http://www.windriver.com/support/resources/csug.pdf. This guide explains many customer support issues, including how to:
Access Wind River Online Support Obtain person-to-person support Track your support requests, whether TSRs (technical support requests) or SPRs (software problem reports) Escalate problems Provide feedback
1.5 Finding Related Documentation

Other documentation includes:
Wind River Workbench Users Guide A guide to using the Workbench GUI to do tasks that are common between Linux and VxWorks.
NOTE: The common guides introduction contains an extensive guide to documentation related to Wind River Workbench. The guide also contains a glossary. We assume that you are familiar with the contents, and that you have worked your way through enough of it so that you can continue here. Be sure to step through the ball example chapter.
Wind River Workbench Online Help Accessible from the Help menu, from platform-specific help keys, or by clicking the ? mark in dialog boxes. Wind River Workbench for Linux DocumentationSee the next sections.
12
1 Overview 1.5 Finding Related Documentation
1.5.1 Online Wind River Workbench for Linux Documentation

The following documentation is provided online for the Workbench version that supports Wind River Linux. Additional documentation is also available online depending on your installation.
Help > Contents > Wind River Documentation > Getting Started
Wind River Workbench Tutorial, Linux Version Developing user mode applications, configuring Wind River Linux, kernel mode debugging, and using the QEMU target emulator.
Help > Contents > Wind River Documentation > Guides > Host Tools
Wind River Workbench by Example (Linux Version) (this document) This guide describes how to configure your Workbench host and a Wind River Linux target to debug applications and kernel objects on the target. It describes how to use Workbench to develop projects, manage targets, and edit, compile, and debug code. Wind River Linux Users Guide The Wind River Linux development environment, which encompasses Wind River Workbench and the Linux command-line environment, helps you develop Linux target kernels and embedded applications. Wind River development environments are available on a number of host platforms, and support a large number of targets.
1.5.2 Other Online Wind River Workbench Documentation

The following documentation is also provided online for Workbench.
Help > Contents > Tips and Tricks
Eclipse Workbench User Guide Sections on using Workbench, editing files, and using CVS in a team environment.
Help > Contents > Wind River Developer Network
Access to the Wind River web site for Workbench developers: http://www.windriver.com/developers/workbench, containing videos on
13
Workbench analysis tools, the Linux patch manager, System Viewer, diagnostics, customer education, white papers, blogs, and so on. See especially the white paper titled The Power of Wind River Linux Layers. (This site contains material appropriate for the current release as well as earlier releases.)
Help > Cheat Sheets
Step-by-step instructions in a Help window that you can follow in Workbenchs perspectives and views, to accomplish tasks related to C/C++ development; using CVS in a team environment; Wind River Linux build specs, sysroots, linked resources, imports, patching, and using the file system layout tool; as well as Wind River Workbench tools such as the code coverage analyzer, the data monitor, memory analyzer, and the performance profiler.
14
2
Getting Started with Workbench
2.1 Introduction 15 2.2 What Type of Developer Are You? 16 2.3 If You Develop Applications... 16 2.4 If You Import and Modify Source Packages... 18 2.5 If You Develop Middleware... 19 2.6 If You Develop or Provide Kernels... 20 2.7 If You Are a Platform Integrator... 21
2.1 Introduction
Where and how do you start using Workbench? This depends on what kind of development you do, whether its application development, middleware, platform integration, kernel modules, and so on. You can use this chapter as a springboard to jump into the appropriate sections of this guide. (For Workbench basics such as file systems, kernels, toolchains, programming environment, et cetera, see 3. Workbench Basics for Linux Developers.)
15
2.2 What Type of Developer Are You?

There is not always a clear distinction between the types of developers, so as you consider which sections mostly apply to you, keep the following in mind:
Application developers typically use Workbench-managed make and sample projects; they run and debug directly to the target; and they add their binaries to the platform project using file system layout tools. None of the example applications, such as mthread, client-server, and Penguin, is a package (see below): they are open applications, just source code in a tree that you build into one or more output files. Application developers can also include locally developed applications that have their own Makefiles. They typically bring these applications into Workbench as a user-defined project, which allows them to use Workbench facilities and features.
Package developers work with user space, divided into packages, typically including local applications with open source and non-local code. Examples of packages include tarballs, RPMs, SRPMs, and so on. Middleware developers work with plug-ins (for example, to develop Java code, or database queries, or PHP pages) and then make sure their products are in the targets file system and that they work on the target. Kernel developers do the kernel configuration, modules, and drivers. Platform developers put everything together, creating a platform from the user space packages and kernel configurations. Often, the kernel developer is also the platform developer.
2.3 If You Develop Applications...

The following perspective might apply to you:
You are writing primarily native applications, generally in C or C++ (maybe with some assembly).
16
2 Getting Started with Workbench 2.3 If You Develop Applications...
You may develop applications from internal code bases. These applications may not be in a package form, and they may normally use your company's configuration management system. You are primarily interested in building applications that are your own. You normally do not work with RPMs or SRPMs, or open source. You use source control for your code. You dont need a file system or kernel until youre ready to test your software. You dont need to create rules for unpacking, or patching. If you use managed Workbench projects, you use the build commands that are in Workbench. If you have your own makefile, you bring it in as a user-defined project and then use Workbench to run your makefile for you. You have experience with traditional tools such as C/C++ debuggers and profilers.
See the following table for pointers to the parts of this users guide (or elsewhere) that may help you the most.
Table 2-1 Application Development Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Develop managed and sample projects Develop user-defined projects Edit, develop code Debug Analyze Add binaries to platform projects
8. If Youre an Application Build commands provided by Developer; Workbench Users Guide Workbench Creating User-Defined Using your own makefile; Projects, Workbench Users Guide telling Workbench how to build your source Workbench Users Guide 15. Debugging User Space; also, Workbench Users Guide Memory Analyzer and Performance Profiler guides 5.5.2 Adding Files and Directories to Your File System, p.61 Using file system layout tool Using GDB and/or the Workbench debugger
17
2.4 If You Import and Modify Source Packages...

You work with user space, divided into packages. You are likely to import and/or modify open source packages, generally in tarball or SRPM form, and you likely have to modify them so they fully cross-compile. You may modify or update wrlinux-supplied packages, which are generally managed by the wrlinux patch system (for example, by using Quilt).
Table 2-2 Package Development Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Import open source 10.4 Importing Source RPM packages Packages from the Web, p.121 Import local packages Develop, capture patches to layers Enhance, investigate, work with code and code-related tools 10.5 Importing Wind River Linux Packages, p.123 11. Patching Packages 12. Managing Packages on Live Targets
RPM archives with source Also see 10.3 Importing Classic Packages from the Installation, p.119 Also see 20. Delivering Layers For example, find whats wrong with open source, or MIPS vs. ARM, or 386 vs. 64-bit, or speed issues; if you touch open source packages, it means youre fixing someone elses code. Static analysis, moving into package, debugging/tracing; general fixing of open source; get object path mapping and source code path mappings so you can do breakpoints and do source code debugging
Debug
15. Debugging User Space; also, Workbench Users Guide
18
2 Getting Started with Workbench 2.5 If You Develop Middleware...
Table 2-2
Package Development Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Analyze
Memory Analyzer and Performance Static Indexer analysis for Profiler guides relationship between structures and files, for RPMs 20. Delivering Layers Layering changes to existing apps lets you maintain pristine source while providing external, or local patches, or fixing broken package contents, while allowing you to keep and track such changes separately
Deploy as layer
2.5 If You Develop Middleware...

You may typically work with plug-ins such as for Java development, or PHP, for which Workbench provides a robust and supportive environment. Youre not really into doing packages: youre developing Java code, or DB queries, or PHP pages (for example). You may bring in middleware components such as PHP, SQL, or X into your file systems so you can develop on top of them. You may bring in open source packages to develop your middleware content, plus. You likely work with the developers who import and modify source packages to make sure your middleware is on the target and is configured correctly for your requirements. You are likely very familiar with commercial and open source Eclipse plug-ins for your development tools and SDKs.
19
Table 2-3
Middleware Development Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Develop DB queries, or Java, PHP, &c. pages
Documented by the community, for example at Eclipse.org Click location to put binaries, click on add, browse to files.
Insert them into file File System Manager system
2.6 If You Develop or Provide Kernels...

You are the primary developer of the kernel, drivers, and kernel modules. You provide the kernel for the application developers.
Table 2-4 Kernel Development Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Configure and manage the kernel Develop kernel modules
Part IV. Developing Packages
You can also import projects configured on the command line into Workbench
12.2 Working with Kernel Modules Sample kernel modules are on the Target, p.149; 19.5 Providing provided Kernels and Modules for Platforms, p.232
20
2 Getting Started with Workbench 2.7 If You Are a Platform Integrator...
2.7 If You Are a Platform Integrator...

You put user space packages together with kernel configurations from the kernel developers. You integrate the file system content from the package and application developers with the kernel. You perform optimizations on the resulting image. You may wrap content into layers to share back with the group. You prepare BSPs (board support packages).
Table 2-5 Platform Integration Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Create single and Site Configuration Guide; Also shared installations D. Installing on Network Servers Integrate layers 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75 Adding Layers, p.79 in 5.8.2 Working with Layers, p.78; 4.6 Working with the File System Layout Tool, p.40 17. Optimizing 14. Deploying to Targets 20. Delivering Layers; 20.2.2 Tailoring and Exporting a Layer, p.237
Shared installations can be placed on NFS servers Custom layers can also be generated and shared across the team If there are kernel flags, you can capture them into a layer using the export layer feature. Summary and pointers to other books Emulated and hardware Using export-layer to capture the project's changes and share them with other projects and team members
Integrate applications, packages, kernels Optimize Deploy to target Deploy projects back as a layer
21
Table 2-5
Platform Integration Tasks, Tools, and Document Links
Tasks
Where Documented
Notes and Comments
Deploy projects forward as a product
20.3.2 Telling Recipients How to Import and Use the Layer, p.239
If you encapsulate completed projects into a layer for the next product version (which may have a newer wrlinux and kernel), you can port the product layer forward and may need only to match any kernel changes.
Configure BSPs
Wind River Linux BSP Developers Working with components Guide: Creating a BSP that make up a BSP, in view of the requirements for a Wind River Linux Platform BSP Wind River Linux BSP Developers Using Linux Test Project Guide: Validating Boards (LTP), and the Open POSIX Test Suite (OPTS) operational tests and software test package, plus BSP Validation Suite
Validate BSPs
22
3
Workbench Basics for Linux Developers
3.1 Introduction 23 3.2 Wind River Linux Projects 24 3.3 Your Programming Environment 26 3.4 Producing a File System and Kernel 27 3.5 Accessing the File System and Kernel on a Target 28 3.6 Debugging and Analyzing on a Target 30 3.7 Productizing 32
3.1 Introduction
This chapter sets the stage for the next chapter, which will take you through the main flow of creating a product within a generalized lifecycle of development. In the following sections, you will find answers to introductory questions about using Wind River Workbench, with an emphasis on basic concepts such as:
Does it matter which host you use for Workbench? What compilers and debuggers do you have available? Can you just use the command line instead?
23
What do you really make when you develop something in Workbench? What is a target, how big is it, and where do you get one? How can you put your file system and kernel onto a target, or access it otherwise? How can you change whats on the targets file system? How do you debug whats on the target? What can you do with what youve created?
If you are looking for help on how to use Workbench, how to open views, perspectives, tabs, and so on, and for tutorials and procedures that step you through working with code, compiling, attaching to targets, debugging, and so forth, see the Wind River Workbench Users Guide.
3.2 Wind River Linux Projects

When you start Workbench for the first time and click the Workbench arrow on the splash screen, you see the Application Development perspective. Quite a few views are visible, but they are empty. So where should you start? From a Workbench point of view, just about everything revolves around projects:
They allow you to manage your source code files by collecting them into logical, and, if necessary, hierarchical, structures. They allow you to create build targets with different build-related settings (known as build specs) so you can build the same sources for different target architectures or different toolchains simply by changing the projects active build spec.
Workbench projects are preconfigured to provide the type of build support required by the task you are working on.
NOTE: You cant change a project type after you create it, so be sure to choose the correct project type initially.
24
3 Workbench Basics for Linux Developers 3.2 Wind River Linux Projects
The most common Wind River Linux projects are:
Applications Workbench supplies the Makefile, determines build order, and provides macros, build paths, and build specifications. The build specs are based on the targets that are tested and supported by Wind River Linux. Appropriate libraries, cross-development tools, and so on are also provided, so much of the gathering and debugging of a working environment is eliminated. Platform Projects These projects are designed for building the entire target platform, including the kernel and file system. Workbench provides special tools for platform configuration, modification, and maintenance. You can build root file systems using default settings, or you can configure the file system through a GUI configuration tool that the project provides. Default kernels are provided for supported targets, and you can configure them using the provided GUI configuration tool. User-defined projects For these, you set up and maintain your own build system, file system contents, Makefile, and so on. Workbench lets you configure the build command to launch your build utility, so you can start builds from Workbench. You can also configure different rules for building, rebuilding, and cleaning the project. You can create build targets in the Project Explorer that reflect rules in your Makefiles, allowing you to select and build any of your make rules directly from the Project Explorer. Build output is captured to the Build Console. Kernel Modules These projects provide a way to create kernel modules for Wind River Linux. You can associate the kernel module with a platform, and the kernel module automatically inherits the build environment of that platform. Native Application Projects These are projects that are developed and deployed on the host; therefore no cross development is required. The build specs assume local development tools. Additional build specs support team development for when a team works with a combination of Windows, Linux, and Solaris host environments.
In addition, there are:
Customer-specific projects Application and kernel projects that are built and reside on the host computer, but run on the target. Workbench provides a generic managed build, allowing you to derive your specific build specs from a set of predefined ones. The customer-specific kernel projects wrap the typical Linux kernel command line build. Because your subsequent Linux application
25
projects will run on the Linux kernel on the target, this is often a necessary first project to build, unless you already have a target kernel. To enable Customer-Specific Linux projects, select Window > Preferences > Wind River > Capabilities. Expand Development. Check Customer-Specific Linux Development. Click Apply Note that user-defined and native application projects are available in both VxWorks and Wind River Linux versions of Workbench. For more information on types of projects, see the Wind River Workbench Users Guide: Projects Overview, especially the sections on project structures involving suband super-projects and project-specific execution environments, particularly the discussion of object.properties files.
3.3 Your Programming Environment

All but application developers want to use Linux hosts, with a standard GNU toolchain, as clarified in this section. Workbench is designed to be interoperable with a standard Linux command-line environment.
3.3.1 Using Windows, Solaris, or Linux Hosts

For Linux hosts, Workbench supports Linux application, platform, and kernel module projects. For Windows and Solaris hosts, Workbench supports only Linux application projects.
3.3.2 Understanding the Toolchain Available to You

For Linux and Solaris hosts, you are expected to have a fairly standard GNU installation. For details and specifics, see the release notes. For Windows hosts, you need to provide your own GNU tools as well, typically in a Cygwin or MinGW environment.
26
3 Workbench Basics for Linux Developers 3.4 Producing a File System and Kernel
For information about the debuggers, see section, 3.6.1 Debuggers, p.30.
3.3.3 Using Workbench and/or the Command Line

Wind River Linux is designed so developers can use Workbench and the command-line virtually indistinguishably. You can create projects in Workbench or configure them using command lines, and at most major intervals in the development process you can alternate between development styles as needed. You can create platform projects using the command line, then import them into a Workbench project choosing Import > Wind River Linux > Existing . . . Platform Project in the Project Explorers right-click context menu. Also you can create application projects in a command-line environment and then: 1. 2. 3. Import or create a new application project. Right click in the Project Explorer and select Import > General > File System. Browse to the folder (directory) containing your application files.
For an example, see 3.4.1 Configuring Projects, p.27.
3.4 Producing a File System and Kernel

When you configure a project and build a file system for it, you also produce a default kernel. These are located in workspace/ProjectName_prj/export/dist and inexport, respectively.
3.4.1 Configuring Projects

When you use the project creation wizards in Workbench, you are manipulating command lines behind the scenes. For example, the following configure command (given in the appropriate directory):
$ ../../installDir/wrlinux-3.0/wrlinux/configure \
27
> --enable-board=arm_versatile_927ejs --enable-kernel=standard \ > --enable-rootfs=glibc_std
has the same effect as the Workbench Create Project wizards Configure Options screen that asks you to specify a particular board, kernel type, and file system. (See Creating the By-Example Platform Project, p.53, for a screenshot.)
3.4.2 Building the File System

During the process of developing platform projects, you build a file system. This file system can contain application files as well.
3.4.3 Finding the File System and Default Kernel

The file system you build appears in workspace/ProjectName_prj/export/dist. Workbench also creates a default kernel in workspace/ProjectName_prj/export. These directories are identical to build directories created by command-line tools and can exist outside of the workspace folder. You may add to or change the file system; you may modify and rebuild the kernel; and you may add modules to the kernel. When the file system and kernel are as you wish, you may use various means to copy them to the target device, or you can set the target device to NFS mount the file system, or you can use TFTP to obtain the kernel from your development host or elsewhere. (See 14. Deploying to Targets.)
3.5 Accessing the File System and Kernel on a Target

You can use emulated or actual hardware targets for the applications, file system, and kernel that you may be developing. Once your target is running, you can explore and manage the file system on it.
28
3 Workbench Basics for Linux Developers 3.5 Accessing the File System and Kernel on a Target
3.5.1 Real and Simulated Targets

Broadly speaking, you can develop file systems and kernels for:
Emulated targets using the Quick Emulator (QEMU) Check the release notes and the Online Support site to see which boards are emulated by QEMU. Currently, these include the Common PC and ARM Versatile AB-926EJS boards, among others.
Real targets Check the release notes and the Online Support site to see which physical target boards are supported.
In either case, Wind River Linux provides specific BSPs for the supported targets.
3.5.2 Communicating with Targets

You cannot boot the target from within Workbench, but once the target boots, the Workbench console views can display the targets standard output. Typically, if you use a serial connection to talk to the target, you can set it up so output is displayed from an earlier stage than if you were using Ethernet. For more information about booting targets, see mainly the Wind River Linux Users Guide.
3.5.3 Exploring File Systems on Targets

Workbench allows you to explore and manage the file system on a target. You can also replace RPMs while the target is running. See 12. Managing Packages on Live Targets.
29
3.6 Debugging and Analyzing on a Target

Depending on your needs and the version of the Linux kernel you are running on your target, you will use one or more of the following debug modes:
User ModeUser mode debugging allows source code debugging of user mode applications, including multi-process and multi-thread debugging. In user mode, a usermode-agent on the target communicates with Workbench on the host, allowing you to use Workbench to edit your source code, step through the application, set breakpoints, and so on. Kernel ModeKernel mode debugging allows for source code debugging of Linux kernels version 2.6 and later. The kernel must be patched for KGDB, the Kernel GNU Debugger, which communicates with GDB, the standard GNU debugger, on the host. Kernel mode source code debugging allows you to debug the kernel using suspends, breakpoints, and so on, as you would with user mode debugging.
NOTE: KGDB is enabled by default for Wind River Linux kernels and only needs to be disabled for you to go to production.
3.6.1 Debuggers
From the right-click context menu for a project, you can choose:
Debug As Local C/C++ Application, which automatically chooses a default GDB debugger Open Debug Dialog, so you can (a) specify a particular GDB debugger (such as Cygwin or MinGW) for C/C++ applications (and the postmortem debugger), or (b) choose other projects that use the Wind River Debugger (WDB).
If you choose Open Debug Dialog, the resulting Configure launch settings dialog (Create, manage, and run configurations), lists the configuration types. These types happen to be the same in VxWorks as in Wind River Linux. They determine whether to use GDB or WDB, as shown in the following table:
30
3 Workbench Basics for Linux Developers 3.6 Debugging and Analyzing on a Target
Table 3-1
Which Debugger for Which Project Type
Debugger
Project Type
WDB GDB GDB GDB GDB KGDB WDB WDB WDB WDB
Attach to Target C/C++ Attach to Local Application C/C++ Local Application C/C++ Postmortem debugger Native Application Kernel Task Launch Control Process on Target RTP on Target Wind River Application
(This table includes Native and Wind River Applications, though these are not in the same context menu.) For those projects that use the Wind River Debugger, there is no Debugger tab in the Configure launch settings dialog. This tab lets you choose a particular GDB debugger, such as GDB, Cygwin GDB, or MinGW.
NOTE: If the Debugger tab does not exist, you are using the Wind River Debugger
(WDB).
3.6.2 Dynamic printf Statements

Wind Rivers Workbench provides an extremely useful feature that lets you set printf( ) breakpoint statements at run time, without recompiling. This lets you display int and char* values when processing reaches the statements. These event points do not require stopping the current task; they can be inserted into unbreakable tasks; and they are supported by the Wind River System Viewer, as well.
31
3.6.3 Analyzers and Profilers

The projects right-click context menu offers Memory Analyze As. This lets you use various analysis tools, such as the mpatrol backend, which are documented in other Wind River guides. The mpatrol facilities allow application developers to identify leaks, heap thrashing, and memory hogs. You access these facilities in Workbenchs Memory Analyzer view, which allows you to aggregate, tree, and time views, and, as well, to navigate into source files from the reported memory events.
3.7 Productizing
This section very briefly describes productization in terms of how to work with:
Your applications, platforms, and kernels to create a product Other members of a development team with different roles in producing intra-team and customer-directed products on an iterative basis Patches and updates, in terms of providing them, when, and for whom
3.7.1 The Role of Your Application, Platform, or Kernel

Your applications provide the binaries for your target. Kernel patches, modules, features, and various enablement options (by which you can turn on parts required by the product) provide the kernel and kernel support functions of the device. The platform is built of kernel and file system, to create the distribution media (ISO, tarballs, flash images, and so on). The platform combines products from other developers (application, kernel, package). The platform is released to a productization team or, for intra-team use, your companys teams in an iterative development environment on an interim basis (for file systems or target images, for example). Platform developers are the gatekeepers of what goes into your product, and what is released in large organizations for development.
32
3 Workbench Basics for Linux Developers 3.7 Productizing
3.7.2 Working in a Team

You can typically divide up work and have applications and kernel developers work separately, relying on platform developers to combine their material and iterate the work each set of developers produces, to make it available as needed while the product is undergoing development internally. You can do your work in terms of layers, which are portable and can be shared within an organization, and can act as a form of source control for Workbench and Linux platforms.
3.7.3 Patching and Updating

As you develop a product, patches are likely to continue to come in, whether for security warnings or notices, or other improvements, particularly as they pertain to open source or plug-ins that you use. And after you release your product, there may be patches you need to provide for the field. You can gather these changes in terms of a layer so you can deliver them back to the sustaining team. Workbench does not address the issue of pushing live changes to live targets, but can be assisted by Wind Rivers Device Management DM products, which allow live patching of products, with live breakpoints, and which provide the infrastructure for pushing changes out to large fielded devices.
33
34
4
Life Cycle Development
4.1 Introduction 36 4.2 What Do You Do? 36 4.3 Where Does Your Work Fit into the Big Picture? 37 4.4 Starting with a Simple Project 38 4.5 Using Pre-Built User Space Content 39 4.6 Working with the File System Layout Tool 40 4.7 Configuring Kernels 41 4.8 Debugging and Deploying 41 4.9 Optimizing 42 4.10 Managing Content 43
35
4.1 Introduction
This chapter describes the typical chronological lifecycle of projects that you can create using Workbench. It introduces the various development stages, providing an introduction for each one, along with pointers to advanced material. This is to help you find and understand topics and tools presented throughout this book.
4.2 What Do You Do?

In general, this guide assumes you fall into one or more of the following types of developers, but that you also manage patches, code modifications, and open source code revisions:
Application developers used to working with middleware and using a high-level application development framework or SDK. You can analyze and debug application behavior. Kernel developers who write and fix kernel features, integrate external source code, mix complicated patches together, and do source code manipulation. You might get the latest Linux kernel to boot on a device, and/or create a kernel driver module for an existing Linux kernel. We assume you can take a kernel and drivers and boot-strap a minimal Linux system with basic libraries, shell and GCC. You can analyze device behavior using tools such as on-chip debugging. Platform integrators who put all the pieces together, communicate to various groups of other developers, and perform integration tests, footprint optimizations, and boot time optimizations. Your deliverable is the production of the integrated platform. You can analyze and debug OS behavior.
In terms of Workbench and Wind River Linux, two types of licenses are available, platform and application:
As a platform developer, you configure the kernel, kernel modules, and the file system, using the Workbench kernel and user space configuration tools. As an application developer, you use the Workbench tools to develop cross-built applications. You get the default, pre-built sysroots that have all the
36
4 Life Cycle Development 4.3 Where Does Your Work Fit into the Big Picture?
necessary libraries, header files, and access to the cross-compilation tools. These pre-built sysroots let you start developing applications until your platform developers prepare a proper sysroot for the actual target system. A sysroot holds the shared header files and libraries from the file system (for example the C runtime libraries), for the use of the other packages.
4.3 Where Does Your Work Fit into the Big Picture?
Figure 4-1 briefly illustrates the development life cycle that Workbench makes available, although only part of this may apply to you, depending on how much of the cycle involves you.
Figure 4-1 Overview of the Product Development Life Cycle Product Requirements
Applications Files Packages Unit Tests Docs Layers Sysroots Profiles Kernel File System
Setup
Templates Layers Packages RPMs, CVS, . . .,
Develop
Config Edit Compile On-Host Workbench
Diagnose
Deploy Debug Test On-Host Workbench & Target
Product Deliverables
Kernel Image File System Image Layers Sysroots
Optimize
System Layout Views Profiles Static Analysis Cores Footprint Workbench, Eclipse, Target
In Figure 4-1, the requirements and deliverables are listed on the left. The deliverables can be to the end customer or to other team members. The life cycle circle suggests that you as a developer can enter the life cycle at any given point, and typically move on from that point to the next in a clockwise fashion. The various stages in the life cycle have, very briefly, the following characteristics for different developers.
37
SetupYou take the profiles, templates, layers, packages, and so on, whether expressed as RPMs, SRPMs, CVS or ClearCase repositories, or whatever, and you set up a Workbench environment so these are all available to Workbench users in the Develop, Diagnose, and Optimize stages (depending on how far such users progress in the cycle). These profiles, templates, layers, and packages come from the Optimize or Deliver stages. The Setup stage produces its own set of deliverables, not shown here, that are used in the next stage, Develop. DevelopBased on what is available as a delivery from the Setup stage and what you can import from external or other local sources, you work with Workbench running on your local or NFS-mounted host (or other remote host), and you go through the common edit, compile, debug cycle within the Develop stage. Upon completion, your deliverables are available to the next stage in the life cycle. DiagnoseStarting with what the Develop stage makes available as a deliverable, you use Workbench and on-target or on-simulated-target projects (kernels and file systems) in a deploy, debug, and test cycle. At this point, your deliverables are available to the Optimization stage, at which you or other developers study your deliverables and figure out how to make them better. OptimizeUsing the deliverables from the Diagnose stage, you work with the target, Workbench, and general Eclipse tools to improve certain aspects such as memory usage, footprint, response time, and so on. These tools may include OProfile, mpatrol, static analysis, core dump analysis, footprint tools, and various system and layout views.
4.4 Starting with a Simple Project

In this simple project, we use a pre-built kernel, vmlinux symbol file, packages, and default layers. The following steps lead you from creating a project to putting it onto a target, and debugging it. The suggested cross references point you to more detailed information. Be sure to return here to continue reading this introduction to life cycle development. 1. Create (configure) a project. See 5.1.1 Building New Platform Projectsan Overview, p.48.
38
4 Life Cycle Development 4.5 Using Pre-Built User Space Content
2. 3. 4.
Build a target file system. See 5.1.1 Building New Platform Projectsan Overview, p.48. Connect to an actual or QEMU-emulated target. See 5.1.3 Connecting to a Target, p.49. Debug as appropriate:
Do user mode debugging. See 15. Debugging User Space. Do KGDB debugging. See 16. Debugging Kernel Space, and especially 16.4 Connecting with KGDB from Workbench, p.192
NOTE: If the connection succeeds and the Editor complains that it cannot find
source for the kgdb.c compilation unit, click Browse and provide the path to your Linux kernels source directory, which will be in your projects build folder. This is known as source path mapping. For more details, see 16.5.1 If the Compilation Unit Source Is Not Found, p.196. For further study, see:
5.8 Customizing Builds with Layers, Templates, and Profiles, p.75, regarding layers and templates The Wind River Linux Users Guide
4.5 Using Pre-Built User Space Content

When you make the file system (that is, right-click a projects fs node and choose Build Target), you are using pre-built RPMs, and the file system build is much faster because you are not building these RPMs from source. But, for some architectures, you might be getting the least-common-denominator architecture. For example, for a Pentium file system, you might be getting the pre-built 386 RPM, which, while it works up through 486 and 586 Pentiums, may not be optimal for your particular case. In this instance, you want to right-click the build-all node and choose Build Target. You can always rebuild targeted packages that you may care about, individually, using the Package Manager. (This balances efficiency and control.)
39
To see which architectures were built for specific packages: 1. 2. Double-click the projects User Space Configuration node to open the Package Manager. Look in Column 3 for the architectures for installed packages. If the package is built for a CPU variant different from the default, you see the variant listed as arch.cpu-variant. If there is no .cpu-variant extension indicated, the package is using the default CPU variant of the file system. To rebuild packages: 1. 2. 3. Open the Package Manager. Highlight the package to rebuild, then click the Targets tab. Click the rebuild button.
NOTE: When you click on User Space Configuration, the User Space Configuration Tool opens. In that view, you can click on the Packages or File System tab to display the Package Manager or the File System Layout tool, respectively.
4.6 Working with the File System Layout Tool

The user space file system layout tool lets you inspect the file system and directly observe and manipulate its contents. To open this tool: 1. 2. 3. 4. 5. Double-click the User Space Configuration node. Click the Filesystem Layout tab below the Installed Packages panel. See 5.5 Exploring the Target File System, p.58. Look for file ownership, placement of files by RPM, sizes, and so on. Observe that you can search for files in the various filters provided. Notice that you can import files and RPMs. See 10.3 Importing Classic Packages from the Installation, p.119, and 10.4 Importing Source RPM Packages from the Web, p.121.
40
4 Life Cycle Development 4.7 Configuring Kernels
For more information, see:
13.2 Assembling Your File System, p.156, which talks about putting together your runtime file system. 17.2 Managing File System Layout, p.212, for help on optimizing the contents of user space.
4
4.7 Configuring Kernels

Using the kernel configuration wizard, you can:
Configure and modify a platform kernel. See 6.2.1 Kernel Configuration Node, p.85. Add and share modules between projects. See 6.3 Prepopulating LKM Projects, p.87. Create custom modules. See 6.4.1 Creating a Custom Kernel Module, p.88.
You must use kernel rebuild target to instantiate changes. Note that this replaces the default sym links by your local kernel and vmlinux symbol file. This means that when you build your own kernel, the vmlinux is tied to your project and now has an automatic source path mapping, so you dont need to set the source path mapping.
4.8 Debugging and Deploying

Debugging uses usermode-agent, the Wind River Debugger, and KGDB, in addition to physical and QEMU-emulated targets with pre-made launch configurations. Deployment simply involves getting the kernel image and the file system to the target, as well as, in some cases, moving specific RPMs to live targets. You can also iterate edit-patch-rebuild cycles and place the results on the target. For deploying and debugging, see:
41
For usermode-agent: 8.2.3 By Example: Building hello_world, p.100, and 15.2.1 Creating a Remote Connection, p.177. For Wind River Debugger, see 15. Debugging User Space. For KGDB kernel space debugging, see 16. Debugging Kernel Space, and also 16.6 Debugging User-Supplied Kernel Modules, p.198, 12.2 Working with Kernel Modules on the Target, p.149, and 12.3 Working with RPMs on the Target, p.151. For QEMU, see 5.1.3 Connecting to a Target, p.49, and 16.8 Using QEMU for KGDB Kernel Debugging, p.206. (You can have multiple instances of QEMU running at the same time, with different targets, if each instance has a higher instance number.) For physical targets, see the Wind River Linux Users Guide. For launch configurations, see the Wind River Workbench Users Guide. For pushing recompiled RPMs straight to live targets without rebooting them, see Table 5-2 on page 65, and the surrounding text.
4.9 Optimizing
Optimizing covers a lot of territory, from working with CPU variants, to optimizing packages, file system layout, kernels, kernel modules, and so on. See the following for pointers:
17.2 Managing File System Layout, p.212 17.3 Profiling CPU Usage with OProfile, p.213 17.4 Analyzing Code Execution Coverage, p.213 17.5 Analyzing Memory Problems with mpatrol, p.214 17.6 Using the System Viewer, p.214
42
4 Life Cycle Development 4.10 Managing Content
4.10 Managing Content

Workbench provides several of means for managing content. The following are only some of them.
Using Meta-Information from the Project Directory and Elsewhere 4
Workbench provides meta-information within the project directory that you can use to manage your project at a high level. Some of the more useful files and directories in the project have been given purposeful names, for example, in workspace/Project_prj:
export What goes on the target. filesystem Pre-target-deployment. layers For managing device software components independently; to control larger configuration issues, perhaps reconfiguring and patching the kernel, modifying system files, and including one or more templates. packages For adding local packages to your build dist or tools directories (Project_prj/dist or Project_prj/tools) templates Typically for relatively small changes at the end of the configuration process.
Importing Packages
The Package Import Tool lets you import packages that are not already available on your system. You can import files and packages locally or by specifying a URL. See 5.6.6 Importing Packages, p.68.
Using Layers
You can export and import layers to make it easy to move software component configurations from one project to the next. See, in particular:
5.8.2 Working with Layers, p.78 (this includes adding layers) 20.2 Example: Preparing Layers that Modify Kernels, p.234 20.3 Providing Layers to Teams and External Customers, p.238
43
44
PAR T I I
Developing Platforms
5 6 7 Developing Platform Projects ........................... 47 Configuring Platform Kernels ........................... 83 Feature Templates and Profiles ........................ 91
45
46
5
Developing Platform Projects
5.1 Introduction 47 5.2 Creating Projects Using Workbench or the Command Line 50 5.3 Building a Target File System 55 5.4 Introducing the User Space Configuration Node 57 5.5 Exploring the Target File System 58 5.6 Using the Package Manager for RPMs 63 5.7 Creating a Project from a Package 73 5.8 Customizing Builds with Layers, Templates, and Profiles 75
5.1 Introduction
This chapter tells you how to create a new Wind River Linux platform project. Except for self-hosted (native-mode) applications, you cannot debug an application or a kernel until you have configured a platform and booted the platform containing the kernel and file system that you have configured. When you use a self-hosted application, you do not have to configure a target platform, because the development host is the target platform. Such applications
47
are only supported on a common PC running Linux. For more information, see the Wind River Workbench Users Guide: Developing Applications.
Figure 5-1 The Platform Development Stage of the Product Life Cycle
Platform Requirements
Applications Binaries Docs Kernel Modules Layers Non-Binary Files Packages
Setup
Relevant Tools
Build Specs File System Layout Tool Layers Open Source Package Import Patch Manager Sysroots User Space Configuration
Develop
Diagnose
Platform Deliverables
File System Kernel Sysroots
Other Tools
Package Manager Quilt
Optimize
5.1.1 Building New Platform Projectsan Overview

Typically, you can use the following steps as a checklist to create new platform projects: 1. 2. Create a Wind River platform project. Right-click in the projects FS node and select Build Target to create a file system for the platform. This creates a ProjectName_prj directory containing the file system for the remote system (target) and a default kernel. The file system and kernel are on the host and, at this point, are not on the target system or accessible by it. 3. Develop the target file system by working with the packages you need (installing and importing them, building them, and removing them as needed). See 5.5 Exploring the Target File System, p.58.
48
5 Developing Platform Projects 5.1 Introduction
NOTE: Working with packages is a major part of developing platform projects. You might consider this current chapter an introduction. For further information and more specific details, see the following chapters: 10. Importing Packages and 11. Patching Packages.
4.
Add templates and profiles to a project, and create and add layers. See 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75.
5.1.2 Are You Deploying a New Platform Project?

In general, after you create a new platform project, you can configure and customize it for your particular project. In addition to simply creating a platform project, you will probably perform these tasks:
Import any needed open source packages and/or local sources and applications Patch packages as necessary Customize your builds with layers and templates Develop your file system Deploy your file system to your target Test and debug your target system
For more information about deploying, see 13. Assembling File Systems and Kernels and 14. Deploying to Targets.
5.1.3 Connecting to a Target

If you want to open and modify a previously created project on your target: 1. Define a connection to the target: a. b. In the Remote Systems toolbar, click Define a connection. Click Wind River QEMU Linux User Mode Target Server.
Workbench simplifies many aspects of creating and using QEMU targets if you follow this approach. The QEMU connections vary as follows:
Linux User Mode Target Server Runs the usermode-agent and QEMU.
49
Backend ConnectionFor use with KGDB, providing a command-line interface to QEMU to start, stop, query registers, and so on. ConnectionAlso uses KGDB, but more similar to an OCD connection, good for debugging Ethernet, early boot-time access before connections are available, and so on. This form of QEMU actually emulates real boards. It starts QEMU for you and opens a connection so you can sign on, or whatever.
2.
Specify (or verify) the connection object path mappings that name the target path (/) and host path, such as workspace/ProjectName_prj/export/dist. This mapping specifies which host directory is to be NFS mounted on the target root directory (or, for QEMU, which directory is to be mapped to the emulated target root directory).
NOTE: Make sure that you have specified the root directory (for example,
workspace/PlatformName_prj/export/dist) in the application root directory build property. If you do not see your subdirectory in /dist, you must rebuild the application project. 3. Run or debug the application on the target. Right-click, choose Run Process on Target or Debug Process on Target, and click Run or Debug in the lower-right of the Create, Manage, and Run Configurations screen For more information, see Part VI. Debugging and Analyzing.
5.2 Creating Projects Using Workbench or the Command Line

In Wind River Workbench, you create projects. When you use the command line, you configure them. If you use the command line while Workbench is running, the results appear in the Project Explorer just as if you had created the project using Workbench. Workbench runs the same command behind the scenes. For example:
$ ../../installDir/wrlinux-3.0/wrlinux/configure \ > --enable-board=arm_versatile_927ejs --enable-kernel=standard \ > --enable-rootfs=glibc_std
50
5 Developing Platform Projects 5.2 Creating Projects Using Workbench or the Command Line
5.2.1 Creating Platform Projects in General

The following steps provide the basic instructions needed to create a platform projects: 1. Right-click in a blank space in the Project Explorer and select New > Wind River Linux Platform Project. When you create a new Wind River Linux Platform Project, the choices displayed in the project wizard are based on your installation. 2. 3. Enter a name for the project and click Next. Depending on your installation, you have different options for selecting a build spec, a root file system, and a kernel. Select:
A board from the board menu. A file system size from the RootFS menu. Possible options are glibc_cgl for carrier grade Linux; glibc_std for standard Linux; glibc_small for a Busybox-based file system; and uclibc_small for one based on uClibc. A kernel. Possible options are cgl, ecgl, standard, small, preempt_rt (native real-time kernel preemption packages), and rtcore (Wind Rivers real-time kernel, installed optionally), depending on the choice of RootFS.
4.
You can see the configure command at the bottom of the wizard:
NOTE: You cannot edit the configure command directly, but you can use the following step to edit it under guidance from Workbench.
5.
(Optional) You can also use Workbenchs list of option-value templates to add or modify arguments to the configure command. a. Find the option-value part of the configuration dialog by clicking Advanced > >, then if needed, expand the dialog so you can see the Option part, for example:
51
b. c.
Click Add to open the Option/Value dialog box. Select options from the list and edit them as needed, substituting actual values for DIR, BUILD, and so on, and choosing between options specified in square brackets and separated by lines. For example, if you select the following option,
--with-toolchain-version=[STRING|current]
be sure to substitute a value for STRING or use current. For example:

--with-toolchain-version=current
If you select an argument containing a DIR value, click the newly-enabled Browse button can find the appropriate directory. d. Click Add to add each additional option. e. 6. When you have finished adding options, click OK.
(Optional) If you click Advanced > >, you can take the following actions (as explained in 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75):
Click Add to add one or more layers. Click Template... to add one or more templates. Click Profile... to add one or more profiles.
7.
Click Finish to ignore the source code indexer and its associated performance penalty.
Workbench executes the configure command and creates two subdirectories in your workspaceone with the project name (project) and one with the project name plus a _prj extension (project_prj).
NOTE: If you are importing an existing platform project, Workbench uses the existing projects location, and does not create a project_prj folder.
Output from the configure command appears in the Build Console and is stored, with additional information, in the project/creation.log file.
52
5 Developing Platform Projects 5.2 Creating Projects Using Workbench or the Command Line
At this point, your project_prj/export directory contains three empty subdirectories: dist, packages, and RPMS.
5.2.2 Creating an ARM Versatile Target, for Example

This section tells you how to create a project by example.
5
Example Data for You to Use
Use the following example data to create and configure a new platform project.
Table 5-1 Example Platform Project Parameters
Data
Field in GUI
Entry
project name board file system size kernel type
Project name Board RootFS Kernel
my_arm arm_versatile_926ejs glibc_std standard
This configuration provides a robust system to help you understand the procedures in creating a project, as well as in debugging it and optimizing it, as described in later chapters. Notice the following about these choices:
ARM Versatile AB-926EJS and Common PC boards are available as QEMU emulated targets. See the release notes and the Online Support site for lists of supported physical and emulated boards. The file system size is standard, meaning it is not specific to a platform or profile, and it avoids limitations found in the small size. The kernel type is common and not a soft or hard real-time kernel. It is appropriate to other examples in this guide.
Creating the By-Example Platform Project
Enter the parameters from Table 5-2 to build an ARM Versatile target.
53
1. 2.
Select New > Wind River Linux Platform Project, name your project my_arm, then click Next. Specify the parameters in the drop-down lists as described in Table 5-1.
3.
Note the following in the Configure Options dialog box:
Build spec is associated with your chosen combination of board, kernel, and root file system. The Profiling build type causes packages to be built with the -fno-omit-frame-pointer flag, but keeps the optimization level from the Production build type. (See Wind River Linux Users Guide: Building libc from Source.) If you enable Link to Development Folders, links will be created to the dist and build folders of your platform project.
4.
Click Finish.
Note that you can debug a production build and make a very small change when done, but if you start out with a debug build, you cannot convert it to a production build.
54
5 Developing Platform Projects 5.3 Building a Target File System
5.2.3 Verifying Your Project Build

Use the Project Explorer to verify that your platform project is successfully built.
Figure 5-2 Platform Project
After you have verified your project, you can build the target file system and continue development.
5.3 Building a Target File System

Your platform project must provide a file system and kernel for the target. Together, these two components comprise a platform that runs on the target. The following procedure creates a file system and a default kernel designed for your particular build requirements. To build a file system:
From the Project Explorer, select fs, right-click, and select Build Target. The Build Console reports on the build progress and status. Depending on the configuration, your build could take several minutes. The creation.log provides a build summary.
55
5.3.1 Verifying Your Build Directory

If you want to view your build in more detail: 1. 2. 3. Open a terminal. Change directories to your workspace/ProjectName_prj directory.
cd /workspace/ProjectName_prj
Use the following information to verify your data:
The export directory contains a link to the default kernel, and a compressed runtime file system (as a tar.bz2 file named according to the board, rootfs, and kernel you chose). The export directory contains a link to the default kernel (a WR3.0au_kernel file). The export/dist directory contains the file system for your target. It contains the build output from the application(s) you create.
5.3.2 Building the Example ARM Versatile File System

To build the file system for the ARM Versatile example: 1. Right-click the fs node as shown in Figure 5-2 and select Build Target. The Build Console provides output:
56
5 Developing Platform Projects 5.4 Introducing the User Space Configuration Node
2.
When the build completes, verify the following:
The runtime file system:

workspace/my_arm.prj/export/arm_versatile_926ejs-glibc_std_std-dist.tar.bz2
The default kernel image:

workspace/my_arm.prj/export/arm-versatile_926ejs-default_kernel_image_WR3.0au_std
The file system for your target:

workspace/my_arm.prj/export/dist/*
NOTE: If you are following the example and using the table data, you should see the same names as above.
5.4 Introducing the User Space Configuration Node

Platform projects provide a User Space Configuration node. The User Space Configuration node lets you handle packages as well as explore the target file system. It lets you:
Explore the target file system, view the contributing packages, and delete or add files to customize and fine-tune the file system content. Work with packages (RPMs) involving the target file system. You can add, remove, import, and build packages.
NOTE: Some Wind River literature uses the acronym USE, for User Space Editor.
To use the User Space Configuration node: 1. 2. In the Project Explorer, double-click User Space Configuration. Click the following tabs in the lower left of the resulting dialog box.
The Filesystem tab opens the Filesystem Layout dialog. See 5.5 Exploring the Target File System, p.58. This tool works with the generated RPM files from the packages, and manipulates the filesystem/changelist.xml file. It does not operate on a live target.
57
The Packages tab opens the Packages dialog. See 5.6 Using the Package Manager for RPMs, p.63. This tool manipulates the pkglist file, plus it lets you send individual RPM packages to a live target.
5.5 Exploring the Target File System

The Filesystem Layout dialog lets you manage the file system in the export/dist directory before Workbench creates the dist.tar.bz2 image.
The export/dist directory is the file system image for all configured projects. Regular targets take that image, then create the dist.tar.bz2 image as the last step in creating the file system Once created, the bz2 image can be expanded into an NFS mount directory; or used directly by QEMU, without needing to be expanded. You cannot NFS mount the export/dist directory.
NOTE: Wind River uses pseudo (replacing fakeroot) to install files into the target
root file system without having to set the UID to root. Like fakeroot, pseudo intercepts the system calls concerning root priority on file operations. It creates the regular, special files and directories but maintains a small database on what the settings would be would be if you had actually been root (these include setuid, setgid file permissions, device file class/major/minor, uid and gid ownership). This allows the build system to create a root file system tar file that has actual device files and root ownership. When you use the File System Layout tool to work with available RPMs, it reports package sizes as reported by them. Each available package is built and converted to an internal RPM file from the respective package's INSTALL_STAGE output. These prebuilt versions allow you to use the RPMs without rebuilding them. The File System Layout view works with those RPM files directly. Therefore, it represents a view of the target file system as it would be expanded into export/dist. Since it manages the file change list, it can modify what ends up in the file system without having to actually change the RPM files, so they stay pristine (untouched). Workbench expands these RPM files in export/dist, then runs fs_final script against the file change list. Finally, Workbench packages export/dist into a tarball file system image.
58
5 Developing Platform Projects 5.5 Exploring the Target File System
Figure 5-3
File System Layout Showing Size
The Filesystem Layout dialog box displays two different views of the file system of the target that you are building, depending on whether you select Flat or Packages by clicking on the View icon to the right of the Pattern Filter field:
Flat provides a list of directories and files. Packages provides a list of packages.
Filesystem Layout components provide the following functionality:
The Pattern Filter field lets you enter and apply filters to the view; for example, allowing you to specify all files with a .pl extension. The Filter icon activates the filter, letting you mark the results for deletion if necessary. The filter works on all packages; for example, you can remove unneeded Perl scripts from all packages. The View icon selects the file system or package view. The file and package list specify file, mode, size, type, owner/group, package, and location. You can change file and package attributes, such as read/write permissions and
59
ownership. Right-click to mark directories to be created in (or removed from) the file system. You can also create nodes, pipes, and devices in the generated file system.
The Estimated Filesystem line annotates the size of files or packages added or removed, along with the total size of the file system currently available. The Log tab reports on the number of packages, files, and so on.
You can use the file system tool to:
Examine meta properties of the files in the file system (see 5.5.1 Examining File Meta Properties, p.60) Add and remove files and directories to and from the file system (see 5.5.2 Adding Files and Directories to Your File System, p.61) Work with packages (see 5.5.4 Viewing Parent Packages and Removing Packages, p.62) Add devices and change ownership (see 5.5.5 Adding a Device, p.62)
NOTE: The File System Layout tool works with the generated RPM files from the packages, and manipulates the filesystem/changelist.xml file. It does not operate on the live target.
5.5.1 Examining File Meta Properties

To examine file properties: 1. 2. 3. 4. Create a platform project. Double-click the project User Space Configuration node. Click the Filesystem tab in the lower left, and observe the file system tree. To examine the meta properties of files: a. b.
Open the bin directory, and examine the first file (for example, arch). Note the following: The mode string (-rwxr-xr-x) The file size (4230) The file type (for example ELF 64-bit LSB executable for a common_pc_64 project)
60
5 Developing Platform Projects 5.5 Exploring the Target File System
The owner and group The file parent package (util-linux-2.13-0.52_WR_a)
5.5.2 Adding Files and Directories to Your File System

To add files and directories: 1. 2. 3. 4. Right-click on the directory /usr and select New > Folder. Enter the name samples. The new folder is added, with a + icon. Right-click the directory /usr/samples and select Add. Browse to the workspace directory and select a build sample project binary (for example, /tmp/workspace/mthread/common_pc-glibc_std-i686/ mthread/Debug/mthread.out). A new file appears with a + icon. The Location column contains the host file system source path.
NOTE: This step assumes that you have built an application project; specifically, for 5
this example, the mthread application.
5.5.3 Removing Files According to Pattern Filters

To use pattern filters to remove files: 1. 2. 3. 4. Open a projects User Space Configuration node. Open the Filesystem tab. Enter the string *.pl in the Pattern Filter. field. Right-click the sub-directory opt, and select Remove. Observe that a dialog pops up with the message, "If a filter is active, only the matching resources will be removed." 5. Repeat this for the usr directory. Observe that the file /usr/bin/ipf-mod.pl has a "remove" decoration. 6. Change the Pattern Filter back to *, and press Enter. Observe that only the file ipf-mod.pl in the /usr/bin directory has a "remove" decoration.
61
5.5.4 Viewing Parent Packages and Removing Packages

You can use Workbench to view parent packages and remove packages: To view parent packages: 1. 2. In the File System Layout view, click the View icon to the right of the Pattern Filter field and choose Packages. Right-click a package, then select View > Packages. The tree shows each package and its part in the target tree. To remove a package, for example, the Perl package and all Perl scripts (as they might be optional in your project): 1. 2. 3. 4. Open the tree to perl-5.8.7-1_WR_a/usr/bin. Right-click this directory, then click Remove. All files in this directory now have a - icon. Right-click the perl-5.8.7-1_WR_a/usr directory then select Remove. All resources under Perl are marked with a - icon. Set the Pattern Filter value to *.pl. The /usr directory that appears already has all contents marked with an - icon. 5. Reset Pattern Filter to blank then click Return. This restores the default tree filter.
5.5.5 Adding a Device

To add a device and change ownership: 1. 2. 3. 4. Right-click the /dev directory then select New > Device. Use the settings Char,luckyDevice,7,11. The new device appears with the added package name. Right-click the device and change the owner to lady and the group to luck. Right-click this new device and select Remove.
62
5 Developing Platform Projects 5.6 Using the Package Manager for RPMs
5.6 Using the Package Manager for RPMs

When you work with packages (RPMs), you can use the Package Manager to add, remove, import, and build them.
NOTE: There is no live RPM manager on small file systems (glibc_small and uclibc_small), so you can't do RPM queries, and you can't do RPM pushes.
Some of the Package Managers commands map directly onto the Linux rpm -option. Some affect packages on live targets. See Table 5-2Package Controls, p.65. The Packages dialog box (Figure 5-4) displays a list of installed packages in Installed Packages. If you look in the pkglist file in the project_prj directory, it displays the same list of files. In Workbench, each package is listed with its version number and the amount of space it occupies. To create a user-defined project from one of these packages, see 5.7 Creating a Project from a Package, p.73. Note that packages are displayed even if their respective RPMs are not yet available: their file size is 0; and a ? question mark overlaps the RPM icon.
63
Figure 5-4
RPMs with 0 Bytes are Placeholders for Packages
To get more information on any package, select it and look at the tabs at the bottom of the view:
The General tab provides a brief description of the package. The Advanced tab provides an editable URL to the RPM for the package, and states the architecture. The Contents tab lists the various files and directories that comprise the package. The Dependencies tab displays package interdependencies in two panels: The Requires panel lists the packages that are required by the package you have selected. The Required By panel lists the packages that require the package you have selected.
The Options tab lets you turn debugging or profiling on or off for particular packages.
64
The Targets tab presents ten buttons that let you choose build targets for the package: build, rebuild, prepatch, postpatch, patch, compile, install, custom, clean, and distclean. The Log tab primarily lists the additional RPMs that are generated by the installed packages.
5
5.6.1 Introducing the Package Controls

The Packages dialog box provides buttons and context menu entries to help you work with one or more packages. Some commands, like Remove or Install, apply to a specific package. Others, like Reload, apply to the whole list. Except for the context menu items Replace, Install, and Force Install, as described in Table 5-2, the Package Manager does not affect live targets.
Table 5-2 Package Controls
Control
Notes and Comments
Add Check Erase Force Install Import Install Open Reload Remove Replace Revert Save
Moves packages from the Installable Packages list into pkglist Confirms the integrity of the package list Removes RPM file from live target, by doing an rpm -erase Installs RPM files on live target, by doing an rpm -install -force; ignores dependencies; see 5.6.4 Using Force Install, p.67 Adds packages not in the Installable Packages list; see 5.6.6 Importing Packages, p.68 Installs RPM on live target, by doing an rpm -install; see 5.6.3 Installing Packages, p.66 Opens pkglist for editing Reloads package lists from pkglist, typically after editing it Deletes from pkglist and puts into Installable Packages; see 5.6.8 Removing Packages, p.72 Does an rpm -erase then an rpm -install on the target Restores pkglist to before view was opened Saves changes
65
NOTE: Check confirms the integrity of the package list by testing all package dependencies (as registered in the respective and collective RPM file set). The integrity cannot be confirmed entirely because of potential conflicts with the original dependency content from upstream and in the respective customer package data.
5.6.2 Viewing and Editing the pkglist File

The Package Manager manipulates the pkglist file. You can also view and edit the file directly: 1. Click the pkglist tab at the lower left of the Package Configuration screen (see Figure 5-4). The pkglist file appears in the Editor. 2. If you make any changes: a. b. c. Use File > Save to save them. Right-click within the Installable Packages list in the Package Manager. Select Reload.
5.6.3 Installing Packages

To install or reinstall packages: 1. Select one or more from the Installable Packages list and click Add. You are prompted with the package(s) to be added and the total space required. Package dependencies are also displayed. 2. Click OK. The package(s) appear in the Installed Packages list. You can add any other packages that you removed. Select File > Save to restore the package configuration to its original state. If you look in the pkglist file, all packages are now listed there. You can select multiple packages to add or remove using Ctrl.
66
5.6.4 Using Force Install

The Force Install context menu entry lets you install an RPM file without regard to any mismatch between the host and target architectures, or package dependencies that cannot be fulfilled. Because the dependencies as defined by RPM are rigid, they may not apply to your platform. For example, if you have removed the perl or python packages, their dependencies do not install. If this dependency does not concern you, you can use Force Install to ignore it. Also, you can use Force Install to get around dependencies that are not quite correct, allowing you to avoid debugging and fixing packages. To test Force Install: 1. Erase (remove) iptables-ipv6 and iptables (its dependent package): a. b. c. First, choose iptables-ipv6, because of the dependency. Select Erase from the context menu. Choose iptables and click Erase.
5
You cannot install iptables now, whether you use Install or Force Install, because iptables-ipv6 is not installed. 2. Use Force Install to install iptables.
5.6.5 Installing Multi-lib Packages

To use the Package Manager to set multi-lib RPMs in the pkglist file: 1. 2. Create a Cavium platform project. Add the following library lines to pkglist:
glibc.mips64_octeon libgcc.mips64_octeon
3. 4.
Export the sysroot (see 19.3.1 Exporting Sysroots, p.229). Now it includes these extra multi-libs. Add this sysroot to your project, using Window > Preferences > Wind River > Layers and Sysroots.
You can now build mthread; for example, for both the 32-bit n32_octeon and the 64-bit octeon build specs.
67
NOTE: If you see a pointer size warning for the octeon spec, it does not affect the
build success.
5.6.6 Importing Packages

The Import button lets you import packages that are not listed in the Installable Packages window. Use this feature to set up the imported package in the build system.
NOTE: See 10.2 Overview of the User Space Configuration Tool, p.118, for a recap of
these instructions, with pointers to specific procedures for each type of package. To import packages: 1. 1. 2. Double-click the User Space Configuration node. Click the Import button. Click Import Package. The Package Import Tool appears. 3. Click the package type or source:
FileClassic Red Hat SRPM packages in bz2, gz, tgz, zip, or src.rpm format, on your system or LAN. WgetPackages available on the web via URL. WR Linux PackageWind River Linux packages (as opposed to open source); in bz2, gz, tgz, zip, or src.rpm format. This allows you to reuse the existing porting information in the respective dist/package directory, and to continue from there.
4.
If you chose File or WR Linux Package, browse for the file or package to import. When you have selected the package, the Package Import Tool screen displays the package list, package name, and version .
5. 6. 7. 8.
Click Go. A shell window opens to display the import activity. Press Enter as needed to return to the import tool from the shell. Examine the progress window to see that it has completed satisfactorily. Click Close. The package imports.
68
You still may need to complete the package; for example, to change it for cross compilation.
5.6.7 Building Packages

Select the Targets tab for a set of buttons of build targets for the selected package. The build targets are the usual with the addition of prepatch, which allows you to prepare the package for patching (see 11. Patching Packages). The prepatch button:
Extracts any RPMs for the package that you selected. Registers kernel patches. Registers patch files. Prepares the Quilt patches directory.
Including Builds with Runtime Dependencies
Some RPMs, as mentioned earlier in the discussion of Figure 5-4, are just placeholder entries in the package manager RPM list, while the package is under development and the resulting RPM file is not yet available. These placeholder RPMs show a size of 0 bytes.
69
Figure 5-5
Placeholder RPMs with Dependencies
If you highlight one of these RPMs and click the Dependencies tab, you can see whether any dependencies have yet been defined for the RPM. (See Figure 5-5.) Because the package manager currently only looks at run-time dependencies, you might remove a package and break a build dependency, but not know it until you try to build the filesystem. If an installed RPMs icon shows a blue "?" decoration, the RPM and its metadata are unavailable until the package is built.
70
Figure 5-6
Unavailable RPMs
This means that there is no RPM file available in either the installation prebuild or in the projects local build. This happens because not all RPMs are pre-built for all architectures. Some are only built when the user builds the file system. This feature allows you to customize the pkglist file for such packages. Previously, Workbench required you to build all needed RPMs locally, even if you just wanted to remove them from your file system.
Turning Package Debugging On or Off
The debugging features available using the User Space Configuration node let you select individual packages and build them with debugging turned on or off, regardless of the rest of the pre-built packages in your project. To enable and disable package debugging: 1. 2. 3. Select the package. Click the Options tab. Check or clear Debug.
71
4.
Click Apply. This sets the build type. Any single package can have only one build type, whether it is profiling, or debug, or default (neither profiling nor debug). The default is to use the build type specified in the configure command.
5.
Verify that the the package name in the pkglist file is marked
BUILD_TYPE=debug.
NOTE: For BUILD_TYPE=profiling, see 17.3 Profiling CPU Usage with OProfile,
p.213.
5.6.8 Removing Packages

To remove packages: 1. 2. 3. Select the Dependencies tab. Select a package such as openssl from the Installed Packages list that contains entries in both the Required and Required By panels. Click Remove to remove the installed package that you have selected.
72
5 Developing Platform Projects 5.7 Creating a Project from a Package
A dialog box opens and lists all the packages to be removed (the selected package and its dependencies) and the total space used by the packages. 4. Click OK.
The removed packages now appear in the Installable Packages list. Select File > Save and view the pkglist file. The packages are removed from the list in that file.
5.7 Creating a Project from a Package

Workbenchs Configuration Management feature adds support to wrap platform project packages into top-level Workbench projects that the common configuration management plug-ins can control. To create a user-defined project from a selected package directory in the build space of a project: 1. 2. Double-click the User Space Configuration node of the platform project. Right-click the package from which you want to create the user-defined project, then choose Create Project, as shown in the following window. For this example, we have chosen the acl package.
73
3.
Accept or change the default project name, choose to create the project at an external location, and specify the directory at that location, then click Finish.
4.
Notice that Workbench creates a user-defined project, which appears in the Project Explorer as a project separate from the platform project:
74
5 Developing Platform Projects 5.8 Customizing Builds with Layers, Templates, and Profiles
The location of the extracted package sources appears inside the build directory. In the case of the acl RPM, this is: project_prj/build/acl-version/...
5.8 Customizing Builds with Layers, Templates, and Profiles

The Workbench Platform Project wizard lets you select features to customize builds, for purposes such as:
Adding templates Creating new BSPs Ensuring that custom builds can be easily repeated Completely separating custom code from the installed Wind River development environment
75
This customizing facility is implemented as templates and layers. These can sometimes be used interchangeably, but they are designed for different purposes.
Templates are suitable for small or discrete changes, and are typically incorporated into a project at the end of the configuration process. Layers are appropriate for adding new packages and making significant changes to BSP templates. Profiles are templates that typically include a kernel, a root file system and, optionally, other features. Kernel profiles are layered to build a set of increasingly specific or enhanced functionality.
5.8.1 Adding Templates

Use Workbench to add templates and customize project templates.
NOTE: You cannot apply all templates at random to platform projects, because, for example, some may have already been applied, and some cannot be applied to particular architectures such are preempt_rt.
To add templates to a platform project: 1. 2. 3. Take the initial steps in creating the project, to the point where you have named it and have reached the Configure Options screen. Click Advanced > >. Click Add (to the right of the Templates box) and click OK. Select checkboxes to specify which templates you want to add. See Table 5-3 for a description of some of the supplied templates. Table 5-3 describes some of templates in subdirectories extra and feature in installDir/wrlinux-3.0/layers/wrll-wrlinux/templates. Each template is in its own directory, with at least a pkglist.add file and a README, for example:
[user@ala-docs-rh4 wifi]$ more README Introduction ============ This layer contains the wifi feature and associated tests for Wind River Linux:Platform for Consumer Devices. Building with the wifi feature ============================== Acquire a Ralink R73-USB part such as the Asus WL-167g and add the following options to your configure command: --with-template=feature/wifi
76
Table 5-3
Some of the Supplied Templates
Template
Function
extra/wrsnmp feature/acpi feature/busybox feature/debug feature/directfbfusion feature/glibc_discrete feature_glibc_small_extras( feature/ipmi feature/prelink feature/uclibc feature/unionfs
Enables Wind River SNMP and the SNMP Agent. Incorporates and starts the logging daemon on kernel-acpi enabled boards with cgl and std file systems. Adds the busybox package and sets up the configuration file in busybox/busybox/config. Adds the usermode-agent to small file system projects. Lets multiple DirectFB applications run at the same time within a session. Replaces busybox with a set of full-featured, discrete utilities (such as in glibc_standard). Replaces busybox with a set of small, extra utilities such as in glibc_small). Adds the IPMI package and enables support for IPMI controllers. Modifies ELF shared libraries and executables, to require fewer relocations to be resolved at runtime. Replaces glibc with the uclibc C library for MIPS and ARM targets with one or more uclibc rootfs names. Lets you boot from CD-ROM, for BSPs with CD-ROMs.
Adding Custom Templates
You can place custom templates anywhere, but they typically reside outside of both the development and build environments. Custom templates are processed last, after all other templates. Because of this, they are especially useful for:
Kernel configuration file fragments that must come at the end of a kernel configuration file. Additions to file system configuration files. For example, networking configuration files in /etc/sysconfig that might have to override default values.
77
The pkglist.add and pkglist.remove files that may have to override previous package list files You also may add a one-line kernel configuration to be processed last.
For more information about creating and adding custom templates to a project, see Wind River Linux Users Guide.
5.8.2 Working with Layers

Workbench lets you create layers by customizing existing layers and exporting the result to new layers. See especially Wind River Linux Users Guide: Understanding Layers for fuller information on them: what they are, and how they are used, created, and modified. The main uses are to:
Create a new layer, where the proper layout and directory names are preset Create new template directories within this layer Duplicate template directories from the Wind River Linux installation Allow recursive duplication, to have a fully stand-alone template Minimize the layer, to remove unneeded directories Display the template include tree for a given template
Layers allow you to package, locate, and review a set of changes, revert undesirable changes, and share your changes in a coordinated method. You could, for example, add packages, remove other packages, and add and remove different kernel features with a single layer. You could then distribute your layer to a group of developers or simply make it available over the LAN. Other developers could then include or exclude your changes with a single configure command switch. You can create layers automatically from a build environment you have modified, or you can create them manually as described in the Wind River Linux Users Guide. Custom layers are processed differently from custom templates. During processing, the system looks first to the custom layer in an attempt to find the template, package, or file it is looking for. Thus, custom layers can be used to add templates, packages, or files, or to override the templates, packages, or files within the development environment. For instance:
A new package added to a custom layer is added to the build system.
78
A template within a custom layer is used instead of the identically named standard template with the development environment.
Although custom layers can be placed anywhere, they typically reside outside of both the development and build environments.
Adding Layers
Use the Platform Project wizard to add multiple layers to a project. These layers can add board and template information that automatically updates the wizard. In the following example (at Step 4), the wizard uses the path for the Real-Time Core layer.
Table 5-4 Basic Provided Layers
Layer
Path from installDir/wrlinux-3.0
Notes
Linux Kernel Toolchain Real Time Core
/layers/wr11-wrlinux /layers/wr11-linux-2.6.27 /layers/wr11-toolchain-4.3.78 /layers/wr11-rtcore-5.2
Base layer and source tree Default layer Default toolchain Optional layer
Use the example data in the following table to create and configure a platform and add and remove layers.
Table 5-5 Example Parameters
Data
Field in GUI
Entry
board file system size kernel type project name
Board RootFS Kernel Project name
common_pc glibc_std standard rtcore_test
To add layers to a platform project: 1. Take the initial steps in creating the project, to the point where you have named it and have reached the Configure Options screen: follow up to Step 5 in
79
5.2 Creating Projects Using Workbench or the Command Line, p.50, but use the parameters from Table 5-5. 2. 3. 4. Click Advanced > >. Click Add to the right of the Layers box. Browse to the directory containing the rtcore layer, as shown in Table 5-4, to include it in the project. Workbench scans the new layer while you wait. The Workbench installation directory contains some layers, such as the kernel implementation in the layer wrlinux-3.0/layers/wrll-linux-2.6.27. However, the layers you choose to add to the project come from other directories. 5. Verify that your changes are working properly: a. b. c. 6. Observe that the kernel select field automatically changes to rtcore. Click Remove to delete this layer. Notice that Workbench rescans the environment that no longer contains the layer. The kernel select field automatically reverts to standard.
Click OK.
Reloading Changes
The Reload button in the layer list refreshes the list after you add, remove, or reorder list items. Without the Reload facility, you would have to wait for Workbench to reorder changes in the list every time you made a single change, rather than wait until you are done changing the list, then re-ordering it all act once. The Reload button only enables when you have made changes. When it is enabled, Workbench disables the Finish button.
80
Figure 5-7
Reload Button to Speed Up Layer List Changes
The Configure Options dialog box displays a message that reminds you to reload.
5.8.3 Exporting Layers

See 20. Delivering Layers for directions on how to modify the export layers.
81
5.8.4 Specifying Profiles

The Configure Options screens Profile... button lets you select a profile from a list, typically to auto-configure the Board, RootFS, and Kernel selections, which are then grayed out. A profile might be something like automotive omap 386, for example. See the following figure.
Click Template... or Profile.. to select one or more templates or profiles to add to the platform project.
Figure 5-8
Template and Profile Features in Platform Project Wizard
Note that you can select <no_kernel >, <no_rootfs >, and/or <no_board >. This lets you create a project with only a rootfs or only a kernel, or a kernel and/or file system, but no board, as has been possible from the command line. For <no_board >, see Wind River Linux Users Guide: Identifying Explicit and Implicit Templates. (Figure 5-8 shows that <no_kernel > has been selected.)
82
6
Configuring Platform Kernels
6.1 Introduction 83 6.2 Configuring Wind River Linux Platform Kernels 84 6.3 Prepopulating LKM Projects 87 6.4 Adding Kernel Modules to the Platform 87
6.1 Introduction
This chapter explains the following topics:
Configuring platform kernels Adding kernel modules to a platform Working with packages, build targets, and target file systems Handling RPMs Managing patches Automating target deployment.
83
Figure 6-1
Configuring Kernels: The Development Stage of the Product Life Cycle
Kernel Requirements
Kernel Modules
Setup
Relevant Tools
Dependencies Filters Kconfig POSIX Signals QEMU Wind River Debugger
Develop
Diagnose
Kernel Deliverables
Kernel Kernel Modules Patches
Other Tools
Build Target Bus Options (CPU)
Optimize
Figure 6-1 shows that configuring Wind River Linux platform kernels involves working with kernel modules, build targets, and options such as bus parameters. In addition, you can add build targets suitable for use by analysis tools. Note that this figure does not address the product life cycle aspects of kernel deployment, diagnosis, optimization, and delivery. For those, see:
Part V. Deploying to Your Board 16. Debugging Kernel Space 12.2 Working with Kernel Modules on the Target, p.149 19.5 Providing Kernels and Modules for Platforms, p.232
6.2 Configuring Wind River Linux Platform Kernels

When you build a kernel in a Wind River Linux Platform project, you can view and modify the current kernel configuration with Workbench. This section summarizes
84
6 Configuring Platform Kernels 6.2 Configuring Wind River Linux Platform Kernels
the major uses of the kernel configuration tools. For detailed reference information on the Kernel Configuration node, see the Wind River Workbench User Interface Reference: Kernel Configuration Editor. For Wind River Linux Platform projects, Workbench provides a Kernel Configuration node that presents the standard Linux configuration choices in a GUI that shows inter-dependencies and provides additional information on each configuration option. If you prefer, you can use the menuconfig or xconfig interface, either from the command line or by clicking the menuconfig or xconfig nodes in the platform project.
6.2.1 Kernel Configuration Node

When you double-click Kernel Configuration in the project folder, a tab with the name of your project opens in the center of the Workbench perspective, displaying a configurator with two tabs: Overview and Configuration.
Overview Tab
The Overview tab displays the project configuration. This corresponds to the choices you made when creating a new Wind River Linux Platform project. The command-line arguments supplied to the configure command to create the initial configuration are shown at the bottom of the view.
Configuration Tab
The Configuration tab consists of two panels. The top panel presents the items for configuration that may be familiar to you from using menuconfig or xconfig to configure kernels. The lower panel consists of three tabs, Help, Dependencies, and Kconfig, that provide additional information on the items you select in the top panel.
NOTE: By moving your cursor around inside the Kernel Configuration view, you can find the drag points to enlarge view sections.
When you select an item in the top panel, help appears in the Help tab. Select the Dependencies tab to see any items your selected item depends on, or items that depend on it. Double-click any item dependency to move to it in the top panel. Select the Kconfig tab to see the definition of the item and the file system location where it is defined. If you click the file path link shown in blue, Workbench adds the file to the Edit view and you are placed at the location of the item definition.
85
Create a new kernel configuration by modifying the settings of menu items in the top panel. The current configuration status of items is indicated by the icons associated with them. (For a detailed description of the icons in the menu, see the second table, which is for Linux, in Wind River Workbench User Interface Reference: Kernel Configuration Quick Reference.) The Configuration view does not show all items, because some of them are disabled due to dependency conditions. To view all items, including disabled items, right-click in the Configuration view and select Filters > Show All. The disabled items are shown as grayed-out. You can still select them and view the Dependencies tab to see the reasons they are disabled.
Modifying the Configuration
For example, if you want your kernel to include support for PCMCIA or CardBus cards, find Bus options in the scroll-down list, click the arrow to expand it, and then click the arrow next to PCCard. This displays the entry for PCCard support. This is a tri-state configuration item which can be set to n for not included, m for included as module, or y for built-in. Double-click the item to change the setting. See the Help tab for details on what the settings mean for each particular item. To find options, use Edit > Find. For example, to find options concerned with USB support, select Edit > Find and enter the string USB. To generate the new kernel, right-click reconfig in the project folder and select Build Target. To save the configuration file, select File > Save. If you make any changes to the kernel using the Kernel Configurator (or menuconfig/xconfig), you need to rebuild the kernel to have the changes applied. To rebuild the kernel in Workbench, right-click the build target kernel_rebuild, and selecting Build Target. (On the command line you would use the make -C build linux.rebuild command.)
NOTE: When a project is configured, a symlink to a default kernel is placed in the export directory. You can use this kernel immediately after you build a file system. If, however, you configured the project with layers or templates that modify the kernel (for example by adding the analysis layer) you should rebuild the kernel since the default kernel image will be missing this content,
86
6 Configuring Platform Kernels 6.3 Prepopulating LKM Projects
6.3 Prepopulating LKM Projects

When you create a new Linux Kernel Module project, you can check Create template source to create a C source file, moduledebug.c, containing template code for your module.
Figure 6-2 Adding Default (Template) Sources to Linux Kernel Module Project
This template code file gives you a head start in creating your own source. It contains a properly formatted and buildable kernel module. It includes a working init handler, a simple kernel thread routine started by init, and a working exit handler. You can use this code to as a basis to writing your own custom kernel module. Note that the sample kernel module testmod provides additional features, for example using a kernel timer, and providing parameter access and control from user space.
NOTE: You will not see this option when you import a command-line LKM project or one of the example projects.
6.4 Adding Kernel Modules to the Platform

You can create a kernel module as a subproject of a kernel project. The kernel module subproject inherits the kernel build properties. Workbench comes with a sample kernel module project that you can add to a kernel project. See 16.6 Debugging User-Supplied Kernel Modules, p.198.
87
6.4.1 Creating a Custom Kernel Module

You can configure the build system for a custom kernel module created from your source files once you have created a platform project. In this example, you directly attach the new module to an existing platform project. Alternatively, you could skip that step and enter the KERNEL, ARCH, and CROSS_COMPILE values directly for an external kernel, or even leave these fields blank and attach or set them at a later date. When you build this custom kernel module, note that the generated Makefile automatically includes the module's source files, and the module name is set from the project name. 1. If you want to assign a superproject to this kernel module project, highlight the superproject in the Project Explorer, otherwise put the cursor in a blank area of the Project Explorer.
NOTE: For more about super and sub projects, see Wind River Workbench Users
Guide: Structuring Projects. 2. 3. 4. Right-click and select New > Wind River Linux Kernel Module Project. Assign a name to your kernel module project and click Next. If you have highlighted a superproject, select it as a superproject for this kernel module and click Next. The following screenshot shows a project being assigned the superproject role.
5.
Note that the Linux kernel information at the bottom of the dialog is already populated because the values have been imported from the platform superproject. Click Finish.
6.
88
6 Configuring Platform Kernels 6.4 Adding Kernel Modules to the Platform
The kernel module project now appears as subproject of the platform superproject in the Project Explorer. 7. Import source files: a. b. c. Right-click the new kernel module project and select Import > General > File System. Browse to installDir/wrlinux-3.0/samples/moduledebug_2_6. Click OK.
6
d. Select the files bpHere.c and moduledebug.c. You could of course import your own source files. The files in this example demonstrate kernel module builds and testing: moduledebug.c provides the module init and exit points, and bpHere.c sets a breakpoint. e. Click Finish.
You can now build the module, deploy it, and test it.
6.4.2 Moving Kernel Module Projects

To move the kernel module project from one platform project to another, use the following procedure: 1. 2. 3. Right-click the kernel module project and select Build Options > Clean Project. Right-click the platform project that currently contains the kernel module subproject, then select Properties. Click Project References, deselect the kernel module project, and click OK. The kernel module project reappears in the Project Explorer at the project level. 4. 5. Right-click the platform project that you want to contain the kernel module subproject and select Properties. Click Project References, select the kernel module project, and click OK. The kernel module project appears as a subproject of the new platform project. 6. Right-click the kernel module project and select Build Clean.
89
90
7
Feature Templates and Profiles
7.1 Introduction 91 7.2 Feature Templates 92 7.3 Profile Basics 93 7.4 Templates and Profiles in the Platform Project Wizard 94
7.1 Introduction
You can use the Project Wizard to add templates or profiles. See 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75). Notice that templates are named depending on their type:
Kernel-specific templates prefix their names with the word KERNEL, as in KERNEL:squashfs. File-system templates use ROOTFS as a prefix, for example, ROOTFS:Debug, where Debug is the name of a profile.
NOTE: Workbench automatically adds this template if you select a small filesystem when youre in the Project Wizard.
See 20.2 Example: Preparing Layers that Modify Kernels, p.234.
91
And see also 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75, for a general discussion. For supplied templates and features, see Table 5-3, Some of the Supplied Templates, particularly the various feature templates.
7.2 Feature Templates

Most changes introduced by a layer are contained in templates. With feature templates, you can enable them explicitly, to fine-tune the platform by selectively including features, while keeping the layer set the same. Another use for feature templates is aggregation. It is possible to create a master template that would include other templates. Imagine that you have a cell phone platform, and you would like to be able to configure the system for different phones, ranging from a base phone to a full-fledged feature phone. For this, we could create different feature templates, each one pulling in a different set of sub-features. As an example, consider a layer named ft that contains multiple feature templates such as feature/camera, feature/edge, and feature/gprs. The feature templates feature/basicphone and feature/featurephone each include a different set of featuressee the corresponding include files. The following example is an advanced feature template layout, where one layer and one code base can be expressed as many different products:
template/feature basicphone pkglist.add zlib include feature/gprs feature/led_display featurephone pkglist.add zlib include feature/gprs feature/lcd_display feature/camera
92
7 Feature Templates and Profiles 7.3 Profile Basics
smartphone pkglist.add zlib tslib include feature/gprs feature/touchdisplay feature/camera
7.3 Profile Basics

You can create profiles, which provide components in a hierarchical fashion.
7.3.1 Making Your Own Profile

For building projects from the command line, you can use a build-system option --with-profile= that will configure a project with a specific set of component packages. You can create your own profile just like you create a layer. In fact, a profile may just be a "special" layer. Your created profile is composed of compatible components. A component is a set of packages that provides a device function for example, a sound component might include all packages appropriate for sound, the graphics component provides graphics packages, and so on.
7.3.2 Profile Hierarchy
Packagethe lowest common denominator Componenta group of packages delivering a named functionality Profilea group of components delivering a vertical solution, for example, a smart phone, a feature phone, or an MP3 player
93
7.3.3 Differences between Profiles and Platforms

A profile is more flexible than a platform, since it is constructed from components that can be applied more easily across a variety of hardware. Currently, Wind River platforms are very close to the hardware. Profiles provide a flexible way to create new device types, using client-server middleware (for example).
NOTE: While there can be many templates, there can be only one profile in a projects configure command.
7.4 Templates and Profiles in the Platform Project Wizard

When you make your templates and profiles available for yourself or other developers using the Platform Project wizard, they will be able to select and manage multiple, high-level profiles. See Part VII. Delivering Your Product. They can click Templates or Profiles to bring up the list of templates or currently defined high-level profiles. See 5.8.4 Specifying Profiles, p.82.
94
PA R T II I
Developing Applications
8 9 10 If Youre an Application Developer ................... 97 Sysroots, Build Specs, and Properties ............ 111 Importing Packages ........................................... 117
95
96
8
If Youre an Application Developer
8.1 Introduction 97 8.2 Creating Applications 98 8.3 Running Applications 106 8.4 Changing Build Specs and Properties 109
8.1 Introduction
This chapter tells you how to:
Create or configure, build, and run applications. Change application build properties such as build specs, libraries, header files, build output location, the actual build command, and so on.
The application development part of the life cycle primarily concentrates on the Develop and Diagnose stages, using tools shown in the middle column. The main deliverables (see Figure 8-1) include application binaries, other files, unit tests, and documentation.
97
Figure 8-1
The Application Development Stage of the Product Life Cycle
Application Requirements
Application Source Docs Sysroots
Setup
Relevant Tools
Launch Configurations Packages, Files
Develop
usermode-agent profiling, memory analysis System Viewer
Diagnose
Application Deliverables
Binaries Other Files Packages Patches Unit Tests
Other Tools
Edit, Script, Make Coverage Package Manager
Optimize
Much of application development in terms of editing and compiling source is described in the Wind River Workbench Users Guide. Also, note that this current chapter does not explain how to deploy, debug, and test an application. For that information, see Part VI. Debugging and Analyzing, as well as related chapters in the Wind River Workbench Users Guide.
8.2 Creating Applications

This chapter is the first chance in this book to use Workbench to create a project. From this point on, we assume that you have worked through the tutorial sections (especially the ball tutorial) of the Wind River Workbench Users Guide, and that you understand how to use the various Workbench views and perspectives. To create applications, you should understand:
Your development environment, as explained in this section. One or more of the simple examples presented in this section.
98
8 If Youre an Application Developer 8.2 Creating Applications
8.2.1 Understanding Your Development Environment

If you are an application developer, you likely have access only to the Application Developer package, which is available for Linux, Solaris, and Windows host systems, as listed in the release notes. It contains a subset of Wind River Linux (target libraries, Wind River host utilities, and Wind River GNU GCC 4.x toolchain), plus Wind River Workbench, with a debugging and analysis tools subset. Likely, platform and kernel developers set up your development environment with the tools, kernel, and file system you need to begin work. Typically, platform developers create a platform project and then produce a sysroot for you. The sysroot provides the target runtime libraries and header files to use on your development host. Because the sysroot duplicates application dependencies of the eventual runtime environment, you can deploy applications as you develop them. Sysroots also provide board-specific, pre-built target libraries to link against when building a package from source. This lets you do builds on the host using the sysroot as a stand-in for the target file system. Platform developers can incorporate developed applications in a project by placing the application under prjbuildDir/filesystem/fs/ or by using the file system layout feature, and then rebuilding the file system. For more information, see 13. Assembling File Systems and Kernels, as well as the Wind River Linux Users Guide: Changing Basic Linux Configuration Files and the Wind River Linux Users Guide: File System Layout Configuration. Depending on your Wind River Linux installation, the directory installDir/wrlinux-version/layers/wrll-toolchain-version contains appropriate tools for your licensed architecture, including the C language cross-compiler. When you built the ball example (see the Wind River Workbench Users Guide), you used cross-development tools to generate a build target for your target architecture.
7
99
8.2.2 Creating Applications in General

You can create applications before you have a platform project to support them, or even an actual target to run them on. The following sections briefly explain how to create native-mode applications that run on your development host.
8.2.3 By Example: Building hello_world

This example produces a native application that is ready to run.
Table 8-1 Native Application Project Parameters
Required Data
Notes
Installation of samples
This was done when you installed Workbench. Confirm that you have directory installDir/wrlinux-3.0/samples
Why we chose this example:
It needs only a few GUI actions. It is documented more thoroughly in the Wind River Workbench Users Guide: Creating Native Application Projects.
To build hello_world: 1. 2. 3. Right-click anywhere in the Project Explorer (at the upper left of the Workbench perspective) and select New > Example. In the Select a Wizard page, choose Native Sample Project and click Next. In the Sample Project Template page, select The Hello World Demonstration Program and click Finish. Workbench creates the hello_world project. The sample project contains all the necessary files to build the program. 4. Right-click the hello_world_Native project folder and select Build Project. Workbench builds the executable, and the Build Console at the bottom of the Workbench perspective shows the build output. 5. Expand the hello_world_Native project folder in the Project Explorer, and expand the Binaries node to see the executable hello_world_Native. This is the build result.
100
Your compiled hello_world application is now ready to run on your target. Because native host applications do not need a target to be configured, you can run this right now, as described in 8.3.1 By Example: Running hello_world, a Native Application, p.106.
8.2.4 By Example: Building Penguin

Penguin, a more complex example program, is a C++ version of the ball program described in the Wind River Workbench Users Guide.
Table 8-2 Penguin Application Project Parameters
Required Data
Notes
Installation of samples
This was done when you installed Workbench. Confirm that you have directory installDir/wrlinux-3.0/samples
Why we chose this example:
It is not documented in the Wind River Workbench Users Guide. It is a more complex project than ball and is used as an example later in this guide. Unlike the hello_world native application, it requires an emulated or actual hardware target.
101
To build Penguin: 1. 2. 3. 4. 5. Right-click anywhere in the Project Explorer (at the upper left of the Workbench perspective) and select New > Example. In the Select a Wizard page, choose Wind River Linux Application Sample Project and click Next. In the Sample Project Template page, select The Penguin Demonstration Program, and click Finish. Workbench creates the Penguin application project. The sample project contains all the necessary files to build the program. Right-click the penguin project folder and select Build Project. Workbench builds the executable, and the Build Console at the bottom of the Workbench perspective shows the build output. 6. Expand the penguin project folder in the Project Explorer, and expand the Binaries node to see the executable penguin.out. This is the build result.
The compiled Penguin application is now ready to run on your target. For information on running the application, see 8.3.2 Running Non-Native Mode Applications, p.108.
102
8.2.5 By Example: Importing Source Code for Penguin

You can use this example to understand how to import source for your own application project.
Table 8-3 Required Source Files to Import
Required Data
Notes
Penguin source directory
This was created when you installed Workbench. Confirm that you have the directory installDir/wrlinux-3.0/samples/penguin/source.
The following table shows the GUI entries for this example.
Table 8-4 Basic Application Data for Importing Penguin Source
Data
Field in GUI
Entry
Project name
Project name
MyPenguin
To import source files for an application: 1. 2. 3. 4. 5. 6. Right-click in the Project Explorer, choose New > Wind River Linux Application Project, and enter the project name. Click Finish. Right-click the MyPenguin project and choose Import. Choose General > File System and click Next. Next to the From directory field, click Browse. In the Import from directory dialog box that appears, find the source directory for the files to be imported:
103
7.
In the Import dialog, Workbench warns you that no files have been selected yet, although you have chosen the directory:
8.
Select the checkbox either for the entire directory or for each individual file that you want to import:
104
9. 10. 11.
Optionally, you can specify the folder to contain the imports, and the options to overwrite, create complete folder structure, or create selected folders only. Click Finish. Workbench imports the files into your application project:
105
12. 13. 14.
Right-click the project name, select Build Project, and click Generate Includes. Click Next, Next, and Finish. Check the Build Console and make changes to your project until it builds correctly. In the example below, the build fails because rand has not been defined:
8.3 Running Applications

You may run native mode applications directly on your development host, as described in 8.3.1 By Example: Running hello_world, a Native Application, p.106. For non-native applications, you need more, as described in 8.3.2 Running Non-Native Mode Applications, p.108.
8.3.1 By Example: Running hello_world, a Native Application

Use this table to ensure that you have built the required application for this section:
Table 8-5 Requirements for Running hello_world
Required Data
Notes
Configure and build hello_world See 8.2.3 By Example: Building hello_world, p.100
106
8 If Youre an Application Developer 8.3 Running Applications
To run a native application such as hello_world, use the following steps: 1. 2. Right-click the project and choose Run Linux Application Process. Click Run to accept the configuration launch defaults:
107
3.
Notice that usermode-agent starts up:
4.
Look for the output in the Console view:
8.3.2 Running Non-Native Mode Applications

If you are developing applications for the host on which you are running Workbench, you are not doing cross-compilation for other architectures. Therefore you are doing native mode applications. If you are developing applications for different architectures, you are doing non-native mode applications. Unlike the hello_world native application example, your non-native applications require an emulated or actual target, plus a defined connection to it. For more information about making this connection, and using your application on the connected target, see 14. Deploying to Targets. You may also find it useful to read Wind River Workbench Users Guide: The Registry.
108
8 If Youre an Application Developer 8.4 Changing Build Specs and Properties
8.4 Changing Build Specs and Properties

The directory installDir/wrlinux-3.0/sysroots contains several pre-built sysroots that are available as build specs out of the box. To change build properties such as target specifications, build output location, and the actual build command, use the following steps: 1. 2. 3.
Table 8-6
Right-click your application project and choose Properties. Click Build Properties. Use the appropriate tab, depending on which properties you want to change:
7
Build Properties Tabs
Build Support and Specs Build Tools Build Macros Build Paths Libraries
Use IDE-generated makefiles; specify build command and build specs Specify build tool (assembler, compiler, linker, librarian); output generation; build-spec-specific settings and so on Build macro definitions; spec-specific settings Redirection root directory, build spec settings, include paths Libraries per specified active build spec
109
110
9
Sysroots, Build Specs, and Properties
9.1 Introduction 111 9.2 Importing Sysroots 112 9.3 Importing Build Specs 113 9.4 Changing Build Properties 114
9.1 Introduction
A board support package (BSP) is a collection of files that allow the creation and use of Linux kernels and file systems on a particular target hardware system, such as a reference board, or possibly a custom piece of hardware. Configuration files are central to a BSP because they integrate it with the Wind River Linux build system and environment, so you can use the standard build system and packages. A BSP may also contain drivers or other code. A build spec is a particular set of build settings appropriate for a specific target board used by Workbench application projects. The BSP determines the build specs that are initially available for a project. Sysroots, which can source one or more build specs for Workbench application projects, provide the libraries, header files, and other files and directories that are essential to the infrastructure of your projects. Sysroots provide the capability of cross building.
111
9.2 Importing Sysroots

Wind River Linux supports sysroots, which include support for building applications with libraries. Sysroots simplify cross-compilation by creating a standard target file system structure on the host system. The target libraries and headers are copied to the sysroot, and not necessarily copied to the remote file system on the target. Builds are done on the host against the sysroot as representative of the target file system. The new sysroot system correctly matches the package list during the build-configure-tailor life cycle. Sysroots capture target libraries into relocatable directories. The Wind River Linux build spec provider script converts these libraries into build specs, for use by application projects. On one hand, they are tuned exactly to a configured project, but on the other hand, they require extra work when you start building applications out of the box. A platform developer can create a custom sysroot in a configured project. See 19.3 Exporting and Copying Sysroots, p.229. The sysroots that came with your installation are automatically available in Workbench, in installDir/wrlinux-3.0/sysroots. You may put others in directories such as ~/myroots, and specify the directory pathnames in Workbench. To add sysroots, you must specify their directory: 1. 2. 3. 4. Choose Window > Preferences > Wind River > Layers and Sysroots. Click Add to the right of the Sysroots panel. Browse to the location of your sysroots. Click OK.
NOTE: Build specs are dynamically derived from the installed board templates or the extended templates from layers. It is not necessary to install additional sysroots for application development.
For multi-lib-specific information, see 5.6.5 Installing Multi-lib Packages, p.67.
112
9 Sysroots, Build Specs, and Properties 9.3 Importing Build Specs
9.3 Importing Build Specs

First, you need an application project; for example, Penguin. To add new build specs without impacting any existing build spec information: 1. 2. 3. 4. Right-click the application project and select Properties > Build Properties. In the Build Support and Specs tab, click Import. In the Import wizard, select Import build settings, select Default settings in the list, and, below the list, select Import specific build specs. Click Next. The next screen shows the four default build specs provided in the Wind River Linux Platforms installation, along with any new sysroots that are available for import.
8
The sysroots that you see are available to you either because you or a platform developer exported them earlier (see 19.3 Exporting and Copying Sysroots, p.229), or because you have added them as described above. 5. Select the desired spec and click Finish.
113
9.4 Changing Build Properties

Every project has a set of build properties, which you can use to change target specifications, relocate build output, see and modify the actual build command line, and more. The build properties for all project types are provided by the platform during project creation. Build property preferences are therefore not available for customer-specific Linux application projects.
9.4.1 Configuring Project Build Properties In General

To configure project properties: 1. 2. 3. Right-click the project name; for example, penguin (Wind River Linux Platform 3.0 Application). Select Properties. Click Build Properties in the left of the Build Properties dialog. If there is no Build Properties choice listed between the entries Resource and Builders, you have not specified the build specs for your project. See 9.3 Importing Build Specs, p.113. 4. Set the active build spec, other build support items such as debug mode and managed build, and any other appropriate settings under the various other tabs such as Build Support and Specs, Build Tools, Build Macros, Build Paths, and Libraries. For example, use the Libraries tab to specify library search paths and filenames, such as L path; and, for libraries, l lib. For the current project example, you should not need to specify any changes, but they are available for reference. Macro values change according to the active build spec, and you would not typically modify them. LAYER, in the Build spec specific settings portion of the Build Macros tab, is the directory from which the sysroot was defined, for example installDir/wrlinux-3.0:
114
9 Sysroots, Build Specs, and Properties 9.4 Changing Build Properties
5.
Click OK to save any modified build properties.
Workbench displays the build specs name on the Build Targets node, shown below as arm_versatile_926ejs-glibc-std-armv5tel_vfp-wrlinux_2_0.
115
9.4.2 By Example: Putting Penguin on a Different Target

You can assign a different target for applications such as penguin.
Table 9-1 What You Need for This Example
Required Data
Notes
Creation of penguin application project To re-assign a target: 1. 2. 3. 4. 5. Right-click penguin.
Source is in installDir/wrlinux-3.0/samples
Choose Properties > Build Properties > Build Macros. Click the down arrow for Active build spec. Choose common_pc-glibc_std-i686-wrlinux_2_0 and click OK. Verify that you have changed the target for penguin:
116
10
Importing Packages
10.1 Introduction 117 10.2 Overview of the User Space Configuration Tool 118 10.3 Importing Classic Packages from the Installation 119 10.4 Importing Source RPM Packages from the Web 121 10.5 Importing Wind River Linux Packages 123
10.1 Introduction
Wind River Linux provides an import package script that lets you:
Import a source package archive to the project packages directory. Create a project dist directory and wrapper Makefile for the package. Create a placeholder RPM file in the Workbench Package Manager. Create a preliminary pkg-wr-integration.patch file, and set it as the top-most patch file for Quilt in the patches.list file. Insert a %configure_target directive after %build and %install section heads.
NOTE: The import package script is also accessible from the command line.
117
Once you have imported a package, you can capture the new package and its controlling dist Makefile to a layer, using the export-layer command. See 20.2.2 Tailoring and Exporting a Layer, p.237, and 20.3.1 Making a Layer Available, p.238.
10.2 Overview of the User Space Configuration Tool

Workbench provides a User Space Configuration tool that lets you import or install different types of Linux source packages classic, SRPMs, or Wind River Linux. When you open a platform project, you can expand its contents to display the User Space Configuration tool icon for your project. Double-click the icon to display the tool and its available options. Then, to import packages: 1. 2. Click Import to install packages that are not listed in the Installable Packages list and to set up the imported package in the build system. When the Package Import tool (ImportPackages.tcl) opens, click a package type File, Wget, or WR Linux Package, as described more fully in, respectively:
10.3 Importing Classic Packages from the Installation, p.119 10.4 Importing Source RPM Packages from the Web, p.121 10.5 Importing Wind River Linux Packages, p.123
3. 4. 5. 6.
Browse for and select the package you want to import to display the package, the package list, package name, and version in the Package Import Tool. Click Go to open a shell window and display the script activity. Press Enter until you exit the shell. When the import tool completes satisfactorily, click Close.
Simply importing a package does not necessarily mean the package is usable. For example, you might need to configure the package for cross-compilation.
118
10 Importing Packages 10.3 Importing Classic Packages from the Installation
10.3 Importing Classic Packages from the Installation

You can import a classic packed tar file and reuse its patches, which already exist in the installation.
NOTE: For an explanation and definition of classic packages, see 11.1.2 Recognizing Classic Tarball Packages, p.129.
To import a classic package: 1. 2. 3. 4. 5. 6. 7. 8. 9. Open the User Space Configuration tool. From the Installable Package list, click Import. The Package Import tool opens. Click Import Package. Select File and then click Browse to locate the archive for this example:
installDir/wrlinux-3.0/layers/wrll-wrlinux/packages/package.tar.gz
Click Go to open a shell window and display the script activity. Press Enter until you exit the shell. When the import tool completes satisfactorily, click Close to allow other Workbench actions, such as builds or Quilt actions. From Installed Packages, select the new entry and then click the Targets tab. Click patch. This step updates the controlling dist Makefile to adapt it to the wrlinux build environment. The patch target rule unpacks the new package and adds the default patches.
10.
Link or refresh the build directory link by performing one of the following actions:
If the build directory is already present, right-click it and then select Refresh to see the updated package directory contents. If it is not present, right-click the project and then select Add Links to Development Folders.
119
10.3.1 Modifying the Makefile

You can modify the dist Makefile as needed to make it cross compile: 1. Browse to and double-click the project Makefile to open dist/package/Makefile. This file has been prepared with default values and may require extra work to set up the package settings to cross compile.
NOTE: At this point you edit the package and its dist Makefile so that it builds;
however, you can also re-use fixes that have already been created. 2. Return to the User Space Configuration, select the package entry, and click Build in the Targets tab. The build completes and generates its RPM files. If the build fails, repeat the steps of editing the dist Makefile file and building it until your build succeeds. For more examples and instructions for making packages cross compile, see the Wind River Linux Users Guide. 3. Modify the package as desired. Use Quilt > Add New File to Top Path to add any files you are going to modify, so that the changes can be captured back into patch files. (Optional) To start a new patch file (rather than use the default top-most path file) select Quilt > New Patch. Browse to the patch file to examine its contents (and the files it affects): open the virtual node patches tree and/or find build/package/patches.
4. 5.
10.3.2 Reusing Fixes for the Package

NOTE: If you are continuing from the previous example, click distclean and then delete the project/dist/package directory.
To reuse fixes already prepared for this package in the wrlinux installation: 1. 2. 3. 4. Open the User Space Configuration tool. Select the new package and click distclean in the Target tab. Right-click the project and select Open Workbench development shell. In the development shell, enter the following commands:
$ cd ../project_prj $ rm -rf dist/package*
120
10 Importing Packages 10.4 Importing Source RPM Packages from the Web
10.4 Importing Source RPM Packages from the Web

Source RPM (SRPM) packages are archives packages that not only contain the binary content found in standard RPMs, but also contain source and spec build rules. To import source packages: 1. 2. Open the User Space Configuration tool. From the Installable Package list, click Import. The Package Import tool opens. 3. 4. Click Import Package. Select Wget and then enter the URL of an SRPM package, for example: http://download.fedora.redhat.com/pub/fedora/linux/releases/7/Fedora/sou rce/SRPMS/dos2unix-3.1-28.fc7.src.rpm. Click Go to open a shell window and display the script activity. Press Enter until you exit the shell. When the import tool completes satisfactorily, click Close to allow other Workbench actions, such as builds or Quilt actions.
9
5. 6. 7.
10.4.1 Updating the Package Spec File

Because this is an SRPM, you must update the spec file and create a patch file for it, as explained in the following steps. For more details, see 11.4.1 Manually Patching SRPM Spec Files, p.139. 1. 2. Select the new package and then click patch in the Targets tab. The patch target rule unpacks the new package and adds the default patches. Add the Build directory link or refresh if necessary: If the build directory is not displayed, right-click the project and select Add Links to Development Folders. If it is displayed, right-click it and select Refresh to view the updated package directory contents. 3. Open the package build directory and double-click the spec file to build it. For example:
build/dos2unix-3.1-28.fc7/dos2unix.spec
121
NOTE: The %configure_target RPM macro is added after every %build and %install section header. There is one %build and one %install used in this example.
4. 5.
Right-click the spec file, select Add File to Top Patch, and click OK to accept the change. Use the Workbench text editor to make the following change to the dos2unix.spec file: a. b. c. Immediately following every %build and %install section header, add the %configure_target RPM macro. (Optional) Add a change indicator (such as -WR), to the Release line. (Optional) Add an entry to changelog.
6. 7.
Right-click the spec file, select Quilt > Refresh Top Patch. Click OK. The modified dos2unix-wr-integration.patch file is located in the build/dos2unix-3.1-28.fc7/patches directory.
NOTE: For more information about patching, see 11. Patching Packages.
10.4.2 Building New Packages

1. 2. Open the User Space Configuration tool. Select the dos2unix entry and click Build in the Targets tab. The package and its RPM files build. 3. (Optional) If you made any changes to dos2unix.spec, copy the updated patch file project_prj/build/pkg-version/patches/dos2unix-wr-integration.patch to dist/dos2unix/patches. That way, you can perform a distclean and also keep your changes persistent. Copy the new patch file to dist/dos2unix/patches and update the patches.list file.
4.
NOTE: You can also use this procedure to import other packages.
122
10 Importing Packages 10.5 Importing Wind River Linux Packages
10.5 Importing Wind River Linux Packages

Workbench lets you import Wind River Linux packages into any Workbench platform project. You can customize a package distributed with Wind River Linux and re-use robust cross-compilation and patch files. The import process sets up the package in the local project, integrates it with the local build environment, and copies in the existing patches and dist Makefile. To import a Wind River Linux package: 1. 2. 3. 4. Open the User Space Configuration tool. From the Installable Package list, click Import. The Package Import tool opens. Click Import Package. Select Wind River Linux Package and click Browse to view the installation packages directory or select a specific package. For example:
installDir/wrlinux-3.0/layers/wrll-wrlinux/packages/package.tar.gz
5. 6. 7.
Click Go to open a shell window and display the script activity. Press Enter until you exit the shell. Click Close to return to the User Space Configuration tool.
Continue by building the package to the patch state. If you want to customize the package, select it, then click Patch in the Targets tab. The patch target rule unpacks the new package and adds the default patches. For instructions, see 10.4.1 Updating the Package Spec File, p.121.
123
124
PA R T I V
Developing Packages
11 12 Patching Packages ............................................. 127 Managing Packages on Live Targets ................ 149
125
126
11
Patching Packages
11.1 Introduction 127 11.2 Patching and Exporting Patches to Layers 131 11.3 Using Quilt Basics 135 11.4 Patching SRPM Packages 139 11.5 Manually Patching Classic Source Files 144
11.1 Introduction
The Wind River Linux build system uses the Quilt patching model. Quilt lets you easily add a series of patches, where each patch may contain multiple files. Quilt tracks changes made by each patch. You can apply these, un-apply them, refresh them, and so on. Quilt patches are managed as a stack and applied incrementally on top of the base virtual folder tree in addition to all preceding patches. They can be pushed to and popped from the top of the stack. By default, most commands apply to the top-most patch on the stack.
127
Quilt is based on the patch package, with an additional set of patching features, which include:
Pushing new patches to go forward Popping patches to go backward Capturing development changes into new patches Deriving patch annotation data
For more about using Quilt, see Andreas Grnbachers How To Survive With Many Patches or Introduction to Quilt, http://www.suse.de/~agruen/quilt.pdf. For information about resolving issues such as path names, fuzz factor, whitespace, and patch reverse situations, see Applying and Resolving Patches in the Wind River Linux Users Guide: Patch Principles and Workflow.
11.1.1 Maintaining PatchesFirst Principles

Wind River Linux strives to keep source code clean (pristine), and therefore it rigorously maintains patch lists. It is important to apply patches to project code only when building a project. Wind River uses the following model for patch workflow:
Product designers decide which template or layer should contain the patch. Individual developers: a. Create a project and import the template or layer to contain the patches.
NOTE: Typically, the more general the layer containing the patch, the greater the scope of testing required. Automated test tools and procedures can help keep the code base correct.
b. c.
Locally develop new code and new patches to extend existing code. Validate work against the central code base before checking in changes and patches.
d. Check in changes.
128
11 Patching Packages 11.1 Introduction
11.1.2 Recognizing Classic Tarball Packages

Classic packages are distributed as tarballs containing an applications source and Makefile(s). They are simple, with no formal metadata about the package, nor do they require any meta language such as in the the spec file of an SRPM. This format makes it easy to package locally developed and maintained packages, but because it lacks formalisms that help make a package cross compile (for example, its Makefile is arbitrarily written without expected all and clean rules), you must fully develop the cross-compile wrapper Makefile, make the required build-phase mapping to the package's Makefile, and add missing rules and actions to make the package follow the conventions of the Wind River Linux build system. Also, you must hand-code, in the cross compile wrapper Makefile, the metadata to be shared with the build system or Workbench. Thus, classic packages are simpler than SRPM packages (discussed in the following sectionsee 11.1.3 Recognizing SRPM Patches, p.129), but they usually require more work and attention to make them cross compile (for example, an SRPM file has already been formatted to match a common convention). Classic packages can have any number of patch files to:
10
Allow the package to cross-compile in the build system. Apply Linux source community patches. Modify the contents and behavior to meet customer requirements.
You can see a packages list of existing Quilt patches if you look in the Quilt Patches folder in the Project Explorer. This patch list is fully manageable by Quilt commands, including pop and push.
11.1.3 Recognizing SRPM Patches

SRPM packages are more complex than simple, classic tarball packages. First, the processing of the SRPM package's content is controlled by a formal spec file, which controls the extraction and patching of the package contents. You must set this file up so that new patches can be applied to the package. The spec file itself is patched by the build system just like a classic file, using the standard Quilt patching described in the previous section. This is in fact the only SRPM file that can be patched this way, because, until the spec file runs, the other files in the package are not yet unpacked nor visible. The patch file if any provided by Wind River that patches the spec file is named pkgname-wr-integration.patch.
129
NOTE: For more details, and for help creating an exact spec file replacement that
doesnt need a patch file, see the Wind River Linux Users Guide: Adding Packages. Second, once the SRPM package is fully unpacked, the inner file content of the package is visible and available. You can use the standard Quilt commands to create new patches for these files. However, to preserve the changes, you must register the new patch files in the spec file, and add the new patch file names to the rpm_patches.list file in the installations layers/wrll-wrlinux/dist/package/patches directory. You can see the spec files list of existing file content patches under the Project Explorer folder SRPM Patches. This patch list is managed only by the spec file, and is provided for reference and patching transparency.
11.1.4 Reviewing the Quilt Menu Commands

The Workbench Quilt menu implements the commands in the quilt man page at installDir/wrlinux-3.0/layers/wrll-host-tools/share/man/man1/quilt.1. At the command-line level, they are similar to CVS commands. (To enable the Quilt man page, edit the /etc/man.config file or enter the pathname in the MANPATH variable. )
Right-click the Quilt Patches folder in the Project Explorer .
Table 11-1
Quilt Menu Commands
Command
Function
Add File to Top Patch Add New File to Top Patch Annotate File Compare With Delete Patch Export Patch
Adds one or more files to the top-most or named patch. Adds a new file. Displays an annotated listing of the specified file, showing which patches modify which lines. Compares (using diff) the specified files in the top-most or specified patch. Removes the specific or top-most patch. Exports an existing or new patch file from your platform project to an external file so that it can be shared. You can also import the exported patch file into a different project.
130
11 Patching Packages 11.2 Patching and Exporting Patches to Layers
Table 11-1
Quilt Menu Commands
Command
Function
Files Fold Patch
Displays the list of files that the specific or top-most patch modifies. Integrates a patch into the top-most patch. Specify the file directly or browse to it. The tree displays the patch contents to verify the patch. Imports external patches, following the current top-most patch. Creates a new patch with a specified name and inserts it after the top-most patch. The patch name in the tree specifies whether or not the patch is loaded. Lists the patches that modified a specified file. Removes one or more patches from the stack of applied patches. Click Details to list the patches that have been removed and/or restored as a result of the pop. Applies one or more patches from the series file. Click Details to list the files patched by the push. Refreshes a specific patch or the default top-most one. Synchronizes information that Workbench has cached (such as command-line use of Quilt). Renames a specific or top-most patch. Removes file(s) from the named or top-most patch.
Import Patch New Patch
10
Patches Pop
Push Refresh Top Patch Reload Rename Patch Remove File from Patch
11.2 Patching and Exporting Patches to Layers

These procedures explain how to import patches from the community and save them into a layer. You can import and patch packages and SRPMs and export the patches into layers of your choice. You will need to read later sections of this chapter for more context and information.
131
11.2.1 Patching and Exporting Classic Packages (General Steps)

To export a patch from the build system to a layer, then rebuild the platform as specified by that layer: 1. 2. Select a package in the Installed Packages list of your platform packages Package Manager view, right-click the Targets tab, and click patch. Open the platform projects build folder, then the classic package, then the Quilt Patches node, then the bold top-most patch, and, finally, double-click a source file below, and edit it. If the build folder is not visible, right-click the project and select Add Links to Development Folders. If the patch is not up-to-date, right-click and select Quilt > Refresh Top Patch. 3. 4. 5. Right-click the patch file, select Export Patch to Layer, and enter an export location. Select the classic package in the Installed Packages list; click the Targets tab, click distclean, and then patch. Right-click the build tree under the platform project and select Refresh.
11.2.2 By Example: Patching and Exporting Classic Packages to a Layer

To illustrate this process:
Step 1: Get ready to patch a package
1. 2. 3. 4. 5.
Step 2:
Create a Platform Project. Open its User Space Configuration node. Select the wrproxy package. Click the Targets tab, and click Patch. Right-click the project, and select Add Links to Development Folders.
Change the package
1. 2.
Open the project tree build > wrproxy > Quilt Patches. Observe that the patch kerntree.patch is the top-most patch (in bold).
132
11 Patching Packages 11.2 Patching and Exporting Patches to Layers
3. 4.
Open the list under kerntree.patch, and double-click the file wrProxyTipcSockLib.c. Make a minor text addition such as in the copyright area, and select File > Save.
Step 3:
Export the patch to a layer
1. 2. 3. 4. 5. 6.
Step 4:
Right-click kerntree.patch, or another patch of your choosing, and select Quilt > Refresh Top Patch. Right-click it again and select Export Patch to Layer. Reset the layer path to installDir/wrlinux-3.0/layers/wrll-wrlinux, if it is not this path already. Select the layer to receive the patch. Add a quick description, and click OK. Click OK in the resulting dialog.
10
Test the patch
1. 2. 3. 4.
Step 5:
Open User Space Configuration in a project. Select the wrproxy package. Click the Targets tab, and click distclean and then patch. Right-click the build tree, and select Refresh.
Observe that changes are now part of the package
11.2.3 By Example: Patching and Exporting SRPM Source File to a Layer

Follow this procedure to patch a file within an SRPM package; capture that change into an SRPM patch; and add the patch to the packages spec file.
NOTE: First, you need to patch the SRPM spec file. See 11.4.1 Manually Patching SRPM Spec Files, p.139. Step 1: Unpack and patch the package
1. 2.
Open the User Space Configuration node onto the Package Manager. Select the acpid package.
133
3. 4. 5.
Step 2:
Click the Targets tab, and click patch. Open the project tree build > acpid-1.0.6.7-fc9 > Quilt Patches. Observe that patch pkgname-wr-integration.patch is the top-most patch.
Change a package file
1.
Right-click the pkgname-wr-integration.patch, select Quilt > New Patch, and give it the name myChanges.patch.
NOTE: You may need to click on the package-version node and choose Refresh to see the new top patch.
2. 3. 4.
Step 3:
Open the tree to build > acpid-1.0.6.7-fc9 > BUILD > acpid-1.0.6, and double-click acpi_listen.c. Right-click acpi_listen.c, and select Quilt > Add to Top Patch. Make a minor text addition in the copyright area, and select File > Save.
Export the patch to a layer
1. 2. 3. 4.
Step 4:
Right-click myChanges.patch, and select Quilt > Refresh Top Patch. Right-click it again and select Export Patch to Layer. Add a description, and click OK. Click OK in the resulting dialog.
Test the patch
1. 2. 3. 4. 5.
Open the projects User Space Configuration node onto the Package Manager. Select the acpid package. Click the Targets tab, and click distclean and then patch. Right-click the build tree, and select Refresh. Open the acpid package under build, and observe that the change is now automatic, and that the custom Quilt patch is now an SRPM patch.
NOTE: SRPM patches are managed by the package's spec file. The techniques just demonstrated show how to use Quilt to create a new patch for the inner files of an SRPM package, and then promote it to a formal SRPM patch by adding it to rpm_patches.list and to the spec file. The Export to Layers script does exactly that. This Quilt patch then becomes an SRPM patch, and is no longer managed by Quilt.
134
11 Patching Packages 11.3 Using Quilt Basics
11.3 Using Quilt Basics

This section explains how to apply classic, non-SRPM patches to a project, rebuild the project, and then recognize the patches node in it. This should help you patch the SRPM spec file, as described in 11.4.1 Manually Patching SRPM Spec Files, p.139.
11.3.1 Configuring Quilt to Manage Patches

1. Open a Wind River Linux platform project within the Project Explorer. If you create a new project, the ProjName_prj Linux directory contains just a README in its dist subdirectory, and only Makefile-related files plus a pkgrpmlist file in its build subdirectory. The build and dist folders do not yet appear in the Project Explorer. 2. Right-click the project and choose Add Links to Development Folders. This lets the build and dist folders appear in the Project Explorer:
10
build, so you can start working directly with the package builds dist, so you can work with local package wrapper Makefile and patches
They have the same content as ProjName_prj/build and ProjName_prj/dist. 3. Open the Package Manager by double-clicking the projects User Space Configuration node. (Click Yes to initialize the prebuilt PM package folder.)
11.3.2 Applying Patches

The resulting Packages dialog (see the following figure) lists the installed and installable packages. 1. 2. Select an installed package, for example, boa. From the Targets tab, click patch. Workbench extracts the package to your workspace and applies all boa patches. Your ProjName_prj/build subdirectory and the Project Explorer build folder now contain boa-0.94.13 (named as package-version). If not, right-click the project build folder and choose Refresh.
135
Figure 11-1
Package Managers Packages List
3. 4.
Expand the package-version folder to display the Quilt Patches node. Right-click the Quilt Patches node to open the Quilt menu.
At this point, the build folder in the Project Explorer stops looking like the build directory in ProjName_prj. You can expand Quilt patches to display the patches applied. You can further expand the files that are part of a patch: for example, right-click a source file such as boa.c and use the Quilt menu Annotate File to annotate it. For more information, see 11.3.5 Viewing Patch Annotations, p.138.
136
11 Patching Packages 11.3 Using Quilt Basics
11.3.3 Importing Patches

To import a patch to your build system: 1. Open your platform project build folder. If the build folder is not visible, right-click the project and select Add Links to Development Folders. This makes the build folder visible. 2. 3. Open the package-version folder of the package to be patched, and then the Quilt Patches folder. Select the package whose patch you want to import, right-click it, and choose Quilt > Import Patch, and then select the patch for it.
Workbench adds the patch file to the package patch list file and places it in the Quilt Patches folder.
10
11.3.4 Creating a New Top Patch File

You can create separate patch files for any set of source file changes by creating a new top patch file, as follows: 1. Open a platform project, and if the build folder does not yet appear in it: a. b. c. Double-click User Space Configuration. Select the package, click the Targets tab, and then click patch. If the the build folder is visible in the project, right-click it and select Refresh, otherwise right-click the project and select Add Links to Development Folders.
2. 3.
Open the build folder, then package-version, then Quilt Patches (a virtual folder displaying the Quilt-applied patches). Right-click this folder, select Quilt > New Patch, and enter a descriptive name such as New_Boa_Patch. An Info alert pops up, reporting that New_Boa_Patch is now on top.
4.
Click OK.
137
11.3.5 Viewing Patch Annotations

Quilt supports a patch annotation feature, which you can use as follows: 1. 2. Open a project and then browse to and select a file under the specific patch. Right-click the file and select Quilt > Annotate File. The file displays. 3. 4. Scroll through the file and view the colored bars in the left-hand margin. Place your cursor over one of the colored bars to open a pop-up box listing the patch name that contributed to the line. When a pop-up box opens, boxes are also displayed in the right-hand margin. These boxes indicate the other file locations that were contributed to by the applied patch.
138
11 Patching Packages 11.4 Patching SRPM Packages
11.4 Patching SRPM Packages

To work with SRPM packages, you need to first manually patch the SRPM spec file, and only then patch the source files.
11.4.1 Manually Patching SRPM Spec Files

All SRPM packages have a spec file that manages how a package is built on the host and how it installs in the target file system. Patching this file lets you customize and enhance the package in the build system and the specific target environment. Quilt manages the SRPM spec file during the unpacking and patch process, providing each package with a Wind River Linux integration patch that allows the spec file to cross compile. After integration, the spec file manages all package source file patches.
Step 1: Open a spec file
10
To unpack and apply current patches to the spec file: 1. 2. 3. 4. Open a platform project. Double-click User Space Configuration to open the Package Manager. Select the package, click the Targets tab, and click patch. Right-click your project and select Add Links to Development Folders. The build tree displays in the Project Explorer. 5. 6.
Step 2:
Open the build tree and browse to package-version > Quilt Patches > package-wr-integration.patch. Open the SPECS/package.spec file, which is the Quilt patch-managed file.
Modify it
7. 8. 9.
Change one of the initial comment lines, for example.) Select File > Save to save your changes. In the Package Manager, click build or rebuild (in the Targets tab) to verify your changes.
139
Step 3:
Save it
1. 2. 3.
Right-click the package-wr-integration.patch node and select Quilt > Refresh Top Patch. Right-click wr-integration.patch again and select Quilt > Export Patch. Save the patch in installDir /wrlinux-3.0/layers/wrll-wrlinux/dist/package/patches:
Rename it to distinguish it from the primary integration patch file. or
Back up the previous version and then save the new patch file.
4. 5.
You do not need to update the patches.list file because this patch file is already registered. Append the patch file name to the patches.list file, for example:
# This comment explains the purpose of this patch Newbzip2-wr-integration.patch
NOTE: If you shared the patches and the patches.list file does not exist, create
it in wrll-wrlinux/dist/package/patches, then append the patch file name.

Step 4: Test it
1. 2. 3.
Open the Package Manager and select the package. From the Target tab, click distclean. Click patch. Your changes are applied to the spec file.
11.4.2 Patching SRPM Source Files

Open source SRPM packages typically contain the package source code, as well as patches that must be applied to the source, to produce the binary for the RPM package. Integrating an SRPM into the Wind River Linux build system allows for cross compiling. A Wind River integration patch (package-wr-integration.patch) is required. Finally, you may further patch the source to make your own changes. SRPM packages have a spec file (as just described see 11.4.1 Manually Patching SRPM Spec Files, p.139) that manages how a package is built on the host and how it installs in the target file system.
140
During the unpacking and patching process, Quilt patches the spec file and then the spec file applies all of its patches to the package source.
NOTE: Ignore errors like cat: write error: Broken pipe. These messages are a
passive artifact of Quilt. To patch an SRPM source file: 1. 2. 3. 4. 5. Create a new top patch file. Save your patch file to the installation or layer location. Add the new patch file to the SRPM rpm_patch.list patch list file. Register the new patch file in the package spec file. Update and save the spec file registration change in its respective wr-integration.patch file.
10
If you patch an automake-managed file like a .am file, you may find that the package already includes the corresponding .in file. If so, patch both files to be safe. Likewise, if you modify a .in file, you should patch the parent .am file, in case working with the package triggers an automatic reconfiguration (autoreconf).
Modifying SRPM Package Files
You can modify any package patch file to customize your installation. 1. 2. 3. 4. 5. Browse the build > package-version source tree and select a source file. Right-click the file and select Quilt > Add New File to Top Patch. Modify the file and select File > Save to save your changes. Right-click the file again and select Quilt > Refresh Top Patch to capture the changes to your new patch file. Double-click User Space Configuration, and in the Targets tab click build or rebuild to verify your changes.
Saving SRPM Patch Files
1. 2.
Right-click the SRPM patch file and select Quilt > Export Patch. Save your patch to installDir /wrlinux-3.0/layers/wrll-wrlinux/dist/package/patches.
141
The working patch file is inside the package build directory, under the wrlinux_quilt_patches directory. 3. Create or append the rpm_patches.list file with the patch file name and description. For example:
# This comment explains the purpose of this patch coreutils_custom_EXTRA_DIST.patch
4.
Modify the patch file context in the saved patch file, so that it matches the context that the SRPM spec file uses: a. b. Open each patch file. Remove the a/build/ and b/build/ prefixes and then append a unique tag (such as .orig) to the original file name, for example: i. Remove the a/build/ and b/build/ prefixes:
--- a/BUILD/coreutils-6.9/Makefile.am +++ b/BUILD/coreutils-6.9/Makefile.am
ii. Append a unique tag:

--- coreutils-6.9/Makefile.am.orig +++ coreutils-6.9/Makefile.am
Adding the SRPM Patch
1. 2.
Open the wr-integration.patch tree and double-click the SPECS/pkg.spec file. Register this new patch as the last patch. Locate the last entry (such as Patch5003:) in the spec file. For example:
... Patch5002: coreutils-6.9.2-cross_compiling_no.patch Patch5003: coreutils-6.9.2-custom_EXTRA_DIST.patch
3. 4.
Add your patch entry after the last Patchxxxx: entry in the spec file. (Optional) Add parameters to customize the patch command. For example:
Use the -p1 parameter to ignore coreutils-6.9/ filename prefixes. Use -b to generate a back-up file before patching the original.
The %patch macro automatically adds a prefix to the package name, version number, and post-fixes the .patch extension. For example:
... %patch5002 -p1 -b .cross_compiling_no %patch5002 -p1 -b .custom_EXTRA_DIST
5.
Select File > Save to save your spec file changes.
142
Saving the Updates as a Patch to the Spec File
The package-wr-integration.patch file tracks all changes to the spec file. To preserve the changes to the spec file as a patch: 1. 2. 3. 4. Pop the source file patch or patches to get the wr-integration patch back to the top-most location on the stack. Right-click package-wr-integration.patch and select Quilt > Refresh Top Patch. Right-click package-wr-integration.patch and select Quilt > Export Patch. Save the patch in installDir /wrlinux-3.0/layers/wrll-wrlinux/dist/package/patches. You do not need to update the patches.list file because this patch is already registered in it. 5. 6. Open the project build/pkg-version/Quilt Patches virtual folder in the Project Explorer. Right-click the project and select Quilt > Pop until wr-integration.patch appears in bold, indicating that it is on top again. The popped patch files appear in italics.
10
11.4.3 Testing the Patches

Now that you have the spec file and the source patch files complete, you can test your changes. To test your patch: 1. 2. 3. 4. Open the Package Manager via the User Space Configuration node. Select the package, click the Targets tab, and click distclean. Click patch to apply the spec file patch and all the new custom patches in the spec file. (Optional) If you get error messages, use them to fix the respective patch file(s). For example, verify that:
Registered and listed filename spellings are correct. The syntax in the spec file is appropriate. The patches are in the proper order.
143
The before/after filename entries are listed in the source patch file.
5. 6.
(Optional) Repeat the package distclean and patch rules until all errors are resolved. Select the package build rule to compile the full package.
11.4.4 By Example: Viewing the SRPM Patch List

The following procedure uses the acpid package as an example. To view the SRPM patch list for the package: 1. 2. 3. 4. Open the Package Manager from a projects User Space Configuration node. Select the acpid package. Open the Targets tab, then click patch. Open the project tree build > acpid-1.0.6.7-fc9 > Quilt Patches. Observe the list of Quilt packages for this package. For an SRPM package, only the spec file will be listed. 5. Open the project tree build > acpid-1.0.6.7-fc9 > SRPM Patches. Observe the list of SRPM-based patches for the package. The patches are placed in the SOURCES folder.
11.5 Manually Patching Classic Source Files

You can patch classic source files and export the patch from the build system to a layer, then rebuild the platform as specified by that layer, as explained in this and the following procedures in this section.
11.5.1 Creating a New Top Patch File

To create a new top patch file: 1. Open a platform project.
144
11 Patching Packages 11.5 Manually Patching Classic Source Files
2. 3. 4. 5. 6.
Double-click User Space Configuration to open the Package Manager. Select the package, click the Targets tab, and click patch. Right-click the project and select Add Links to Development Folders. The build tree displays in the Project Explorer. Open the build tree and browse to build > package-version > Quilt Patches (a virtual folder displaying the Quilt-applied patches). Right-click this folder, select Quilt > New Patch, and enter a descriptive file name (for example, coreutils-6.9.2-custom_EXTRA_DIST.patch). If the package build folder does not display or is out-dated, right-click the build tree and select Refresh.
NOTE: You can create several new patch files containing any set of source file
changes. To switch between each patch file, right-click the project and select Quilt > Pop or Quilt > Push.
10
11.5.2 Modifying Package Files

You can modify any package patch file to customize your installation. 1. Select a source file from the build > package-version tree, such as extras/alphasort.c, or src/boa.c. This is the file you plan to modify. 2. 3. Right-click the file and select Quilt > Add New File to Top Patch. Give the patch file a new name, or enter the old one, then click OK:
145
4. 5.
Modify the file and select File > Save to save your changes. Right-click the file and select Quilt > Refresh Top Patch to capture the changes to your new patch file, then click OK when the Info popup reports the refresh by name (for example, Refreshed patch New_Boa_Patch.) Double-click the User Space Configuration node, and, in the Targets tab, click build or rebuild to verify your changes.
6.
11.5.3 Exporting a Patch

After modifying your patch, you must export it to the appropriate installation location.
NOTE: Keep a copy of the previous file version and be sure you have a back-up.
1.
Right-click the new patch file and then select Quilt > Export Patch. For example, right-click the New_Boa_Patch:
2.
To save the patch so others can use it, save it in installDir/wrlinux-3.0/layers/wrll-wrlinux/dist/package/patches.
146
11 Patching Packages 11.5 Manually Patching Classic Source Files
3.
To save the patch in your own workspace, as in the following screenshot, accept the default wrlinux_quilt_patches folder, which in this example will be Workspace/my_arm_prj/build/boa-0.94.13/wrlinux_quilt_patches.
10
4.
Append the patch file name to the patches.list file:

# Explain the purpose of the patchname you enter below. new-patch-file-name.patch
NOTE: If patches.list does not exist, create it and add the patch filename(s).
5.
Repeat these steps if you have any additional patch files to export. Keep the entries in the patches.list file in the order you want them applied.
11.5.4 Testing a Patch

To test your new patch: 1. Select your test package in the Package Configurations Installed Packages list. Double-click the User Space Configuration icon and click Packages to open the Package Manager if it is not visible. 2. 3. From the Target tab, click distclean. Click patch to apply the patch. Your changes are applied to the spec file.
147
148
12
Managing Packages on Live Targets
12.1 Introduction 149 12.2 Working with Kernel Modules on the Target 149 12.3 Working with RPMs on the Target 151
12.1 Introduction
This section tells you how to put (and remove) RPMs and kernel modules on a target. You can also launch RPMs on a live target and replace them live.
12.2 Working with Kernel Modules on the Target

You can install and remove kernel modules as described in this section.
149
12.2.1 Installing Kernel Modules to the Target

To install a kernel module, such as moduleDebugExample.ko: 1. 2. Create a platform project. Build the kernel and file system. You need this step to set up the module development support in the kernel directory. 3. 4. 5. 6. 7. Create the moduledebug_2_6 sample kernel module project, attach it to the platform project, and build it. Boot the target. Attach the usermode-agent. (You must have an active usermode-agent running on the target.) Right-click moduleDebugExample.ko in the project explorer, and select Insert Module. Accept the connection request if asked. (If Workbench asks for usermode arguments, it does not need any.) Decide which connection to use, if asked. (You can also start, stop, or create a connection at this point.) Click OK to insert the module into the running target.
8.
12.2.2 Removing Kernel Modules from the Target

There are two ways to remove a kernel module running on a target. To remove a kernel module using the command line, first check that there are no errors in the Workbench Console view, and then issue the following commands on the target:
% lsmod % rmmod module_name
To remove a kernel module using Workbench, first check that there are no errors in the Workbench Console view, and then right-click the .ko file and select Remove Module.
150
12 Managing Packages on Live Targets 12.3 Working with RPMs on the Target
12.3 Working with RPMs on the Target

This section tells you how to launch RPMs to the target, and how to replace and remove them from a running target. Workbench allows you to manipulate RPMs running on your target just as you would on a regular Linux host, because they are added to your targets file system, and the RPM database is pre-populated with the installed RPM files. Workbench provides a GUI interface to commands such as rpm -install package.
NOTE: There is no RPM manager on glibc_small and uclibc_small file systems.
12.3.1 Launching RPMs Straight to the Target

To launch an RPM from your host straight to a running target, without requiring compilation or rebooting: 1. 2. 3. 4. 5. 6. 7. 8. Right-click an RPM in the Package Manager list and select Install. Accept the connection request if asked. If Workbench asks for usermode arguments, it does not need any. Decide which connection to use, if asked. (You can also start, stop, or create a connection at this point.) Click OK to launch the RPM into the running target. When the RPM finishes, look for a done message. The console and its thread close automatically. Observe the pop-up, and, if you choose it, that a message in the lower-right of Workbench showing the uploaded or currently selected RPM file. When the upload finishes, the pop-up disappears, but this is when the target-resident script actually starts to run. Observe in the console a message that appears to specify the action being taken on the RPM, and, generally next, a message asking you to wait.
11
If you have requested an RPM install on the running target, the installation time depends on the size and complexity. (Operations other than installing are generally much faster.)
151
12.3.2 Removing Running RPMs

To remove an RPM such as iptrables-ipv6 that is running on your target: 1. 2. 3. 4. Create a platform project. Build the project, and start it on a target (real or emulated). Open the platforms User Space Configuration node and click Packages to open the Package Manager. Right-click on the entry iptables-ipv6 (for example) and select Erase.
You have now removed the RPM from the target.
12.3.3 Replacing Running RPMs

To replace a running RPM, for example, iptables-ipv6: 1. Remove the RPM running on the target: a. b. c. 2. Open the User Space Configuration node and click Packages to open the Package Manager. Right-click the entry iptables-ipv6 and select Erase. Right-click the entry iptables and select Erase.
Optional: right-click the entry iptables-ipv6 and select Install. This returns an error message that indicates the prerequisite for installing this RPM:
error: Failed dependencies: iptables = 1.3.7 is needed by iptables-ipv6-1.3.7-2_WR3.0bl.armv5tel_vfp /lib/iptables is needed by iptables-ipv6-1.3.7-2_WR3.0bl.armv5tel_vfp
3.
Install the replacement(s) for the RPM. For example, to re-install what you just removed: a. b. Right-click on the entry iptables and select Install. Right-click on the entry iptables-ipv6 and select Install.
You now have both these packages replaced and running on the target.
152
PA R T V
Deploying to Your Board

13 14 Assembling File Systems and Kernels ............. 155 Deploying to Targets .......................................... 159
153
154
13
Assembling File Systems and Kernels
13.1 Introduction 155 13.2 Assembling Your File System 156 13.3 Assembling Your Kernel 156 13.4 More on Build Targets 157 13.5 Adding Applications to Your File System 157 13.6 Collecting Your Files for Export 158
13.1 Introduction
This chapter briefly summarizes how to assemble your file systems and kernels so they can be placed (deployed) onto your target, whether it is physical or emulated, as explained in the next chapter. For more than these brief explanations, see the Wind River Linux Users Guide, particularly the sections on creating run-time systems (in the Design Overview: Build Environment chapter), and the relevant chapters on network or stand-alone deployment.
155
13.2 Assembling Your File System

When you right-click a platform projects fs node and choose Build Target (or use the command make fs), you create, in workspace/ProjectName_prj/export/dist, a complete run-time file system from pre-built RPMs. The dist directory will later also contain the build output from the applications that have been created for this platform. The system also creates a link to the default, pre-built, board-specific kernel from installDir/wrlinux-3.0/layers/wrll-linux-version/boards/board-name/kernel-type, in the export directory within the project build directory. (That is, in workspace/ProjectName_prj/export.) This directory also contains a link to a compressed runtime file system, that is, to a tar.bz2 file named according to the board, rootfs, and kernel you chose when you created the platform project.
13.3 Assembling Your Kernel

When you right-click a projects kernel_build node and choose Build Target, you are doing the equivalent of a command-line make -C build linux: building a new board-specific kernel from source, and generating a new set of RPMs from source files to build a compressed run-time file system image. (If instead you choose kernel_rebuild, Workbench does a make clean first and then builds the kernel. The make clean cleans up files from previous compilations, but it is slower because it needs more recompilation.) The kernel build reproduces builds of the kernel and compressed run-time system file from any newly created RPMs you might have made, and installs them in workspace/ProjectName_prj/export/dist. The Linux kernel is created; the file system and modules are compressed into a tar file, and the modules alone are compressed into a separate bzipped tar file. A separate vmlinux file for debugging is also created, along with a System.map file. Examples of these files for the Wind River PowerQUICC II board are:
wrs_powerquiccii_82xx-System.map-WR3.0bl_standard wrs_powerquiccii_82xx-default_kernel_image-WR3.0bl_standard wrs_powerquiccii_82xx-linux-modules-WR3.0bl_standard.tar.bz2
156
13 Assembling File Systems and Kernels 13.4 More on Build Targets
wrs_powerquiccii_82xx-uImage-WR3.0bl_standard wrs_powerquiccii_82xx-vmlinux-stripped-WR3.0bl_standard wrs_powerquiccii_82xx-vmlinux-symbols-WR3.0bl_standard
NOTE: Some of these are links, not files.
13.4 More on Build Targets

You can also make your own build targets. And you can build from within the Package Manager, as explained in 5. Developing Platform Projects.
12
13.5 Adding Applications to Your File System

You can add applications to your platform projects file system, but keep in mind the following points:
If you deploy to a QEMU-emulated target, you can put the application binaries and any associated data files into the appropriate locations within the file system that has been created at workspace/ProjectName_prj/export/dist. If you use the dist.tar.bz2 file in workspace/ProjectName_prj/export, which is present as a link in that directory, you must add your application files in a template under the fs node and then do a Build Target on the fs node.
NOTE: Your application and related files must be built into the dist.tar.bz2 file by means of the Build Target action. It does not work to uncompress dist.tar.bz2, add the application files, and then recompress.
157
13.6 Collecting Your Files for Export

At this point, you should have the following items in your workspace/ProjectName_prj/export and workspace/ProjectName_prj/export/dist directories:
The kernel and related files as described in 13.3 Assembling Your Kernel, p.156 The run-time file system as described in 13.2 Assembling Your File System, p.156 Any applications and related files, in the dist.tar.bz2 file, as described in 13.5 Adding Applications to Your File System, p.157
You can now plan to: 1. 2. 3. Unpack the file system from dist.tar.bz2 into a location from which it can be exported to a target. Copy the kernel to a similar location from where it can be exported to a target. Continue with chapter 14. Deploying to Targets.
158
14
Deploying to Targets
14.1 Introduction 159 14.2 Introducing Target Deployment 160 14.3 Connecting to Targets in General 162 14.4 Connecting to Emulated Targets 164 14.5 Connecting with KGDB 167 14.6 Using Advanced KGDB Options 170 14.7 Using Target Server Options 171 14.8 Using the Connection Summary Page 172
14.1 Introduction
You must configure and establish a target connection between your host and target machines before you can deploy your projects to the target for testing and debugging. The target connection runs on your host and manages the communications between your host tools and the target system. This chapter provides the information you need to define and configure a remote connection to your target. See also 4.8 Debugging and Deploying, p.41 for an overview of topics such as how usermode-agent is used.
159
14.2 Introducing Target Deployment

How you deploy your kernel and file system to your target depends on your development environment, as described very briefly in this section.
NOTE: For specific instructions about deploying your project to your target and booting the target, see the Wind River Platforms Users Guide.
14.2.1 Using a Typical NFS Target Networking Environment

With the NFS network configuration shown in Figure 14-1, you build a new kernel and file system on the development host, make them available to the board, then reboot the board. The board is configured to automatically load the kernel and mount the file system from your development host each time it reboots.
Figure 14-1 Typical Network Development Environment
File System Kernel
File System Kernel
NFS Mount TFTP Download
File System Kernel
Platform Project
Download Directories
Development Host
Target Board
14.2.2 Using an Emulated Target Environment

The basic functions are the same as when you use an actual target board. The target still downloads the kernel and NFS-mounts the root file system from the development host. Except, now, the target is a simulation running on the development host, not external hardware.
160
14 Deploying to Targets 14.2 Introducing Target Deployment
Figure 14-2
QEMU Emulator Development Environment
File System Kernel
NFS Mount Virtual Download
File System Kernel
Platform Project Development Host
QEMU Emulation
See 14.4 Connecting to Emulated Targets, p.164, for specific instructions.
14.2.3 Using a Flash Development Environment

In general, with flash-based development, in an environment as sketched in Figure 14-3, you boot the target up to its boot loader, which then uses tftp to acquire the root file system and kernel from your development host or a network server. The bootloader then burns the kernel and file system to flash and boots the target from the flash image.
Figure 14-3 Flash Development Environment
13
File System Kernel
File System Kernel
TFTP Download TFTP Download
Bootloader
Platform Project
Download Directories
Flash or RAM Target Board
Development Host
161
14.3 Connecting to Targets in General

Use the Wind River Workbench Remote Systems view to configure your host connection and modify related settings. The Remote Systems view lets you:

Define new connections Connect and disconnect targets Modify connection properties
NOTE: After you connect to a target, more commands are enabled on the right-click context menu. See the Wind River Workbench Users Guide.
The Remote Systems view is available through both the Application Development and Device Debug perspectives. If it is not visible, choose Window > Show View > Remote Systems or Window > Show View > Other.
14.3.1 Defining a New Connection

The Remote Systems view provides a connection wizard to step you through your remote connection. To open the New Connection wizard: 1. Select Target > New Connection. The Select Remote System Type dialog opens. 2.
Table 14-1
Select one of the following connection types, then click Next.
Remote Connection Types
Connection Type
Creates a . . .
Application Core Dump Target Server
Connection to a Linux 3.0 application core dump (for step-by-step instructions, see 18. Analyzing Core Files)
Host Development Target Server Host development connection to a Linux 3.0 application
162
14 Deploying to Targets 14.3 Connecting to Targets in General
Table 14-1
Remote Connection Types
Connection Type
Creates a . . .
KGDB
Kernel mode connection to a Linux 3.0 version kernel (see 16.6 Debugging User-Supplied Kernel Modules, p.198 and 16.8 Using QEMU for KGDB Kernel Debugging, p.206). RTCore Connection. Usermode connection to the target. Command-line interface to QEMU for KGDB back-end connection debugging. Uses KGDB and OCD-like connection to real board (in emulation)
RTCore User Mode Target Server QEMU Backend QEMU
QEMU Linux User Mode Target Uses usermode-agent for target connection Server (see 15. Debugging User Space).
13
3.
Enter any connection-specific properties. For example, if you select Wind River Linux Host Development Target Server Connection, a Browse button appears for the usermode-agent field. For more information about these options, see 14.7 Using Target Server Options, p.171.
NOTE: Typically, after configuring a new connection, Wind River Workbench automatically attempts a connection. If you do not want an automatic connection, deselect Immediately connect to target if possible.
14.3.2 Connecting and Disconnecting

When you make a target connection, it is registered and made accessible using the Wind River Registry. You can use the remote registries to maintain connection data in a central location and to share data between hosts. For more information, see the Wind River Workbench Users Guide: The Registry. Use the Remote Systems view to connect to, or disconnect from, your target: 1. 2. Right-click a connection node. Click Connect or Disconnect.
163
14.3.3 Modifying Connection Properties

To modify the properties you set during your new target connection: 1. 2. 3. 4. 5. 6. Open the Remote Systems view. Disconnect from your target. Select a connection node. Right-click and select Properties from the context menu. Modify and save your changes. Connect to your target.
14.4 Connecting to Emulated Targets

Quick EMUlator (QEMU) is an open source machine emulator that lets you configure the kernel and root file system for emulated boards for BSPs such as the Common PC, ARM Versatile AB-926EJS, and Qemu-PPC32. QEMU loads the kernel found in the project build export directory, and NFS mounts the file system within the export/dist directory. Unlike configuring hardware targets, where you can place the kernel and file system in any location on your host to be NFS mounted, QEMU requires specific locations.
NOTE: If you specify localhost and Port 4444, Workbench automatically creates a QEMU connection. The port number depends on the running QEMU instance; for example, for an instance of 0, the port is 4444; for an instance of 1, the port is 4544: for each increase, the port number increases by 100.
Use the Remote Systems view to create and configure a QEMU connection for an emulated target: 1. 2. Select New > Connection. The Select Remote System Type dialog displays. Select Wind River Linux > Wind River QEMU Linux User Mode Target Server Connection then click Next. The QEMU Simulator Configuration screen appears.
164
14 Deploying to Targets 14.4 Connecting to Emulated Targets
3.
Select the project root directory or browse to workspace/projectName_prj then click Next. The following dialog appears.
13
4.
Select the workspace/projectName_prj/export/dist root file system and click Next. This is the file system you want exported to QEMU. The following dialog appears.
165
The object path mappings determine which part of the host file system gets NFS mounted (or mounted by QEMU) on the target. If your default target path is not your workspace (/) directory, or the host path is not your platform_prj/export/dist directory, click Add to specify them. 5. Click Finish. The Virtual-WRLinux0 terminal window opens. It outputs the connection processes. The WRQEMULinuxUser_Project_prj connection appears in the Remote Systems view. This is the target connection that Workbench uses to debug the application on the platform.
NOTE: You might have to log in to the terminal as root, with the password root. If
you are using a small rootFS, you are automatically logged in as root.
166
14 Deploying to Targets 14.5 Connecting with KGDB
14.5 Connecting with KGDB

To configure a kernel mode (KGDB) connection: 1. Select New > Connection. The Select Remote System Type dialog displays. 2. Select one of the following connection types:
Description
Connection Type
Linux KGDB via RS232 Linux KGDB via Ethernet Linux KGDB via Terminal Server Custom Linux KGDB Connection
Serial cable connection. Ethernet connection. Connection through a terminal server to the target. No defaults. Used for custom situations. See Wind River Support.
13
The Linux KGDB Connection Properties dialog opens. 3. Select a back end setting from the following list to define how the target server communicates with a target.
Provides . . .
Back End Setting
RS232
A direct serial port connection (connection with a null-modem cable). You must specify your serial line settings. A connection to a terminal server with a direct serial connection. An Ethernet connection on the same subnet. Not currently supported.
TCP UDP PIPE 4. 5.
Select the target processor from the Select menu, or leave the target default to have Workbench identify the target CPU. Specify serial line or remote host settings, depending on the connection template or back-end setting that you have chosen:
167
For serial line settings, enter the standard speed, data, parity, and stop bits, plus flow control. For networked hardware, enter a target name or an IP address , plus a port number (or accept the default 6443.)
6. 7.
Click Next. The Target Operating System Settings dialog opens. Enter the full path name including the kernel symbol file (for example, /home/wbuser/WindRiver/workspace/new_prj/export/vmlinux-symbols). By default, the debug server attempts to load module symbols each time a module is loaded. In the rare cases where you want to download a module or start a process without loading the symbol file, deselect Load module symbols to debug server automatically if possible.
NOTE: The target server must be configured with the same communication back end as the one built for the kernel image and used by the target agent.
8.
Click Next. The Object Path Mappings dialog displays.
14.5.1 Using Object Path Mapping

Workbench uses Object Path Mappings for the following tasks:
To enable the debugger to find symbol files for processes created on the target by creating a correspondence between a path on the target and the appropriate path on the host. To calculate target paths for processes that you want to launch by browsing to them with a host file system browser.
To specify an object file for the debugger to use (or if you are loading object code on the target or associating symbols with previously loaded modules): 1. Right-click a container in the Remote Systems view, then select Load/Add Symbols to Debug Server. A dialog appears with your connection and core already entered. Click Add to add a new object file to the Symbol Files and Order list. Select the file, then click Open. In the Symbol Load Options section, select Specify base start address or Specify start address for each section. Click OK.
2. 3. 4. 5.
168
14 Deploying to Targets 14.5 Connecting with KGDB
For more information about the fields in this dialog, click in the Remote Systems view, then press the help key for your host.
Pathname Prefix Mappings
The pathname prefix mappings match target path prefixes to host paths. You must use full paths and not relative paths. For example, mapping / to /opt/eldk/ppc_82xx/ tells the debugger that files accessible in / on the target can be found in /opt/eldk/ppc_82xx/ on the host. In most cases, Workbench provides correct defaults. If you need to make changes:
Click Add to add new mappings or select existing mappings. Click Edit to modify existing mappings.
NOTE: You cannot edit the supplied default mappings.
Basename Mappings
13
Use square brackets to enclose each mapping of target file basenames (left element) to host file basenames (right element), separated by a semi-colon (;). Mapping pairs (in square brackets) are separated by commas. You can use an asterisk (*) as a wildcard.For example, if debug versions of files are identified by the extension *.unstripped, the mapping [*;*.unstripped] ensures that the debugger loads yourApp.unstripped when yourApp is launched on the target.
14.5.2 Using Target State Refresh Page

Because retrieving status information from the target can cause considerable target traffic, the Target State Refresh page lets you configure how often, and under what conditions, the information in the Remote Systems view is updated. To change these setting: 1. 2. Right-click the target connection then select Refresh Properties. Modify the appropriate properties:
169
Property
Description
Available CPU(s) on target board Initial target state query and settings Target state refresh settings
Workbench correctly identifies the target CPU. In rare cases, a close variant might be misidentified. If so, manually set the CPU. Specify whether or not Workbench should query the target on connect, on stopped events, and/or on running events. You can select all options. Specify that the target state is refreshed only when you manually choose to do so, or if (and how often) the display should be refreshed automatically. Specify whether or not Workbench should listen for life-cycle events.
Listen to execution context life-cycle events 3. Save your changes.
14.6 Using Advanced KGDB Options

The New Connection dialog box displays advanced options for KGDB connections. To choose advanced KGDB options:
Select from the following options.

Description or Procedure
Advanced Option
Back end Communication Log File Target Plugin Pass-through Options
Logs communications between agent and server. (See 16.6 Debugging User-Supplied Kernel Modules, p.198.)
For more information on connecting in kernel mode and configuring the target to support KGDB, see 16.8 Using QEMU for KGDB Kernel Debugging, p.206.
170
14 Deploying to Targets 14.7 Using Target Server Options
14.7 Using Target Server Options

Target server options are passed to the tgtsvr program at the command line (user mode only). To choose advanced user mode features:
Enter the following options manually, or click Edit for GUI assisted editing.
Description
Advanced Option
Edit Target Server Options
Opens the Edit Target Server Options window. The options are subdivided into three tabbed groupsMemory, Logging, and Symbols. Sets how many seconds the target server waits for an answer from the target before sending a timeout, how often to retry, and at what intervals it should ping the target, (in seconds). The target server maintains a cache on the host system to avoid excessive data-transfer transactions with the target. By default, this cache can expand to 1 MB. A larger maximum cache size may be desirable if the memory pool used by host tools on the target is large, because transactions on memory outside the cache are far slower.
Timeout Options
Memory Cache Size
13
Logging
Options on the logging tab are used mainly by Wind River support for troubleshooting. A maximum size can be specified for each of these files. If so, files are rewritten from the beginning when the maximum size is reached. If the file initially exists, it is deleted. If the target server restarts (for example, reboots), the log file is reset. For the WTX (Wind River Tool Exchange) log file, you can specify a filter (a regular expression that limits the type of information logged). In the absence of a filter, the log captures all WTX communication between host and target. Use this option in consultation with Customer Support.
171
NOTE: The command line field is filled in based on the values you enter in this dialog box.
14.8 Using the Connection Summary Page

The Connection Summary page proposes a unique but modifiable Connection name, and a Summary of name and path mappings (Target Server Connection). You can set the following options:
SharedProvides the following functionality:
Target connection configurations are normally only visible for your user-id. If you define it as Shared, other users can also see the configuration in your registry, provided that they connect to your registry (by adding it as a remote registry on their computer, see Wind River Workbench Users Guide: Remote Registries. Typically, when you disconnect a target connection, the target server (and simulator) are killed because they are no longer needed. In a connection that is flagged as Shared however, they are left running so that other users can connect to them. You can flag a connection as shared if you want to keep the target server (and simulator) running after you disconnect or exit Workbench.
Immediately connect to target if possibleIf you do not want to connect to the target immediately, you can connect to the target later using one of the ways described in Wind River Workbench Users Guide: Debugging Projects.
If you have applications ready to run using the connection(s) you have just created, also see Wind River Workbench Users Guide: Launching Programs.
172
PA R T VI
Debugging and Analyzing

15 16 17 18 Debugging User Space ...................................... 175 Debugging Kernel Space ................................... 183 Optimizing ........................................................... 211 Analyzing Core Files .......................................... 221
173
174
15
Debugging User Space
15.1 Introduction 175 15.2 Using the Wind River Debugger 176 15.3 Debugging Using GDB 178 15.4 Stepping Through Your Output 178 15.5 Using Dynamic printf Breakpoint Statements 180 15.6 Sending Signals to Processes 181
15.1 Introduction
Wind River Workbench provides two types of user-space application debugging toolsthe Wind River Debugger (WDB) for remote debugging and the GNU Debugger (GDB) for self-hosted debugging. The Wind River Debugger provides Eclipse-based tools specifically intended for debugging user-space applications. GDB is a standard Linux debugging tool included in the Eclipse distribution. Both tools let you step through a compiled program, set breakpoints, and view the original source text simultaneously. You can also analyze a crash using a core dump. The following examples provide the instructions needed to debug the hello_world application using the Wind River Debugger and GDB.
175
For more information, see Knowing Which Debugger Gets the Breakpoints, in Wind River Workbench Users Guide: Working with Breakpoints, or the following website: http://download.eclipse.org/tools/cdt/docs/tutorials/debug_tutorial/cdt_w_ debug.htm. Figure 15-1 illustrates the user space debugging process in a typical product life cycle.
Figure 15-1 Debugging User Space: The Diagnosis Stage of the Product Life Cycle
User Space Requirements

File System Kernel Packages
Setup
Relevant Tools
Dynamic printf Launch Configurations Live Package Manager Remote System Explorer POSIX Signals Wind River Debugger
Develop
Diagnose
User Space Deliverables
Patches Unit Tests
Other Tools
GDB
Optimize
15.2 Using the Wind River Debugger

To use the Wind River Debugger, you must first create a remote connection to your target. In addition to using the local Workbench, you can use the Wind River Debugger to debug self-hosted applications from another instance of Workbench on another host. This allows you to use a 64-bit host, that you share with other 32-bit hosts, to develop 64/32 bit applications when 64-bit hosts are not available.
176
15 Debugging User Space 15.2 Using the Wind River Debugger
To debug self-hosted applications from another host, start the usermode-agent on the self-hosted machine as if it were a target, then connect to it from another host.
15.2.1 Creating a Remote Connection

To create a remote connection to your target: 1. 2. In the Remote Systems view, select WRLinuxHost_username. Click Connect to open a default output window and the usermode-agent.
NOTE: If WRLinuxHost_username is not connected, click Connect in the Debug dialog box.
3. 4.
Right-click WRLinuxHost_username and then, from the Workbench toolbar, select Debug > Debug Process on Target. Locate the Exec Path on Target text box. If there is no default path listed, browse to the location of the hello_world executable. The default location is workspace/hello_world_Native/Linux-gnu-native-3.x/ hello_world_Native /Debug/hello_world_Native. Select hello_world and click OK. Click Debug. The debugger runs and displays your output.
14
5. 6.
15.2.2 Viewing all Running Processes

You can use the Remote Systems view to display all processes running on the target, as well as the state of each process. To display all running processes: 1. 2. 3. In the Remote Systems view, expand Processes. Locate the process ID you want to view. Expand the process. If the entry for the process shows [Stopped], it has hit a breakpoint.
177
15.3 Debugging Using GDB

Use GDB to debug native-mode, self-hosted applications. To debug hello_world using GDB: 1. 2. 3. Right-click the hello_world_Native project folder. Select Debug As > Local C/C++ Application. Choose gdb Debugger. GDB runs and displays your output.
15.4 Stepping Through Your Output

The debugging process and viewable output is similar for both the Wind River Debugger and GDB. When you initialize the debugging process, both debuggers execute until they reach main( ). The Workbench Device Debug perspective displays the Debug view; an editor containing the source file; and other views that display typical debugging operations.
Figure 15-2 Debug View
178
15 Debugging User Space 15.4 Stepping Through Your Output
The Debug view provides the following process information:

Wind River Output
GDB Output
Process ID (PID) in the entry hello_world_Nat: PID (Task Mode). Entry hello_world_Nat: PID (Stopped - Breakpoint Hit). Breakpoint appears as main( ) helloworld.c:8. Execution is stopped at Line 8 in helloworld.c.
Process ID (PID) in the entry hello_world_Nat: PID (Task Mode). Entry hello_world_Nat: PID (Stopped - Step End). Breakpoint appears as main( ) helloworld.c:8. Execution is stopped at Line 8 in helloworld.c.
After you start the debugger, you can choose from the following functions:
Resume Restart a debugging session. Terminate End a debugging session. Disconnect Disconnect a remote host (Wind River remote debugging only). Step Into Single-step through code (step one line at a time.) Step Over Single-step through code without going into subroutines. Step Return After a step, continue execution until the current subroutine completes, then return control to the debugger in the calling statement. Toggle Assembly Stepping Mode Toggle between showing instruction-level steps or source-level steps. Clicking this button also causes Workbench to toggle between showing the Editor or showing the Disassembly view. Drop to Frame Resume until execution returns to the selected stack frame.
14
NOTE: You can use function keys for common activities. For a list, click Run in the Workbench toolbar.
To step through your output: 1. Click Step Over (or press F6). The program counter advances one line in the Editor and Hello World displays in the Console view. If variables are added to helloworld.c (and they have assigned values), click the Variables tab to display them. 2. Click Resume (or press F8) to continue stepping through the program. When the program has completed, the Debug view displays its exit status:
179
Wind River Output
GDB Output
<terminated, exit value: 0>hello_world_Nat: PID <terminated, exit value: \ 0>hello_world_Native [C/C++ Local Application]
15.5 Using Dynamic printf Breakpoint Statements

Dynamic printf event points let you set printf( ) breakpoint statements at run time. This powerful Workbench breakpoint feature lets you display int and char* values when processing reaches the statements. When no debugging information is available (for example, if your module has not been built in the Breakpoints view), the original line number appears, with the new line.
NOTE: Since these event points do not require stopping the current task, you can insert them into unbreakable tasks, but notice that the event is not raised if the routine is called from an interrupt handler. (Note also that Wind River System Viewer can report these events, as well.)
You can implement these event points as both software and breakpoints, and you can enable, disable, edit, or remove them just like regular breakpoints. To add a dynamic printf event point: 1. 2. Right-click in the editor or in the gutter. Select Add Dynamic printf from the context menu. This brings up the dynamic printf dialog. 3. Use this dialog to specify the printf arguments and other attributes. Workbench fills in the printf arguments for you, depending on their type. 4. Click OK to create the event point. The event point appears in the gutter, like any other breakpoint. For more information on this debugging tool, see Wind River Workbench Users Guide: Dynamic printf Event Points.
180
15 Debugging User Space 15.6 Sending Signals to Processes
15.6 Sending Signals to Processes

In POSIX systems, a signal is an asynchronous notification sent to a process when an event occurs. Sending a signal to a process interrupts its normal execution. Signals are defined in the header file signal.h in the C Standard Library. The debugger is alerted when a signal is sent to a process and displays a description in the Debug view. If a signal suspends a process, the Debug view shows the signal name and a description. For example, if a process is suspended because it receives a SIGHUP signal, the Debug view shows the following:
(Stopped - Signal Received: SIGHUP, Hangup)
You can resume a suspended process with or without a signal. The selected process resumes and discards pending signals. In the Debug view:
Right-click and select Resume Without Signal. or
Right-click and select Resume With Signal.

14
In both cases, a dialog box opens where you can select a signal and then click OK. The process resumes and immediately receives the selected signal.
15.6.1 Configuring a Signal

You can configure process signal attributes to pass signals to a process or to force a process to suspend when it receives a signal. 1. 2. Right-click the process in the Debug view and select Edit Signal Configuration. A dialog box opens where you can configure signal attributes. Select an attribute and click its value to toggle between true and false.
181
Attribute
Description
Values
Pass
Controls whether or not a trueProcess silently discards the signal sent to a process should signal. pass. falseProcess cannot silently discard the signal. Controls whether or not the trueSignal suspends the process process should suspend when when the process receives it. it receives the signal. falseProcess continues running after it receives the signal.
Suspend
15.6.2 Terminating a Process

You can terminate a process and remove all terminated launches using the Debug view.
Terminate Click Terminate. Remove launches Click Remove All Terminated Launches.
182
16
Debugging Kernel Space
16.1 Introduction 184 16.2 Background Steps and Concepts 185 16.3 Preparing the Target for KGDB 190 16.4 Connecting with KGDB from Workbench 192 16.5 Attaching and Debugging the Kernel from Workbench 196 16.6 Debugging User-Supplied Kernel Modules 198 16.7 Creating a Custom Kernel Module 205
16.8 Using QEMU for KGDB Kernel Debugging 206 16.9 Enabling and Disabling KGDB in the Kernel 209
183
16.1 Introduction
Wind River Workbench provides source-level debugging for Linux 2.6 kernels that support the Kernel GNU Debugger (KGDB).
NOTE: If you are not using a Wind River Linux platform, contact Wind River support about configuring your kernel for symbolic debugging with Workbench.
With KGDB installed, you can debug the kernel in the same way that you debug applications, including stepping through code, setting breakpoints, and examining variables. Kernel mode debugging between Workbench and the target takes place over a serial protocol connection, which may be over a serial line or Ethernet.
NOTE: With Wind River Linux, kernel debugging is enabled by default, and you only have to turn it off when going to production.
Wind River is a contributor to the KGDB open source project. Basic information on KGDB can be found at http://sourceforge.net/projects/kgdb/. Wind River has added several features to the mainline KGDB, including:
Functionality that is tested on all supported boards Support for CPU auto-detection Additional flags and test features added to the KGDB agent
For information on using the command line to debug with KGDB, to enable or disable KGDB, or to build your own cross-architecture gdb, see the Wind River Linux Users Guide.
184
16 Debugging Kernel Space 16.2 Background Steps and Concepts
Figure 16-1
Debugging Kernel Space: The Diagnose Stage of the Product Life Cycle
Kernel Debug Requirements

File System Kernel Kernel Modules
Setup
Relevant Tools
agent-proxy CPU Auto-Detection NFS-Mounted File System POSIX Signals QEMU Wind River Debugger
Develop
Diagnose
Kernel Debug Deliverables
Kernel Modules Patches
Other Tools
KGDB Multiple Connection Types Safe Areas User-Supplied Kernel Modules Wind River Flags and Features
Optimize
Figure 16-1 illustrates in brief the topics covered by this chapter: various tools that help you debug kernel space.
NOTE: See 15.5 Using Dynamic printf Breakpoint Statements, p.180, for a brief
description of dynamic printf event points, which let you set printf( ) breakpoint statements at run time, without recompilation.
16.2 Background Steps and Concepts

This section briefly describes how to set up KGDB to work over subnets using agent-proxy. It describes how to mount the target file system and how to disable KGDB, which is enabled by default.
185
16.2.1 Setting Up for kgdboe Between a Target and a Development Host

KGDB over Ethernet (kgdboe) is designed to work within single subnets, because it is based on unicast UDP packets. The connection is from the host over UDP to the target, using the standard port 6443 for KGDB, as sketched in the following figure:
Figure 16-2 Connecting from the Host to the Target for KGDB
Subnet 192.168.99.* Target Kernel IP 192.168.99.123 UDP Port 6443 (kgdboe) Target
Workbench IP 192.168.99.77 Development Host
16.2.2 Using agent-proxy to Cross Subnet Boundaries for kgdboe

Wind River Linux provides a utility that can convert TCP connections on an intranet to UDP connections in a subnet. If there is an available host that sits on both the intranet and the subnet, the utility agent-proxy can provide this required access. agent-proxy is in the host-tools/bin directory, which you would copy to the bridging host. Example instructions for using agent-proxy: 1. Log into the bridging host. In this example, the bridging host has one Ethernet connection on the intranet (208.77.190.11), and a second Ethernet connection on the targets subnet (192.168.29.11). (See Figure 16-3.)
186
Figure 16-3
Using agent-proxy to Bridge Subnets
Intranet ETH0: 208.77.190.11 Workbench From: TCP Port 3333 agent-proxy To: 192.168.99.123 UDP Port 6443 ETH1: 192.168.99.11 Development Host Bridging Host
Subnet 192.168.99.*
Target Kernel IP 192.168.99.123 UDP Port 6443 (kgdboe)
IP 208.77.188.166
Target
2.
Start a copy of agent-proxy. This will connect the TCP port 3333 to the UDP port 6443 from 192.168.99.123
$ ./agent-proxy 3333 192.168.99.123 udp:6443
3.
Log into the target (192.168.99.123), and enter the following command. This starts the kgdboe agent, connected to the bridging host.
root@target:/> modprobe kgdboe kgdboe=@192.168.99.123/,@192.168.29.11/
4. 5.
Log into the development host on the intranet. Start Workbench and create a kgdboe connection with these parameters:
TRANSPORT=TCP CPU=default IP=208.77.190.11 Port=3333
Workbench connects to the TCP port 3333 on 208.77.190.11, and treats it like a normal KGDB connection.
NOTE: You can have any number of agent-proxy connections running on the bridging host, one for each target within the subnet. Just assign a different TCP port, for example 3334, 3335, 3336, and so forth.
If you run agent-proxy without any parameters, it returns a list of its commands and abilities, as shown below:
$ wrlinux/host-tools/bin/agent-proxy agent-proxy version 1.6
187
Usage: agentproxy <[udp:][virt IP:]local port> <remote host> <[udp:]remote port> For udp wdb agent proxy example for default ports agentproxy udp:0x1001 10.0.0.2 udp:0x4321 agentproxy udp:0x1002 remotehost2 udp:0x4321 For KGDB udp target to udp host with default g agentproxy udp:3331 10.0.0.2 udp:6443 For KGDB udp target to tcp host with default g agentproxy 3332 10.0.0.3 udp:6443 Also you can bind to a local vitual interface IE: agentproxy udp:47.1.1.2:0x4321 10.0.0.2 udp:0x4321 agentproxy udp:47.1.1.3:0x4321 10.0.0.3 udp:0x4321 agentproxy udp:47.1.1.3:6443 10.0.0.3 udp:6443 agentproxy 47.1.1.3:44444 10.0.0.3 44444
The KGDB over serial connection does not have this limitation. You will need a physical serial cable that can make the connection; or, alternatively, you can set up a Telnet port repeater that connects the serial connection to a Telnet port on the intranet.
16.2.3 Mounting the Targets File System using NFS

If you already have the NFS image mounted to your targets file system, skip this section. To allow kernel module transfers from the host to the target, especially if your target is NFS mounted via pxeboot: 1. 2. 3. Open a console on your host. Log in as root. Create a mount directory for the target rootfs.
$ mkdir /target $ chmod a+rw /target
4.
Mount this directory. In this example, the many lab boards get their root file systems from NFS directories on a shared host.
$ mount t nfs ala-tuxlab://export/pxeboot/my_board/rootfs /target
5.
Exit root.
188
16.2.4 Kernels: Enabling KGDB versus Debug Builds

KGDB is a Linux kernel configuration option (as opposed to compiling the kernel using the debug flags.) By default, the pre-built and configured Wind River Linux kernels have KGDB support enabled. You can configure a platform project with --enable-debug, but this has no effect on KGDB and only applies to the package builds. The pre-built or generated vmlinux file contains all the debug information required for the kernel. To disable KGDB, see 16.9 Enabling and Disabling KGDB in the Kernel , p.209.
16.2.5 KGDB and Safe Areas when Debugging the Kernel

Due to the nature of KGDB debugging, not all sections of the kernel can be safely or reliably debugged. In kgdboe, for example, it is impossible to debug the Ethernet driver itself, or any of its related services. In general, the kgdb8560 serial interface option has fewer dependencies, but it still has sections where it cannot go, and it runs more slowly than the Ethernet connection. The On-Chip Debugger (OCD) has the fewest restrictions on where it can debug, since it does not rely on kernel services at all, but it does require additional hardware. Also, there will be different behavior in parts of the kernel depending on the specific architecture or configuration. If a common breakpoint location (for example, do_fork) does not seem to work on a particular installation, note it and find an alternative break location. While these restrictions may discourage some people from employing interactive kernel debugging, this feature does provide some advantages over simply using printk. Here are some of the sections of the kernel code to avoid:
Spin locks. The Ethernet driver has several spin locks, and if you attempt to step over one that is needed, the connection locks up. Printk. This routine also has spin locks that freeze the KGDB connection. Simultaneous usermode-agent connections. The two debugging connections indirectly and unavoidably share some spin locks.
189
16.3 Preparing the Target for KGDB

You must start the KGDB agent on the target before you can make any connection from Workbench. You can use two connection methods to connect to KGDB: the first over the Ethernet using UDP, and the second using a serial connection, either directly to a COMM port or over Telnet. The Ethernet KGDB connections are typically much faster than serial connections.
16.3.1 Option 1: Using a UDP Connection on a Non-PCD Target

On the target with the KGDB-enabled kernel, find the IP address of the target and the IP address of the host where you will be running gdb/Workbench. The kgdboe module usage syntax follows. Typically you do not need to enter the source port or the host MAC address.
kgdboe=[src-port]@[src-ip]/[dev],[hst-port]@hst-ip/[hst-macaddr]
Wind River recommends that you explicitly call out the Ethernet port, because this guarantees that kgdboe uses the correct port (kgdboe does not know which port the device was booted with). Since many boards have multiple Ethernet ports, the default of eth0 may not be correct.
Target_# modprobe kgdboe kgdboe=@/eth2,@192.168.29.107
NOTE: To underline this point, if a board has multiple Ethernet ports, and/or the port you want is not the default port, you must explicitly select the alternate Ethernet port. You can use ipconfig to identify the proper port to use.
If you have problems connecting to KGDB, double check which port is configured and connected to the network. If, for example, the modprobe command takes a long time to return, it may be accessing or defaulting to a port that is not connected, and the only other sign of error is that kgdboe connections do not succeed. Here are some common short cuts for starting kgdboe:
This version assumes the default Ethernet port, for example eth0:
target_# modprobe kgdboe kgdboe=@/,@192.168.29.107/
This version explicitly calls out the targets IP address:

target_# modprobe kgdboe kgdboe=@192.168.29.96/,@192.168.29.107/
You can now skip to 16.4 Connecting with KGDB from Workbench, p.192.
190
16 Debugging Kernel Space 16.3 Preparing the Target for KGDB
16.3.2 Option 2: Using a UDP Connection on a PCD Product

In the Wind River Platform for Consumer Devices (PCD) product, the kgdboe module is statically and automatically linked into the kernel. There are two ways to configure the kgdboe module, as described below.
Statically Configuring KGDBOE for PCD (uclibc_small+small)
The first method is to add the kgdboe configuration into the boot command. You must know the IP address of both the target and the host at boot time. You can immediately connect with KGDB any time after the boot completes. For example, if you had:
Target IP: 10.1.1.12 Host IP: 10.1.1.111
On the boot line you would need

kgdboe=@10.1.1.12/,@10.1.1.111/
So the boot line would look like:

boot root=/dev/nfs rw console=ttyS0,115200 kgdboe=@10.1.1.12/,@10.1.1.111/ nfsroot=10.1.1.111:/rootfs ip=10.1.1.12:: 10.1.1.1:255.255.255.0:mainstone:eth0:off mem=128M
And during the boot you would see:

kgdboe: device eth0 not up yet, forcing it eth0: link down eth0: link up, 100Mbps, full-duplex, lpa 0x45E1 kgdboe: debugging over ethernet enabled kgdb: Defering I/O setup to kernel module.
Dynamically Configuring KGDBOE for PCD (uclibc_small+small)
The kernel now also supports the new dynamic kgdboe configuration when used as a kernel built-in. Use the following command:
$ echo @/,@10.1.1.111/ > /proc/sys/kgdboe
To see the current configuration, enter:

$ cat /proc/sys/kgdboe
191
NOTE: Since the device has booted, you do not need to specify its IP address.
16.3.3 Option 3: Using a Serial/Telnet Connection

On the target with the KGDB-enabled kernel, determine the IP addresses of the both the target and the host where you want to run gdb or Workbench. The kgdb-8250 module usage syntax is:
8250_kgdb kgdb8250=com-port,baud-rate
This example is for a COM1 connection at 115200 baud:

target_# modprobe 8250_kgdb kgdb8250=0,115200
This example is for a COM2 connection at 9600 baud:

target_# modprobe 8250_kgdb kgdb8250=1,9600
Do not use a port that has a console attached to it. You may make a connection, but it cannot work because the console attempts to interpret the KGDB data as typed commands. Also, for 9600 baud connections, you may want to reduce the KGDB watch options to achieve reasonable performance.
16.4 Connecting with KGDB from Workbench

This section describes creating a Target Connection for KGDB from Workbench. This assumes that the KGDB agent is already running on the target, as described in 16.3 Preparing the Target for KGDB, p.190.
16.4.1 Option 1: Making an Ethernet Connection

1. 2. From the Remote Systems view, click New Target Connection. Select Wind River Linux KGDB Connection and click Next.
192
16 Debugging Kernel Space 16.4 Connecting with KGDB from Workbench
3. 4.
Select Linux KGDB via Ethernet and click Next. Select UDP as the transport.
NOTE: If you are using the agent-proxy, make this a TCP connection, as described in 16.2.2 Using agent-proxy to Cross Subnet Boundaries for kgdboe, p.186.
5.
Use the Default from Target CPU default.

NOTE: Select the architecture only if necessary (for Pentium targets, use Pentium4 instead of ia32). Use the new architecture families when explicitly selecting the target CPU type.
6.
Enter the targets IP address. The IP address must match the setting from 16.3.1 Option 1: Using a UDP Connection on a Non-PCD Target, p.190.
7.
Use port 6443. This port is reserved for KGDB connections. If you are using the agent-proxy, select the respective agent-proxy port number, as described earlier.
8. 9. 10.
Click Next. Select Target OS Linux 2.6 if it is not already set. For the Kernel Image, point to your kernels vmlinux file and click Next.
$ mybuild/export/*-vmlinux-*
If you have built the kernel, the physical location of the new symbol file is at
$ mybuild/build/Linux-2.6.14/vmlinux
NOTE: Do not select the kernel image itself (for example the bzImage file).
11.
In the Object Path Mappings page, click Add, set the following values, and click OK:
Target Path = (leave empty) Host Path = /target/
12.
Click Next through the following dialog boxes, then click Done. It may take 20 to 40 seconds to load all the kernel symbols. When it completes, a red S appears on the vmlinux element in the targets connection tree.
193
NOTE: Make sure that the target has started the module kgdboe before opening the connection in Workbench; otherwise you will get a timeout and an connection error summary.
When the connection is successful, the Remote Systems view displays the connected message, and the kernel is shown as Stopped. Proceed to 16.5 Attaching and Debugging the Kernel from Workbench, p.196. If the connection fails, go to 16.4.4 Troubleshooting a KGDB Connection , p.195.
16.4.2 Option 2: Making a Telnet Connection

A port selector device can aggregate multiple serial port connections into telnet connections that can be made available across the network. The IP address for this telnet virtual connection would be the one for this port selector device, and the port number would be the one for the port of that target. For example, if your multiplexer digiswitch_1 were at 192.168.29.2 and the Telnet serial port for the target were 2011, then the IP address would be 192.168.29.2, and the port would be 2011. To make a KGDB telnet connection: 1. 2. 3. 4. 5. From the Remote Systems view, click New Target Connection. Select Wind River Linux KGDB Connection and then click Next. Select the connection option Linux KGDB via Terminal Server and then click Next. Select TCP as the transport. Use the Default from Target CPU default.
NOTE: Select the architecture only if necessary (for Pentium targets, use Pentium4 instead of ia32).
6.
Enter the targets IP address. The IP address must match the device providing the Telnet connection.
7. 8.
Enter the telnet port. Click Next.
Proceed to 16.5 Attaching and Debugging the Kernel from Workbench, p.196.
194
16 Debugging Kernel Space 16.4 Connecting with KGDB from Workbench
If the connection fails, go to 16.4.4 Troubleshooting a KGDB Connection , p.195.
16.4.3 Option 3: Making a Serial Cable Connection

To make a serial cable connection: 1. 2. 3. 4. From the Remote Systems view, click New Target Connection. Select Wind River Linux KGDB Connection and click Next. Select the connection option Linux KGDB via RS-232 and click Next. Select the Baud rate, Data Bits, Parity, Stop Bits, and Flow control appropriate to the connection. Note that the baud rate must match the setting from 16.3.3 Option 3: Using a Serial/Telnet Connection, p.192. Click Next.
5.
Proceed to 16.5 Attaching and Debugging the Kernel from Workbench, p.196. If the connection fails, go to 16.4.4 Troubleshooting a KGDB Connection , p.195.
16.4.4 Troubleshooting a KGDB Connection

If the connection fails, troubleshoot by answering the following questions:
Is the KGDB agent on the target running? Use the lsmod command on the target to see if the module is loaded. Is the KGDB agent using a functional network connection? For example, run the command ifconfig on the target and confirm that the kgdboe agent is using the correct Ethernet connection. Are all the IP addresses for the target and host correct? Run ifconfig on both the target and host. Are the target and host connected? Use the ping command to query the target from the host and the host from the target. The ping command uses TCP and KGDB uses the more restrictive unicast UDP packet; make sure that you are on the same subnet or have setup an intranet-to-subnet agent. Is there a firewall? Make sure that there are no firewalls on the host or target blocking the connection. Is there more than one copy of the Wind River WTX Target Registry running? Use the kill command to end any running copies and then restart Workbench.
195
Can your host locate the target? Make sure you have declared 127.0.0.1 localhost within your /etc/hosts file so the Remote Systems view can find the Target Registry on the host. Is your debug log turned on? You can turn on the debug log for your KGDB connection by adding the following options in the connection wizard. a. b. c. Right-click the connection and select Properties. Enter a location for the log in the Backend Log field. Try to connect again.
d. Select Help > Collect Logfiles. This gathers the connection log files. e. Forward the log files to the Wind River Support team.
16.5 Attaching and Debugging the Kernel from Workbench

After you establish a KGDB connection, Workbench lets you access the target kernel and debug source code. If the connection fails, see 16.4.4 Troubleshooting a KGDB Connection , p.195. Once the connection is established, Workbench shifts to the Embedded Debug perspective and the Editor opens to the stopped location in the kgdb.c source file. If you use the pre-built vmlinux file that comes with the pre-built kernel (in wrlinux-1.x/boards) the path to the source files is not immediately known to Workbench. To resolve this. right-click the entry in the Debug view and then select Edit Source Lookup.
16.5.1 If the Compilation Unit Source Is Not Found

If the Editor where kgdb.c should appear instead displays a message that says Source not found for compilation unit, your vmlinux file is either missing or, more likely, does not point to the current location of your Linux kernel source. To fix this: 1. Click the Browse button in this error message and navigate to your Linux kernels source directory.
196
16 Debugging Kernel Space 16.5 Attaching and Debugging the Kernel from Workbench
If you have performed a make fs, make C dist linux, or a make all, the Linux source folder will have been expanded in your projects build folder; for example, /home/user/workdir/myBoard/build/linux-2.6.14-type. 2. Click Next until you can click Finish. Workbench resolves the location of kgdb.c and any other kernel source. You can view the mappings between the object files and the respective source files by right-clicking the entry in the Debug view and selecting Edit Source Lookup.
16.5.2 If the Targets Terminal Is Stopped

If you have a terminal open to the target, you may see that it is stopped. For example, you may not be able to enter commands in the terminal. To resume execution of the kernel, click Resume in the Debug view.
16.5.3 Setting and Removing a Sample Breakpoint

With the kernel running again, set a breakpoint as follows: 1. 2. 3. Select Run > Add Expression Breakpoint. In the Breakpoint Location and General Attributes dialog, enter do_fork in the Location Expression box. Click OK.
NOTE: If the do_fork location as a breakpoint does not work on this installation, note it and choose another kernel entry point. For possible explanations, see 16.2.5 KGDB and Safe Areas when Debugging the Kernel, p.189.
4.
Enter a command, for example ls (press ENTER only once,) on the target. It does not return because execution has stopped at the fork. The Editor opens the fork.c source file. Click Resume in the Debug view to allow the command to complete; the next fork, for example another command, again causes a break.
5. 6.
To complete this example, remove the breakpoint and click Resume in the Debug view to continue execution of the kernel. To end the session, right-click the target connection in the Remote Systems view and select Disconnect.
197
16.6 Debugging User-Supplied Kernel Modules

Workbench includes a sample project to demonstrate kernel module debugging. This example requires that you have access to the kernel source you used to build the kernel and that you have terminal or console access to the target.
16.6.1 Building the Sample User-Supplied Kernel Module

NOTE: You must have the full kernel built in your project. If not, the infrastructure for building kernel modules is not configured properly.
To build the sample user-supplied kernel module: 1. 2. Open a Workbench project. Right-click the kernel_build build target and select Build Target. Typically, the kernel takes about 30 minutes to build. 3. 4. 5. Select File > New > Example. Select Wind River Linux Kernel Module Sample Project and click Next. Select The Kernel Module Debug 2.6 Demonstration and click Finish. A new project called moduledebug_2_6 appears in the Project Explorer. 6. Select a platform project and do the following: a. b. c. Select Project > Properties > Project References. Select the checkbox for moduledebug_2_6. Click OK. The moduledebug_2_6 project disappears from the Project Explorer and appears in the platform project tree. 7. 8. Open the platform project and find the sub-project moduledebug_2_6. Right-click the sub-project moduledebug_2_6 and select Build Project. The module moduleDebugExample.ko appears in the directory of the moduledebug_2_6 project. If you do not see it under the project icon, right-click the project and select Refresh. Remember, for the kernel module to build, the Linux kernel must be already built (by building the kernel_build build target in the platform project).
198
16 Debugging Kernel Space 16.6 Debugging User-Supplied Kernel Modules
9.
Right-click on the moduledebug_2_6 sub-project and select Properties > Build Properties. You can see how the kernel root directory, target architecture, and cross compile prefix are set from the parent platform project.
You can add additional build options by appending them to the Build command entry make.
16.6.2 Debugging a Running User-Supplied Kernel Module

To debug a user-supplied kernel module that is currently running: 1. In the terminal or console on the target, get the new file to the target, and use the insmod command to install the module.
kgdb_target_$ sftp your_host kgdb_target_$ cd myhome/workspace/moduledebug_2_6 kgdb_target_$ get moduleDebugExample.ko kgdb_target_$ quit kgdb_target_$ insmod moduleDebugExample.ko
2.
Ensure that you can see periodic output from the user module. Enter the following command:
kgdb_target_$ klogd c 8
This command re-directs the kernel print statements to the console. You will see a message display every second or so. You may want to open an ssh or second Telnet session to remove this module when you are done. If klogd is already running and there is no output, you can locate the PID, kill the current instance, and then restart the demon. For example:
kgdb_target_$ cat /var/run/klogd.pid 1084 kgdb_target_$ kill 1084 kgdb_target_$ klogd c 8
If you still do not see output, enter the following command:

kgdb_target_$ cat /proc/kmsg
Two messages are internally printed: a global and a local message. Depending on the display level, you might see both messages interspersed. If the Workbench Remote Systems connection is connected to the target, disconnect. After Workbench is running, reconnect to the target with the KGDB connection.
199
If you have placed moduleDebugExample.ko in a location other than the root, adjust the target connection object mapping list to include that location and then connect to the target. Make sure that the host path contains a forward slash (/) at the end. 3. Find the moduleDebugExample.ko entry in the Remote Systems view. If it does not have a red S mark on its icon, right-click it and select Load Symbols. The red S appears, indicating that symbols have been loaded. If the symbols do not load, or if moduleDebugExample.ko does not appear in the Remote Systems view, go to the platform projects Object Path Mappings screen, click Add, set the following values, and click OK:
Target Path = (leave empty) Host Path = /target/
4. 5. 6.
Right-click the Arch (OS) entry in the Remote Systems view and select Attach to Core. Click Resume in the Debug view so that the kernel is Running. Double-click bpHere.c in the moduledebug project. It appears in the Editor. Right-click in the gutter to the left of bpHere.c at line 21 (printfk(KERN_ALERT ) of the routine putBreakPointHere. Select a System Context breakpoint.
NOTE: If you find that the break point cannot be planted, make sure you added
the Object Mapping. 7. 8. Once it breaks (as seen in the Debug view), try single steps in and then out of this procedure. Then click Resume. When it breaks again, disable the breakpoint and click Resume.
You can remove the module from the kernel with the rmmod command:
kgdb_target_$ rmmod moduleDebugExample.ko
16.6.3 Stepping into User-Supplied Kernel Module init from module.c

You can place a breakpoint in the kernel module load routine and step directly into a loading module init routine.
200
This technique can be used in many ways beyond this example. See the following section for ways to break within specific kernel module init routines, loaded or not. 1. Select File > Open File and browse to the kernel subdirectory of your builds Linux-2.6.14 source tree root. For example, module.c might be found at:
/home/user/workdir/myboard/build/linux-2.6.14-type/kernel/module.c
2. 3.
Double-click the module.c file to open it in the Editor. Go to the sys_init_module routine and find the lines that call the modules init procedure (search for the string Start the Module).
=> /* Start the Module */ if (mod->init != NULL) ret = mod->init();
4. .
Right-click in the gutter to insert a System Context breakpoint.

NOTE: If the breakpoint cannot be planted, make sure you added the Object Mapping as described earlier. Also, do not single step from the break at sys_init_module to this location you will hit spin locks that will block your KGDB connection.
5.
On the target, start the module:

kgdb_target_$ insmod moduleDebugExample.ko
The Debug view shows the System Context as stopped, and load_module is highlighted; the Editor opens module.c to the location of the breakpoint. Note that the target terminal is hung at the insmod command. 6. Ensure that the moduleDebugExample.ko is registered by the Remote Systems view. Examine the terminal for your target connection, and look for moduleDebugExample.ko in the list on installed kernel modules, under Processes. If is not present, take the following steps to synchronize the Remote Systems view: a. b. c. Collapse the Processes node for the target. Click Refresh in the Remote Systems view. Expand the Processes node for the target again.
d. It the module does not yet appear, repeat the above steps. 7. Ensure that the symbols for moduleDebugExample.ko are loaded. Examine the Remote Systems view for your target, and look for
201
moduleDebugExample.ko in the list of installed kernel modules, under Processes. The icon for this module should be marked with a red S. If it is not, right-click the module and select Load Symbols. You can now single step into the initialization routine of the kernel module. 8. 9. 10. To resume processing, remove the breakpoint and click Resume in the Debug view. The insmod command completes. You can remove the module from the kernel with the rmmod command:
kgdb_target_$ rmmod moduleDebugExample.ko
When you remove the module, notice that moduleDebugExample.ko is no longer registered in the Remote Systems view.
16.6.4 Placing Breakpoints in Modules Not Yet Loaded

When a kernel module is loaded, it tries to load the symbol table and place any pending breakpoints. You can make use of this to break in the init routine of a kernel module, as follows: 1. 2. 3. 4. 5. Right-click the GDB target connection entry in the Remote Systems view. Select Properties > Object Path Mapping. Click Add. Leave the Target Path empty. Click Browse for the Host Path, and select workspacedir/moduledebug_2_6 for the directory where the generated moduleDebugExample.ko file is located. Click OK for the path and in the connection properties dialog to make the connection to the target. If that connection is already active, disconnect and reconnect to assert the new mappings. Click Resume so that the target is running. Right-click in the left gutter of the bpHere.c or modules.c source file at the location indicated for the breakpoint, and select Breakpoint > Add Breakpoint (Scope = System Context). You can change the scope of any breakpoint by clicking it in the Breakpoints view.
6.
7.
202
NOTE: If you see a dialog stating that the location for the breakpoint is not available, remember that the module is not currently loaded. Click OK to continue. If you close the source file you will see that Workbench opens it when the breakpoint is hit.
8.
Load the module on the target.

$ insmod moduleDebugExample.ko
Observe the breakpoint being hit, and the source being opened to that location. You can now debug the init routine, or resume the execution. 9. When you are finished, remove the module:
$ rmmod moduleDebugExample.ko
You may see another dialog stating that the location for the breakpoint is not available, because the module is unloaded. Click OK to continue.
16.6.5 Providing Object Path Mappings to All Modules

For Workbench to find the appropriate source file for a module, it requires the path to the object files. However, , the kernel modules for a given kernel may be scattered across many subdirectories, making it a tedious task to specify all of them. To gather all those paths and make them available to Workbench, use the following procedure: 1. 2. In Workbench, build the kernel_build target so that all kernel files are available. Select Project > Open Shell and enter the following command:
$ cd build/linux-version-type
The shell now opens automatically in the project_prj directory. 3. Create a link to all kernel modules within the Linux kernel, and place them in this directory:
$ foreach file (` find . -name "*.ko" -print`) foreach? ln -s $file foreach? end $
4.
Add this object path mapping to your KGDB connection: a. Right-click the specific KGDB target connection entry.
203
b. c.
Select Properties > Object Path Mapping. Click Add.
d. Leave the Target Path empty. e. f. 5. Browse for the Host Path; select projectname_prj/build/linux-version-type. Click OK for the path, then OK for the target connections properties dialog.
Make the connection to the target. If that connection is already active, disconnect and reconnect to assert the new mappings.
You can now place breakpoints in any kernel module source, have them planted by Workbench, hit those breakpoints, and have Workbench always be able to bring up the correct source file.
16.6.6 Using the testmod Enhanced Sample Kernel Module

Workbench includes a sample kernel module that demonstrates the following features:
A simple kernel module. The file main.c initializes and removes the module. Parameter passing. A kernel timer. The file timer.c manages the timers. The sysctl command to change the timeout. The file settings.c manages the sysctl bindings.
To create a new kernel module project: 1. 2. 3. 4. Select File > Example. Select Wind River Linux Sample Project and click Next. Select Wind River Linux Kernel Module Sample Project and click Next. Select the Example Kernel Module Demonstration and click Finish. A new project called testmod appears in the Project Explorer. 5. Select and open an existing platform project in Workbench: a. Select Project > Property > Project References, then select testmod. Note that the testmod project disappears from the Project Explorer and appears in the platform project tree.
204
16 Debugging Kernel Space 16.7 Creating a Custom Kernel Module
b. c.
Open the platform project and find the sub-project testmod. Right-click testmod and select Build Project. The module testmod.ko appears in the directory of the testmod sub-project. If you do not see it under the project icon, right-click on the project and select Refresh.
NOTE: For the kernel module to build, the Linux package must be already built (by building the Linux build target, for example).
6.
In the terminal or console on the target, use the get command to move the new file to the target and then use the insmod command to install the module.
kgdb_target_$ kgdb_target_$ kgdb_target_$ kgdb_target_$ ftp your host cd myhome/workspace/moduleDebug get testmod.ko quit
kgdb_target_$ insmod testmod.ko timeout=2340
7.
Verify that the console output shows testmod:

kgdb_target_$ dmesg | tail Loading testmod timeout is 2340
You can use various additional sysctl supported commands to work with this module. For example:
sysctl -a shows all variables. sysctl dev.testmod.timeout queries variables. sysctl dev.testmod.timeout=5000 sets variables.
You can also query and set variables using /proc/sys/dev/testmod/timeout. 8. When you are finished, remove the module with the following command:
kgdb_target_$ rmmod testmod.ko
16.7 Creating a Custom Kernel Module

Workbench lets you create custom kernel module projects. To create a custom module, use the following procedure:
205
1. 2.
Select File > New > Example > WR Linux Kernel Module Project. Give the project a name, for example custom_lkm. Click Next. To attach this project to a platform project within Workbench, leave these values empty. To connect this custom kernel module to a platform project outside of Workbench: a. b. Fill in the Linux Kernel Directory, its ARCH, and its CROSS_COMPILE value. (You can edit these values later using the projects Build Properties.) Click Finish.
3.
Right-click the project and select Import > General > File System.
NOTE: The code for this kernel module is borrowed from an existing Wind River Linux sample project. You can import your own module code if you have some available.
4. 5. 6.
Browse to installDir/wrlinux-3.0/samples/moduledebug_2_6. Select the files bpHere.c and moduledebug.c and click Finish. You can now build this project:
If you have attached this project to an external platform project. If you have attached this project to an existing Workbench platform project as described in 16.6 Debugging User-Supplied Kernel Modules, p.198.
This module is now ready for deploying and testing.
16.8 Using QEMU for KGDB Kernel Debugging

The Quick Emulator (QEMU) offers two types of kernel-mode debugging, using KGDB:
In-circuit emulator (ICE)-like debugging using the KGDB agent built into QEMU. This allows you to debug areas, such as exception vectors and Ethernet drivers, that regular KGDB-on-target debugging normally does not allow. (See 16.2.5 KGDB and Safe Areas when Debugging the Kernel, p.189.)
206
16 Debugging Kernel Space 16.8 Using QEMU for KGDB Kernel Debugging
A KGDB over Ethernet (kgdboe) agent running inside your kernel, on your target, loaded using the modprob command. This type of connection can show you, for example, the context that has caused a panic( ) state in the target.
This section describes ICE-like connection debugging. To create an ICE-like connection and open the target kernel in the debugger: 1. 2. 3. 4.
In the Remote Systems view, click Create a New Target Connection. Select Wind River Linux KGDB Connection and click Next. Select Linux KGDB via Ethernet and click Next. In the Linux KGDB Connection Properties dialog box, choose or enter the following, then click Next. Back End: TCP CPU: ARM9-LE (or any supported QEMU connection) Name/IP Address: localhost Port: 1234 Target Plugin Pass-through Options: notasklist=1
207
5.
In the Kernel image field in the Target Operating System Settings dialog, enter the name and path of the Linux kernel symbol file, using the syntax project_prj/export/boardName-vmlinux-symbols-version_fsType. For example:
project_prj/export/arm_versatile_926ejs-vmlinux-symbols-WR3.0ao_standard 6. 7. 8. 9. Click Next until you reach the Connection Summary dialog. Enter a name for the new connection. Select the Immediately connect to target if possible checkbox. Click Finish. The new connection appears in the Remote Systems view, and the debugger opens onto the kernel running on the emulated target.
208
16 Debugging Kernel Space 16.9 Enabling and Disabling KGDB in the Kernel
At this point, the debugger has attached the KGDB agent in QEMU on the target side, halted the target, and stopped in the kernel. 10. In the Debug view, click Resume to resume the target operation.
You can now do any kernel mode debugging that you would normally do using in-circuit emulation with a real target.
16.9 Enabling and Disabling KGDB in the Kernel

By default, KGDB is enabled in the pre-built and generated Wind River Linux kernels. To disable KGDB (for example, when transitioning to production builds) use the following steps: 1. Double-click the projects Kernel Configurator icon in the Project Explorer. If you have not previously extracted the kernel, answer Yes when Workbench prompts you to extract the kernel files. 2. 3. Open the Kernel Hacking tree. Double-click the Compile the kernel with debug info menu item to toggle between Yes and No.
209
4. 5.
Select File > Save, to capture the configure changes. Right-click the projects build target kernel_rebuild.
The new kernel and vmlinux file are available in the workspaces projectname_prj/export directory.
210
17
Optimizing
17.1 Introduction 211 17.2 Managing File System Layout 212 17.3 Profiling CPU Usage with OProfile 213 17.4 Analyzing Code Execution Coverage 213 17.5 Analyzing Memory Problems with mpatrol 214 17.6 Using the System Viewer 214 17.7 Improving Boot Time 215 17.8 Optimizing Footprint 215
17.1 Introduction
Wind River tools can help when you want to analyze your projects footprint, memory use, code profile, and so on. In addition, Workbench and the Linux Platforms products incorporate some open-source tools related to profiling and memory usage.
211
Figure 17-1
The Optimize Stage of the Product Life Cycle
Optimization Requirements
Applications File System (FS) FS Change List Kernel Unit Tests
Setup
Relevant Tools
File System Layout Indexer mpatrol Memory Analysis OProfile CPU Analysis System Viewer
Develop
Optimization Deliverables
Applications File System (FS) FS Change List Kernel Non-Binary Files Patches
Diagnose
Other Tools
Boot Time Tools
Optimize
Figure 17-1 lists some of the major analysis and optimization tools:
File System Layout Tools Wind River System Viewer Wind River Analysis Tools (formerly Wind River ScopeTools)
See also 18. Analyzing Core Files.
17.2 Managing File System Layout

You can use the File System Layout Configuration tool for the following optimization purposes:
Adding and removing files and directories to and from the file system. Finding running totals of estimated file system sizes, thus allowing you to see changes as you use the tool.
212
17 Optimizing 17.3 Profiling CPU Usage with OProfile
Exporting file dependencies so users can do their own analyses, such as finding all parents of a package, output from RPM, data about contents and interrelationships. Importing and exporting file system settings, including the package list, changed file list, and layout changes. Taking snapshots of the file system by saving changes to the file system package list and explicit file content.
For more information, see 5.5 Exploring the Target File System, p.58.
17.3 Profiling CPU Usage with OProfile

It is often hard to find the causes of poor system performance, but once you do, they are relatively easy to fix. The Wind River Workbench Performance Profiler lets you analyze where your CPU is spending its cycles, by providing a detailed, function-by-function analysis that shows how individual routines within the processes consume those cycles. The performance profiler uses OProfile, as described at http://oprofile.sourceforge.net/about/. See the Wind River Workbench Performance Profiler User's Guide.
16
17.4 Analyzing Code Execution Coverage

The Wind River Code Coverage Analyzer lets you determine the percentage of source code executed by your software test case, and points you to the sections of code that have not been fully tested. See the Wind River Workbench Code Coverage Analyzer User's Guide.
213
17.5 Analyzing Memory Problems with mpatrol

If your product demonstrates poor performance and failures, it may be suffering from undiscovered memory problems such as memory leaks, corruption, and fragmentation. Wind River Workbench Memory Analyzer is a dynamic memory analysis tool that helps you prevent and fix such problems. The memory analyzer uses the open-source tool mpatrol, a memory handling library that replaces calls to malloc() and free(). You must configure your Wind River Linux Platform Project and rebuild the binaries to use mpatrol. For information, see the Wind River Workbench Memory Analyzer User's Guide: Using mpatrol with Wind River Linux. See also http://mpatrol.sourceforge.net/.
17.6 Using the System Viewer

Wind River System Viewer supports visualization of multi-core systems; per-core filter and search facilities; the recording of a number of custom events, which use a printf-like format string; graphical and tabular representations of various types of log file analyses such as CPU usage (aggregate and per core), system load, and per-core ready and running states. System Viewer also supports a host-driven upload method for log files, resulting in log transfer without interference from task CPU use. It also allows for transfer of multiple logs, plus transfer without requiring you to call target functions.
NOTE: Memory Analyzer is integrated with the System Viewer, so you can view memory allocation and free events directly in a System Viewer window.
See the Wind River System Viewer User's Guide for more details.
214
17 Optimizing 17.7 Improving Boot Time
17.7 Improving Boot Time

To configure your platform project to support boot time logging, add the wrll-analysis-1.0 layer and the boottime feature template when you create the project. Then, when you build your file system, Workbench creates a bootlogger script and appropriate configuration files for it. You may use this script as part of the init process. The script uses the Linux kernels ftrace feature to capture profiling data from the Wind River Linux boot sequence. For more information, see the section, Analyzing and Optimizing Boot Time, in Wind River Linux Users Guide: Configuring Scalable Features.
NOTE: This feature is not available directly from Workbench, but you may set up the file system as described, and then use the command line for your analysis.
17.8 Optimizing Footprint

The files that determine the size of your footprint are pkglist and changelist.xml.
16
pkglist contains the list of installed packages changelist.xml typically configures the file system layout
You can see the approximate size of the file system on the Filesystem Layout Configuration screen. See Figure 5-3, File System Layout Showing Size, on page 59. As you use the Filesystem Layout tool, you can monitor the effect. For a command-line perspective, see Wind River Linux Users Guide: Getting a Footprint Snapshot.
17.8.1 Looking up a Packages Removal Size

Follow these steps to see how much space you can save if you remove a package. 1. 2. 3. Double-click the User Space Configuration node. In the Package Manager view, right-click an entry in the Installed Packages list. Select Show Remove Size.
215
A list of dependent packages and their total size appears 4. Click Cancel.
17.8.2 Looking up Packages that Require Particular Files or Directories

To see which packages are dependent on any particular file: 1. 2. 3. Click the Filesystem tab at the bottom of the Package Manager In the Filesystem Layout window, right-click any file in the tree and choose Show Dependencies.... Note the packages listed and their sizes.
17.8.3 Looking up a Packages Dependencies

To find dependent packages: 1. In the Installed Packages list, highlight a package and click Dependencies. A list of dependent packages appears. These are packages that are required by the package you highlighted. 2. 3. Notice the sizes of the dependent packages. Click Cancel.
17.8.4 Saving and Restoring Footprint Snapshots

Use the procedures in this section to create base-line snapshots of a footprint, update a snapshot, and restore a snapshot.
Creating a Footprint Baseline Snapshot
To export (create) a snapshot: 1. 2. 3. Click the Filesystem tab at the bottom of the Package Manager. Click the Targets tab if it is not already selected. Click Export Snapshot Footprint. A footprintPackage.tcl dialog appears.
216
17 Optimizing 17.8 Optimizing Footprint
4. 5.
Click Browse and choose a destination directory. Click Export.
Creating a Footprint Update Snapshot
To create an update snapshot: 1. Make a change such as the following:
In the Package Manager, remove a package such as acl from the Installed Packages list. Or make changes in the Filesystem Layout Configuration.
2. 3. 4. 5.
Select File > Save. Return to the Filesystem Layout view. Click the Targets tab if it is not already selected. Click Export Snapshot Footprint. A footprintPackage.tcl dialog appears.
6. 7.
Click Browse and choose a destination directory. Click Export.

16
Restoring a Footprint Baseline Snapshot
1. 2. 3.
Click the Filesystem tab at the bottom of the Package Manager. Click the Targets tab if it is not already selected. Click Import Snapshot Footprint. A footprintPackage.tcl dialog appears.
4. 5.
Click Browse and choose the directory containing the snapshot. Click Import.
NOTE: You could also refresh the package data by clicking the Packages tab, then right-clicking and selecting Reload. This forces the update of the Makefiles derived from the package list file, and reloads the data into Workbench.
217
6.
Observe that the package list and the Filesystem Layout view have reverted to the previous baseline settings.
17.8.5 Exporting Package Dependency Information

To export package dependency information: 1. 2. 3. 4. 5. Click the Filesystem tab at the bottom of the Package Manager. Click the Targets tab if it is not already selected. Click Export Dependencies. Click on Export Dependencies. Observe that there are three reports to select from:
6. 7. 8.
Select Rpm Sizes. Browse to a directory and specify a file. Click Export. If you list this file, you will see, for example:
Package : libgcc Size : 108704
218
17 Optimizing 17.8 Optimizing Footprint
Package : setup Size : 434210 Package : filesystem Size : 0 Package : ncurses-base Size : 454 Package : cracklib-dicts Size : 5094668 ...
9.
Repeat this by selecting Rpm Files and clicking Export. The resulting file might look like this:
Package : libgcc List of files in rpm : /lib/libgcc_s.so.1 Package : setup List of files in rpm : /etc/aliases /etc/bashrc /etc/csh.cshrc /etc/csh.login /etc/environment ...
16
219
220
18
Analyzing Core Files
18.1 Introduction 221 18.2 Acquiring Core Files 222 18.3 Attaching Workbench to a Core File 223
18.1 Introduction
Workbench lets you configure your target system to save status and memory information from programs that crash for various reasons. For example, you can specify that the data should be saved if a process exceeds a certain size, or tries to access memory outside of its allowed memory space. This data is saved on the target in an ELF core dump file, typically named core.pid, where pid is the process ID of the program that crashed. This file contains status and memory information that can help you configure and troubleshoot your system. It contains an image of the process memory space, details of the process state, and additional information about processes occurring at the time of the crash. You can transfer this file to your host and use Workbench to analyze the cause of the crash.
221
18.2 Acquiring Core Files

With the bash shell, you control the creation of core dumps with the ulimit command. For example, to determine your current settings, enter the following:
target_$ ulimit -a core file size (blocks, -c) data seg size (kbytes, -d) file size (blocks, -f) pending signals (-i) max locked memory (kbytes, -l) max memory size (kbytes, -m) open files (-n) pipe size (512 bytes, -p) POSIX message queues (bytes, -q) stack size (kbytes, -s) cpu time (seconds, -t) max user processes (-u) virtual memory (kbytes, -v) file locks (-x) target_$ 0 unlimited 20 1024 32 unlimited 1024 8 819200 10240 unlimited 11768 unlimited unlimited
Most Linux systems do not allow core file generation by default. In the above example, this is shown as a core file size setting of 0. You can turn on core file generation by specifying a maximum size or unlimited as the core file size, for example:
target_$ ulimit -c unlimited
Certain conditions, for example a program trying to access restricted memory, will then generate core dumps, as in:
target_$ ./segtest.out Segmentation fault (core dumped)
You can also turn on core file generation by setting a core file size (unlimited or as specified), and then cause a core file to be generated by setting a limit on some condition. For example:
target_$ ulimit 0 target_$ ulimit target_$ ulimit 12000 target_$ ulimit unlimited target_$ ulimit target_$ ulimit 2000 -c -c 12000 -c -m -m 2000 -m
The shell is now set to generate a core file of a maximum size of 12000 KB if the memory size for a process exceeds 2000 KB.
222
18 Analyzing Core Files 18.3 Attaching Workbench to a Core File
NOTE: Your ulimit settings entered at the command line apply to the current shell only. If you want to continue to generate core dumps across logins, add the ulimit commands to a shell startup file, for example to .bash_login.
Transfer the core dump to your host if it is not already on a file system that your target mounts from the host. You can now analyze the core file using the Workbench debugging tools.
18.3 Attaching Workbench to a Core File

Use the Remote Systems view to create a connection to the core file. You do not need to be connected to the target if you have access to the target file system, because core file analysis takes place on the host. Note that when you are using Workbench to analyze the core file, you are not debugging an active process; you are only examining the state and conditions of a process at the moment it failed to determine the cause of the failure. 1. 2. 3. 4. In the Remote Systems view, select Create a New Target Connection. Select Wind River Linux Application Core Dump Target Server Connection and click Next. In the Core dump file field, enter or browse to the path for the core dump file you wish to analyze. You can enter the CPU number for Force CPU number and the version of Linux for Force OS version. The CPU number for your CPU can be found in the text file $WIND_FOUNDATION_PATH/resource/target/architecturedb. For example, the architecturedb file shows that the CPU number to enter for an XScale CPU is 1120:
... [CPU_1120] cpuname = xscale cpuFamilyName = XSCALE ...
17
The OS version value to enter is 2.6.
223
NOTE: The core file does not contain information on the type of CPU or the version
of the operating system that it was created with. If you get a Failed to connect target error message indicating a target-CPU mismatch, it is likely that specifying the CPU number and OS version will resolve it. 5. 6. In the File field, enter or browse to the path of the application image that created the core dump file. The command line your selections have created is displayed at the bottom of the dialog. To add additional options for memory cache size, logging, and symbol loading, click the Edit button (next to the Options field) and make your selections. Click Next. Specify the location of the target root by clicking Add and entering the Target path (for example, /) and the Host path (for example, /target/rootfs), click OK, and then click Next. Click Next in the Target Refresh dialog box and then click Finish in the Connection Summary. Your core file connection appears in the Remote Systems view. You can now connect to the core dump by right-clicking the [stopped] process in the Remote Systems view and selecting Attach to Process. The Debug view shows the debugger attached to the process at the point of the failure and the Editor opens at the error location in the source file.
7.
8.
Core File Analysis
You can now perform various activities on the core file; for example, view a stack trace, a memory dump, a thread list, local and global variables, and register values. But remember that this is only a read-only view of the process at the time of the core dump.
Ending the Session
To end the core file debugging session, disconnect in the Debug view and disconnect in the Remote Systems view.
224
PAR T VI I
Delivering Your Product

19 20 Providing Platforms and Kernels ...................... 227 Delivering Layers ................................................ 233
225
226
19
Providing Platforms and Kernels
19.1 Introduction 227 19.2 Providing Platforms for Application Developers 228 19.3 Exporting and Copying Sysroots 229 19.4 Integrating Applications 232 19.5 Providing Kernels and Modules for Platforms 232
19.1 Introduction
This chapter discusses issues of delivering or productizing, including:
Providing platforms for application developers to use Integrating applications Providing kernels and kernel modules for platform and application developers
The Deliver stage, as suggested in Figure 19-1, uses various tools and procedures to deliver the product components shown. Of these, Workbench directly supplies export-sysroot, which is a node in the project tree that you can build as a target, and export-layer, which is a build target under build options.
227
For information on how to deliver layers, whether for internal teams or external customers, see 20. Delivering Layers.
Figure 19-1 Delivery Stage of the Product Development Life Cycle
Setup Requirements
Kernel Image File System Image Layers Packages Sysroots
Setup
Relevant Tools
export-layer export-sysroot tar
Develop
Product Deliverables
Docs File System Image Kernel Image Kernel Modules Layers Non-Binary Files Packages Patches Profiles Sysroots Templates Unit Tests
Diagnose
Optimize
Deliver
19.2 Providing Platforms for Application Developers

Platform developers typically generate a kernel and basic file system to support applications to be developed for specific targets. The file system image is generally a bz2 file. The kernel is a system file, generally a uimage. Usually, these and a contained application are delivered as an image for a target or for a QEMU emulated environment. Application developers can then further develop their applications. For help setting up targets and booting, see the Wind River Linux Users Guide. When the target is set up and booting properly, the application developer boots the target and communicates with it, using Workbench to continue to refine, debug, optimize, and test the application against the targets and images, using Workbench
228
19 Providing Platforms and Kernels 19.3 Exporting and Copying Sysroots
tools such as described in 8. If Youre an Application Developer, and in the Wind River Workbench Users Guide.
19.3 Exporting and Copying Sysroots

Platform developers typically create a family of required sysroots and share them with application developers, who add them to their Workbench environment. The application developers in turn get build specs that are built from those sysroots. The target libraries and headers are copied by the platform developer or integrator to the sysroot. (They are not necessarily copied to the remote file system on the target.) You, as a platform developer, can execute the export sysroot command, tar up the directory, deliver it to application or other developers, who untar it, then add it as a sysroot using the Workbench build preferences dialog to import sysroots and layers. Alternatively, you can just place the exported sysroots into the installation used by the application developers, in the wrlinux.3.x/sysroots directory, because these are automatically registered into Workbench.
19.3.1 Exporting Sysroots

To export sysroots: 1. 2. Obtain a sysroot, as explained in the Wind River Linux Users Guide. Modify it if needed. In Workbench: a. b. Right-click export-sysroot node in the project tree. Choose Build Target.
18
This creates the sysroot in the export/sysroot directory and names it according to the target and rootfs values by default. If you create it external to the workspace, you or your application users need to add it to their sysroot directory, by choosing Window > Preferences > Wind River > Layers and Sysroots.
229
19.3.2 Copying Sysroots

Because sysroot contents are organized in a relative path structure, they are completely portable and can be placed in any location. You can put them in a shared, read-only location, for instance, for greatest access, centralized control, and rapid updating. Note that they contain the toolchain wrappers for each of the supported hosts. You can build them on one type of host, and copy them to any other supported host.
19.3.3 Sysroots by Example: Adding 64-bit Multi-libs

This example demonstrates how to add 64-bit multilibs to a platform project, create a sysroot that includes the respective target libraries, and then use it as a build spec to build 64-bit applications. Use the example data in the following table to create and configure the platform as shown in the following sections.
Table 19-1 Platform Project Parameters
Data
Field in GUI
Entry
board file system size kernel type project name
Board RootFS Kernel Project name
arm_versatile_926ejs glibc_std standard mti_malta64f_be
Adding Available Multilibs
To add available multilibs: 1. 2. 3. 4. 5. Create a platform project with the values shown in Table 19-1. Open the User Space Configuration. Add the following two entries from the Available list: glibc(mips 64) and libgcc(mips 64). Click Accept. Select File > Save.
230
19 Providing Platforms and Kernels 19.3 Exporting and Copying Sysroots
For each added variant, Workbench prompts you with the variant plus any required additional variant RPMs on which the original RPM depends.
Adding Multilibs That Are Not Yet Available
To add multilibs that are not yet available: 1. 2. 3. 4. 5. 6. 7. 8. Create a platform project with the values shown in Table 19-1. Click Import. Click Add Multi-libs. Select the CPU Variant. Select the package glibc, click Lookup, and click Add to pkglist. Select the package libgcc, click Lookup, and click Add to pkglist. Click OK. Select File > Save.
This second procedure works even if the respective RPMs have not yet been built, but you need to make the file system and generate the RPMs to see the added package with multilibs in the User Space Configuration.
Verifying, Exporting, and Using the Multilibs Sysroot
To verify that you have added the multilib, and to export and use it: 1. Right-click anywhere in the Package Manager and select Edit pkglist. The pkglist file opens in the editor, and you can see that the two multilibs were added.
NOTE: You can make manual changes to the pkglist file. If you do make changes, be sure to right-click in the Package Manager and select Reload to update the view.
18
2. 3. 4.
Export the sysroot by building the export-sysroot build target. It will then include these extra multilibs in the sysroot. Add the sysroot to Window > Preferences > Wind River > Layers and Sysroots. Create a new mthread sample project.
231
5. 6.
Observe that there are now two new build specs, one for the 32-bit and one for the 64-bit CPU variant. Build mthread for both the 32-bit mips64_n32 and the 64-bit mips64 and notice that the appropriate separate build specs now work
19.4 Integrating Applications

Application developers can export their content into a layer and provide it back to the platform developer; or they can provide binaries that the platform developer can turn into a package, or can include explicitly, using the File System Layout Tool. (See 5.5 Exploring the Target File System, p.58.) Although binaries might be useful for proprietary reasons, Wind River recommends layers, because they allow the platform to be built from scratch, and they wrap the content so it can be shared. See 20. Delivering Layers.
19.5 Providing Kernels and Modules for Platforms

Kernel developers, or platform developers who take their role, typically export kernel changes as a layer or just provide a binary kernel. Kernel developers do the same as application developers: provide binaries to platform developers who act as integrators and create a layer or drop them in. [If there are kernel flags, you can capture them into a layer using the export layer feature.
232
20
Delivering Layers
20.1 Introduction 233 20.2 Example: Preparing Layers that Modify Kernels 234 20.3 Providing Layers to Teams and External Customers 238
20.1 Introduction
You can distribute layers that you have created, either by sending them to a group of developers or making them available over your intranet. Other developers can then include or exclude your layers changes with a single configure command switch (if configuring a project using the command line), or by adding the layer as described in Adding Layers, p.79. Remember, layers are suitable for both internal projects as well as for projects delivered to external customers. They are portable and can overlay any installation, regardless of whether it is read-only, write-only, internal, or external.
233
20.2 Example: Preparing Layers that Modify Kernels

The following procedures demonstrate how to make custom changes in a projects kernel configuration (such as removing a package and adding an external package), create a layer from the changes, set up a template in the new layer, and deliver the layer for use.
By Example: Data to Use
Use the example data in the following table to create and configure a platform for which we will modify a kernel configuration, save the result, and export (deliver) the result as a layer.
Table 20-1 Basic Project Parameters
Data
Field in GUI
Entry
board file system size kernel type project name package to remove package to import
Board RootFS Kernel Project name (list item) (URL)
common_pc glibc_std standard common_pc rmgtools dos2unix-3.1-28.fc7.src.rpm
20.2.1 Creating a Project and Modifying Its Kernel Configuration

To create a project and change the kernel configuration for it: 1. 2. Create a project using the parameters shown in Table 20-1. Make changes to the kernel: a. b. c. 3. Open the Kernel Configuration node. (Click Yes if asked to extract kernel sources.) Open the tree General Setup, and, for example, double click Example Debug Container Subsystem to change it to Y. Select File > Save.
Make changes to the package list:
234
20 Delivering Layers 20.2 Example: Preparing Layers that Modify Kernels
a. b. c. 4.
Double-click the User Space Configuration to open it. Select the entry rngtools, click Remove, and OK. Select File > Save.
Import an external package: a. Open the User Space Editor (that is, the User Space Configuration node), click Import, then click Import Packages.
Figure 20-1
The Import Button
b.
This will bring up the import tool. (See Figure 20-2.)
19
235
Figure 20-2
Import Packages Scripts Display
c.
Select Wget to get the package from the Web.
d. Into Package Location, paste the URL to the package. For example, for dos2unix: http://download.fedora.redhat.com/pub/fedora/linux/releases/7/Fedora/source/ SRPMS/dos2unix-3.1-28.fc7.src.rpm e. Click Go. A shell opens and a script runs to perform the import and package setup. f. g. Press ENTER when done, to close the shell. Click Close, to return to Workbench.
236
20 Delivering Layers 20.2 Example: Preparing Layers that Modify Kernels
h. Select File > Save.
20.2.2 Tailoring and Exporting a Layer

To export the layer for the package changes you have just made to the kernel: 1. Create a new layer directory with a tarball in the default location: a. b. Right-click the project's title (top) node. Select Build Options > Export Changes as a New Layer.
The new layer directory will be created in builddir/export/export-layer/. (Note that builddir is the same as workspace/project_prj.) The export-layer directory contains the layer directory and a tar image of that same directory, for example:
builddir/export/export-layer/common_pc.prj.Wed_Oct_1_150608_PDT_2008 builddir/export/export-layer/common_pc.prj.Wed_Oct_1_150608_PDT_2008.tar
2.
Export the layer: a. b. c. Right-click the project. Select Open Workbench Development Shell. View the new layer's content, which reflects the changes you made:
$ cd export/export-layer/common_pc_prj.Wed_Oct_1_150608_PDT_2008 $ ls conf_cmd.ref dist packages README templates $ ls dist/ dos2unix $ ls packages/ dos2unix-3.1-28.fc7.src.rpm dos2unix-3.1.tar.bz2 $ ls templates/ default $ ls templates/default config.sh knl-base.cfg modlist.remove pkglist.remove fs modlist.add pkglist.add README $ cat templates/default/knl-base.cfg CONFIG_CONTAINERS=y CONFIG_CONTAINER_DEBUG=y $ cat templates/default/pkglist.add dos2unix $ cat templates/default/pkglist.remove # rng-tools
19
All layer changes placed in the templates/default subdirectory are automatically applied when the layer is added: they do not need a template selection to enable them. You can, however, re-arrange the new layer directory
237
so some of the changes can be placed into optional template selections, for the benefit of the user of your layer. 3. Make some of the changes optional (for example, you can move pkglist.remove into a separate template subdirectory, no_rng-tools): a. b. Create a non-default subdirectory:
$ mkdir templates/no_rng-tools
Move the removal package list to it:

$ mv pkglist.remove templates/no_rng-tools
When the developer using your layer wants to remove the rng-tools package, its a simple matter of selecting the template with the layer:
--with-layer=/path/layer --with-template=no_rng-tools
NOTE: The above part of a command would be used in the command-line configuration of a project, as explained in the Wind River Linux Users Guide.
20.3 Providing Layers to Teams and External Customers

The layer directory is portable and self-contained. It can be copied and shared with other users and on other development hosts. Your recipient can copy the layer directory anywhere, and can use Workbench to add it to a project.
20.3.1 Making a Layer Available

To make a layer available to your recipients: 1. Obtain the layer as a tar file from the builddir/export/export-layer directory; for example, from
builddir/export/export-layer/common_pc.prj.Wed_Oct_1_150608_PDT_2008.tar
2. 3.
Send your recipients the tar file or a pointer to it. Explain how they can import and use the layer, as described in the next section.
238
20 Delivering Layers 20.3 Providing Layers to Teams and External Customers
20.3.2 Telling Recipients How to Import and Use the Layer

If your recipients are developing packages or platforms using Workbench, they would import and use the layer as follows: 1. 2. 3. 4. Create a project using the parameters shown in Table 20-1. Click Add to add the new layer's directory. Click Finish. Verify that the layer has been added. For the example, you should see that the dos2unix package is visible after a make fs, and that the kernel and package list changes are present.
20.3.3 By Example: Importing File System Change Lists from Layers

You can create file change lists for projects and export them to a layer. The following procedure explains how to export changes as a new layer, and how to verify that they are in turn actually imported into a project from the layer. 1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. Configure a first project. Go to User Space Configuration > Filesystem. Right-click /usr/games (for example), and select Remove. Select File > Save. Right-click the project, select Build Options > Export changes as a new layer. Copy the new layer export/export-layer/Project_name.date to /tmp/layer1. Configure a second project. Go to User Space Configuration > Filesystem. Right-click /usr, select New > Folder, and add the directory my-user. Select File > Save. Right-click the project and select Build Options > Export changes as a new layer. Copy the new layer export/export-layer/Project_name.date to /tmp/layer2. Configure a third project, adding the layers /tmp/layer1 and /tmp/layer2.
19
239
14. 15.
Go to User Space Configuration > Filesystem. Observe that the two changes from the two layers are applied to the file system.
240
PAR T V II I
Reference
A B C D E FAQs .................................................................... 243 Starting usermode-agent at Boot Time ............ 255 Workbench and Command-Line Techniques ... 259 Installing on Network Servers ........................... 265 Glossary .............................................................. 269
241
242
A
FAQs
Is make reconfig really dangerous? 246 Can I still use standard managed builds for application projects? 246 Why is flexible managed build so great? 246 How can I say what should go into my flexible managed build? 247 How can I migrate Workbench 3.0 projects? 247 Can I structure projects? 247 Why can't I delete sub-projects from within the Project Explorer? 248 Can symbolic links be used for sources? 248 Why are the file permissions changed after importing sources? 248 How can I browse the generated file system user and permissions? 248 Can layers also be used for application code? 249 Can you use layers and templates to patch user space packages? 249 Where do build specs come from? 249 Where can I specify required libraries and library search paths? 249 What is the right way to get a reduced filesystem to a board template? 249 Do packages added via layers appear in the list of installable packages? 250 How is the list of installable packages populated? 250 Do you have to rebuild the wrproxy source for a proxy host? 250
243
How can I launch the Registry in read-only Workbench directories? 250 How can I redirect remote X environments to local servers? 250 Why doesnt Workbench list any available serial ports? 251 Where can I specify include search paths for application projects? 252 How can I modify compiler flags for application projects? 252 Is there a debug mode flag for application projects? 252 Can you redirect standard In when running/debugging via Workbench? 252 Can you multiplex multiple-process output into a single I/O console? 253 How do I collect logs? 253
244
A FAQs A.1 Introduction
A.1 Introduction
This appendix presents frequently asked questions about Workbench and Wind River Linux, and their answers, primarily to draw your attention to capabilities that you might not easily find in other areas of the documentation. Notice that you should: 1. 2. Direct generic Workbench questions to the Wind River Workbench Users Guide. See the same guides Troubleshooting section, which includes Linux issues.
This appendix presents the questions in the following groups, to help you see related questions. Although many fit into several groups, they are not repeated.
A.2 Projects in General, p.246. Reconfiguring projects; flexible vs. standard builds; structuring projects; symbolic links; imported file permissions; browsing file system user and permissions. A.3 Build Properties, Specs, Layers, and Templates, p.249. Layers for application code and patching user space packages; build specs; required libraries and search paths; reducing file system size for board templates. A.4 Package Manager, p.250. What appears in the list of installable packages. A.5 Host-Related Issues, p.250. Rebuilding wrproxy source for proxy hosts; launching the registry in read-only installations; redirection of remote X environments; enabling serial ports. A.6 Application Projects, p.252. Including search paths; compiler flags. A.7 Debugging, p.252. Debug mode flag for application projects; redirecting standard in; multiplexing multi-process output. A.8 Troubleshooting, p.253. Collecting logs.
245
A.2 Projects in General

Is make reconfig really dangerous?
The make reconfig is a powerful new tool to re-configure a project without having to create it again from scratch. You must however use it with care. For example, any custom changes to the file system or the fs tree will be lost without warning. (See, for example, 5.5 Exploring the Target File System, p.58.)
Can I still use standard managed builds for application projects?
Yes, but standard managed build is no longer the default managed build simply because flexible managed build is superior, and at the same time as easy to set up and configure. This is independent of the CDT adoption. You can use Project > Build Options > Convert to Flexible Managed Build to convert standard managed builds.
Why is flexible managed build so great?
Use flexible managed build wherever possible anyway. It is as easy to setup, provides much more features, and is much more powerful overall. Thus, talking about managed build basically means talking about flexible managed build. With flexible managed builds, you can:
Completely separate the project and build definition as well as the build output from the source code. Select build target contents from all over the workspace, also including build target references. Use multiple external source trees and linked resources. Add parts of the same source tree to multiple build targets, even within the same project. Exclude single files, or whole sub folders from the build, or even specify regular expression patterns for excludes. Disable single files, or whole sub folders from the build for specific build specs. Set up a flexible managed build for an existing project in a new project, which thus can coexist with another build system in place (for example to evaluate how easy it is to set up a flexible managed build.
246
A FAQs A.2 Projects in General
Specify all compiler options directly on the build target level (these are part of the build property leveling chain). Recursively create virtual folders, where you can group lists of files or sub-folders, which should be built with specific options (these are part of the build property leveling chain, too), dramatically simplifying build property management (as options only are set in one single place). Specify different compiler options for the same source file within different build targets. Directly find flexible build target contents and exclusions. Find new icon overlays that describe the status of each build target and each content node (such as unresolved contents or references, or deltas for overridden levels).
How can I say what should go into my flexible managed build?
As soon as you need to build something specific (as opposed to building everything inside your project to end up with a single binary), the flexible managed build system helps you define your build targets and any related build properties. You can specify arbitrary build targets of different types within a single project, with arbitrary contents or content exclusions from all over the workspace. Use New > Build Target" wizard, and subsequently either Edit Content... or Edit Excludes... from the context menu, or the corresponding tabs within Properties > Build Properties on any level of project, build target, build target content or virtual build target content.
How can I migrate Workbench 3.0 projects?
Follow the directions in Wind River Linux Migration Guide: Wind River Workbench.
Can I structure projects?
Yes, of course, although this is not available in standard Eclipse. This enables automatic recursive builds to reflect the build hierarchy using super- and sub-project relations. You can also specify the build order of sibling projects, in the Eclipse Preferences, but this is not visualized, and the information can not be shared in a team).
247
Why can't I delete sub-projects from within the Project Explorer?
This could cause confusion. For example, imagine that the user just wants to remove the reference of the sub-project from the super-project, but mistakenly uses Delete. To delete a sub-project, first remove all references until it is a root project: use Project > Remove Project Reference , or do it in the Project Explorer.
Can symbolic links be used for sources?
Eclipse itself has no support of symbolic links and treat symbolic links like normal files. Thus the import wizard (File > Import... > File System) destroys symbolic links and replaces them with copies of the linked files. If you want to keep the permissions and symbolic links, copy the files outside of Eclipse.
Why are the file permissions changed after importing sources?
Eclipse changes file permissions. To keep the permissions, copy the files outside of Eclipse.
How can I browse the generated file system user and permissions?
The file system user and permissions are managed in parallel by the pseudo tool, so that files can be owned by the user on the real file system, but become root files in the target. You can enter this pseudo environment on your host, and examine the target-specific file owership and permissions. To examine a specific file via pseudo:
$ host-cross/bin/pseudo ls -l export/dist/path-to-file
To open a pseudo shell:

$ host-cross/bin/pseudo sh $ cd export/dist
248
A FAQs A.3 Build Properties, Specs, Layers, and Templates
A.3 Build Properties, Specs, Layers, and Templates

Can layers also be used for application code?
Yes, the Analysis layer is an example of application code for the wr-opagent automatically wrapped into a package. See Wind River Workbench Performance Profiler User's Guide.
Can you use layers and templates to patch user space packages?
Yes, layers and templates can patch specific user space packages. . You can do this by creating a sub-directory within the templates. Use the package's name, and then place a patches directory there.
Where do build specs come from?
A TCL build spec provider script is responsible for all build defaults. This script provides build specs derived from sysroots (in the wrlinux/sysroots directory) and registered via Workbench Preferences. You can find the relevant files for provision in the $WIND_BASE scripts. As these are highly dynamic, build defaults are evaluated for each new project directly.
Where can I specify required libraries and library search paths?
You can specify and order libraries and LSPs within Properties > Build Properties > Libraries. You can manually add the same information in the dedicated LIBS and LIBPATH macros within Properties > Build Properties > Build Macros.
What is the right way to get a reduced filesystem to a board template?
For methods to reduce your file system, see 20.2 Example: Preparing Layers that Modify Kernels, p.234; 20.2.2 Tailoring and Exporting a Layer, p.237; Adding Custom Templates, p.77; and 5.5.4 Viewing Parent Packages and Removing Packages, p.62.
249
A.4 Package Manager

Do packages added via layers appear in the list of installable packages?
The package will show up as a placeholder entry in the Installed Packages list. If a prebuilt RPM binary that matches this configuration is not present in the layer, the entry will be a placeholder until the package is built locally.
How is the list of installable packages populated?
The list is populated from the package list file, and it depends on the respective RPM files.
Prebuilt RPM files can come from any layer in the installation directories. Locally built RPM files, where the projects pkgrpmlist.properties file maps package names to RPM names. (The project is always to topmost layer).
Formerly, prebuilt RPMs were not listed until you did a make fs or the equivalent. Now, there are placeholder entries until the respective RPM files are generated. , but of course they dont have the full dependency and other metadata until then.
A.5 Host-Related Issues

Do you have to rebuild the wrproxy source for a proxy host?
The wrproxy binaries provided in the Linux installation are for the host on which you have installed Workbench. If you use a proxy host between your install host and your target, you need to rebuild the wrproxy source for your proxy host.
How can I launch the Registry in read-only Workbench directories?
Run installDir > /wrenv.sh -p package wtxregd help to get a list of options. Use -d filePath to put the database directory in a different location from the default $WIND_HOME/.wind directory.
How can I redirect remote X environments to local servers?
Eclipse and Workbench have the same performance fingerprint when it comes to X performance. If you are having performance problems in a remote X
250
A FAQs A.5 Host-Related Issues
environment where Workbench runs on a remote system and X is redirected to the local server, try the following solutions:
VNC (server, viewer)Use VNC to encapsulate X calls to greatly improve Workbench performance. Both the server and the client need to be read-writable for the installation of VNC. (This may not be applicable for very large company environments.) Clients and servers connected via a 10MBit TCP/IP networkUse half duplex instead of the standard and otherwise favorable full duplex setting on the local Ethernet card. Servers running Linux-GTKA gnome issue affects the anti-aliasing feature, so disable that setting. Use your desktop facilities such as the Gnome Font Properties dialog, of possible. Or, ensure that your ~/fonts.conf or system-wide fonts.conf file contains the following:
<match target="font"> <edit name="antialias" mode="assign"><bool>false</bool></edit> <edit name="hinting" mode="assign"><bool>true</bool></edit> <edit name="autohint" mode="assign"><bool>false</bool></edit> </match>
Clients using Exceed to connect to the remote XTry disabling Exceeds extension for rendering the fonts: Exceed Tools > XConfig > X Server Protocol > Extensions > RENDER. Or, tune Exceed for Workbench, by using xperf like this: Exceed Tools > XConfig > Other Server Settings > Performance > Tune...
Why doesnt Workbench list any available serial ports?
If the Terminal view or the KGDB serial connection dialog has an empty list when you try to select a serial port, examine the port, specifically /dev/ttyS0, which maps to the default port, for example:
$ ls -la /dev/ttyS0 crw-rw---- 1 root uucp 4, 64 Dec 1 11:25 /dev/ttyS0
This tells you that the default serial port is read/write accessible by root and by the uucp group. Since you are not likely running as root, make sure that you are are in the uucp group:
$ grep uucp /etc/group uucp:x:14:uucp,Username
Your username should be included in the uucp list. If not, you need to get it added.
251
A.6 Application Projects

Where can I specify include search paths for application projects?
On the first build after project creation, you will be asked to choose Generate Includes.... This wizard helps you specify ISPs. (It is also available from Properties > Build Properties > Build Paths, then Generate. At the same page, you can specify and order ISPs directly.)
How can I modify compiler flags for application projects?
Use Properties > Build Properties > Build Tool; select C-Compiler ;and, if you need them, also Assembler and C++-Compiler. Then edit the Tool Flags in the entry field (or where it may be available within the specific options dialogs). You can click the Tools Flag, Debug Mode, and NonDebug Mode buttons for access to the common compiler flags. If you only want to temporarily add a flag instead, you can use the dedicated build macros (typically ADDED_CFLAGS and ADDED_C++FLAGS) from the managed build extension mechanism. Specify these in the User Build Arguments entry field in the Build Console. (For user-defined build projects you have to edit your Makefiles manually, or hope to have available, dedicated build macros just like for managed builds, which in a permanent or temporary manner. )
A.7 Debugging
Is there a debug mode flag for application projects?
For Wind River Linux, Workbench the project wizard provides a Debug checkbox along with the build spec selection. For platform packages, there is we a Debug check box in the User Space Configuration > Packages > Options tab.
Can you redirect standard In when running/debugging via Workbench?
No, there is no way to redirecting the input anywhere other than the debug console.
252
A FAQs A.8 Troubleshooting
Can you multiplex multiple-process output into a single I/O console?
No.
A.8 Troubleshooting
How do I collect logs?
If you can start Workbench, collect all log files using Help > Collect Log Files... It is important to check the box of the project(s) for which you have identified issues, for example your platform project's configure command. This allows that project-specific information to be included with the log.
253
254
B
Starting usermode-agent at Boot Time
B.1 Introduction 255 B.2 Basic Requirements 255 B.3 Writing and Placing the Script 256
B.1 Introduction
This appendix contains an example script for starting usermode-agent when the Linux target system boots.
B.2 Basic Requirements

To do user mode debugging, you must run the usermode-agent on the Wind River target. The agent becomes installed in the root file system by default, but without this script or an equivalent, you have to start it manually. This script does the following:
255
Installs the user mode agent as an OS service. Enables automatic startup using the init mechanism when booting.
B.3 Writing and Placing the Script

Place this script in /etc/rc3.d in the target file system.
#!/bin/sh # # usermode-agent # # prog="usermode-agent" start() { # Attach usermode-agent device echo -n $"Starting $prog: " echo `/usr/bin/usermode-agent -v` /bin/sh -c "/usr/bin/usermode-agent -v" > /tmp/usermode-agent.version 2>&1 & /bin/sh -c "/usr/bin/usermode-agent -V" > /tmp/usermode-agent.log 2>&1 & echo "[ OK ]" touch /var/lock/subsys/usermode-agent echo } stop() { # Stop service. echo -n $"Shutting down $prog: " killproc usermode-agent rm -f /var/lock/subsys/usermode-agent echo } # See how we were called. case "$1" in start) start ;; stop) stop ;; restart|reload) stop
This script takes care of starting and stopping UMA
256
B Starting usermode-agent at Boot Time B.3 Writing and Placing the Script
start ;; condrestart) [ -e /var/lock/subsys/usermode-agent ] && (stop; start) ;; *) echo $"Usage: $0 {start|stop|restart|reload|condrestart}" exit 1 esac exit 0
257
258
C
Workbench and Command-Line Techniques
C.1 Introduction 259 C.2 Workbench and the Command Shell Environment 260 C.3 Setting the Environment Without Starting a Sub-shell 263
C.1 Introduction
The following discussion explores some of the ways that Workbench and the command-line are interchangeable and complementary, so that you can use the right tool for the task, or even use one to help debug the other.
259
C.2 Workbench and the Command Shell Environment

Wind River Linux uses its own Makefile system to set its environment, so in ordinary use an environment is automatically set up for each make command. However, if you wish to try things outside of those Makefiles, you will need to set up the Wind River Linux environment using the wrenv command.
C.2.1 Setting the Environment with wrenv

The wrenv command gathers environment settings from the installed products, for example when Workbench executes a build command, or when Workbench itself is launched. The standard usage for wrenv is
$ ./wrenv.sh -p package-name
where package-name is the package name as it appears in the install.properties file. For Wind River Linux 3.0, the command is
$ ./wrenv.sh -p wrlinux-3.0
This spawns a sub-shell with the environment for the selected package-name, in this case wrlinux-3.0. In this shell the Wind River Linux toolchain and other required environment variables are preset.
NOTE: Wind River Linux has no dependencies on Workbench or other Wind River products, so except for the procedures described in this appendix, you should never need to use the wrenv command.
C.2.2 Setting the Environment with Workbench

To open a shell for a specific project and have its environment automatically preset: 1. 2. Select a project in the Project Explorer. Select Project > Open Shell.
You now have a shell in that project's directory with the Wind River Linux environment. You can stay with this simple shell, or open a preferred shell like sh on Windows, or bash and csh on Solaris and Linux.
260
C Workbench and Command-Line Techniques C.2 Workbench and the Command Shell Environment
If this is a platform project, you can cd over to its configured project directory as follows:
$ cd ../project_name_prj
C.2.3 Executing Workbench Build Commands

Workbench and its build system are designed to allow the build process to be as simple and automatic as possible. Sometimes it is valuable to take a build command from Workbench and run it on the command line. Reasons may include:
There may be a very complicated build issue, perhaps with a new BSP or a makefile, where you want to explore and modify the command and its environment. You may wish to instrument the makefiles to print or capture trace and debug information on the fly. You may want to experiment with build flags without endangering the existing build specs.
Here is an example of how to do this: 1. In Workbench, execute the build you wish to examine. For example, here is the build command for the mthread sample project as it appears in the build log:
echo "building fsl_8548cds-glibc_cgl_DEBUG/mthread.o ";powerpc-wrs-linux-gnu-e500v2-glibc_cgl-gcc -g -fno-omit-frame-pointer -mpowerpc -mcpu=8548 -pipe -MD -MP -c -DARCH=ppc -o "fsl_8548cds-glibc_cgl_DEBUG/mthread.o" "mthread.c"
2.
Copy the command from the build log.

NOTE: When you cut a long command from Workbench, line breaks are inserted. You may need to paste this text into a text editor and remove those line breaks, and then re-copy the line from the text editor. B
3.
Open a shell, as described in C.2.2 Setting the Environment with Workbench, p.260. This gives you the compatible shell environment. You can run the env command to see all the provided environment settings that your make commands will inherit. If you are on a Windows host, you will need to start a sh shell so that you have a proper make environment.
c:\WindRiver\workspace\mthread> sh
261
sh-2.04$
4.
Paste the command in the shell and press ENTER.

sh-2.04$ echo "building fsl_8548cds-glibc_cgl_DEBUG/mthread.o ";powerpc-wrs-linux-gnu-e500v2-glibc_cgl-gcc -g -fno-omit-frame-pointer -mpowerpc -mcpu=8548 -pipe -MD -MP -c -DARCH=ppc -o "fsl_8548cds-glibc_cgl_DEBUG/mthread.o" "mthread.c"
You should get the exact same build results as you would get executing this in Workbench. 5. You can now experiment with the command and its environment to troubleshoot problems.
C.2.4 Executing Shell Commands in Workbench

Just as you can test Workbench commands in a shell, you can add shell or script commands to Workbench. Reasons to do this include:
You want to have housekeeping scripts available in Workbench. You want to have scripts that execute in the correct and specific environment. You want to add temporary debug scripts that are project specific.
The following example assumes you want a command that displays all environment settings that contain the project's name. 1. 2. 3. 4. 5. 6. 7. 8. 9. Right-click a platfrom project and select Properties > Build Properties > Build targets. In the Custom build targets section, click New. Enter the name Display Environment. Click Variables, select Project Name, and click OK. Finish the command so that it looks like this:
sh -c "env | grep %selected_project_name%"
Set the Type to Command. Set Refresh after execution to Nothing. Click OK for the Build Target dialog box. Click OK for the Properties dialog box.
Now try the new command:
262
C Workbench and Command-Line Techniques C.3 Setting the Environment Without Starting a Sub-shell
1. 2.
Right-click the project and select Build Options > Display Environment. Observe the output in the Build Log. Note that only the PWD setting from the environment has the project's name in it.
... Command sh -c env | grep samplePlatformProject ... PWD=/home/user/WindRiver/Workspace/samplePlatformProject
This is probably the most complicated shell command you should enter in this dialog. It is generally better to have the command execute a script and pass parameters to it, using hand selected parameters, ones added from the project's variables as above, or ones from the project's macro list.
C.3 Setting the Environment Without Starting a Sub-shell

In some cases it is not desirable to start a sub-shell. For example:
You are executing a script, and do not want it to have to start a sub-shell. You have .cshrc or .profile files that override PATH or other variables whenever a sub-shell is started.
NOTE: Most command-line Linux developers prefer to have absolute control over
their environment settings. This usage allows such developers to choose exactly when and what to add to the given shell for the task at hand.
C.3.1 Exporting Environment Settings to the Current Shell

You can use the following command to send the environment variables to standard output:
$ ./wrenv.sh -p wrlinux-3.0 -p print_env -f shell-type
The possible values for shell-type include plain, sh, csh, bat, and tcl. A more concrete example setting environment in csh without starting a sub-shell:
$ eval `wrenv.sh -p wrlinux-3.0 -p print_env -f csh`
263
C.3.2 Extracting Environment Settings

You can use the following command to send the environment variables to standard output:
$ ./wrenv.sh -p wrlinux-3.0 -p print_env | path-label
For example, suppose you had a script that needed to find all packages that added a path for WIND_WRLINUX_LAYERS. These paths would be in install.properties in the following form:
ipnet60.eval.01=addpath WIND_WRLINUX_LAYERS $(WIND_HOME)$/ipnet-6.0
To extract these paths, you could run this command:

$ ./wrenv.sh -p wrlinux-3.0 -p print_env | WIND_WRLINUX_LAYERS
NOTE: In Windows, separate paths with a colon (:). For UNIX and Linux, separate
paths with a semi-colon (;). If there are no matches, the command returns an empty string.
264
D
Installing on Network Servers
D.1 Introduction 265 D.2 Basic Considerations 266 D.3 Shared Wind River Linux Installation 267 D.4 Local Workbench Installation 267
D.1 Introduction
Workbench and Wind River Linux can be installed on a network server instead of locally. This allows you to reduce the number of installations, simplify maintenance, and save disk space. You can also install Wind River Linux on a network server and then use a local installation of Workbench to access it.
265
D.2 Basic Considerations

You should consider the following issues when making an installation of Wind River Linux for use on your network:
You must use the same absolute path when installing and using the shared installation.
For example, you could mount an NFS-export from the network server locally on a Linux host on /net. You then cd to the installation directory under /net and install Workbench and Linux there. To run Workbench, you would reference the same directory, for example:
$ cd /net/installDir $ ./startWorkbench
Do not log on to the remote server and run Workbench using the path that is local to that server.
You must create a .wind directory at the shared location that is accessible to all users.
This is required for the Remote Systems view.

NOTE: You can make the rest of the installation read-only if you want to. Only the .wind directory must allow general access.
Note that Workbench will continue to use the .workbench-version in your home directory and that you can also have a local workspace.
You must install Workbench on the shared installation server, and you must install it first.
This applies even if you are going to be using a local installation of Workbench. The Workbench installation on the server provides some necessary support for the Wind River Linux installation that you perform after Workbench is installed.
You must use the appropriate installation license key.
Do not, for example, use a key for a platform development installation if you are installing an application development environment, because this will install the wrong infrastructure files.
266
D Installing on Network Servers D.3 Shared Wind River Linux Installation
You must have unique installations for each host operating system.
You cannot use the same shared installation for multiple host operating systems. Each host type must have its separate shared installation to get the proper host tools and infrastructure details.
D.3 Shared Wind River Linux Installation

Use the following procedure to install Workbench and Wind River Linux on your network server. 1. 2. 3. 4. On the local host (Windows, Linux, or Solaris), install Workbench in the shared location using the proper license key. On the local host, install Wind River Linux in the same location using the same key. Use Workbench from any host of the same type (Windows, Linux, or Solaris). Specify a local workspace.
D.4 Local Workbench Installation

You may want to use a local installation of Workbench to reduce network traffic and dependencies, or for performance reasons. Use the following procedure to install a local copy of Workbench that uses the shared Wind River Linux installation. 1. 2. Install Workbench on your local host. Append the contents of the installDir/install.properties file, located in the wrlinux-version directory of the shared installation, to your local installDir/install.properties file. Edit the WIND_LX_HOME value in your local installDir/install.properties file to point to the shared installDir. Note that you must always use $/ as the directory delimiter, even for Windows hosts. For example:
3.
267
Before:
wrlinux14.eval.02=export WIND_LX_HOME=$(builtin:InstallHome)
After:
wrlinux14.eval.02=export WIND_LX_HOME=$/net$/sharedLinuxPlatDevDir$/WindRiver
You can now use this local Workbench and it will automatically use the data from the shared installation.
NOTE: If you install an additional Wind River product in this local directory, you must repeat the modifications to the local install.properties file described in this example.
268
E
Glossary
This glossary defines terms used in Workbench Wind River Linux projects. For additional terms involving the Workbench IDE and GUI presentation, see also the Wind River Workbench Users Guide.
back end
Functionality configured into a target server to allow it to communicate with various target agents, based on the mode of communication that you establish between the host and the target (network, serial, and so on).
board support package (BSP)
A Board Support Package (BSP) consists primarily of the hardware-specific code for a particular target board. A BSP includes facilities for hardware initialization, interrupt handling and generation, hardware clock and timer management, mapping of local and bus memory space, and so on.
BSP directory
The directory containing a particular BSP. This directory is found in the templates/board subdirectory of the layer containing the BSP.
build
The type of project built: managed build by default (formerly flexible build); and also a deprecated but still available standard managed build (sometimes known as a standard build). There are also user-defined and disabled builds.
269
build directory
The directory named build in a project, where build tasks such as patching and compilation are actually performed.
build output analysis
Also referred to as discovery, a mechanism to analyze build output to determine include paths, symbols, and the build scope (affected files) during a build run.
build scope
The set of files built during a build run, determining which source files are processed by the indexer. Generally, all projects use a build-driven setup, unless build information is missing, in which case, all files will be parsed (indexed).
build spec
A particular set of build settings appropriate for a specific target board. This provides functionality that is configured into a target server to allow it to communicate with various target agents, based on the mode of communication that you establish between the host and the target (network, serial, and so on).
CDT (C/C++ Development Tooling)
The Eclipse C/C++ IDE.

cross-development
The process of writing code on one system, known as the host, that will run on another system, known as the target.
debugger framework (DFW)
The debugger backend, which communicates between the target server and target agent to provide debugging control in Workbench (as well as control in Workbenchs Remote Systems and OCD views).
debuggable objects
Debuggable objects are the executable application files, kernels, kernel modules, and libraries that can be accessed by both the host and target. These objects are ideally compiled without optimization, compiled with the appropriate debug flags (for example with -g, or -g-dwarf-2), and are not stripped of symbols.
270
E Glossary
DFW
See debugger framework (DFW)

disabled build
Project builds for which Workbench provides no build support at all. Useful for projects or folders that contain, for example, only header or documentation files that do not need to be built.
discovery
See build output analysis.

external API
An index holding a pre-parsed platform API for a project type. Most managed project types come with an external API package which, when indexed, provides the most common API functions, methods, and types for code completion and parameter hints in the source editor.
flexible managed build
Deprecated name for what is currently called managed build.

help key
The host-dependent key in Workbench that provides get context-sensitive help. On a Windows host, press F1. On a Linux or Solaris host, press CTRL+F1.
host shell
A Wind River command shell that provides a command-line environment for GDB and KGDB debugging. The host shell also provides Tcl scripting support.
host toolchain
Used on the development host to build the host tools and other software. This toolchain is provided by the development host operating system, for example by Red Hot or Ubuntu. This is a different toolchain than the cross-development toolchain.
271
host tools
Used on the development host to perform functions that are part of the build process, but other than the toolchain compiling functions. They are built by Wind River or by the user.
hunk
In Linux, a hunk is a contiguous group of source lines generated when the diff program is applied to compare files. The patch program and the Quilt patch program based upon it use diff to create patches, which are then internally represented as one or more hunks to apply to a file to patch it.
index
Source analysis information gathered by the indexer by parsing source code. The index is the basis for any source navigation and editing capabilities, such as navigation between declaration and definition of methods, showing included files in the Include Browser, showing the call tree of functions and methods, showing the type hierarchy of classes, code completion in the editor, hover information, etc.
JDT
Java Development Toolkit provided by the Eclipse organization (http://www.eclipse.org) and included with Workbench.
JNI
Java Native Interface is a means of calling non-Java code (native code) from within a Java application.
kernel mode
For Linux 2.6 and higher kernels, two connection modes are supported: kernel and user mode connections. Kernel mode connections allow kgdb debugging of the kernel in a manner analogous to debugging applications in user mode.
kernel module
A piece of code, such as a device driver, that can be loaded and unloaded without the need to rebuild and reboot the kernel.
272
E Glossary
launch configuration
A run-mode set of instructions that instructs Workbench to connect to your target and launch a process or application. A debug-mode launch configuration, for example, completes these actions and then attaches the debugger.
layer
A collection of packages and templates for use with the Wind River Linux build system.
layer directory
The directory containing a particular layer.

managed build
A build for which Workbench controls all phases, available for all project types except user-defined projects.
native mode development environment
A development environment requiring a usermode-agent program to be running on the target, in a Linux operating system. In this environment, the debugger and application are compiled with the same toolchain, thus no emulator is required when running in self-hosted mode. A native mode development environment can only be used for application development.
object path mappings
The object path mappings specify where the debuggable objects are to be found for both the debugger running on the host and the Linux target. In Workbench, this is set within the Remote Systems views Target Connection Properties.
package
A collection of software and files for installation on a targets root file system. The term package is used generically for both source builds and binary distributions. Examples include the ncurses library, or the busybox shell and utilities.
273
patch file
A file containing modifications to make to source code, conventionally in a format understood by the historic patch utility. Patches for use with Wind River Linux Platforms should be in unified diff format.
patch list
A list of patch files to apply, usually stored in a file called patches.list.

plug-in
An independent module, available from Wind River, the Eclipse Foundation, or from many web sites, that delivers new functionality to Workbench without the need to recompile or reinstall it.
project
A collection of source code files, build settings, and binaries that are used to create a downloadable application, file system, kernel, bootable system image, and so on. Projects can be linked together in a hierarchical structure displayed as a project/subproject tree in the Project Explorer. This structure reflects the inner dependencies of the projects, and therefore the order in which they should be compiled and linked.
project description files
Automatically-generated files that contain information about a project, such as project properties, build information, Makefile fragments, and other metadata.
project directory
The directory containing a project. Created by the configure script, or the Wind River Workbench configuration tool.
registry
The registry associates a target servers name with the network address needed to connect to that target server, thereby allowing you to select a target server by a convenient name.
self-hosted development environment
The opposite of cross-development. The debugger and the application are running on the same machine.
274
E Glossary
source lookup path
The source lookup path specifies the location that the Workbench debugger uses to identify and open each source file as it is being debugged. This is set in the Debug view in Workbench.
spec file
All SRPM packages have a spec file that manages how a package is built on the host and how it installs in the target file system. Patching this file lets you customize and enhance the package in the build system and the specific target environment.
standard build; standard managed build
Synonymous, deprecated project build types suitable for projects with build structures similar to the file system structure.
system mode
When in system mode, the debugger is focused on kernel processes and threads. When a process is suspended, all processes stop. Compare with user mode.
sysroot
A sysroot holds the shared header files and libraries (for example the C runtime libraries) from the file system, for the use of other packages in a project. If the package list does not change, the sysroot does not change.
target
A piece of hardware or simulated hardware on which software needs to be run. Typically, software is built and configured for a particular target before being installed. A target generally refers to a specific configuration of a board.
target agent
The target agent runs on the target, and is the interface between Wind River Linux and all other Wind River Workbench tools running on the host or target.
target server
The target server runs on the host, and connects the Wind River Workbench tools to the target agent. There is one server for each target; all host tools access the target through this server.
275
template
A collection of configurations, settings, and patches used to modify the kernel or file system built for a target. Templates are combined to create a project.
TIPC
Transparent inter-process communication protocol typically used by nodes within a cluster. Wind River provides a proxy and usermode agent program that allow Workbench to access targets within the TIPC cluster.
toolchain
The compiler and other tools used on the development host to compile the software that will run on the target. Also called cross-development toolchain to distinguish it from the host toolchain.
user-defined build
Project builds for which you set up and maintain your own build system and Makefiles, and for which Workbench provides minimal support beyond a GUI launch, make rules expressed in the Project Explorer, and build output to the Build Console.
user mode
When in user mode, the debugger is focused on user applications and processes. When a process is suspended, other processes continue to run. Compare with system mode. For Linux 2.6 and higher kernels, user mode is a separate connection type. Compare with kernel mode.
workspace
The central location (installDir/workspace by default) for all the Workbench resources you see : your projects, folders, and files; settings that describe your working environment: open projects and views, how you have your views arranged within the perspective, whether you have breakpoints set, and so on. You can create more than one workspace. To share the build objects of your projects with a target, the workspace (directory) may be in a file system that is exported to the target, or you may redirect build objects from your workspace to a location exported to the target.
276
Index
Symbols
%build 117, 122 %configure_target 117, 122 %install 117, 122 +/- icon 61 .ko file 150 /dev directory 62
A
Add Links to Development Folders 121 adding layers 52 profiles 52 templates 52 Advanced tab 64 agent-proxy 186, 193 connections 187 port numbers 193 application binaries 157 developers 16, 36 projects 25 applications adding to file system 157 creating 98 development environment 99
importing code 103 incorporating into platforms 99 penguin 101 providing in layers 232 running native 106 running non-native 108 sysroots for 99 arch.cpu-variant 40 architecturedb file 223 archives 121 ARM Versatile AB-926EJS 164 creating target 53 emulation 29 assembly view debugging 179 attaching to core file 223
B
back end 269 Backend Connection 50 ball tutorial 98 baseline snapshots 216 bin directory 60 board menu 51 support package 111, 269
277
booting targets 228 boot-time access 50 feature template 215 logging 215 breakpoints 179 kernel 197 per debugger 176 bridging hosts 186 BSPs 75, 111, 269 directory 269 build 269 build target 65 directory 54, 56, 270 output 56, 270 paths 109 properties 109 scope 270 specs 54, 111, 113, 270 targets 65, 157 tools 109 Build Console 52 build properties build macros 109 changing 109, 114 libraries 109 Build Target 39, 55 BUILD_TYPE=debug 72 BUILD_TYPE=profiling 72 build-all node 39 Bus options 86
C
CardBus cards 86 Cavium example platform project 67 CDT (C/C++ Development Tooling) 270 cgl kernel type 51 changelist.xml 57, 60, 215 classic packages defined 130 importing 119 clean
build target 65 ClearCase repositories 38 Code Coverage Analyzer 213 command line configuring projects 50 Common PC 164 emulation 29 compile build target 65 components definition 93 hierarchy 93 configure command 51 modifying 51 output in Build Console 52 Configure Options dialog 54 connecting to targets 49 Connection 50 connections connect and disconnect 163 creating 177 emulated 164 Ethernet 192 ICE-like debugging 207 KGDB 167 new 162 properties 164 QEMU types 49 serial 195 serial cable 195 serial/telnet 192 shared 172 summary page 172 TCP 186 telnet 194 troubleshooting KGDB 195 types 162 types of KGDB 167 UDP 186 using KGDB 196 Contents tab 64 core files acquiring 222 analysis 224
278
Index
attaching to Workbench 223 attaching Workbench 223 core.pid 221 CPU type 224 Create template source 87 creating custom kernel module 88 creation.log 52, 55 cross compiling 120 cross-development 270 custom build target 65 kernel module projects 205 Custom Linux KGDB Connection 167 customer-specific projects 25 enabling 26 CVS repositories 38 Cygwin 26, 30
D
database queries 16 Debug Process on Target 50, 177 debuggable objects 270 debugger framework (DFW) 270 Debugger tab 31 debuggers table of 31 which breakpoints 176 debugging assembly 179 breakpoints 179 breakpoints in kernel modules 202 kernel mode, intro 30 kernel modules 198 kernel space 183 KGDB command-line 184 object path in kernel modules 202 object paths in kernel modules 203 packages, on or off 64 process overview 178 turning off for production 184 user mode, intro 30 user space 176 user supplied kernel modules 199, 200
default kernel 55, 56, 57, 156 Dependencies tab 64, 70, 72 deploying emulated targets 160 NFS 160 to targets 159 development environment 26 device adding 62 file class 58 ownership 62 Device Debug perspective 178 Device Management (DM) products 33 DFW 270, 271 directories adding and removing from file system 60, 61 disabled build 271 discovery 271 dist directory 53, 54, 156 Makefile 120 dist.tar.bz2 image 58, 157 distclean 120 build target 65 distribution media 32 DM products 33 do_fork 189 dynamic printf 180
E
ecgl kernel type 51 Eclipse plug-ins 19 Eclipse C/C++ IDE 270 Edit Source Lookup 196 ELF core dump file 221 Embedded Debug perspective 196 emulated target environment 160 --enable-debug 189 environment settings 260 environment variables sending to standard out 263
Index
279
Estimated Filesystem line 60 Ethernet connections 192 ports, multiple 190 event points 180 Exec Path on Target 177 export /dist directory 56, 58 directory 56 sysroot command 229 export directory 56 export/dist 58, 157 export/dist directories QEMU 164 exporting sysroots 229 export-layer build target 227 export-sysroot node 227 external API 271
File System Layout Configuration tool 40, 57, 58, 212 files adding and removing from file system 60, 61 collecting for export 158 Filesystem tab 60 Filter icon 59 fixes reusing package 120 Flat view 59 flexible managed build 271 footprint exporting dependency data 218 snapshots, creating 216 snapshots, restoring 217 snapshots, updating 217 Force Install 67 RPM 65 fs node 48, 55, 156 fs_final script 58
F
fakeroot 58 feature templates major description 92 file change list 58 ownership 40 properties 60 file system 57 adding applications 157 building example 56 components 156 configuration 57 creating 55 estimated size 60 finding 28 making exportable 158 managing 58 NFS mounting 188 NFS mounts 188 root 165 size 215 small 63
G
GDB GNU Debugger 175 native-mode applications using 178 General tab 64 generated RPM files 57 gid ownership 58 glibc_cgl carrier-grade Linux 51 glibc_small 63 Busybox-based 51 glibc_std standard Linux 51 GNU Debugger (GDB) 175 tools 26 Grnbacher, Andreas 128 178
280
Index
H
hello_world building 100 tutorial 100, 102 help key 271 host bridging 186 file system source path 61 shell 271 toolchain 271 tools 272 hosts supported 26 host-tools/bin directory 186 http //oprofile.sourceforge.net/about/ 213 //sourceforge.net/projects/kgdb/ 184 hunk 272
shared 11 shared Wind River Linux 267 installed packages 63 ipconfig 190
J
Java code 16 JDT 272 JNI 272
K
Kconfig tab 85 kernel 156 configuration 84 debugging 184 debugging with QEMU 207 default 55, 56 default, finding 28 developers 16, 36 image, default 57 information 88 pre-built 38 rebuild target 41 reconfiguration 84 safe areas 189 symbol file 168 symlink to default 86 types 51 Kernel Configuration node 85 Kernel GNU Debugger 30 Kernel Hacking tree 209 kernel mode 272 debugging 30 kernel module 272 debugging 198 moving projects 89 projects 25 kernel modules 87 adding 87 breakpoints in unloaded 202
I
ICE-like debugging 206, 207 Immediately connect to target 163 Import tool 235 importing classic packages 119 packages 68 source code 103 index 272 insmod command 199 Install RPM 65 install build target 65 install.properties file 260, 267 INSTALL_STAGE output 58 Installable Packages list 66, 73 window 68 installation licensing 11 local Workbench 267 network servers 265
Index
281
custom 88 custom projects 205 debugging 198 installing 150 moving projects 89 object path mappings 202, 203 providing 232 removing 150 testmod enhanced sample 204 user supplied, debugging 199 user supplied, stepping into 200 kernel space debugging 183 kernel_build 198 kernel_build node 156 kernel_rebuild 156 kernel_rebuild build target 86 kernels breakpoints 197 exporting layers 237 making exportable 158 modified by layers 234 providing 232 rebuilding 86, 156 KGDB advanced connections 170 and Workbench 184 command-line debugging 184 connection from Workbench 192 connections 167 connections -- UDP or COMM 190 disabling for production 30 enabled by default 189 enabling 189 enabling and disabling 209 Linux kernel config option 189 open source project 184 over Ethernet 207 over subnets 185 patching kernel for 30 QEMU kernel debugging 50, 206 standard port 186 starting agent on target 190 troubleshooting connection 195 using connection 196 KGDB over Ethernet (kgdboe) 186
kgdb.c compilation unit 39 source file 196 kgdb-8250 module usage syntax 192 kgdboe 186 agent 187 connection 187 for non-PCD 190 for PCD, dynamic config 191 for PCD, static config 191 starting, examples 190 static linked in kernel 191 UDP packets 186 klogd command 199
L
launch configurations 42, 273 layers 75, 273 adding 52, 79 directories 273 distributing 233 example to modify kernels 234 exporting kernel 237 importing 239 introduction 8 making available for team 238 of applications 232 libraries build properties 109 into relocatable directories 112 licensing and installation 11 life cycle introduction 37 Link to Development Folders 54 Linux hosts 26 Linux kernel information 88 Linux Kernel Module projects prepopulating 87 Linux kernels version 2.6 30 Linux KGDB via Ethernet 167, 193 Linux KGDB via RS-232 167, 195 Linux KGDB via Terminal Server 167, 194 Linux User Mode Target Server 49
282
Index
live targets 57, 58, 60, 63, 65 RPMs and kernel modules 149 Load/Add Symbols to Debug Server 168 localhost.localdomain 11 Log tab 60 generated RPMs 65 logging into terminals 166 lsmod command 195
M
make clean 156 make fs 156 Makefile modifying for cross-compile 120 managed build 269, 273 mapping source path 39 memory cache size, target server 171 Memory Analyze As 32 Memory Analyzer 214 menuconfig interface 85 meta properties files 60 middleware developers 16 MinGW 26, 30 modprobe commands 190 module.c 200 moduledebug.c 87 moduleDebugExample.ko 200 mpatrol 32, 38 multi-core systems 214 multi-lib RPMs installing 67
development environment 273 native-mode applications 47 network servers 265 networked hardware 168 New Connection wizard 162 NFS builds 11 directories on shared hosts 188 mounted hosts 38 mounting file system 188 mounting targets 188 target environment 160 non-native applications running 108
O
Object Path Mappings Ethernet 193 object path mappings 50, 203, 273 QEMU 166 symbol files and target paths 168 object.properties files 26 OCD connections 50 On-Chip Debugger 189 octeon spec warning message 68 On-Chip Debugger (OCD) 189 Open Workbench development shell 120 openssl 72 OProfile 38, 213 Option/Value dialog 52 Options tab 64 option-value templates 51 Index
N
native applications projects 25 running 106 native mode
P
package developers 16 Package Import Tool 68 Package Manager 63 intro 39
283
package sizes 58 package_RPM_ALL 10 package_RPM_DEFAULT 10 package_RPM_DEVEL 10 package_RPM_NAME 10 packages 273 archives 121 building new 122 classic 130 customizing 123 debugging 71 dependencies 66 dependent 216 directory 53 hierarchy 93 importing 68, 119 importing Wind River Linux 123 Package Manager 63 parent 62 removing 62, 72 required files 215 reusing fixes 120 RPMs 63 sizes of 215 turning debugging off 64 updating spec file 121 Packages dialog 58, 65 Packages view 59 parent packages 62 patch annotations 138 build target 65 files 274 lists 274 target rules 123 patch files modifying SRPM 141 patches annotations 138 applying and resolving 128 creating new top files 137 exporting 146 folder 137 models for using 128 modifying 145
new top files 144 new top patch files 130 popped files 143 registering 142 registering as last 142 running distclean on 147 saving SRPM 141 saving updates as 143 testing 143, 147 patches.list file 117, 143, 147 patching 127 SRPM packages 140 path mapping target to host 169 pathname prefix mappings 169 Pattern Filter field 59, 62 value 62 PCCard support 86 PCD Wind River Platform for Consumer Devices 191 PCMCIA cards 86 Penguin building 101 Performance Profiler 213 PHP pages 16 PIDs 179 pkglist file 58, 63, 65, 66, 67, 71, 73, 215 pkg-wr-integration.patch file 117 pkg-wr-integration.patch tree 142 placeholder RPMs 69 platform 47, 87 developers 16 integrators 36 kernel modules 87 projects 25 platform project verifying build 55 platform projects general steps 51 overview of building 47 plug-ins 274 Eclipse 19 ports
284
Index
6443 for KGDB 186 POSIX signals 181 postpatch build target 65 pre-built kernels 156, 196 RPMs 39 pre-built kernel 38 preempt_rt kernel type 51 prepatch 69 build target 65 printf 180 Printk 189 pristine RPM files 58 process IDs (PIDs) 179 processes reviewing 177 terminating 182 product development life cycle 37 profiles adding 52 basics 93 creating 93 differences from platforms 94 hierarchy 93 Profiling build type 54 profiling CPU usage 213 project 274 description files 274 directory 274 ProjectName_prj directory 48 projects application 25 customer-specific 25 kernel modules 25 native applications 25 platform 25 user-defined 25 Wind River Linux 25 properties 164 pseudo 58 pxeboot 188
Q
QEMU backend CLI connections 163 connecting to emulated targets 164 connections 49 emulated boards 29 export/dist directories 164 KGDB debugging 206, 207 Linux User Mode Target 163 object path mappings 166 Qemu-PPC32 164 Quilt Add File to Top Patch 122 Add New File to Top Patch 141 configuring 127 Export Patch 143 Import Patch 137 importing packages 121 introduction 127 menu 130 New Patch 120 new top patch files 144 patches node 136 Pop 143 Refresh Top Patch 122 setting up 135 starting 135 viewing patch annotations 138
R
rebuild build target 65 registered patches 142 Registry 108, 274 remote connections 177 Remote Systems view 162 New Connection wizard 162 pathname prefix mappings 169 shared connection configuration 172 Replace RPM 65 Required By panel 64
Index
285
Requires panel 64 root 58 directory 50 file system 165 RootFS menu 51 RPM dependencies 67 generated files 57 macros 122 manager 63, 151 pushes 63 queries 63 rpm -erase 65 rpm -install 65 rpm -install -force 65 rpm -option 63 rpm_patches.list 130 rpm_patches.list file 142 RPMs 63 available 58 configuration 57 installing multi-lib 67 launching to target 151 placeholder 69 pre-built 39 removing from target 152 replacing running 152 unavailable 63, 70 URLs for 64 RPMS directory 53 rtcore kernel type 51 Run Process on Target 50 runtime file system 57
S
safe areas 189 self-hosted applications 47 debugging 176 self-hosted development environment 274 serial cable connections 195 serial line settings 168 serial port connections 194
serial/telnet connections 192 setgid file permissions 58 shared connections 172 installations 11, 267 shell commands in Workbench 262 signals configuring 181 POSIX 181 simultaneous usermode-agent connections 189 small kernel type 51 snapshots baseline 216 Solaris hosts 26 source code indexer 52 source lookup path 275 source path mapping 39 Source RPM (SRPM) packages 121 spec files 143, 275 saving 140 SRPM package 140 updating 121 SPECS/pkg.spec file 142 Spin locks 189 SQL 19 SRPM packages 121 importing 121 packages importing SRPMs 121 patching 140 URLs 121 SRPM patch files modifying 141 saving 141 SRPMs cross compiling 140 integrating into Wind River Linux 140 standard builds 275 kernel types 51 managed builds 275 subprojects 88 superprojects 88 symbol files 168
286
Index
pre-built 38 Symbol Files and Order list 168 Symbol Load Options 168 sysroots 111, 112, 275 adding 112 copying 230 exporting 229 importing 112 provided 112 system mode 275 System Viewer 214 System.map file 156
tgtsvr command (TIPC) 171 timeout options 171 TIPC 276 toolchain 276 available 26 host 271 tools, development communications, managing tutorial Hello World 100, 102
159
U T
tar.bz2 files 56, 156 tarball file system image 58 target agent 275 environments 160 paths 168 servers 171, 275 memory cache size 171 timeout options 171 Target Operating System Settings dialog 208 targets 275 connecting 49 PCD 191 properties 169 server options 171 state refresh page 169 timeout 171 Targets tab 65, 69 TCP connections 186 telnet connections 194 templates 75, 276 adding 52 code 87 feature 92 named per type 91 terminals logging into 166 testmod, enhanced sample LKM 204 uClibc 51 uclibc_small 63 uClibc-based file system 51 UDP connections 186 packets 186 uid ownership 58 UID root 58 uimage 228 ulimit settings 223 URL to RPM 64 USE 57 user mode 276 debugging intro 30 User Mode Target Server 163 User Space Configuration node 40, 57 User Space Configuration Tool overview 118 user space debugging 176 User Space Editor 57 user-defined builds 276 projects 25 user-defined projects 63 usermode-agent and QEMU 49
Index
287
V
View icon 59, 62 Virtual-WRLinux0 terminal window vmlinux pre-built symbol file 38 vmlinux symbol file 41, 189, 193 166
wrenv command 260 wr-integration.patch file 143 wrlinux_quilt_patches directory 142 WRLinuxHost_username 177 wrll-analysis-1.0 layer 215 wrll-toolchain-version 99 WRQEMULinuxUser_Project_prj connection 166
W
WDB debugger 30, 175 Wget 68, 121 Wind River Debugger 30, 176 Wind River Debugger (WDB) 175 Wind River Linux Application Core Dump Target Server Connection 223 Wind River Linux KGDB Connection 192, 195 Wind River Linux Migration Guide 10 Wind River Linux Platform Project 54 Wind River Linux Release Notes 10 Wind River Linux Users Guide 42, 155, 184, 215 Wind River Platform for Consumer Devices (PCD) 191 Wind River Workbench Code Coverage Analyzer User's Guide 213 Wind River Workbench Memory Analyzer User's Guide 214 Wind River Workbench Performance Profiler User's Guide 213 Wind River Workbench Users Guide 24, 42, 98, 172 WIND_LX_HOME 267 Windows hosts 26 Workbench build commands 261 local installation 267 setting environment 260 shell commands 262 starting 24 workspace 276 directory 61 WR Linux Kernel Module Project 206 WR Linux Package 68 WR3.0au_kernel files 56
X
X 19 xconfig interface 85
288

Wind River Workbench (Linux 3 Version) by Example, 3.1

Загружено:

Сведения о документе

Исходное описание:

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

Wind River Workbench (Linux 3 Version) by Example, 3.1

Загружено:

Авторское право:

Доступные форматы

Wind River Workbench (Linux 3 Version) By Example, 3.

Wind River Workbench

Wind River Workbench By Example, 3.1 (Linux 3 Version)

Getting Started with Workbench ........................................................ 15

Workbench Basics for Linux Developers .......................................... 23

Life Cycle Development ......................................................................

Wind River Workbench By Example, 3.1 (Linux 3 Version)

4.8 4.9 4.10

PART II: DEVELOPING PLATFORMS

Configuring Platform Kernels ............................................................

Wind River Workbench By Example, 3.1 (Linux 3 Version)

Moving Kernel Module Projects ............................................................

Feature Templates and Profiles ......................................................... 91

Templates and Profiles in the Platform Project Wizard ..................................

PART III: DEVELOPING APPLICATIONS

Changing Build Specs and Properties ................................................................ 109

Sysroots, Build Specs, and Properties ............................................. 111

Importing Packages ............................................................................ 117

Importing Wind River Linux Packages .............................................................. 123

PART IV: DEVELOPING PACKAGES

Wind River Workbench By Example, 3.1 (Linux 3 Version)

Reviewing the Quilt Menu Commands ................................................ 130

Managing Packages on Live Targets ................................................. 149

PART V: DEPLOYING TO YOUR BOARD

Deploying to Targets ........................................................................... 159

Wind River Workbench By Example, 3.1 (Linux 3 Version)

14.3.2 14.3.3 14.4 14.5

14.6 14.7 14.8

PART VI: DEBUGGING AND ANALYZING

Debugging Kernel Space .................................................................... 183

Wind River Workbench By Example, 3.1 (Linux 3 Version)

16.6.4 16.6.5 16.6.6 16.7 16.8 16.9

Optimizing ............................................................................................ 211

Analyzing Core Files ........................................................................... 221

PART VII: DELIVERING YOUR PRODUCT

Delivering Layers ................................................................................ 233

Wind River Workbench By Example, 3.1 (Linux 3 Version)

PART VIII: REFERENCE

Starting usermode-agent at Boot Time .............................................. 255

Workbench and Command-Line Techniques ..................................... 259

C.2.1 C.2.2 C.2.3 C.2.4 C.3

Installing on Network Servers ............................................................ 265

Glossary ................................................................................................ 269

Index .............................................................................................................. 277

Wind River Workbench By Example, 3.1 (Linux 3 Version)

Wind River Workbench By Example, 3.1 (Linux 3 Version)

Wind River Workbench By Example, 3.1 (Linux 3 Version)

1.2 How to Use this Guide

1.2.1 How is this Guide Organized?

1 Overview 1.2 How to Use this Guide

1.2.2 When is the Table of Contents Most Helpful?

1.2.3 What if You Just Know Your Major Role?

1.2.4 How Do You Set Up Your Development Environment?

Wind River Workbench By Example, 3.1 (Linux 3 Version)

1.3 Introducing Wind River Workbench and Linux

1.3.1 Cross Development Environment

1.3.2 The Wind River Build System

1 Overview 1.3 Introducing Wind River Workbench and Linux

The build system has the following characteristics:

Build System Overview

Features... Kernel Core Project Repository

sysroot Binary Kernel Binary RPMs...

Root File System Optimized Bootable Image