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

Wind River Workbench

BY EXAMPLE

®

3.1

Linux 3 Version

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

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 HeadquartersWind River Systems, Inc.500 Wind River WayAlameda, CA 94501-1153U.S.A.

toll free (U.S.): (800) 545-WINDtelephone: (510) 748-4100facsimile: (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

http://www.windriver.com/company/terms/trademark.html

http://www.windriver.com

http://www.windriver.com/support

iii

Contents

PART I: INTRODUCTION

1 Overview .............................................................................................. 3

1.1 Introduction ............................................................................................................. 3

1.2 How to Use this Guide .......................................................................................... 4

1.2.1 How is this Guide Organized? ............................................................... 4

1.2.2 When is the Table of Contents Most Helpful? ..................................... 5

1.2.3 What if You Just Know Your Major Role? ............................................ 5

1.2.4 How Do You Set Up Your Development Environment? .................... 5

1.3 Introducing Wind River Workbench and Linux .............................................. 6

1.3.1 Cross Development Environment ......................................................... 6

1.3.2 The Wind River Build System ................................................................ 6

Layers ......................................................................................................... 7Standard Product Layers ......................................................................... 8Optional Content with Feature Templates ........................................... 8When to Use Layers or Templates ......................................................... 9Sysroots ...................................................................................................... 9

1.3.3 Accessing the Sample Projects ................................................................ 9

1.3.4 Migrating Projects Forward .................................................................... 10

Wind River WorkbenchBy Example, 3.1 (Linux 3 Version)

iv

1.4 Notes about Installing Workbench ..................................................................... 11

1.4.1 Installation and Licensing ....................................................................... 11

1.4.2 Shared Installations .................................................................................. 11

1.4.3 Building across NFS ................................................................................. 11

1.4.4 Reporting Issues and Enhancements to Wind River ........................... 12

1.5 Finding Related Documentation ......................................................................... 12

1.5.1 Online Wind River Workbench for Linux Documentation ................ 13

1.5.2 Other Online Wind River Workbench Documentation ...................... 13

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

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

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

3.1 Introduction ............................................................................................................. 23

3.2 Wind River Linux Projects .................................................................................... 24

3.3 Your Programming Environment ........................................................................ 26

3.3.1 Using Windows, Solaris, or Linux Hosts .............................................. 26

3.3.2 Understanding the Toolchain Available to You ................................... 26

3.3.3 Using Workbench and/or the Command Line .................................... 27

Contents

v

3.4 Producing a File System and Kernel .................................................................. 27

3.4.1 Configuring Projects ................................................................................ 27

3.4.2 Building the File System .......................................................................... 28

3.4.3 Finding the File System and Default Kernel ........................................ 28

3.5 Accessing the File System and Kernel on a Target .......................................... 28

3.5.1 Real and Simulated Targets .................................................................... 29

3.5.2 Communicating with Targets ................................................................. 29

3.5.3 Exploring File Systems on Targets ......................................................... 29

3.6 Debugging and Analyzing on a Target .............................................................. 30

3.6.1 Debuggers ................................................................................................. 30

3.6.2 Dynamic printf Statements ..................................................................... 31

3.6.3 Analyzers and Profilers ........................................................................... 32

3.7 Productizing ............................................................................................................ 32

3.7.1 The Role of Your Application, Platform, or Kernel ............................. 32

3.7.2 Working in a Team ................................................................................... 33

3.7.3 Patching and Updating ........................................................................... 33

4 Life Cycle Development ...................................................................... 35

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


vi

4.8 Debugging and Deploying ................................................................................... 41

4.9 Optimizing ............................................................................................................... 42

4.10 Managing Content .................................................................................................. 43

PART II: DEVELOPING PLATFORMS

5 Developing Platform Projects ............................................................ 47

5.1 Introduction ............................................................................................................. 47

5.1.1 Building New Platform Projects—an Overview .................................. 48

5.1.2 Are You Deploying a New Platform Project? ....................................... 49

5.1.3 Connecting to a Target ............................................................................. 49

5.2 Creating Projects Using Workbench or the Command Line .......................... 50

5.2.1 Creating Platform Projects in General ................................................... 51

5.2.2 Creating an ARM Versatile Target, for Example .................................. 53

Example Data for You to Use .................................................................. 53Creating the By-Example Platform Project ........................................... 53

5.2.3 Verifying Your Project Build ................................................................... 55

5.3 Building a Target File System .............................................................................. 55

5.3.1 Verifying Your Build Directory ............................................................... 56

5.3.2 Building the Example ARM Versatile File System .............................. 56

5.4 Introducing the User Space Configuration Node ............................................ 57

5.5 Exploring the Target File System ......................................................................... 58

5.5.1 Examining File Meta Properties ............................................................. 60

5.5.2 Adding Files and Directories to Your File System ............................... 61

5.5.3 Removing Files According to Pattern Filters ....................................... 61

5.5.4 Viewing Parent Packages and Removing Packages ............................ 62

5.5.5 Adding a Device ....................................................................................... 62

Contents

vii

5.6 Using the Package Manager for RPMs ............................................................... 63

5.6.1 Introducing the Package Controls ......................................................... 65

5.6.2 Viewing and Editing the pkglist File ..................................................... 66

5.6.3 Installing Packages ................................................................................... 66

5.6.4 Using Force Install .................................................................................... 67

5.6.5 Installing Multi-lib Packages .................................................................. 67

5.6.6 Importing Packages ................................................................................. 68

5.6.7 Building Packages .................................................................................... 69

Including Builds with Runtime Dependencies .................................... 69Turning Package Debugging On or Off ................................................ 71

5.6.8 Removing Packages ................................................................................. 72

5.7 Creating a Project from a Package ....................................................................... 73

5.8 Customizing Builds with Layers, Templates, and Profiles ............................ 75

5.8.1 Adding Templates .................................................................................... 76

Adding Custom Templates ..................................................................... 77

5.8.2 Working with Layers ............................................................................... 78

Adding Layers .......................................................................................... 79Reloading Changes ................................................................................... 80

5.8.3 Exporting Layers ...................................................................................... 81

5.8.4 Specifying Profiles .................................................................................... 82

6 Configuring Platform Kernels ............................................................ 83

6.1 Introduction ............................................................................................................. 83

6.2 Configuring Wind River Linux Platform Kernels ........................................... 84

6.2.1 Kernel Configuration Node .................................................................... 85

6.3 Prepopulating LKM Projects ................................................................................ 87

6.4 Adding Kernel Modules to the Platform ........................................................... 87

6.4.1 Creating a Custom Kernel Module ........................................................ 88


viii

6.4.2 Moving Kernel Module Projects ............................................................ 89

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

7.1 Introduction ............................................................................................................. 91

7.2 Feature Templates ................................................................................................... 92

7.3 Profile Basics ........................................................................................................... 93

7.3.1 Making Your Own Profile ....................................................................... 93

7.3.2 Profile Hierarchy ...................................................................................... 93

7.3.3 Differences between Profiles and Platforms ......................................... 94

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

PART III: DEVELOPING APPLICATIONS

8 If You’re an Application Developer .................................................... 97

8.1 Introduction ............................................................................................................. 97

8.2 Creating Applications ............................................................................................ 98

8.2.1 Understanding Your Development Environment ............................... 99

8.2.2 Creating Applications in General .......................................................... 100

8.2.3 By Example: Building hello_world ........................................................ 100

8.2.4 By Example: Building Penguin .............................................................. 101

8.2.5 By Example: Importing Source Code for Penguin .............................. 103

8.3 Running Applications ........................................................................................... 106

8.3.1 By Example: Running hello_world, a Native Application ................. 106

8.3.2 Running Non-Native Mode Applications ............................................ 108

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

Contents

ix

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

9.1 Introduction ............................................................................................................. 111

9.2 Importing Sysroots ................................................................................................. 112

9.3 Importing Build Specs ........................................................................................... 113

9.4 Changing Build Properties ................................................................................... 114

9.4.1 Configuring Project Build Properties In General ................................. 114

9.4.2 By Example: Putting Penguin on a Different Target ........................... 116

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

10.1 Introduction ............................................................................................................. 117

10.2 Overview of the User Space Configuration Tool ............................................. 118

10.3 Importing Classic Packages from the Installation ........................................... 119

10.3.1 Modifying the Makefile ........................................................................... 120

10.3.2 Reusing Fixes for the Package ................................................................ 120

10.4 Importing Source RPM Packages from the Web .............................................. 121

10.4.1 Updating the Package Spec File ............................................................. 121

10.4.2 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 Maintaining Patches—First Principles .................................................. 128

11.1.2 Recognizing Classic Tarball Packages ................................................... 129

11.1.3 Recognizing SRPM Patches .................................................................... 129


x

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

11.2 Patching and Exporting Patches to Layers ......................................................... 131

11.2.1 Patching and Exporting Classic Packages (General Steps) ................ 132

11.2.2 By Example: Patching and Exporting Classic Packages to a Layer .. 132

11.2.3 By Example: Patching and Exporting SRPM Source File to a Layer . 133

11.3 Using Quilt Basics .................................................................................................. 135

11.3.1 Configuring Quilt to Manage Patches ................................................... 135

11.3.2 Applying Patches ..................................................................................... 135

11.3.3 Importing Patches .................................................................................... 137

11.3.4 Creating a New Top Patch File ............................................................... 137

11.3.5 Viewing Patch Annotations .................................................................... 138

11.4 Patching SRPM Packages ...................................................................................... 139

11.4.1 Manually Patching SRPM Spec Files ..................................................... 139

11.4.2 Patching SRPM Source Files ................................................................... 140

Modifying SRPM Package Files ............................................................. 141Saving SRPM Patch Files ......................................................................... 141Adding the SRPM Patch .......................................................................... 142Saving the Updates as a Patch to the Spec File .................................... 143

11.4.3 Testing the Patches ................................................................................... 143

11.4.4 By Example: Viewing the SRPM Patch List .......................................... 144

11.5 Manually Patching Classic Source Files ............................................................ 144

11.5.1 Creating a New Top Patch File ............................................................... 144

11.5.2 Modifying Package Files ......................................................................... 145

11.5.3 Exporting a Patch ..................................................................................... 146

11.5.4 Testing a Patch .......................................................................................... 147

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

12.1 Introduction ............................................................................................................. 149

Contents

xi

12.2 Working with Kernel Modules on the Target ................................................... 149

12.2.1 Installing Kernel Modules to the Target ............................................... 150

12.2.2 Removing Kernel Modules from the Target ......................................... 150

12.3 Working with RPMs on the Target ...................................................................... 151

12.3.1 Launching RPMs Straight to the Target ................................................ 151

12.3.2 Removing Running RPMs ...................................................................... 152

12.3.3 Replacing Running RPMs ....................................................................... 152

PART V: DEPLOYING TO YOUR BOARD

13 Assembling File Systems and Kernels ............................................. 155

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

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

14.1 Introduction ............................................................................................................. 159

14.2 Introducing Target Deployment .......................................................................... 160

14.2.1 Using a Typical NFS Target Networking Environment ...................... 160

14.2.2 Using an Emulated Target Environment .............................................. 160

14.2.3 Using a Flash Development Environment ........................................... 161

14.3 Connecting to Targets in General ........................................................................ 162

14.3.1 Defining a New Connection ................................................................... 162


xii

14.3.2 Connecting and Disconnecting .............................................................. 163

14.3.3 Modifying Connection Properties ......................................................... 164

14.4 Connecting to Emulated Targets .......................................................................... 164

14.5 Connecting with KGDB ........................................................................................ 167

14.5.1 Using Object Path Mapping .................................................................... 168

Pathname Prefix Mappings ..................................................................... 169Basename Mappings ................................................................................ 169

14.5.2 Using Target State Refresh Page ............................................................. 169

14.6 Using Advanced KGDB Options ........................................................................ 170

14.7 Using Target Server Options ................................................................................ 171

14.8 Using the Connection Summary Page ................................................................ 172

PART VI: DEBUGGING AND ANALYZING

15 Debugging User Space ....................................................................... 175

15.1 Introduction ............................................................................................................. 175

15.2 Using the Wind River Debugger ......................................................................... 176

15.2.1 Creating a Remote Connection ............................................................... 177

15.2.2 Viewing all Running Processes .............................................................. 177

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.6.1 Configuring a Signal ................................................................................ 181

15.6.2 Terminating a Process .............................................................................. 182

Contents

xiii

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

16.1 Introduction ............................................................................................................. 184

16.2 Background Steps and Concepts ......................................................................... 185

16.2.1 Setting Up for kgdboe Between a Target and a Development Host . 186

16.2.2 Using agent-proxy to Cross Subnet Boundaries for kgdboe .............. 186

16.2.3 Mounting the Target’s File System using NFS ..................................... 188

16.2.4 Kernels: Enabling KGDB versus Debug Builds ................................... 189

16.2.5 KGDB and Safe Areas when Debugging the Kernel ........................... 189

16.3 Preparing the Target for KGDB ........................................................................... 190

16.3.1 Option 1: Using a UDP Connection on a Non-PCD Target ................ 190

16.3.2 Option 2: Using a UDP Connection on a PCD Product ...................... 191

Statically Configuring KGDBOE for PCD (uclibc_small+small) ...... 191Dynamically 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 Option 1: Making an Ethernet Connection ........................................... 192

16.4.2 Option 2: Making a Telnet Connection ................................................. 194

16.4.3 Option 3: Making a Serial Cable Connection ....................................... 195

16.4.4 Troubleshooting a KGDB Connection .................................................. 195

16.5 Attaching and Debugging the Kernel from Workbench ................................ 196

16.5.1 If the Compilation Unit Source Is Not Found ...................................... 196

16.5.2 If the Target’s Terminal Is Stopped ........................................................ 197

16.5.3 Setting and Removing a Sample Breakpoint ........................................ 197

16.6 Debugging User-Supplied Kernel Modules ..................................................... 198

16.6.1 Building the Sample User-Supplied Kernel Module .......................... 198

16.6.2 Debugging a Running User-Supplied Kernel Module ....................... 199

16.6.3 Stepping into User-Supplied Kernel Module init from module.c ..... 200


xiv

16.6.4 Placing Breakpoints in Modules Not Yet Loaded ................................ 202

16.6.5 Providing Object Path Mappings to All Modules ............................... 203

16.6.6 Using the testmod Enhanced Sample Kernel Module ........................ 204

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

17 Optimizing ............................................................................................ 211

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.8.1 Looking up a Package’s Removal Size .................................................. 215

17.8.2 Looking up Packages that Require Particular Files or Directories .... 216

17.8.3 Looking up a Package’s Dependencies ................................................. 216

17.8.4 Saving and Restoring Footprint Snapshots .......................................... 216

Creating a Footprint Baseline Snapshot ................................................ 216Creating a Footprint Update Snapshot ................................................. 217Restoring a Footprint Baseline Snapshot .............................................. 217

17.8.5 Exporting Package Dependency Information ...................................... 218

Contents

xv

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

18.1 Introduction ............................................................................................................. 221

18.2 Acquiring Core Files .............................................................................................. 222

18.3 Attaching Workbench to a Core File ................................................................... 223

Core File Analysis .................................................................................... 224Ending the Session ................................................................................... 224

PART VII: DELIVERING YOUR PRODUCT

19 Providing Platforms and Kernels ....................................................... 227

19.1 Introduction ............................................................................................................. 227

19.2 Providing Platforms for Application Developers ............................................ 228

19.3 Exporting and Copying Sysroots ......................................................................... 229

19.3.1 Exporting Sysroots ................................................................................... 229

19.3.2 Copying Sysroots ..................................................................................... 230

19.3.3 Sysroots by Example: Adding 64-bit Multi-libs ................................... 230

Adding Available Multilibs .................................................................... 230Adding Multilibs That Are Not Yet Available ..................................... 231Verifying, Exporting, and Using the Multilibs Sysroot ...................... 231

19.4 Integrating Applications ....................................................................................... 232

19.5 Providing Kernels and Modules for Platforms ................................................ 232

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

20.1 Introduction ............................................................................................................. 233

20.2 Example: Preparing Layers that Modify Kernels ............................................. 234

20.2.1 Creating a Project and Modifying Its Kernel Configuration .............. 234

20.2.2 Tailoring and Exporting a Layer ............................................................ 237


xvi

20.3 Providing Layers to Teams and External Customers ....................................... 238

20.3.1 Making a Layer Available ....................................................................... 238

20.3.2 Telling Recipients How to Import and Use the Layer ........................ 239

20.3.3 By Example: Importing File System Change Lists from Layers ........ 239

PART VIII: REFERENCE

A FAQs ...................................................................................................... 243

A.1 Introduction ............................................................................................................. 245

A.2 Projects in General ................................................................................................. 246

A.3 Build Properties, Specs, Layers, and Templates ............................................... 249

A.4 Package Manager .................................................................................................... 250

A.5 Host-Related Issues ................................................................................................ 250

A.6 Application Projects ............................................................................................... 252

A.7 Debugging ............................................................................................................... 252

A.8 Troubleshooting ...................................................................................................... 253

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

B.1 Introduction ............................................................................................................. 255

B.2 Basic Requirements ................................................................................................ 255

B.3 Writing and Placing the Script ............................................................................. 256

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

C.1 Introduction ............................................................................................................. 259

C.2 Workbench and the Command Shell Environment ......................................... 260

Contents

xvii

C.2.1 Setting the Environment with wrenv .................................................... 260

C.2.2 Setting the Environment with Workbench ........................................... 260

C.2.3 Executing Workbench Build Commands .............................................. 261

C.2.4 Executing Shell Commands in Workbench .......................................... 262

C.3 Setting the Environment Without Starting a Sub-shell .................................. 263

C.3.1 Exporting Environment Settings to the Current Shell ........................ 263

C.3.2 Extracting Environment Settings ........................................................... 264

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

D.1 Introduction ............................................................................................................. 265

D.2 Basic Considerations .............................................................................................. 266

D.3 Shared Wind River Linux Installation ............................................................... 267

D.4 Local Workbench Installation .............................................................................. 267

E Glossary ................................................................................................ 269

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


xviii

1

PAR T I

Introduction

1 Overview ............................................................. 3

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

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

4 Life Cycle Development ..................................... 35


2

3

1Overview

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.


4

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 Overview1.2 How to Use this Guide

5

11.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 you’re 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


6

■ Debugging and analyzing what’s 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 system’s infrastructure includes layer support, including core and Linux kernel layers. It is not a traditional binary Linux distribution.

1 Overview1.3 Introducing Wind River Workbench and Linux

7

1The 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

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.

Figure 1-1 Build System Overview

Features...

Kernel

CoreBinary RPMs...

OptimizedBootable Image

RootFile System

Layers

Binary Kernel

sysroot

ProjectRepository

PackageSelection

ProjectCreation Smudges

Patches

Toolchain Wrappers

Package Builder

Toolchain

BuilderDeployable Image

Generator

File SystemGenerator

Hardware

QEMUSimulation

Targets

Wind River Build System


8

Layers provide both required and optional content for a target project, which allow you to:

1. Select and optimize the content first at the package level

2. Further optimize the content to develop runtime components

3. Generate the intermediate binaries (for example, the collection of generated RPM files from which the file system is assembled)

4. Trim and optimize those binaries (for example, stripping out debug information or adding pre-linking)

5. 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 Overview1.3 Introducing Wind River Workbench and Linux

9

1You 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.


10

1. Open Workbench.

2. Choose File > New > Example.

3. 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

1 Overview1.4 Notes about Installing Workbench

11

11.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.


12

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 User’s Guide — A guide to using the Workbench GUI to do tasks that are common between Linux and VxWorks.

■ 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 Documentation—See the next sections.

NOTE: The common guide’s 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.

1 Overview1.5 Finding Related Documentation

13

11.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 User’s 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


14

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 Workbench’s 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.

15

2Getting 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 it’s 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.)


16

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 target’s 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).

2 Getting Started with Workbench2.3 If You Develop Applications...

17

2

■ 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 don’t need a file system or kernel until you’re ready to test your software.

■ You don’t 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 user’s 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

8. If You’re an Application Developer; Workbench User’s Guide

Build commands provided by Workbench

Develop user-defined projects

“Creating User-Defined Projects,” Workbench User’s Guide

Using your own makefile; telling Workbench how to build your source

Edit, develop code Workbench User’s Guide

Debug 15. Debugging User Space; also, Workbench User’s Guide

Using GDB and/or the Workbench debugger

Analyze Memory Analyzer and Performance Profiler guides

Add binaries to platform projects

5.5.2 Adding Files and Directories to Your File System, p.61

Using file system layout tool


18

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


Import open source packages

10.4 Importing Source RPM Packages from the Web, p.121

RPM archives with source

Import local packages

10.5 Importing Wind River Linux Packages, p.123

Also see 10.3 Importing Classic Packages from the Installation, p.119

Develop, capture patches to layers

11. Patching Packages Also see 20. Delivering Layers

Enhance, investigate, work with code and code-related tools

12. Managing Packages on Live Targets

For example, find what’s wrong with open source, or MIPS vs. ARM, or 386 vs. 64-bit, or speed issues; if you touch open source packages, it means you’re fixing someone else’s code.

Debug 15. Debugging User Space; also, Workbench User’s Guide

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

2 Getting Started with Workbench2.5 If You Develop Middleware...

19

2

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.

■ You’re not really into doing packages: you’re 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.


Analyze Memory Analyzer and Performance Profiler guides

Static Indexer analysis for relationship between structures and files, for RPMs

Deploy as layer 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

Table 2-2 Package Development Tasks, Tools, and Document Links



20

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-3 Middleware Development Tasks, Tools, and Document Links


Develop DB queries, or Java, PHP, &c. pages

Documented by the community, for example at Eclipse.org

Insert them into file system

File System Manager Click location to put binaries, click on add, browse to files.

Table 2-4 Kernel Development Tasks, Tools, and Document Links


Configure and manage the kernel

Part IV. Developing Packages You can also import projects configured on the command line into Workbench

Develop kernel modules

12.2 Working with Kernel Modules on the Target, p.149; 19.5 Providing Kernels and Modules for Platforms, p.232

Sample kernel modules are provided

2 Getting Started with Workbench2.7 If You Are a Platform Integrator...

21

2

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


Create single and shared installations

Site Configuration Guide; Also D. Installing on Network Servers

Shared installations can be placed on NFS servers

Integrate layers 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75

Custom layers can also be generated and shared across the team

Integrate applications, packages, kernels

Adding Layers, p.79 in 5.8.2 Working with Layers, p.78; 4.6 Working with the File System Layout Tool, p.40

If there are kernel flags, you can capture them into a layer using the export layer feature.

Optimize 17. Optimizing Summary and pointers to other books

Deploy to target 14. Deploying to Targets Emulated and hardware

Deploy projects back as a layer

20. Delivering Layers; 20.2.2 Tailoring and Exporting a Layer, p.237

Using export-layer to capture the project's changes and share them with other projects and team members


22

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 Developer’s Guide: Creating a BSP

Working with components that make up a BSP, in view of the requirements for a Wind River Linux Platform BSP

Validate BSPs Wind River Linux BSP Developer’s Guide: Validating Boards

Using Linux Test Project (LTP), and the Open POSIX Test Suite (OPTS) operational tests and software test package, plus BSP Validation Suite

Table 2-5 Platform Integration Tasks, Tools, and Document Links


23

3Workbench 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?


24

■ 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 what’s on the target’s file system?

■ How do you debug what’s on the target?

■ What can you do with what you’ve 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 User’s 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 project’s active build spec.

Workbench projects are preconfigured to provide the type of build support required by the task you are working on.

NOTE: You can’t change a project type after you create it, so be sure to choose the correct project type initially.

3 Workbench Basics for Linux Developers3.2 Wind River Linux Projects

25

3

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


26

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 User’s Guide: Projects Overview, especially the sections on project structures involving sub- and 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.

3 Workbench Basics for Linux Developers3.4 Producing a File System and Kernel

27

3

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 Explorer’s right-click context menu.

Also you can create application projects in a command-line environment and then:

1. Import or create a new application project.

2. Right click in the Project Explorer and select Import > General > File System.

3. 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 \


28

> --enable-board=arm_versatile_927ejs --enable-kernel=standard \> --enable-rootfs=glibc_std

has the same effect as the Workbench Create Project wizard’s 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.

3 Workbench Basics for Linux Developers3.5 Accessing the File System and Kernel on a Target

29

3

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 target’s 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 User’s 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.


30

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 Mode—User 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 Mode—Kernel 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.

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:

NOTE: KGDB is enabled by default for Wind River Linux kernels and only needs to be disabled for you to go to production.

3 Workbench Basics for Linux Developers3.6 Debugging and Analyzing on a Target

31

3

(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.

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.

Table 3-1 Which Debugger for Which Project Type

Debugger Project Type

WDB Attach to Target

GDB C/C++ Attach to Local Application

GDB C/C++ Local Application

GDB C/C++ Postmortem debugger

GDB Native Application

KGDB Kernel Task

WDB Launch Control

WDB Process on Target

WDB RTP on Target

WDB Wind River Application

NOTE: If the Debugger tab does not exist, you are using the Wind River Debugger (WDB).


32

3.6.3 Analyzers and Profilers

The project’s 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 Workbench’s 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 company’s 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.

3 Workbench Basics for Linux Developers3.7 Productizing

33

3

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 River’s 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.


34

35

4Life 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


36

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

4 Life Cycle Development4.3 Where Does Your Work Fit into the Big Picture?

37

4

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.

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.

Figure 4-1 Overview of the Product Development Life Cycle

ProductSetup

RPMs, CVS, . . ., Applications

FilesPackagesUnit Tests

DocsLayers

SysrootsProfilesKernel

File System

Templates • Layers • Packages

Develop

On-Host Workbench Config • Edit • Compile

Diagnose

On-Host Workbench & TargetDeploy • Debug • Test

Optimize

Workbench, Eclipse, TargetStatic Analysis • Cores • FootprintSystem Layout • Views • Profiles

Requirements

Kernel ImageFile System Image

LayersSysroots

ProductDeliverables


38

■ Setup—You 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.

■ Develop—Based 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.

■ Diagnose—Starting 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.

■ Optimize—Using 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 Projects—an Overview, p.48.

4 Life Cycle Development4.5 Using Pre-Built User Space Content

39

4

2. Build a target file system. See 5.1.1 Building New Platform Projects—an Overview, p.48.

3. Connect to an actual or QEMU-emulated target. See 5.1.3 Connecting to a Target, p.49.

4. 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

For further study, see:

■ 5.8 Customizing Builds with Layers, Templates, and Profiles, p.75, regarding layers and templates

■ The Wind River Linux User’s Guide

4.5 Using Pre-Built User Space Content

When you make the file system (that is, right-click a project’s 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.)

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 kernel’s source directory, which will be in your project’s 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.


40

To see which architectures were built for specific packages:

1. Double-click the project’s User Space Configuration node to open the Package Manager.

2. 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. Open the Package Manager.

2. Highlight the package to rebuild, then click the Targets tab.

3. Click the rebuild button.

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. Double-click the User Space Configuration node.

2. Click the Filesystem Layout tab below the Installed Packages panel. See 5.5 Exploring the Target File System, p.58.

3. Look for file ownership, placement of files by RPM, sizes, and so on.

4. Observe that you can search for files in the various filters provided.

5. 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.

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 Life Cycle Development4.7 Configuring Kernels

41

4

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.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 don’t 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:


42

■ 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 User’s Guide.

■ For launch configurations, see the Wind River Workbench User’s 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

4 Life Cycle Development4.10 Managing Content

43

4

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

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


44

45

PAR T II

Developing Platforms

5 Developing Platform Projects ........................... 47

6 Configuring Platform Kernels ........................... 83

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


46

47

5Developing 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


48

are only supported on a common PC running Linux. For more information, see the Wind River Workbench User’s Guide: Developing Applications.

5.1.1 Building New Platform Projects—an Overview

Typically, you can use the following steps as a checklist to create new platform projects:

1. Create a Wind River platform project.

2. Right-click in the project’s 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.

Figure 5-1 The Platform Development Stage of the Product Life Cycle

Platform Setup

RPMs, CVS, . . ., ApplicationsBinaries

Docs


Develop


Diagnose


Optimize


Requirements

Packages

Sysroots

PlatformDeliverables

Other Tools

Package ManagerQuilt

Open Source Package ImportPatch Manager

Sysroots

Relevant Tools

File System Layout ToolLayers

KernelFile System

Non-Binary Files

Kernel ModulesLayers

Build Specs

User Space Configuration

5 Developing Platform Projects5.1 Introduction

49

54. 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. In the Remote Systems toolbar, click Define a connection.

b. 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.

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.


50

■ Backend Connection—For use with KGDB, providing a command-line interface to QEMU to start, stop, query registers, and so on.

■ Connection—Also 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).

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

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.

5 Developing Platform Projects5.2 Creating Projects Using Workbench or the Command Line

51

5

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. Enter a name for the project and click Next.

3. 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 River’s real-time kernel, installed optionally), depending on the choice of RootFS.

4. You can see the configure command at the bottom of the wizard:

5. (Optional) You can also use Workbench’s 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:

NOTE: You cannot edit the configure command directly, but you can use the following step to edit it under guidance from Workbench.


52

b. Click Add to open the Option/Value dialog box.

c. 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. When you have finished adding options, click OK.

6. (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 workspace—one with the project name (project) and one with the project name plus a _prj extension (project_prj).

Output from the configure command appears in the Build Console and is stored, with additional information, in the project/creation.log file.

NOTE: If you are importing an existing platform project, Workbench uses the existing project’s location, and does not create a project_prj folder.

5 Developing Platform Projects5.2 Creating Projects Using Workbench or the Command Line

53

5

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.

Example Data for You to Use

Use the following example data to create and configure a new platform project.

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.

Table 5-1 Example Platform Project Parameters

Data Field in GUI Entry

project name Project name my_arm

board Board arm_versatile_926ejs

file system size RootFS glibc_std

kernel type Kernel standard


54

1. Select New > Wind River Linux Platform Project, name your project my_arm, then click Next.

2. 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 User’s 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.

5 Developing Platform Projects5.3 Building a Target File System

55

5

5.2.3 Verifying Your Project Build

Use the Project Explorer to verify that your platform project is successfully built.

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.

Figure 5-2 Platform Project


56

5.3.1 Verifying Your Build Directory

If you want to view your build in more detail:

1. Open a terminal.

2. Change directories to your workspace/ProjectName_prj directory.

cd /workspace/ProjectName_prj

3. 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:

5 Developing Platform Projects5.4 Introducing the User Space Configuration Node

57

5

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/*

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.

To use the User Space Configuration node:

1. In the Project Explorer, double-click User Space Configuration.

2. 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.

NOTE: If you are following the example and using the table data, you should see the same names as above.

NOTE: Some Wind River literature uses the acronym USE, for User Space Editor.


58

■ 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.

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.

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.

5 Developing Platform Projects5.5 Exploring the Target File System

59

5

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

Figure 5-3 File System Layout Showing Size


60

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)

5.5.1 Examining File Meta Properties

To examine file properties:

1. Create a platform project.

2. Double-click the project User Space Configuration node.

3. Click the Filesystem tab in the lower left, and observe the file system tree.

4. To examine the meta properties of files:

a. Open the bin directory, and examine the first file (for example, arch).

b. 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)

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 Developing Platform Projects5.5 Exploring the Target File System

61

5

■ 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. Right-click on the directory /usr and select New > Folder.

2. Enter the name samples. The new folder is added, with a “+” icon.

3. Right-click the directory /usr/samples and select Add.

4. 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.

5.5.3 Removing Files According to Pattern Filters

To use pattern filters to remove files:

1. Open a project’s User Space Configuration node.

2. Open the Filesystem tab.

3. Enter the string *.pl in the Pattern Filter. field.

4. 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.

NOTE: This step assumes that you have built an application project; specifically, for this example, the mthread application.


62

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. In the File System Layout view, click the View icon to the right of the Pattern Filter field and choose Packages.

2. 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. Open the tree to perl-5.8.7-1_WR_a/usr/bin.

2. Right-click this directory, then click Remove. All files in this directory now have a “-” icon.

3. Right-click the perl-5.8.7-1_WR_a/usr directory then select Remove. All resources under Perl are marked with a “-” icon.

4. 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. Right-click the /dev directory then select New > Device.

2. Use the settings Char,”luckyDevice”,7,11. The new device appears with the added package name.

3. Right-click the device and change the owner to lady and the group to luck.

4. Right-click this new device and select Remove.

5 Developing Platform Projects5.6 Using the Package Manager for RPMs

63

5

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.

Some of the Package Manager’s 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.

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.


64

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.

Figure 5-4 RPMs with 0 Bytes are Placeholders for Packages


65

5

■ 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.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 Moves packages from the Installable Packages list into pkglist

Check Confirms the integrity of the package list

Erase Removes RPM file from live target, by doing an rpm -erase

Force Install Installs RPM files on live target, by doing an rpm -install -force; ignores dependencies; see 5.6.4 Using Force Install, p.67

Import Adds packages not in the Installable Packages list; see 5.6.6 Importing Packages, p.68

Install Installs RPM on live target, by doing an rpm -install; see 5.6.3 Installing Packages, p.66

Open Opens pkglist for editing

Reload Reloads package lists from pkglist, typically after editing it

Remove Deletes from pkglist and puts into Installable Packages; see 5.6.8 Removing Packages, p.72

Replace Does an rpm -erase then an rpm -install on the target

Revert Restores pkglist to before view was opened

Save Saves changes


66

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. Use File > Save to save them.

b. Right-click within the Installable Packages list in the Package Manager.

c. 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.

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.


67

5

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. First, choose iptables-ipv6, because of the dependency.

b. Select Erase from the context menu.

c. Choose iptables and click Erase.

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. Create a Cavium platform project.

2. Add the following library lines to pkglist:

glibc.mips64_octeon libgcc.mips64_octeon

3. Export the sysroot (see 19.3.1 Exporting Sysroots, p.229). Now it includes these extra multi-libs.

4. 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.


68

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.

To import packages:


1. Click the Import button.

2. Click Import Package.

The Package Import Tool appears.

3. Click the package type or source:

■ File—Classic Red Hat SRPM packages in bz2, gz, tgz, zip, or src.rpm format, on your system or LAN.

■ Wget—Packages available on the web via URL.

■ WR Linux Package—Wind 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. Click Go. A shell window opens to display the import activity.

6. Press Enter as needed to return to the import tool from the shell.

7. Examine the progress window to see that it has completed satisfactorily.

8. Click Close. The package imports.

NOTE: If you see a pointer size warning for the octeon spec, it does not affect the build success.

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.


69

5

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.


70

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 RPM’s icon shows a blue "?" decoration, the RPM and its metadata are unavailable until the package is built.

Figure 5-5 Placeholder RPMs with Dependencies


71

5

This means that there is no RPM file available in either the installation prebuild or in the project’s 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. Select the package.

2. Click the Options tab.

3. Check or clear Debug.

Figure 5-6 Unavailable RPMs


72

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.

5.6.8 Removing Packages

To remove packages:

1. Select the Dependencies tab.

2. Select a package such as openssl from the Installed Packages list that contains entries in both the Required and Required By panels.

3. Click Remove to remove the installed package that you have selected.

NOTE: For BUILD_TYPE=profiling, see 17.3 Profiling CPU Usage with OProfile, p.213.

5 Developing Platform Projects5.7 Creating a Project from a Package

73

5

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

Workbench’s 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. Double-click the User Space Configuration node of the platform project.

2. 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.


74

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:

5 Developing Platform Projects5.8 Customizing Builds with Layers, Templates, and Profiles

75

5

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


76

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.

To add templates 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.

2. Click Advanced > >.

3. 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 READMEIntroduction============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

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.


77

5

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.

Table 5-3 Some of the Supplied Templates

Template Function

extra/wrsnmp Enables Wind River SNMP and the SNMP Agent.

feature/acpi Incorporates and starts the logging daemon on kernel-acpi enabled boards with cgl and std file systems.

feature/busybox Adds the busybox package and sets up the configuration file in busybox/busybox/config.

feature/debug Adds the usermode-agent to small file system projects.

feature/directfbfusion Lets multiple DirectFB applications run at the same time within a session.

feature/glibc_discrete Replaces busybox with a set of full-featured, discrete utilities (such as in glibc_standard).

feature_glibc_small_extras( Replaces busybox with a set of small, extra utilities such as in glibc_small).

feature/ipmi Adds the IPMI package and enables support for IPMI controllers.

feature/prelink Modifies ELF shared libraries and executables, to require fewer relocations to be resolved at runtime.

feature/uclibc Replaces glibc with the uclibc C library for MIPS and ARM targets with one or more uclibc rootfs names.

feature/unionfs Lets you boot from CD-ROM, for BSPs with CD-ROMs.


78

■ 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 User’s 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 User’s 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 User’s 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.


79

5

■ 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.

Use the example data in the following table to create and configure a platform and add and remove layers.

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

Table 5-4 Basic Provided Layers

Layer Path from installDir/wrlinux-3.0 Notes

Linux /layers/wr11-wrlinux Base layer and source tree

Kernel /layers/wr11-linux-2.6.27 Default layer

Toolchain /layers/wr11-toolchain-4.3.78 Default toolchain

Real Time Core /layers/wr11-rtcore-5.2 Optional layer

Table 5-5 Example Parameters


board Board common_pc



project name Project name rtcore_test


80

5.2 Creating Projects Using Workbench or the Command Line, p.50, but use the parameters from Table 5-5.

2. Click Advanced > >.

3. Click Add to the right of the Layers box.

4. 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. Observe that the kernel select field automatically changes to rtcore.

b. Click Remove to delete this layer. Notice that Workbench rescans the environment that no longer contains the layer.

c. The kernel select field automatically reverts to standard.

6. 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.


81

5

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.

Figure 5-7 Reload Button to Speed Up Layer List Changes


82

5.8.4 Specifying Profiles

The Configure Options screen’s 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.

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 User’s Guide: Identifying Explicit and Implicit Templates. (Figure 5-8 shows that <no_kernel > has been selected.)

Figure 5-8 Template and Profile Features in Platform Project Wizard

83

6Configuring 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.


84

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

Figure 6-1 Configuring Kernels: The Development Stage of the Product Life Cycle

Kernel Setup

RPMs, CVS, . . ., Kernel Modules


Develop


Diagnose


Optimize


Requirements

Kernel Deliverables

POSIX SignalsQEMU

Wind River Debugger

Relevant Tools

FiltersKconfig

Kernel ModulesKernel

Dependencies

Other Tools

Bus Options (CPU)Build Target

Patches

6 Configuring Platform Kernels6.2 Configuring Wind River Linux Platform Kernels

85

6

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.

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.

NOTE: By moving your cursor around inside the Kernel Configuration view, you can find the drag points to enlarge view sections.


86

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,

6 Configuring Platform Kernels6.3 Prepopulating LKM Projects

87

6

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.

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.

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.

Figure 6-2 Adding Default (Template) Sources to Linux Kernel Module Project

NOTE: You will not see this option when you import a command-line LKM project or one of the example projects.


88

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.

2. Right-click and select New > Wind River Linux Kernel Module Project.

3. Assign a name to your kernel module project and click Next.

4. 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.

6. Click Finish.

NOTE: For more about super and sub projects, see Wind River Workbench User’s Guide: Structuring Projects.

6 Configuring Platform Kernels6.4 Adding Kernel Modules to the Platform

89

6

The kernel module project now appears as subproject of the platform superproject in the Project Explorer.

7. Import source files:

a. Right-click the new kernel module project and select Import > General > File System.

b. Browse to installDir/wrlinux-3.0/samples/moduledebug_2_6.

c. Click OK.

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. Right-click the kernel module project and select Build Options > Clean Project.

2. Right-click the platform project that currently contains the kernel module subproject, then select Properties.

3. 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. Right-click the platform project that you want to contain the kernel module subproject and select Properties.

5. 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.


90

91

7Feature 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.

See 20.2 Example: Preparing Layers that Modify Kernels, p.234.

NOTE: Workbench automatically adds this template if you select a small filesystem when you’re in the Project Wizard.


92

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 features—see 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

7 Feature Templates and Profiles7.3 Profile Basics

93

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

■ Package—the lowest common denominator

■ Component—a group of packages delivering a named functionality

■ Profile—a group of components delivering a vertical solution, for example, a smart phone, a feature phone, or an MP3 player


94

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).

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.

NOTE: While there can be many templates, there can be only one profile in a project’s configure command.

95

PART II I

Developing Applications

8 If You’re an Application Developer ................... 97

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

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


96

97

8If You’re 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.


98

Much of application development in terms of editing and compiling source is described in the Wind River Workbench User’s 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 User’s 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 User’s 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.

Figure 8-1 The Application Development Stage of the Product Life Cycle

Application Setup

RPMs, CVS, . . ., Application SourceDocs

Sysroots


Develop


Diagnose


Optimize


Requirements

PackagesPatches

Unit Tests

ApplicationDeliverables Other Tools

Edit, Script, Make

Coverage

Package Manager

usermode-agent

profiling, memory analysis

System Viewer

Relevant Tools

Launch Configurations

Packages, Files

Other FilesBinaries

8 If You’re an Application Developer8.2 Creating Applications

99

7

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 User’s Guide: Changing Basic Linux Configuration Files and the Wind River Linux User’s 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 User’s Guide), you used cross-development tools to generate a build target for your target architecture.


100

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.

Why we chose this example:

■ It needs only a few GUI actions.

■ It is documented more thoroughly in the Wind River Workbench User’s Guide: Creating Native Application Projects.

To build hello_world:

1. Right-click anywhere in the Project Explorer (at the upper left of the Workbench perspective) and select New > Example.

2. In the Select a Wizard page, choose Native Sample Project and click Next.

3. 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.

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


101

7

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 User’s Guide.

Why we chose this example:

■ It is not documented in the Wind River Workbench User’s 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.

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


102

To build Penguin:

1. Right-click anywhere in the Project Explorer (at the upper left of the Workbench perspective) and select New > Example.

2. In the Select a Wizard page, choose Wind River Linux Application Sample Project and click Next.

3. In the Sample Project Template page, select The Penguin Demonstration Program, and click Finish.

4. Workbench creates the Penguin application project. The sample project contains all the necessary files to build the program.

5. 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.


103

7

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.

The following table shows the GUI entries for this example.

To import source files for an application:

1. Right-click in the Project Explorer, choose New > Wind River Linux Application Project, and enter the project name.

2. Click Finish.

3. Right-click the MyPenguin project and choose Import.

4. Choose General > File System and click Next.

5. Next to the From directory field, click Browse.

6. In the Import from directory dialog box that appears, find the source directory for the files to be imported:

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.

Table 8-4 Basic Application Data for Importing Penguin Source


Project name Project name MyPenguin


104

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:


105

7

9. Optionally, you can specify the folder to contain the imports, and the options to overwrite, create complete folder structure, or create selected folders only.

10. Click Finish.

11. Workbench imports the files into your application project:


106

12. Right-click the project name, select Build Project, and click Generate Includes.

13. Click Next, Next, and Finish.

14. 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

8 If You’re an Application Developer8.3 Running Applications

107

7

To run a native application such as hello_world, use the following steps:

1. Right-click the project and choose Run Linux Application Process.

2. Click Run to accept the configuration launch defaults:


108

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 User’s Guide: The Registry.

8 If You’re an Application Developer8.4 Changing Build Specs and Properties

109

7

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. Right-click your application project and choose Properties.

2. Click Build Properties.

3. Use the appropriate tab, depending on which properties you want to change:

Table 8-6 Build Properties Tabs

Build Support and Specs Use IDE-generated makefiles; specify build command and build specs

Build Tools Specify build tool (assembler, compiler, linker, librarian); output generation; build-spec-specific settings and so on

Build Macros Build macro definitions; spec-specific settings

Build Paths Redirection root directory, build spec settings, include paths

Libraries Libraries per specified active build spec


110

111

9Sysroots, 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.


112

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. Choose Window > Preferences > Wind River > Layers and Sysroots.

2. Click Add to the right of the Sysroots panel.

3. Browse to the location of your sysroots.

4. Click OK.

For multi-lib-specific information, see 5.6.5 Installing Multi-lib Packages, p.67.

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.

9 Sysroots, Build Specs, and Properties9.3 Importing Build Specs

113

8

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. Right-click the application project and select Properties > Build Properties.

2. In the Build Support and Specs tab, click Import.

3. 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.

4. 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.

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.


114

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. Right-click the project name; for example, penguin (Wind River Linux Platform 3.0 Application).

2. Select Properties.

3. 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:

9 Sysroots, Build Specs, and Properties9.4 Changing Build Properties

115

8

5. Click OK to save any modified build properties.

Workbench displays the build spec’s name on the Build Targets node, shown below as arm_versatile_926ejs-glibc-std-armv5tel_vfp-wrlinux_2_0.


116

9.4.2 By Example: Putting Penguin on a Different Target

You can assign a different target for applications such as penguin.

To re-assign a target:

1. Right-click penguin.

2. Choose Properties > Build Properties > Build Macros.

3. Click the down arrow for Active build spec.

4. Choose common_pc-glibc_std-i686-wrlinux_2_0 and click OK.

5. Verify that you have changed the target for penguin:

Table 9-1 What You Need for This Example

Required Data Notes

Creation of penguin application project

Source is in installDir/wrlinux-3.0/samples

117

10 Importing Packages


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.


118

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. 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.

2. 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. 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.

4. Click Go to open a shell window and display the script activity.

5. Press Enter until you exit the shell.

6. 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.

10 Importing Packages10.3 Importing Classic Packages from the Installation

119

9

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.

To import a classic package:

1. Open the User Space Configuration tool.

2. From the Installable Package list, click Import. The Package Import tool opens.


4. Select File and then click Browse to locate the archive for this example:

installDir/wrlinux-3.0/layers/wrll-wrlinux/packages/package.tar.gz



7. When the import tool completes satisfactorily, click Close to allow other Workbench actions, such as builds or Quilt actions.

8. From Installed Packages, select the new entry and then click the Targets tab.

9. 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.

NOTE: For an explanation and definition of classic packages, see 11.1.2 Recognizing Classic Tarball Packages, p.129.


120

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.

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 User’s 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.

4. (Optional) To start a new patch file (rather than use the default top-most path file) select Quilt > New Patch.

5. 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.

10.3.2 Reusing Fixes for the Package

To reuse fixes already prepared for this package in the wrlinux installation:


2. Select the new package and click distclean in the Target tab.

3. Right-click the project and select Open Workbench development shell.

4. In the development shell, enter the following commands:

$ cd ../project_prj $ rm -rf dist/package*

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.

NOTE: If you are continuing from the previous example, click distclean and then delete the project/dist/package directory.

10 Importing Packages10.4 Importing Source RPM Packages from the Web

121

9

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:


2. From the Installable Package list, click Import.

The Package Import tool opens.


4. Select Wget and then enter the URL of an SRPM package, for example: http://download.fedora.redhat.com/pub/fedora/linux/releases/7/Fedora/source/SRPMS/dos2unix-3.1-28.fc7.src.rpm.



7. When the import tool completes satisfactorily, click Close to allow other Workbench actions, such as builds or Quilt actions.

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. 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.

2. 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

http://download.fedora.redhat.com/pub/fedora/linux/releases/7/Fedora/source/SRPMS/dos2unix-3.1-28.fc7.src.rpm



122

4. Right-click the spec file, select Add File to Top Patch, and click OK to accept the change.

5. Use the Workbench text editor to make the following change to the dos2unix.spec file:

a. Immediately following every %build and %install section header, add the %configure_target RPM macro.

b. (Optional) Add a change indicator (such as -WR), to the Release line.

c. (Optional) Add an entry to changelog.

6. Right-click the spec file, select Quilt > Refresh Top Patch.

7. Click OK.

The modified dos2unix-wr-integration.patch file is located in the build/dos2unix-3.1-28.fc7/patches directory.

10.4.2 Building New Packages


2. 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.

4. Copy the new patch file to dist/dos2unix/patches and update the patches.list file.

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.

NOTE: For more information about patching, see 11. Patching Packages.

NOTE: You can also use this procedure to import other packages.

10 Importing Packages10.5 Importing Wind River Linux Packages

123

9

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:


2. From the Installable Package list, click Import. The Package Import tool opens.


4. 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



7. 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.


124

125

PAR T IV

Developing Packages

11 Patching Packages ............................................. 127

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


126

127

11 Patching Packages


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.


128

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 Grünbacher’s “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 User’s Guide: Patch Principles and Workflow.

11.1.1 Maintaining Patches—First 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.

b. Locally develop new code and new patches to extend existing code.

c. Validate work against the central code base before checking in changes and patches.

d. Check in changes.

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.

http://www.suse.de/~agruen/quilt.pdf

11 Patching Packages11.1 Introduction

129

10

11.1.2 Recognizing Classic Tarball Packages

Classic packages are distributed as tarballs containing an application’s 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 section—see 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:

■ 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 package’s 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.


130

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 installation’s layers/wrll-wrlinux/dist/package/patches directory.

You can see the spec file’s 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 .

NOTE: For more details, and for help creating an exact spec file replacement that doesn’t need a patch file, see the Wind River Linux User’s Guide: Adding Packages.

Table 11-1 Quilt Menu Commands

Command Function

Add File to Top Patch Adds one or more files to the top-most or named patch.

Add New File to Top Patch Adds a new file.

Annotate File Displays an annotated listing of the specified file, showing which patches modify which lines.

Compare With Compares (using diff) the specified files in the top-most or specified patch.

Delete Patch Removes the specific or top-most patch.

Export 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.

11 Patching Packages11.2 Patching and Exporting Patches to Layers

131

10

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.

Files Displays the list of files that the specific or top-most patch modifies.

Fold Patch 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.

Import Patch Imports external patches, following the current top-most patch.

New 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.

Patches Lists the patches that modified a specified file.

Pop 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.

Push Applies one or more patches from the series file. Click Details to list the files patched by the push.

Refresh Top Patch Refreshes a specific patch or the default top-most one.

Reload Synchronizes information that Workbench has cached (such as command-line use of Quilt).

Rename Patch Renames a specific or top-most patch.

Remove File from Patch Removes file(s) from the named or top-most patch.

Table 11-1 Quilt Menu Commands

Command Function


132

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. Select a package in the Installed Packages list of your platform package’s Package Manager view, right-click the Targets tab, and click patch.

2. Open the platform project’s 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. Right-click the patch file, select Export Patch to Layer, and enter an export location.

4. Select the classic package in the Installed Packages list; click the Targets tab, click distclean, and then patch.

5. 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. Create a Platform Project.

2. Open its User Space Configuration node.

3. Select the wrproxy package.

4. Click the Targets tab, and click Patch.

5. Right-click the project, and select Add Links to Development Folders.

Step 2: Change the package

1. Open the project tree build > wrproxy > Quilt Patches.

2. Observe that the patch kerntree.patch is the top-most patch (in bold).

11 Patching Packages11.2 Patching and Exporting Patches to Layers

133

10

3. Open the list under kerntree.patch, and double-click the file wrProxyTipcSockLib.c.

4. Make a minor text addition such as in the copyright area, and select File > Save.

Step 3: Export the patch to a layer

1. Right-click kerntree.patch, or another patch of your choosing, and select Quilt > Refresh Top Patch.

2. Right-click it again and select Export Patch to Layer.

3. Reset the layer path to installDir/wrlinux-3.0/layers/wrll-wrlinux, if it is not this path already.

4. Select the layer to receive the patch.

5. Add a quick description, and click OK.

6. Click OK in the resulting dialog.

Step 4: Test the patch

1. Open User Space Configuration in a project.

2. Select the wrproxy package.

3. Click the Targets tab, and click distclean and then patch.

4. Right-click the build tree, and select Refresh.

Step 5: 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 package’s spec file.

Step 1: Unpack and patch the package

1. Open the User Space Configuration node onto the Package Manager.

2. Select the acpid package.

NOTE: First, you need to patch the SRPM spec file. See 11.4.1 Manually Patching SRPM Spec Files, p.139.


134

3. Click the Targets tab, and click patch.

4. Open the project tree build > acpid-1.0.6.7-fc9 > Quilt Patches.

5. Observe that patch pkgname-wr-integration.patch is the top-most patch.

Step 2: Change a package file

1. Right-click the pkgname-wr-integration.patch, select Quilt > New Patch, and give it the name myChanges.patch.

2. Open the tree to build > acpid-1.0.6.7-fc9 > BUILD > acpid-1.0.6, and double-click acpi_listen.c.

3. Right-click acpi_listen.c, and select Quilt > Add to Top Patch.

4. Make a minor text addition in the copyright area, and select File > Save.

Step 3: Export the patch to a layer

1. Right-click myChanges.patch, and select Quilt > Refresh Top Patch.

2. Right-click it again and select Export Patch to Layer.

3. Add a description, and click OK.

4. Click OK in the resulting dialog.

Step 4: Test the patch

1. Open the project’s User Space Configuration node onto the Package Manager.


3. Click the Targets tab, and click distclean and then patch.

4. Right-click the build tree, and select Refresh.

5. 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: You may need to click on the package-version node and choose Refresh to see the new top 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.

11 Patching Packages11.3 Using Quilt Basics

135

10

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:

■ 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 project’s 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. Select an installed package, for example, boa.

2. 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.


136

3. Expand the package-version folder to display the Quilt Patches node.

4. 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.

Figure 11-1 Package Manager’s Packages List

11 Patching Packages11.3 Using Quilt Basics

137

10

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. Open the package-version folder of the package to be patched, and then the Quilt Patches folder.

3. 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.

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. Double-click User Space Configuration.

b. Select the package, click the Targets tab, and then click patch.

c. 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. Open the build folder, then package-version, then Quilt Patches (a virtual folder displaying the Quilt-applied patches).

3. 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.


138

11.3.5 Viewing Patch Annotations

Quilt supports a patch annotation feature, which you can use as follows:

1. Open a project and then browse to and select a file under the specific patch.

2. Right-click the file and select Quilt > Annotate File.

The file displays.

3. Scroll through the file and view the colored bars in the left-hand margin.

4. 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.

11 Patching Packages11.4 Patching SRPM Packages

139

10

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

To unpack and apply current patches to the spec file:

1. Open a platform project.

2. Double-click User Space Configuration to open the Package Manager.

3. Select the package, click the Targets tab, and click patch.

4. Right-click your project and select Add Links to Development Folders.

The build tree displays in the Project Explorer.

5. Open the build tree and browse to package-version > Quilt Patches > package-wr-integration.patch.

6. Open the SPECS/package.spec file, which is the Quilt patch-managed file.

Step 2: Modify it

7. Change one of the initial comment lines, for example.)

8. Select File > Save to save your changes.

9. In the Package Manager, click build or rebuild (in the Targets tab) to verify your changes.


140

Step 3: Save it

1. Right-click the package-wr-integration.patch node and select Quilt > Refresh Top Patch.

2. Right-click wr-integration.patch again and select Quilt > Export Patch.

3. 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. You do not need to update the patches.list file because this patch file is already registered.

5. Append the patch file name to the patches.list file, for example:

# This comment explains the purpose of this patchNewbzip2-wr-integration.patch

Step 4: Test it

1. Open the Package Manager and select the package.

2. From the Target tab, click distclean.

3. 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.

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.


141

10

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.

To patch an SRPM source file:

1. Create a new top patch file.

2. Save your patch file to the installation or layer location.

3. Add the new patch file to the SRPM rpm_patch.list patch list file.

4. Register the new patch file in the package spec file.

5. Update and save the spec file registration change in its respective wr-integration.patch file.

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. Browse the build > package-version source tree and select a source file.

2. Right-click the file and select Quilt > Add New File to Top Patch.

3. Modify the file and select File > Save to save your changes.

4. Right-click the file again and select Quilt > Refresh Top Patch to capture the changes to your new patch file.

5. Double-click User Space Configuration, and in the Targets tab click build or rebuild to verify your changes.

Saving SRPM Patch Files

1. Right-click the SRPM patch file and select Quilt > Export Patch.

2. Save your patch to installDir /wrlinux-3.0/layers/wrll-wrlinux/dist/package/patches.

NOTE: Ignore errors like cat: write error: Broken pipe. These messages are a passive artifact of Quilt.


142

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. Open each patch file.

b. 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. Open the wr-integration.patch tree and double-click the SPECS/pkg.spec file.

2. 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.patchPatch5003: coreutils-6.9.2-custom_EXTRA_DIST.patch

3. Add your patch entry after the last Patchxxxx: entry in the spec file.

4. (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.


143

10

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. Pop the source file patch or patches to get the wr-integration patch back to the top-most location on the stack.

2. Right-click package-wr-integration.patch and select Quilt > Refresh Top Patch.

3. Right-click package-wr-integration.patch and select Quilt > Export Patch.

4. 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. Open the project build/pkg-version/Quilt Patches virtual folder in the Project Explorer.

6. 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.

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. Open the Package Manager via the User Space Configuration node.

2. Select the package, click the Targets tab, and click distclean.

3. Click patch to apply the spec file patch and all the new custom patches in the spec file.

4. (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.


144

■ The before/after filename entries are listed in the source patch file.

5. (Optional) Repeat the package distclean and patch rules until all errors are resolved.

6. 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. Open the Package Manager from a project’s User Space Configuration node.


3. Open the Targets tab, then click patch.

4. 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.

11 Patching Packages11.5 Manually Patching Classic Source Files

145

10

2. Double-click User Space Configuration to open the Package Manager.

3. Select the package, click the Targets tab, and click patch.

4. Right-click the project and select Add Links to Development Folders. The build tree displays in the Project Explorer.

5. Open the build tree and browse to build > package-version > Quilt Patches (a virtual folder displaying the Quilt-applied patches).

6. 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.

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. Right-click the file and select Quilt > Add New File to Top Patch.

3. Give the patch file a new name, or enter the old one, then click OK:

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.


146

4. Modify the file and select File > Save to save your changes.

5. 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.)

6. Double-click the User Space Configuration node, and, in the Targets tab, click build or rebuild to verify your changes.

11.5.3 Exporting a Patch

After modifying your patch, you must export it to the appropriate installation location.

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.

NOTE: Keep a copy of the previous file version and be sure you have a back-up.

11 Patching Packages11.5 Manually Patching Classic Source Files

147

10

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.

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

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 Configuration’s Installed Packages list.

Double-click the User Space Configuration icon and click Packages to open the Package Manager if it is not visible.

2. From the Target tab, click distclean.

3. Click patch to apply the patch. Your changes are applied to the spec file.

NOTE: If patches.list does not exist, create it and add the patch filename(s).


148

149

12 Managing Packages on Live

Targets


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.


150

12.2.1 Installing Kernel Modules to the Target

To install a kernel module, such as moduleDebugExample.ko:


2. Build the kernel and file system.

You need this step to set up the module development support in the kernel directory.

3. Create the moduledebug_2_6 sample kernel module project, attach it to the platform project, and build it.

4. Boot the target.

5. Attach the usermode-agent. (You must have an active usermode-agent running on the target.)

6. Right-click moduleDebugExample.ko in the project explorer, and select Insert Module.

7. 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.)

8. Click OK to insert the module into the running target.

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.

12 Managing Packages on Live Targets12.3 Working with RPMs on the Target

151

11

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 target’s 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.

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. Right-click an RPM in the Package Manager list and select Install.

2. Accept the connection request if asked. If Workbench asks for usermode arguments, it does not need any.

3. Decide which connection to use, if asked. (You can also start, stop, or create a connection at this point.)

4. Click OK to launch the RPM into the running target.

5. When the RPM finishes, look for a done message. The console and its thread close automatically.

6. 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.

7. When the upload finishes, the pop-up disappears, but this is when the target-resident script actually starts to run.

8. 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.

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.)

NOTE: There is no RPM manager on glibc_small and uclibc_small file systems.


152

12.3.2 Removing Running RPMs

To remove an RPM such as iptrables-ipv6 that is running on your target:


2. Build the project, and start it on a target (real or emulated).

3. Open the platform’s User Space Configuration node and click Packages to open the Package Manager.

4. 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. Open the User Space Configuration node and click Packages to open the Package Manager.

b. Right-click the entry iptables-ipv6 and select Erase.

c. Right-click the entry iptables and select Erase.

2. 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. Right-click on the entry iptables and select Install.

b. Right-click on the entry iptables-ipv6 and select Install.

You now have both these packages replaced and running on the target.

153

PART V

Deploying to Your Board

13 Assembling File Systems and Kernels ............. 155

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


154

155

13 Assembling File Systems and

Kernels


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 User’s 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.


156

13.2 Assembling Your File System

When you right-click a platform project’s 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 project’s 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

13 Assembling File Systems and Kernels13.4 More on Build Targets

157

12

■ wrs_powerquiccii_82xx-uImage-WR3.0bl_standard

■ wrs_powerquiccii_82xx-vmlinux-stripped-WR3.0bl_standard

■ wrs_powerquiccii_82xx-vmlinux-symbols-WR3.0bl_standard

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.

13.5 Adding Applications to Your File System

You can add applications to your platform project’s 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: Some of these are links, not files.

I

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.


158

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. Unpack the file system from dist.tar.bz2 into a location from which it can be exported to a target.

2. Copy the kernel to a similar location from where it can be exported to a target.

3. Continue with chapter 14. Deploying to Targets.

159

14 Deploying to Targets


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.


160

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.

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.

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.

NOTE: For specific instructions about deploying your project to your target and booting the target, see the Wind River Platforms User’s Guide.

Figure 14-1 Typical Network Development Environment

Development Host

PlatformProject

Target Board

NFS Mount

TFTP Download

FileSystem

Kernel

FileSystem

Kernel

FileSystem

Kernel

DownloadDirectories

14 Deploying to Targets14.2 Introducing Target Deployment

161

13

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-2 QEMU Emulator Development Environment

Development Host

PlatformProject

NFS Mount

Virtual Download

FileSystem

Kernel

QEMUEmulation

FileSystem

Kernel

Figure 14-3 Flash Development Environment

Development Host

PlatformProject

Target Board

TFTP Download

FileSystem

Kernel

FileSystem

Kernel

TFTP DownloadBoot-

DownloadDirectories

Flash or RAM

loader


162

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

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. Select one of the following connection types, then click Next.

NOTE: After you connect to a target, more commands are enabled on the right-click context menu. See the Wind River Workbench User’s Guide.

Table 14-1 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

14 Deploying to Targets14.3 Connecting to Targets in General

163

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.

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 User’s Guide: The Registry.

Use the Remote Systems view to connect to, or disconnect from, your target:

1. Right-click a connection node.

2. Click Connect or Disconnect.

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 RTCore Connection.

User Mode Target Server Usermode connection to the target.

QEMU Backend Command-line interface to QEMU for KGDB back-end connection debugging.

QEMU Uses KGDB and OCD-like connection to real board (in emulation)

QEMU Linux User Mode Target Server

Uses usermode-agent for target connection (see 15. Debugging User Space).

Table 14-1 Remote Connection Types

Connection Type Creates a . . .

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.


164

14.3.3 Modifying Connection Properties

To modify the properties you set during your new target connection:

1. Open the Remote Systems view.

2. Disconnect from your target.

3. Select a connection node.

4. Right-click and select Properties from the context menu.

5. Modify and save your changes.

6. 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.

Use the Remote Systems view to create and configure a QEMU connection for an emulated target:

1. Select New > Connection. The Select Remote System Type dialog displays.

2. Select Wind River Linux > Wind River QEMU Linux User Mode Target Server Connection then click Next. The QEMU Simulator Configuration screen appears.

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.

14 Deploying to Targets14.4 Connecting to Emulated Targets

165

13

3. Select the project root directory or browse to workspace/projectName_prj then click Next. The following dialog appears.

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.


166

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.

14 Deploying to Targets14.5 Connecting with KGDB

167

13

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:

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.

4. Select the target processor from the Select menu, or leave the target default to have Workbench identify the target CPU.

5. Specify serial line or remote host settings, depending on the connection template or back-end setting that you have chosen:

Connection Type Description

Linux KGDB via RS232 Serial cable connection.

Linux KGDB via Ethernet Ethernet connection.

Linux KGDB via Terminal Server Connection through a terminal server to the target.

Custom Linux KGDB Connection No defaults. Used for custom situations. See Wind River Support.

Back End Setting Provides . . .

RS232 A direct serial port connection (connection with a null-modem cable). You must specify your serial line settings.

TCP A connection to a terminal server with a direct serial connection.

UDP An Ethernet connection on the same subnet.

PIPE Not currently supported.


168

■ 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. Click Next. The Target Operating System Settings dialog opens.

7. 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.

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.

2. Click Add to add a new object file to the Symbol Files and Order list.

3. Select the file, then click Open.

4. In the Symbol Load Options section, select Specify base start address or Specify start address for each section.

5. Click OK.

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.

14 Deploying to Targets14.5 Connecting with KGDB

169

13

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.

Basename Mappings

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. Right-click the target connection then select Refresh Properties.

2. Modify the appropriate properties:

NOTE: You cannot edit the supplied default mappings.


170

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.

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.

Property Description

Available CPU(s) on target board

Workbench correctly identifies the target CPU. In rare cases, a close variant might be misidentified. If so, manually set the CPU.

Initial target state query and settings

Specify whether or not Workbench should query the target on connect, on stopped events, and/or on running events. You can select all options.

Target state refresh settings 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.

Listen to execution context life-cycle events

Specify whether or not Workbench should listen for life-cycle events.

Advanced Option Description or Procedure

Back end Communication Log File Logs communications between agent and server.

Target Plugin Pass-through Options (See 16.6 Debugging User-Supplied Kernel Modules, p.198.)

14 Deploying to Targets14.7 Using Target Server Options

171

13

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.

Advanced Option Description

Edit Target Server Options Opens the Edit Target Server Options window. The options are subdivided into three tabbed groups—Memory, Logging, and Symbols.

Timeout Options 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).

Memory Cache Size 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.

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.


172

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:

■ Shared—Provides 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 User’s 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 possible—If 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 User’s Guide: Debugging Projects.

If you have applications ready to run using the connection(s) you have just created, also see Wind River Workbench User’s Guide: Launching Programs.

NOTE: The command line field is filled in based on the values you enter in this dialog box.

173

PAR T VI

Debugging and Analyzing

15 Debugging User Space ...................................... 175

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

17 Optimizing ........................................................... 211

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


174

175

15 Debugging User Space


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 tools—the 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.


176

For more information, see Knowing Which Debugger Gets the Breakpoints, in Wind River Workbench User’s 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.

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.

Figure 15-1 Debugging User Space: The Diagnosis Stage of the Product Life Cycle

User Space Setup

RPMs, CVS, . . ., File SystemKernel

Packages


Develop


Diagnose


Optimize


Requirements

User SpaceDeliverables

Other Tools

Remote System ExplorerPOSIX Signals

Wind River Debugger

Relevant Tools

Launch ConfigurationsLive Package Manager

Unit TestsPatches

Dynamic printf

GDB

http://download.eclipse.org/tools/cdt/docs/tutorials/debug_tutorial/cdt_w_debug.htm

http://download.eclipse.org/tools/cdt/docs/tutorials/debug_tutorial/cdt_w_debug.htm

15 Debugging User Space15.2 Using the Wind River Debugger

177

14

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. In the Remote Systems view, select WRLinuxHost_username.

2. Click Connect to open a default output window and the usermode-agent.

3. Right-click WRLinuxHost_username and then, from the Workbench toolbar, select Debug > Debug Process on Target.

4. 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.

5. Select hello_world and click OK.

6. Click Debug. The debugger runs and displays your output.

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. In the Remote Systems view, expand Processes.

2. Locate the process ID you want to view.

3. Expand the process. If the entry for the process shows [Stopped], it has hit a breakpoint.

NOTE: If WRLinuxHost_username is not connected, click Connect in the Debug dialog box.


178

15.3 Debugging Using GDB

Use GDB to debug native-mode, self-hosted applications.

To debug hello_world using GDB:

1. Right-click the hello_world_Native project folder.

2. Select Debug As > Local C/C++ Application.

3. 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

15 Debugging User Space15.4 Stepping Through Your Output

179

14

The Debug view provides the following process information:

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.

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:

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.

NOTE: You can use function keys for common activities. For a list, click Run in the Workbench toolbar.


180

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.

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. Right-click in the editor or in the gutter.

2. 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 User’s Guide: Dynamic printf Event Points.

Wind River Output GDB Output

<terminated, exit value: 0>hello_world_Nat: PID <terminated, exit value: \0>hello_world_Native [C/C++ LocalApplication]

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.)

15 Debugging User Space15.6 Sending Signals to Processes

181

14

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.

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. Right-click the process in the Debug view and select Edit Signal Configuration. A dialog box opens where you can configure signal attributes.

2. Select an attribute and click its value to toggle between true and false.


182

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.

Attribute Description Values

Pass Controls whether or not a signal sent to a process should pass.

true—Process silently discards the signal.

false—Process cannot silently discard the signal.

Suspend Controls whether or not the process should suspend when it receives the signal.

true—Signal suspends the process when the process receives it.

false—Process continues running after it receives the signal.

183

16 Debugging Kernel Space


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


184

16.1 Introduction

Wind River Workbench provides source-level debugging for Linux 2.6 kernels that support the Kernel GNU Debugger (KGDB).

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.

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 User’s Guide.

NOTE: If you are not using a Wind River Linux platform, contact Wind River support about configuring your kernel for symbolic debugging with Workbench.

NOTE: With Wind River Linux, kernel debugging is enabled by default, and you only have to turn it off when going to production.

16 Debugging Kernel Space16.2 Background Steps and Concepts

185

Figure 16-1 illustrates in brief the topics covered by this chapter: various tools that help you debug kernel space.

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.

Figure 16-1 Debugging Kernel Space: The Diagnose Stage of the Product Life Cycle

Kernel Debug Setup

RPMs, CVS, . . ., File SystemKernel

Kernel Modules


Develop


Diagnose


Optimize


Requirements

Kernel DebugDeliverables

POSIX SignalsQEMU

Wind River Debugger

Relevant Tools

CPU Auto-DetectionNFS-Mounted File System

PatchesKernel Modules

agent-proxy

User-Supplied Kernel ModulesWind River Flags and Features

Other Tools

Multiple Connection TypesSafe Areas

KGDB

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.


186

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:

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 target’s subnet (192.168.29.11). (See Figure 16-3.)

Figure 16-2 Connecting from the Host to the Target for KGDB

IP 192.168.99.77IP 192.168.99.123

UDP Port 6443 (kgdboe)

Workbench Target Kernel

Subnet 192.168.99.*

Development Host Target


187

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 [email protected]/,@192.168.29.11/

4. Log into the development host on the intranet.

5. Start Workbench and create a kgdboe connection with these parameters:

TRANSPORT=TCPCPU=defaultIP=208.77.190.11Port=3333

Workbench connects to the TCP port 3333 on 208.77.190.11, and treats it like a normal KGDB connection.

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-proxyagent-proxy version 1.6

Figure 16-3 Using agent-proxy to Bridge Subnets

IP 192.168.99.123

UDP Port 6443 (kgdboe)

Subnet 192.168.99.*

Target

Target Kernel

IP 208.77.188.166

Intranet

Development Host

Workbench

Bridging Host

ETH1: 192.168.99.11

From: TCP Port 3333

ETH0: 208.77.190.11

agent-proxyTo: 192.168.99.123

UDP Port 6443

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.


188

Usage:agentproxy <[udp:][virt IP:]local port> <remote host> <[udp:]remote port>

For udp wdb agent proxy example for default portsagentproxy udp:0x1001 10.0.0.2 udp:0x4321agentproxy udp:0x1002 remotehost2 udp:0x4321For KGDB udp target to udp host with default gagentproxy udp:3331 10.0.0.2 udp:6443For KGDB udp target to tcp host with default gagentproxy 3332 10.0.0.3 udp:6443Also you can bind to a local vitual interface IE:

agentproxy udp:47.1.1.2:0x4321 10.0.0.2 udp:0x4321agentproxy udp:47.1.1.3:0x4321 10.0.0.3 udp:0x4321agentproxy udp:47.1.1.3:6443 10.0.0.3 udp:6443agentproxy 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 Target’s File System using NFS

If you already have the NFS image mounted to your target’s 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. Open a console on your host.

2. Log in as root.

3. 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.


189

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.


190

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

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 target’s IP address:

target_# modprobe kgdboe [email protected]/,@192.168.29.107/

You can now skip to 16.4 Connecting with KGDB from Workbench, p.192.

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.

16 Debugging Kernel Space16.3 Preparing the Target for KGDB

191

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

[email protected]/,@10.1.1.111/

So the boot line would look like:

boot root=/dev/nfs rw console=ttyS0,115200 [email protected]/,@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 iteth0: link downeth0: link up, 100Mbps, full-duplex, lpa 0x45E1kgdboe: debugging over ethernet enabledkgdb: 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


192


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. From the Remote Systems view, click New Target Connection.

2. Select Wind River Linux KGDB Connection and click Next.

NOTE: Since the device has booted, you do not need to specify its IP address.

16 Debugging Kernel Space16.4 Connecting with KGDB from Workbench

193

3. Select Linux KGDB via Ethernet and click Next.

4. Select UDP as the transport.

5. Use the Default from Target CPU default.

6. Enter the target’s 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. Click Next.

9. Select Target OS Linux 2.6 if it is not already set.

10. For the Kernel Image, point to your kernel’s 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

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 target’s connection tree.

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.

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.

NOTE: Do not select the kernel image itself (for example the bzImage file).


194

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:


2. Select Wind River Linux KGDB Connection and then click Next.

3. Select the connection option Linux KGDB via Terminal Server and then click Next.

4. Select TCP as the transport.

5. Use the Default from Target CPU default.

6. Enter the target’s IP address.

The IP address must match the device providing the Telnet connection.

7. Enter the telnet port.

8. Click Next.


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.

NOTE: Select the architecture only if necessary (for Pentium targets, use Pentium4 instead of ia32).

16 Debugging Kernel Space16.4 Connecting with KGDB from Workbench

195


16.4.3 Option 3: Making a Serial Cable Connection

To make a serial cable connection:



3. Select the connection option Linux KGDB via RS-232 and click Next.

4. 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.

5. Click Next.



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.


196

■ 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. Right-click the connection and select Properties.

b. Enter a location for the log in the Backend Log field.

c. 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 kernel’s source directory.

16 Debugging Kernel Space16.5 Attaching and Debugging the Kernel from Workbench

197

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 project’s 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 Target’s 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. Select Run > Add Expression Breakpoint.

2. In the Breakpoint Location and General Attributes dialog, enter do_fork in the Location Expression box.

3. Click OK.

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. To complete this example, remove the breakpoint and click Resume in the Debug view to continue execution of the kernel.

6. To end the session, right-click the target connection in the Remote Systems view and select Disconnect.

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.


198

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

To build the sample user-supplied kernel module:

1. Open a Workbench project.

2. Right-click the kernel_build build target and select Build Target.

Typically, the kernel takes about 30 minutes to build.

3. Select File > New > Example.

4. Select Wind River Linux Kernel Module Sample Project and click Next.

5. 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. Select Project > Properties > Project References.

b. Select the checkbox for moduledebug_2_6.

c. Click OK.

The moduledebug_2_6 project disappears from the Project Explorer and appears in the platform project tree.

7. Open the platform project and find the sub-project moduledebug_2_6.

8. 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).

NOTE: You must have the full kernel built in your project. If not, the infrastructure for building kernel modules is not configured properly.

16 Debugging Kernel Space16.6 Debugging User-Supplied Kernel Modules

199

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_hostkgdb_target_$ cd myhome/workspace/moduledebug_2_6 kgdb_target_$ get moduleDebugExample.kokgdb_target_$ quitkgdb_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.pid1084

kgdb_target_$ kill 1084kgdb_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.


200

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 project’s Object Path Mappings screen, click Add, set the following values, and click OK:

■ Target Path = (leave empty)

■ Host Path = /target/

4. 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.

5. Double-click bpHere.c in the moduledebug project. It appears in the Editor.

6. 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.

7. Once it breaks (as seen in the Debug view), try single steps in and then out of this procedure. Then click Resume.

8. 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.

NOTE: If you find that the break point cannot be planted, make sure you added the Object Mapping.


201

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 build’s 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. Double-click the module.c file to open it in the Editor.

3. Go to the sys_init_module routine and find the lines that call the module’s 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.

.

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. Collapse the Processes node for the target.

b. Click Refresh in the Remote Systems view.

c. 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

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.


202

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. To resume processing, remove the breakpoint and click Resume in the Debug view. The insmod command completes.

9. You can remove the module from the kernel with the rmmod command:

kgdb_target_$ rmmod moduleDebugExample.ko

10. 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. Right-click the GDB target connection entry in the Remote Systems view.

2. Select Properties > Object Path Mapping.

3. Click Add.

4. Leave the Target Path empty.

5. Click Browse for the Host Path, and select workspacedir/moduledebug_2_6 for the directory where the generated moduleDebugExample.ko file is located.

6. 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.

7. 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.


203

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. In Workbench, build the kernel_build target so that all kernel files are available.

2. 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 $fileforeach? end$

4. Add this object path mapping to your KGDB connection:

a. Right-click the specific KGDB target connection entry.

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.


204

b. Select Properties > Object Path Mapping.

c. Click Add.

d. Leave the Target Path empty.

e. Browse for the Host Path; select projectname_prj/build/linux-version-type.

f. Click OK for the path, then OK for the target connection’s properties dialog.

5. 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. Select File > Example.

2. Select Wind River Linux Sample Project and click Next.

3. Select Wind River Linux Kernel Module Sample Project and click Next.

4. 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.

16 Debugging Kernel Space16.7 Creating a Custom Kernel Module

205

b. Open the platform project and find the sub-project testmod.

c. 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.

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_$ ftp your hostkgdb_target_$ cd myhome/workspace/moduleDebug kgdb_target_$ get testmod.kokgdb_target_$ quit

kgdb_target_$ insmod testmod.ko timeout=2340

7. Verify that the console output shows testmod:

kgdb_target_$ dmesg | tailLoading testmodtimeout 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:

NOTE: For the kernel module to build, the Linux package must be already built (by building the Linux build target, for example).


206

1. Select File > New > Example > WR Linux Kernel Module Project.

2. 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. Fill in the Linux Kernel Directory, its ARCH, and its CROSS_COMPILE value. (You can edit these values later using the project’s Build Properties.)

b. Click Finish.

3. Right-click the project and select Import > General > File System.

4. Browse to installDir/wrlinux-3.0/samples/moduledebug_2_6.

5. Select the files bpHere.c and moduledebug.c and click Finish.

6. 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.)

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.

16 Debugging Kernel Space16.8 Using QEMU for KGDB Kernel Debugging

207

■ 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. In the Remote Systems view, click Create a New Target Connection.


3. Select Linux KGDB via Ethernet and click Next.

4. 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


208

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. Click Next until you reach the Connection Summary dialog.

7. Enter a name for the new connection.

8. Select the Immediately connect to target if possible checkbox.

9. Click Finish.

The new connection appears in the Remote Systems view, and the debugger opens onto the kernel running on the emulated target.

16 Debugging Kernel Space16.9 Enabling and Disabling KGDB in the Kernel

209

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 project’s 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. Open the Kernel Hacking tree.

3. Double-click the Compile the kernel with debug info menu item to toggle between Yes and No.


210

4. Select File > Save, to capture the configure changes.

5. Right-click the project’s build target kernel_rebuild.

The new kernel and vmlinux file are available in the workspace’s projectname_prj/export directory.

211

17 Optimizing


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 project’s 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.


212

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.

Figure 17-1 The Optimize Stage of the Product Life Cycle

Optimization Setup

RPMs, CVS, . . ., ApplicationsFile System (FS)


Develop


Diagnose


Optimize


Requirements

OptimizationDeliverables

OProfile CPU AnalysisSystem Viewer

Relevant Tools

Indexermpatrol Memory Analysis

Kernel

Patches

File System Layout

Other ToolsBoot Time Tools

FS Change ListKernel

Unit Tests

Non-Binary Files

ApplicationsFile System (FS)FS Change List

17 Optimizing17.3 Profiling CPU Usage with OProfile

213

16

■ 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.

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.


214

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.

See the Wind River System Viewer User's Guide for more details.

NOTE: Memory Analyzer is integrated with the System Viewer, so you can view memory allocation and free events directly in a System Viewer window.

http://mpatrol.sourceforge.net/

17 Optimizing17.7 Improving Boot Time

215

16

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 kernel’s 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 User’s Guide: Configuring Scalable Features.

17.8 Optimizing Footprint

The files that determine the size of your footprint are pkglist and changelist.xml.

■ 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 User’s Guide: Getting a Footprint Snapshot.

17.8.1 Looking up a Package’s Removal Size

Follow these steps to see how much space you can save if you remove a package.


2. In the Package Manager view, right-click an entry in the Installed Packages list.

3. Select Show Remove Size.

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.


216

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. Click the Filesystem tab at the bottom of the Package Manager

2. In the Filesystem Layout window, right-click any file in the tree and choose Show Dependencies....

3. Note the packages listed and their sizes.

17.8.3 Looking up a Package’s 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. Notice the sizes of the dependent packages.

3. 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. Click the Filesystem tab at the bottom of the Package Manager.

2. Click the Targets tab if it is not already selected.

3. Click Export Snapshot Footprint.

A footprintPackage.tcl dialog appears.

17 Optimizing17.8 Optimizing Footprint

217

16

4. Click Browse and choose a destination directory.

5. 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. Select File > Save.

3. Return to the Filesystem Layout view.


5. Click Export Snapshot Footprint.


6. Click Browse and choose a destination directory.

7. Click Export.

Restoring a Footprint Baseline Snapshot



3. Click Import Snapshot Footprint.


4. Click Browse and choose the directory containing the snapshot.

5. 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.


218

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:



3. Click Export Dependencies.

4. Click on Export Dependencies.

5. Observe that there are three reports to select from:

6. Select Rpm Sizes.

7. Browse to a directory and specify a file.

8. Click Export.

If you list this file, you will see, for example:

Package : libgccSize : 108704

17 Optimizing17.8 Optimizing Footprint

219

16

Package : setupSize : 434210

Package : filesystemSize : 0

Package : ncurses-baseSize : 454

Package : cracklib-dictsSize : 5094668...

9. Repeat this by selecting Rpm Files and clicking Export.

The resulting file might look like this:

Package : libgccList of files in rpm :/lib/libgcc_s.so.1

Package : setupList of files in rpm :/etc/aliases/etc/bashrc/etc/csh.cshrc/etc/csh.login/etc/environment ...


220

221

18 Analyzing Core Files


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.


222

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 -acore file size (blocks, -c) 0data seg size (kbytes, -d) unlimitedfile size (blocks, -f) 20pending signals (-i) 1024max locked memory (kbytes, -l) 32max memory size (kbytes, -m) unlimitedopen files (-n) 1024pipe size (512 bytes, -p) 8POSIX message queues (bytes, -q) 819200stack size (kbytes, -s) 10240cpu time (seconds, -t) unlimitedmax user processes (-u) 11768virtual memory (kbytes, -v) unlimitedfile locks (-x) unlimitedtarget_$

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.outSegmentation 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 -c0target_$ ulimit -c 12000target_$ ulimit -c 12000target_$ ulimit -munlimitedtarget_$ ulimit -m 2000target_$ ulimit -m2000

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.

18 Analyzing Core Files18.3 Attaching Workbench to a Core File

223

17

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. In the Remote Systems view, select Create a New Target Connection.

2. Select Wind River Linux Application Core Dump Target Server Connection and click Next.

3. In the Core dump file field, enter or browse to the path for the core dump file you wish to analyze.

4. 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 = xscalecpuFamilyName = XSCALE...

The OS version value to enter is 2.6.

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.


224

5. In the File field, enter or browse to the path of the application image that created the core dump file.

6. 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.

7. 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.

8. 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.

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.

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.

225

PAR T VII

Delivering Your Product

19 Providing Platforms and Kernels ...................... 227

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


226

227

19 Providing Platforms and

Kernels


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.


228

For information on how to deliver layers, whether for internal teams or external customers, see 20. Delivering Layers.

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 User’s 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

Figure 19-1 Delivery Stage of the Product Development Life Cycle

Product

Setup

RPMs, CVS, . . .,

DocsFile System Image

Kernel ImageKernel Modules

LayersNon-Binary Files

PackagesPatchesProfiles


Develop


Diagnose


Optimize

Workbench, Eclipse, TargetStatic Analysis • Cores • Footprint

System Layout • Views • Profiles

Deliverables

Deliver

Kernel ImageFile System Image

LayersPackages

SetupRequirements

SysrootsTemplates

Sysroots

Unit Tests

Relevant Tools

export-layerexport-sysroot

tar

19 Providing Platforms and Kernels19.3 Exporting and Copying Sysroots

229

18

tools such as described in 8. If You’re an Application Developer, and in the Wind River Workbench User’s 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. Obtain a sysroot, as explained in the Wind River Linux User’s Guide. Modify it if needed.

2. In Workbench:

a. Right-click export-sysroot node in the project tree.

b. Choose Build Target.

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.


230

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.

Adding Available Multilibs

To add available multilibs:

1. Create a platform project with the values shown in Table 19-1.

2. Open the User Space Configuration.

3. Add the following two entries from the Available list: glibc(mips 64) and libgcc(mips 64).

4. Click Accept.


Table 19-1 Platform Project Parameters


board Board arm_versatile_926ejs



project name Project name mti_malta64f_be

19 Providing Platforms and Kernels19.3 Exporting and Copying Sysroots

231

18

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. Create a platform project with the values shown in Table 19-1.

2. Click Import.

3. Click Add Multi-libs.

4. Select the CPU Variant.

5. Select the package glibc, click Lookup, and click Add to pkglist.

6. Select the package libgcc, click Lookup, and click Add to pkglist.

7. Click OK.


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.

2. Export the sysroot by building the export-sysroot build target. It will then include these extra multilibs in the sysroot.

3. Add the sysroot to Window > Preferences > Wind River > Layers and Sysroots.

4. Create a new mthread sample project.

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.


232

5. Observe that there are now two new build specs, one for the 32-bit and one for the 64-bit CPU variant.

6. 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.

233

20 Delivering Layers


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 layer’s 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.


234

20.2 Example: Preparing Layers that Modify Kernels

The following procedures demonstrate how to make custom changes in a project’s 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.

20.2.1 Creating a Project and Modifying Its Kernel Configuration

To create a project and change the kernel configuration for it:

1. Create a project using the parameters shown in Table 20-1.

2. Make changes to the kernel:

a. Open the Kernel Configuration node. (Click Yes if asked to extract kernel sources.)

b. Open the tree General Setup, and, for example, double click Example Debug Container Subsystem to change it to Y.

c. Select File > Save.

3. Make changes to the package list:

Table 20-1 Basic Project Parameters


board Board common_pc



project name Project name common_pc

package to remove (list item) rmgtools

package to import (URL) dos2unix-3.1-28.fc7.src.rpm

20 Delivering Layers20.2 Example: Preparing Layers that Modify Kernels

235

19

a. Double-click the User Space Configuration to open it.

b. Select the entry rngtools, click Remove, and OK.

c. Select File > Save.

4. Import an external package:

a. Open the User Space Editor (that is, the User Space Configuration node), click Import, then click Import Packages.

b. This will bring up the import tool. (See Figure 20-2.)

Figure 20-1 The Import Button


236

c. Select Wget to get the package from the Web.

d. Into Package Location, paste the URL to the package. For example, for dos2unix:


e. Click Go.

A shell opens and a script runs to perform the import and package setup.

f. Press ENTER when done, to close the shell.

g. Click Close, to return to Workbench.

Figure 20-2 Import Packages Script’s Display

20 Delivering Layers20.2 Example: Preparing Layers that Modify Kernels

237

19

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. Right-click the project's title (top) node.

b. 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_2008builddir/export/export-layer/common_pc.prj.Wed_Oct_1_150608_PDT_2008.tar

2. Export the layer:

a. Right-click the project.

b. Select Open Workbench Development Shell.

c. 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$ lsconf_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/defaultconfig.sh knl-base.cfg modlist.remove pkglist.removefs modlist.add pkglist.add README$ cat templates/default/knl-base.cfgCONFIG_CONTAINERS=yCONFIG_CONTAINER_DEBUG=y$ cat templates/default/pkglist.adddos2unix$ cat templates/default/pkglist.remove#rng-tools

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


238

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. Create a non-default subdirectory:$ mkdir templates/no_rng-tools

b. 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, it’s a simple matter of selecting the template with the layer:

--with-layer=/path/layer --with-template=no_rng-tools

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. Send your recipients the tar file or a pointer to it.

3. Explain how they can import and use the layer, as described in the next section.

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 User’s Guide.

20 Delivering Layers20.3 Providing Layers to Teams and External Customers

239

19

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. Create a project using the parameters shown in Table 20-1.

2. Click Add to add the new layer's directory.

3. Click Finish.

4. 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. Configure a first project.

2. Go to User Space Configuration > Filesystem.

3. Right-click /usr/games (for example), and select Remove.


5. Right-click the project, select Build Options > Export changes as a new layer.

6. Copy the new layer export/export-layer/Project_name.date to /tmp/layer1.

7. Configure a second project.


9. Right-click /usr, select New > Folder, and add the directory my-user.


11. Right-click the project and select Build Options > Export changes as a new layer.

12. Copy the new layer export/export-layer/Project_name.date to /tmp/layer2.

13. Configure a third project, adding the layers /tmp/layer1 and /tmp/layer2.


240


15. Observe that the two changes from the two layers are applied to the file system.

241

PAR T VII I

Reference

A FAQs .................................................................... 243

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

C Workbench and Command-Line Techniques ... 259

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

E Glossary .............................................................. 269


242

243

AFAQs

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


244

How can I launch the Registry in read-only Workbench directories? 250

How can I redirect remote X environments to local servers? 250

Why doesn’t 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

A FAQsA.1 Introduction

245

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. Direct generic Workbench questions to the Wind River Workbench User’s Guide.

2. See the same guide’s 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.


246

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.

A FAQsA.2 Projects in General

247

■ 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).


248

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

A FAQsA.3 Build Properties, Specs, Layers, and Templates

249

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.


250

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 project’s 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 don’t 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

A FAQsA.5 Host-Related Issues

251

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 network—Use half duplex instead of the standard and otherwise favorable full duplex setting on the local Ethernet card.

■ Servers running Linux-GTK—A 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 X—Try disabling Exceed’s 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 doesn’t 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/ttyS0crw-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/groupuucp:x:14:uucp,Username

Your username should be included in the uucp list. If not, you need to get it added.


252

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.

A FAQsA.8 Troubleshooting

253

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.


254

255

BStarting 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:


256

■ 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 This script takes care of starting and stopping UMA##

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-agentrm -f /var/lock/subsys/usermode-agent

echo}

# See how we were called.

case "$1" instart)start

;;stop)stop

;;restart|reload)stop

B Starting usermode-agent at Boot TimeB.3 Writing and Placing the Script

257

A

start;;

condrestart)[ -e /var/lock/subsys/usermode-agent ] && (stop; start);;

*)echo $"Usage: $0 {start|stop|restart|reload|condrestart}"exit 1

esac

exit 0


258

259

CWorkbench 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.


260

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.

C.2.2 Setting the Environment with Workbench

To open a shell for a specific project and have its environment automatically preset:

1. Select a project in the Project Explorer.

2. 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.

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 Workbench and Command-Line TechniquesC.2 Workbench and the Command Shell Environment

261

B

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.

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

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.


262

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. Right-click a platfrom project and select Properties > Build Properties > Build targets.

2. In the Custom build targets section, click New.

3. Enter the name Display Environment.

4. Click Variables, select Project Name, and click OK.

5. Finish the command so that it looks like this:

sh -c "env | grep %selected_project_name%"

6. Set the Type to Command.

7. Set Refresh after execution to Nothing.

8. Click OK for the Build Target dialog box.

9. Click OK for the Properties dialog box.

Now try the new command:

C Workbench and Command-Line TechniquesC.3 Setting the Environment Without Starting a Sub-shell

263

B

1. Right-click the project and select Build Options > Display Environment.

2. 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.

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`

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.


264

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.

265

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.


266

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 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.

NOTE: You can make the rest of the installation read-only if you want to. Only the .wind directory must allow general access.

D Installing on Network ServersD.3 Shared Wind River Linux Installation

267

C

■ 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. On the local host (Windows, Linux, or Solaris), install Workbench in the shared location using the proper license key.

2. On the local host, install Wind River Linux in the same location using the same key.

3. Use Workbench from any host of the same type (Windows, Linux, or Solaris).

4. 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. Install Workbench on your local host.

2. 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.

3. 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:


268

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.

269

EGlossary

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 User’s 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.


270

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 Workbench’s 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.

E Glossary

271

D

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.


272

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.

http://www.eclipse.org

E Glossary

273

D

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 view’s Target Connection Properties.

package

A collection of software and files for installation on a target’s 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.


274

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 server’s 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.

E Glossary

275

D

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.


276

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.

277

Index

Symbols%build 117, 122%configure_target 117, 122%install 117, 122+/- icon 61.ko file 150/dev directory 62

AAdd Links to Development Folders 121adding

layers 52profiles 52templates 52

Advanced tab 64agent-proxy 186, 193

connections 187port numbers 193

applicationbinaries 157developers 16, 36projects 25

applicationsadding to file system 157creating 98development environment 99

importing code 103incorporating into platforms 99penguin 101providing in layers 232running native 106running non-native 108sysroots for 99

arch.cpu-variant 40architecturedb file 223archives 121ARM Versatile

AB-926EJS 164creating target 53emulation 29

assembly view debugging 179attaching

to core file 223

Bback end 269Backend Connection 50ball tutorial 98baseline snapshots 216bin directory 60board

menu 51support package 111, 269

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

278

booting targets 228boot-time

access 50feature template 215logging 215

breakpoints 179kernel 197per debugger 176

bridging hosts 186BSPs 75, 111, 269

directory 269build 269

build target 65directory 54, 56, 270output 56, 270paths 109properties 109scope 270specs 54, 111, 113, 270targets 65, 157tools 109

Build Console 52build properties

build macros 109changing 109, 114libraries 109

Build Target 39, 55BUILD_TYPE=debug 72BUILD_TYPE=profiling 72build-all node 39Bus options 86

CCardBus cards 86Cavium example platform project 67CDT (C/C++ Development Tooling) 270cgl

kernel type 51changelist.xml 57, 60, 215classic packages

defined 130importing 119

clean

build target 65ClearCase repositories 38Code Coverage Analyzer 213command line

configuring projects 50Common PC 164

emulation 29compile

build target 65components

definition 93hierarchy 93

configure command 51modifying 51output in Build Console 52

Configure Options dialog 54connecting

to targets 49Connection 50connections

connect and disconnect 163creating 177emulated 164Ethernet 192ICE-like debugging 207KGDB 167new 162properties 164QEMU types 49serial 195serial cable 195serial/telnet 192shared 172summary page 172TCP 186telnet 194troubleshooting KGDB 195types 162types of KGDB 167UDP 186using KGDB 196

Contents tab 64core files

acquiring 222analysis 224

Index

279

Index

attaching to Workbench 223attaching Workbench 223

core.pid 221CPU type 224Create template source 87creating custom kernel module 88creation.log 52, 55cross compiling 120cross-development 270custom

build target 65kernel module projects 205

Custom Linux KGDB Connection 167customer-specific projects 25

enabling 26CVS repositories 38Cygwin 26, 30

Ddatabase queries 16Debug Process on Target 50, 177debuggable objects 270debugger framework (DFW) 270Debugger tab 31debuggers

table of 31which breakpoints 176

debuggingassembly 179breakpoints 179breakpoints in kernel modules 202kernel mode, intro 30kernel modules 198kernel space 183KGDB command-line 184object path in kernel modules 202object paths in kernel modules 203packages, on or off 64process overview 178turning off for production 184user mode, intro 30user space 176user supplied kernel modules 199, 200

default kernel 55, 56, 57, 156Dependencies tab 64, 70, 72deploying

emulated targets 160NFS 160to targets 159

development environment 26device

adding 62file class 58ownership 62

Device Debug perspective 178Device Management (DM) products 33DFW 270, 271directories

adding and removing from file system 60, 61disabled build 271discovery 271dist

directory 53, 54, 156Makefile 120

dist.tar.bz2 image 58, 157distclean 120

build target 65distribution media 32DM products 33do_fork 189dynamic printf 180

Eecgl

kernel type 51Eclipse

plug-ins 19Eclipse C/C++ IDE 270Edit Source Lookup 196ELF core dump file 221Embedded Debug perspective 196emulated target environment 160--enable-debug 189environment settings 260environment variables

sending to standard out 263


280

Estimated Filesystem line 60Ethernet

connections 192ports, multiple 190

event points 180Exec Path on Target 177export

/dist directory 56, 58directory 56sysroot command 229

export directory 56export/dist 58, 157export/dist directories

QEMU 164exporting

sysroots 229export-layer build target 227export-sysroot node 227external API 271

Ffakeroot 58feature templates

major description 92file

change list 58ownership 40properties 60

file system 57adding applications 157building example 56components 156configuration 57creating 55estimated size 60finding 28making exportable 158managing 58NFS mounting 188NFS mounts 188root 165size 215small 63

File System Layout Configuration tool 40, 57, 58, 212

filesadding and removing from file system 60, 61collecting for export 158

Filesystem tab 60Filter icon 59fixes

reusing package 120Flat view 59flexible managed build 271footprint

exporting dependency data 218snapshots, creating 216snapshots, restoring 217snapshots, updating 217

Force Install 67RPM 65

fs node 48, 55, 156fs_final script 58

GGDB

GNU Debugger 175native-mode applications 178using 178

General tab 64generated RPM files 57gid ownership 58glibc_cgl

carrier-grade Linux 51glibc_small 63

Busybox-based 51glibc_std

standard Linux 51GNU

Debugger (GDB) 175tools 26

Grünbacher, Andreas 128

Index

281

Index

Hhello_world

building 100tutorial 100, 102

help key 271host

bridging 186file system source path 61shell 271toolchain 271tools 272

hostssupported 26

host-tools/bin directory 186http

//oprofile.sourceforge.net/about/ 213//sourceforge.net/projects/kgdb/ 184

hunk 272

IICE-like debugging 206, 207Immediately connect to target 163Import tool 235importing

classic packages 119packages 68source code 103

index 272insmod command 199Install

RPM 65install

build target 65install.properties file 260, 267INSTALL_STAGE output 58Installable Packages

list 66, 73window 68

installationlicensing 11local Workbench 267network servers 265

shared 11shared Wind River Linux 267

installed packages 63ipconfig 190

JJava code 16JDT 272JNI 272

KKconfig tab 85kernel 156

configuration 84debugging 184debugging with QEMU 207default 55, 56default, finding 28developers 16, 36image, default 57information 88pre-built 38rebuild target 41reconfiguration 84safe areas 189symbol file 168symlink to default 86types 51

Kernel Configuration node 85Kernel GNU Debugger 30Kernel Hacking tree 209kernel mode 272

debugging 30kernel module 272

debugging 198moving projects 89projects 25

kernel modules 87adding 87breakpoints in unloaded 202


282

custom 88custom projects 205debugging 198installing 150moving projects 89object path mappings 202, 203providing 232removing 150testmod enhanced sample 204user supplied, debugging 199user supplied, stepping into 200

kernel space debugging 183kernel_build 198kernel_build node 156kernel_rebuild 156kernel_rebuild build target 86kernels

breakpoints 197exporting layers 237making exportable 158modified by layers 234providing 232rebuilding 86, 156

KGDBadvanced connections 170and Workbench 184command-line debugging 184connection from Workbench 192connections 167connections -- UDP or COMM 190disabling for production 30enabled by default 189enabling 189enabling and disabling 209Linux kernel config option 189open source project 184over Ethernet 207over subnets 185patching kernel for 30QEMU kernel debugging 50, 206standard port 186starting agent on target 190troubleshooting connection 195using connection 196

KGDB over Ethernet (kgdboe) 186

kgdb.ccompilation unit 39source file 196

kgdb-8250 module usage syntax 192kgdboe 186

agent 187connection 187for non-PCD 190for PCD, dynamic config 191for PCD, static config 191starting, examples 190static linked in kernel 191UDP packets 186

klogd command 199

Llaunch configurations 42, 273layers 75, 273

adding 52, 79directories 273distributing 233example to modify kernels 234exporting kernel 237importing 239introduction 8making available for team 238of applications 232

librariesbuild properties 109into relocatable directories 112

licensing and installation 11life cycle

introduction 37Link to Development Folders 54Linux hosts 26Linux kernel information 88Linux Kernel Module projects

prepopulating 87Linux kernels version 2.6 30Linux KGDB via Ethernet 167, 193Linux KGDB via RS-232 167, 195Linux KGDB via Terminal Server 167, 194Linux User Mode Target Server 49

Index

283

Index

live targets 57, 58, 60, 63, 65RPMs and kernel modules 149

Load/Add Symbols to Debug Server 168localhost.localdomain 11Log tab 60

generated RPMs 65logging into terminals 166lsmod command 195

Mmake clean 156make fs 156Makefile

modifying for cross-compile 120managed build 269, 273mapping

source path 39memory

cache size, target server 171Memory Analyze As 32Memory Analyzer 214menuconfig interface 85meta properties

files 60middleware developers 16MinGW 26, 30modprobe commands 190module.c 200moduledebug.c 87moduleDebugExample.ko 200mpatrol 32, 38multi-core systems 214multi-lib RPMs

installing 67

Nnative applications

projects 25running 106

native mode

development environment 273native-mode

applications 47network servers 265networked hardware 168New Connection wizard 162NFS

builds 11directories on shared hosts 188mounted hosts 38mounting file system 188mounting targets 188target environment 160

non-native applicationsrunning 108

OObject Path Mappings

Ethernet 193object path mappings 50, 203, 273

QEMU 166symbol files and target paths 168

object.properties files 26OCD

connections 50On-Chip Debugger 189

octeon spec warning message 68On-Chip Debugger (OCD) 189Open Workbench development shell 120openssl 72OProfile 38, 213Option/Value dialog 52Options tab 64option-value templates 51

Ppackage developers 16Package Import Tool 68Package Manager 63

intro 39


284

package sizes 58package_RPM_ALL 10package_RPM_DEFAULT 10package_RPM_DEVEL 10package_RPM_NAME 10packages 273

archives 121building new 122classic 130customizing 123debugging 71dependencies 66dependent 216directory 53hierarchy 93importing 68, 119importing Wind River Linux 123Package Manager 63parent 62removing 62, 72required files 215reusing fixes 120RPMs 63sizes of 215turning debugging off 64updating spec file 121

Packages dialog 58, 65Packages view 59parent packages 62patch

annotations 138build target 65files 274lists 274target rules 123

patch filesmodifying SRPM 141

patchesannotations 138applying and resolving 128creating new top files 137exporting 146folder 137models for using 128modifying 145

new top files 144new top patch files 130popped files 143registering 142registering as last 142running distclean on 147saving SRPM 141saving updates as 143testing 143, 147

patches.list file 117, 143, 147patching 127

SRPM packages 140path

mapping target to host 169pathname prefix mappings 169Pattern Filter

field 59, 62value 62

PCCard support 86PCD

Wind River Platform for Consumer Devices191

PCMCIA cards 86Penguin

building 101Performance Profiler 213PHP pages 16PIDs 179pkglist file 58, 63, 65, 66, 67, 71, 73, 215pkg-wr-integration.patch file 117pkg-wr-integration.patch tree 142placeholder RPMs 69platform 47, 87

developers 16integrators 36kernel modules 87projects 25

platform projectverifying build 55

platform projectsgeneral steps 51overview of building 47

plug-ins 274Eclipse 19

ports

Index

285

Index

6443 for KGDB 186POSIX signals 181postpatch

build target 65pre-built

kernels 156, 196RPMs 39

pre-built kernel 38preempt_rt

kernel type 51prepatch 69

build target 65printf 180Printk 189pristine RPM files 58process IDs (PIDs) 179processes

reviewing 177terminating 182

product developmentlife cycle 37

profilesadding 52basics 93creating 93differences from platforms 94hierarchy 93

Profiling build type 54profiling CPU usage 213project 274

description files 274directory 274

ProjectName_prj directory 48projects

application 25customer-specific 25kernel modules 25native applications 25platform 25user-defined 25Wind River Linux 25

properties 164pseudo 58pxeboot 188

QQEMU

backend CLI connections 163connecting to emulated targets 164connections 49emulated boards 29export/dist directories 164KGDB debugging 206, 207Linux User Mode Target 163object path mappings 166

Qemu-PPC32 164Quilt

Add File to Top Patch 122Add New File to Top Patch 141configuring 127Export Patch 143Import Patch 137importing packages 121introduction 127menu 130New Patch 120new top patch files 144patches node 136Pop 143Refresh Top Patch 122setting up 135starting 135viewing patch annotations 138

Rrebuild

build target 65registered patches 142Registry 108, 274remote connections 177Remote Systems view 162

New Connection wizard 162pathname prefix mappings 169shared connection configuration 172

ReplaceRPM 65

Required By panel 64


286

Requires panel 64root 58

directory 50file system 165

RootFS menu 51RPM

dependencies 67generated files 57macros 122manager 63, 151pushes 63queries 63

rpm -erase 65rpm -install 65rpm -install -force 65rpm -option 63rpm_patches.list 130rpm_patches.list file 142RPMs 63

available 58configuration 57installing multi-lib 67launching to target 151placeholder 69pre-built 39removing from target 152replacing running 152unavailable 63, 70URLs for 64

RPMS directory 53rtcore

kernel type 51Run Process on Target 50runtime file system 57

Ssafe areas 189self-hosted applications 47

debugging 176self-hosted development environment 274serial cable connections 195serial line settings 168serial port connections 194

serial/telnet connections 192setgid file permissions 58shared

connections 172installations 11, 267

shell commands in Workbench 262signals

configuring 181POSIX 181

simultaneous usermode-agent connections 189small

kernel type 51snapshots

baseline 216Solaris hosts 26source code indexer 52source lookup path 275source path mapping 39Source RPM (SRPM) packages 121spec files 143, 275

saving 140SRPM package 140updating 121

SPECS/pkg.spec file 142Spin locks 189SQL 19SRPM packages 121

importing 121packages

importing SRPMs 121patching 140URLs 121

SRPM patch filesmodifying 141saving 141

SRPMscross compiling 140integrating into Wind River Linux 140

standardbuilds 275kernel types 51managed builds 275

subprojects 88superprojects 88symbol files 168

Index

287

Index

pre-built 38Symbol Files and Order list 168Symbol Load Options 168sysroots 111, 112, 275

adding 112copying 230exporting 229importing 112provided 112

system mode 275System Viewer 214System.map file 156

Ttar.bz2 files 56, 156tarball

file system image 58target

agent 275environments 160paths 168servers 171, 275

memory cache size 171timeout options 171

Target Operating System Settings dialog 208targets 275

connecting 49PCD 191properties 169server options 171state refresh page 169timeout 171

Targets tab 65, 69TCP connections 186telnet connections 194templates 75, 276

adding 52code 87feature 92named per type 91

terminalslogging into 166

testmod, enhanced sample LKM 204

tgtsvr command (TIPC) 171timeout options 171TIPC 276toolchain 276

available 26host 271

tools, developmentcommunications, managing 159

tutorialHello World 100, 102

UuClibc 51uclibc_small 63

uClibc-based file system 51UDP

connections 186packets 186

uid ownership 58UID root 58uimage 228ulimit settings 223URL

to RPM 64USE 57user mode 276

debuggingintro 30

User Mode Target Server 163User Space Configuration node 40, 57User Space Configuration Tool

overview 118user space debugging 176User Space Editor 57user-defined

builds 276projects 25

user-defined projects 63usermode-agent

and QEMU 49


288

VView icon 59, 62Virtual-WRLinux0 terminal window 166vmlinux

pre-built symbol file 38vmlinux symbol file 41, 189, 193

WWDB debugger 30, 175Wget 68, 121Wind River Debugger 30, 176Wind River Debugger (WDB) 175Wind River Linux Application Core Dump Target

Server Connection 223Wind River Linux KGDB Connection 192, 195Wind River Linux Migration Guide 10Wind River Linux Platform Project 54Wind River Linux Release Notes 10Wind River Linux User’s Guide 42, 155, 184, 215Wind River Platform for Consumer Devices (PCD)

191Wind River Workbench Code Coverage Analyzer

User's Guide 213Wind River Workbench Memory Analyzer User's

Guide 214Wind River Workbench Performance Profiler User's

Guide 213Wind River Workbench User’s Guide 24, 42, 98,

172WIND_LX_HOME 267Windows hosts 26Workbench

build commands 261local installation 267setting environment 260shell commands 262starting 24

workspace 276directory 61

WR Linux Kernel Module Project 206WR Linux Package 68WR3.0au_kernel files 56

wrenv command 260wr-integration.patch file 143wrlinux_quilt_patches directory 142WRLinuxHost_username 177wrll-analysis-1.0 layer 215wrll-toolchain-version 99WRQEMULinuxUser_Project_prj connection 166

XX 19xconfig interface 85

Documents

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