Wind River Workbench (VxWorks 6 Version) By Example, 3read.pudn.com/downloads305/sourcecode/embedded/1358019/wr_w… · ClearCase. This guide also includes troubleshooting information

Wind River Workbench

BY EXAMPLE

3.2

VxWorks 6 Version

®

Wind River Workbench (VxWorks 6 Version) By Example, 3.2

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, Tornado, and VxWorks are registered trademarks of Wind River Systems, Inc. The Wind River logo is a trademark 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:

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 River500 Wind River WayAlameda, CA 94501-1153U.S.A.

Toll free (U.S.A.): 800-545-WINDTelephone: 510-748-4100Facsimile: 510-749-2010

For additional contact information, see the Wind River Web site:

www.windriver.com

For information on how to contact Customer Support, see:

www.windriver.com/support

Wind River WorkbenchBy Example3.2 VxWorks 6 Version

11 Nov 09

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 This Guide is Organized ...................................................................................... 3

1.3 Related Documentation ................................................................................................. 4

PART II: SETTING UP YOUR ENVIRONMENT

2 Getting Started With Workbench .............................................................. 9

2.1 Introduction ...................................................................................................................... 9

2.2 Deciding on a Kernel Image ......................................................................................... 10

2.3 Writing Applications in Workbench ........................................................................... 11

2.4 Creating a Library to Use With an Application ......................................................... 12

2.5 Loading and Booting the Kernel Image ...................................................................... 12

2.6 Customizing a Board Support Package ....................................................................... 12

2.7 Deploying an Application with a System Image ...................................................... 13

2.8 The Benefits of Projects ................................................................................................. 13

2.9 Walkthrough Examples .................................................................................................. 15

2.10 Workbench Example Projects ....................................................................................... 15

3 Setting Up Your Host & Target .................................................................. 17

3.1 Introduction ...................................................................................................................... 17

Wind River WorkbenchBy Example, 3.2

iv

3.2 Your Development Environment ................................................................................. 18

3.3 Configuring Your Host Machine .................................................................................. 18

3.4 Configuring Your Target ............................................................................................... 20

3.5 Booting a Target with VxWorks ................................................................................... 24

3.6 Troubleshooting VxWorks Boot Problems ................................................................ 27

PART III: CUSTOMIZING THE OPERATING SYSTEM

4 Configuring and Building VxWorks .......................................................... 31

4.1 Introduction ...................................................................................................................... 31

4.2 Before You Begin Creating a Kernel Image ............................................................... 32

4.3 Creating a Custom VxWorks Image ............................................................................ 32

4.4 Configuring VxWorks .................................................................................................... 35

4.5 Example: Building a VIP With Sources in a Subdirectory ...................................... 39

4.6 Importing and Migrating Existing VxWorks Image Projects ................................. 41

4.7 Creating a VxWorks Source Build Project .................................................................. 44

4.8 Configuring Custom VxWorks Libraries ................................................................... 46

4.9 Example: Customizing VxWorks Libraries as a Base For a VIP ............................. 47

4.10 Rebasing VSB and VIP Projects ................................................................................... 50

4.11 Loading the VxWorks Image onto the Target ............................................................ 51

5 Working with Board Support Packages ................................................... 57

5.1 Introduction ...................................................................................................................... 57

5.2 Creating an Experimental Default BSP ....................................................................... 58

5.3 Example: Customizing a BSP ........................................................................................ 59

PART IV: DEVELOPING AND DEBUGGING APPLICATIONS

6 Building Applications and Libraries ......................................................... 65

6.1 Introduction ...................................................................................................................... 65

6.2 Deciding on an Application Type ................................................................................ 66

Contents

v

6.3 Creating a Project For Your Application ..................................................................... 67

6.4 Example: Discussion of PowerPC Build Spec Variants ........................................... 69

6.5 Example: Creating and Passing a Build Target ......................................................... 70

6.6 Reconfiguring Your Project Later in the Development Cycle ................................ 73

6.7 Example: Adding IPNet Support to a DKM .............................................................. 78

6.8 Using RTP Overlapped Virtual Memory ................................................................... 80

6.9 Creating Statically Linked Libraries ........................................................................... 80

6.10 Creating Shared Libraries .............................................................................................. 81

6.11 Creating Plug-Ins ............................................................................................................ 82

6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins ............................. 82

6.13 Running Applications on a Hardware Target ........................................................... 91

7 Connecting to VxWorks Targets ............................................................... 93

7.1 Introduction ...................................................................................................................... 93

7.2 What Are Target Servers and Target Agents? ............................................................ 94

7.3 Creating a VxWorks Simulator Connection ............................................................... 95

7.4 Defining a New Target Server Connection ................................................................ 97

7.5 Example: Connecting a Target Server to a Target Agent ......................................... 102

7.6 Defining a New Remote Connection .......................................................................... 104

7.7 Troubleshooting Target Server Connections ............................................................. 104

8 Running and Debugging VxWorks Applications ..................................... 107

8.1 Introduction ...................................................................................................................... 107

8.2 How Can Workbench Help Me Run My Code? ........................................................ 108

8.3 How Do I Create a Launch Configuration? ................................................................ 108

8.4 Running Your Applications .......................................................................................... 111

8.5 Debugging Your Applications ...................................................................................... 113

8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins .................................. 114

8.7 Monitoring Semaphores During Debugging ............................................................ 116


vi

PART V: DEPLOYING APPLICATIONS

9 Deploying VxWorks Systems .................................................................... 121

9.1 Introduction ...................................................................................................................... 121

9.2 Reconfiguring VxWorks for Deployment .................................................................. 121

9.3 Adding Kernel Applications to a VxWorks Image ................................................... 123

9.4 Example: Bundling a VxWorks Image ........................................................................ 125

PART VI: REFERENCE

A What Are All These Project Files For? ...................................................... 135

A.1 Introduction ...................................................................................................................... 135

A.2 Files Common to Many Project Types ........................................................................ 136

A.3 Project Files in VxWorks Image Projects .................................................................... 137

A.4 Project Files in VxWorks Source Build Projects ....................................................... 140

A.5 Project Files in Downloadable Kernel Module Projects ......................................... 142

A.6 Project Files in Real-Time Process Projects ................................................................ 144

A.7 Project Files in Boot Loader/BSP Projects .................................................................. 146

A.8 Project Files in Shared Library Projects ...................................................................... 147

B Debugging a VxWorks 5.5 Target ............................................................. 149

B.1 Introduction ...................................................................................................................... 149

B.2 Before You Begin ............................................................................................................. 149

B.3 Creating a VxWorks 5.5 DKM Project ......................................................................... 150

B.4 Creating a VxWorks 5.5.x Target Server Connection ............................................... 151

B.5 Launching a Kernel Task and Attaching the Debugger .......................................... 151

B.6 Using Existing Tornado 2.x Projects ............................................................................ 154

C Glossary ..................................................................................................... 157

C.1 Introduction ...................................................................................................................... 157

C.2 Searching for Terms in Online Documentation ........................................................ 157

Contents

vii

C.3 Terms ................................................................................................................................. 158

Index ..................................................................................................................... 165


viii

1

PART I

Introduction

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


2

3

1Overview

1.1 Introduction 3

1.2 How This Guide is Organized 3

1.3 Related Documentation 4

1.1 Introduction

Welcome to Wind River Workbench By Example for the VxWorks target operating system.

The purpose of this guide is to provide real-world examples of accomplishing tasks and solving problems that can occur during daily development. Through performing these tasks, you learn to use Wind River Workbench to develop, debug, and deploy VxWorks images and applications.

NOTE: This guide does not cover installation and licensing issues. You should have already installed your Wind River platform, including Workbench, and resolved all licensing requirements. For information on how to accomplish this, go to the following web site: http://www.windriver.com/support/site_configuration

1.2 How This Guide is Organized

This guide is organized so that it follows to the develop, debug, and deploy project life cycle. The following task map lists the topics that are covered in each development phase, and where you can find the information.

http://www.windriver.com/support/site_configuration/


4

VxWorks By Example Task Map

1.3 Related Documentation

The Wind River Workbench documentation set includes the following:

■ Wind River Workbench By Example (this guide)

■ Wind River Workbench User’s Guide

■ Context-sensitive help.

Wind River Workbench By Example Guide

This guide provides solutions to common VxWorks-related problems that can occur in everyday development. By performing the tasks in this guide, you learn to use Wind River Workbench to develop, debug, and deploy VxWorks images and applications.

Topic Description Where to Find the Information

Setting up your environment

How to get started using Workbench and set up your host system and target.

2. Getting Started With Workbench

3. Setting Up Your Host & Target

Developing How to create various projects and build applications and libraries.

4. Configuring and Building VxWorks

5. Working with Board Support Packages

6. Building Applications and Libraries

Debugging How to run and debug applications on your host system and target.

7. Connecting to VxWorks Targets

8. Running and Debugging VxWorks Applications

Deploying How to reconfigure VxWorks and add kernel applications to an image in the process of deployment.

9. Deploying VxWorks Systems

Reference Provides information on VxWorks project file types, how to debug a VxWorks 5.5 target, and a glossary of terms.

A. What Are All These Project Files For?

B. Debugging a VxWorks 5.5 Target

C. Glossary

1 Overview1.3 Related Documentation

5

Wind River Workbench User’s Guide

Refer to the User’s Guide for general information about Workbench, including working with projects, building your applications, connecting and downloading your applications to targets, and working with version control systems such as ClearCase. This guide also includes troubleshooting information and a glossary of terms.

Context-Sensitive Help

You can bring up context-sensitive help for a Workbench feature, as well as perform a keyword search for information on a feature.

To find information about a Workbench feature, do the following:

1. Navigate to the view, dialog, or feature.

2. Press the help key for your host:

■ F1 on Windows

■ CTRL-F1 on Linux and Solaris

The Help view appears with a list of related documentation links.

To perform a keyword search, do the following:

1. Open the help view, by pressing F1 or by selecting Help > Search.

2. Enter a term or phrase in the Search Expression field, and click GO.

The Help view displays a list of topics and links to related documentation.


6

7

PART II

Setting Up Your Environment

2 Getting Started With Workbench ............................................ 9

3 Setting Up Your Host & Target ................................................ 17


8

9

2Getting Started With Workbench

2.1 Introduction 9

2.2 Deciding on a Kernel Image 10

2.3 Writing Applications in Workbench 11

2.4 Creating a Library to Use With an Application 12

2.5 Loading and Booting the Kernel Image 12

2.6 Customizing a Board Support Package 12

2.7 Deploying an Application with a System Image 13

2.8 The Benefits of Projects 13

2.9 Walkthrough Examples 15

2.10 Workbench Example Projects 15

2.1 Introduction

This chapter covers the decisions you need to make before you start a development project, and addresses the decisions you must make before you begin using Workbench. Subsequent chapters show you how to use Workbench to attain your development goals.

Before you can get started with Workbench, you should be able to answer the following questions:

■ Do you want to build a new VxWorks image, or import an existing one from one of your team members?

■ Are you responsible for writing kernel or user space applications?

■ Do you want a prebuilt VxWorks image on which to run your applications, or a customized VxWorks kernel image that automatically starts your application at boot time?


10

By default, Workbench opens to the Basic Device Development perspective. When you first launch Workbench, many of the views in the Basic Device Development perspective are empty. As you work through the examples in this guide, you will learn the purpose and function of these views, as well as the views in other perspectives.

2.2 Deciding on a Kernel Image

A kernel image is necessary for a functioning target. Before you choose a kernel image, you need to understand the following conditions:

■ When to Use a Pre-built image

■ When to Use a Custom Kernel Image

■ When to Rebuild the VxWorks Libraries and Build Your Kernel Image

When to Use a Pre-built image

You can use one of the default, or pre-built, images if your application does not require a specially configured kernel image. If you are responsible for writing applications, you need a kernel in order to test and run your applications. Your Platform ships pre-built VxWorks kernel images for all supported board support packages.

The pre-built kernel images are tested and ready to run, and can be found in the following location:

installDir\vxworks-6.x\target/proj\bsp-toolchain\default\vxWorks

The installDir variable in the path refers to the directory where Workbench is installed, and the bsp-toolchain variable corresponds to the board support package and compiler that are compatible with your target board. For details on how to use these default images, see 3.5 Booting a Target with VxWorks, p.24.

When to Use a Custom Kernel Image

You would use a customized kernel image, if for example, your application requires a bootable VxWorks operating system image to provide support for real-time processes. In this case, the Workbench structure you would create to contain your sources would be a VxWorks image project (also known as a VIP).

Using a VIP based on the default VxWorks libraries, you can create a VxWorks image that you can link with kernel modules, or that you can configure to include a ROMFS file system and real-time processes.

Fore more information about projects in general, see 2.8 The Benefits of Projects, p.13. For more information about VxWorks Image projects in particular, see 4. Configuring and Building VxWorks.

2 Getting Started With Workbench2.3 Writing Applications in Workbench

11

When to Rebuild the VxWorks Libraries and Build Your Kernel Image

Create and configure a VxWorks Source Build project and then base your VIP on that project, to achieve the following results:

■ To have your kernel image support products shipped with your Platform, such as networking products, or security products.

■ To exclude unneeded components to decrease the size of the VxWorks kernel image.

For information about VxWorks Source Build projects, see 4.7 Creating a VxWorks Source Build Project, p.44.

2.3 Writing Applications in Workbench

You can develop different types of applications in Workbench using a similar develop-debug-deploy workflow. In this case, you would select a project type based on the application you are developing. Kernel applications and user applications use different project types.

About Kernel Applications

Kernel applications run in kernel mode, with no barriers between the memory used by the kernel application and the memory used by the kernel itself. Kernel applications can be statically linked into the kernel at build time, or they can be freestanding modules that are downloaded and dynamically linked to the kernel at run time.

If you are developing kernel applications, then a Downloadable Kernel Module project (also known as a DKM) provides the build support you need. For more information about DKMs, both static and dynamic, see Writing Kernel Applications, p.66.

About User Applications

User applications are run in user mode, and are completely separate from the memory space used by the kernel. Wind River user applications are also known as real-time process applications (or RTP applications).

If you are developing user applications, a Real-Time Process project (or RTP project) will be of benefit to you. For more information about RTPs, see Writing Real-Time Process Applications, p.67.


12

2.4 Creating a Library to Use With an Application

The type of application that uses a library determines what kind of Workbench project you should to create. The following guidelines apply:

■ If you are developing a library that will be statically linked to a kernel application at build time, you should create a Downloadable Kernel Module project.

■ If you are developing a library that will be statically linked to a user application at build time, you should create a VxWorks Real-Time Process project. For information on how to create these, see 6.9 Creating Statically Linked Libraries, p.80.

■ If you are developing a library that will dynamically link to a user application at run time, you should create a VxWorks Shared Library project. For information about how to do this, see 6.10 Creating Shared Libraries, p.81.

2.5 Loading and Booting the Kernel Image

You can use a default boot loader provided with your Platform, or customize a bootloader to suite your needs.

Wind River provides default boot loaders with your Platform to automatically boot your target with VxWorks. For more information, see VxWorks Kernel Programmer’s Guide: Boot Loader.

You can customize a boot loader to include a driver for a specific piece of hardware, or to support a new target board, you should create a VxWorks Boot Loader/BSP project. For information on how to do this, see 4.11 Loading the VxWorks Image onto the Target, p.51.

2.6 Customizing a Board Support Package

Some projects may require features that are not included in the board support packages (also known as BSPs) that shipped with your Platform. For these projects, you can create a VxWorks Boot Loader/BSP project and make copies of existing BSP source files and customize them. This gives you a starting point from which to develop a custom BSP. This speeds up development and allows you to experiment without altering the VxWorks installation tree.

For more information about customizing BSPs, see 5. Working with Board Support Packages.

2 Getting Started With Workbench2.7 Deploying an Application with a System Image

13

2.7 Deploying an Application with a System Image

You can create a read-only memory file system that can be configured into a VxWorks kernel image to store your RTP application, libraries, and other files as a single unit (which is convenient for deployed systems). To do this you should create a VxWorks ROMFS File System project and configure the system to run your application automatically at boot time. For more information on how to do this, see 9.4 Example: Bundling a VxWorks Image, p.125.

You can deploy a kernel application with your VxWorks system, by linking the application directly with the kernel and then configuring the system to start it automatically at boot time. For details, see 9.3 Adding Kernel Applications to a VxWorks Image, p.123.

2.8 The Benefits of Projects

Workbench supports a variety of project types, each which creates a supportive framework for a specific task. The Workbench project structure facilitates the following:

■ It allows you to manage your source code files by collecting them into logical, and if necessary hierarchical, structures.

■ It allows you to create build targets with different build-related settings (called build specs) so that you can build the same sources for different target architectures or different toolchains simply by changing the project’s active build spec.

Workbench projects provide specified build support, and this support varies from one project type to another. This means that it is not possible to change a project‘s type after it is created. If you discover that you chose the wrong project type when you created the project, you need to create a new project and then import your source files into it.

The examples in this guide tell you what type of project is best suited to the tasks they are demonstrating. Performing the tasks in these examples gives you experience, so that you can select the correct Workbench projects for your own development projects.

Using the Wind River Workbench New Project Wizard

All application code is managed by projects of one type or another. You can create projects in any location, but in most cases they are created in a workspace directory. This section shows you how to create a new project using the Wind River Workbench New Project wizard.


14

When you create projects outside the workspace, you must have write permission at the external location. You must have write permission, because Workbench project administration files must be written in the project directory.

You can access context-sensitive help from the wizard by pressing the help key for your host:

■ F1 on Windows

■ CTRL-F1 on Linux and Solaris

To create a project using the new project wizard, do the following:

1. Select File > New > Wind River Workbench Project. The Wind River Workbench New Project wizard appears.

2. Choose a Target operating system from the drop-down menu and click Next.

3. Select a Build Type from the drop-down menu and click Next.

You may see different project types depending on your installed software. Platform developers have access to kernel source and kernel tools, whereas application developers do not.

4. Enter a unique Project name, specify one of the following for a location:

■ Create project in workspace

■ Create project in external location—Browse to a location outside the workspace, select the folder, and click OK.

■ Create project in workspace with content at external location—Browse to a location outside the workspace, select the folder, and click OK.

5. Click Finish.

Your new project appears in the Project Explorer.

NOTE: The Advanced Device Development perspective provides shortcuts for creating common project types on the File > New pull-right menu.

2 Getting Started With Workbench2.9 Walkthrough Examples

15

2.9 Walkthrough Examples

The examples in this guide illustrate procedures that are common in many development environments. The following list outlines these examples and where you can find them:

4.5 Example: Building a VIP With Sources in a Subdirectory, p.39

4.9 Example: Customizing VxWorks Libraries as a Base For a VIP, p.47

5.3 Example: Customizing a BSP, p.59

6.4 Example: Discussion of PowerPC Build Spec Variants, p.69

6.5 Example: Creating and Passing a Build Target, p.70

6.7 Example: Adding IPNet Support to a DKM, p.78

6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.82

7.5 Example: Connecting a Target Server to a Target Agent, p.102

8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins, p.114

9.4 Example: Bundling a VxWorks Image, p.125

B. Debugging a VxWorks 5.5 Target

2.10 Workbench Example Projects

Workbench provides a selection of sample projects for you to learn from and use.

To locate a Workbench sample project, do the following:

1. Select File > New > Example.

2. Select a project type from the list and click Next.

3. Select an example program and click Finish.


16

17

3Setting Up Your Host & Target

3.1 Introduction 17

3.2 Your Development Environment 18

3.3 Configuring Your Host Machine 18

3.4 Configuring Your Target 20

3.5 Booting a Target with VxWorks 24

3.6 Troubleshooting VxWorks Boot Problems 27

3.1 Introduction

Cross-development is the process of writing code on one system, known as a host, that will run on another system, known as a target.

Cross-development allows you to write code on a system that you have available to you (such as a PC running Linux, Windows, or Solaris) and produce applications that run on hardware that you would have no other convenient way of programming, such as a chip destined for a mobile phone.

Before you can work with VxWorks applications, kernel images, or libraries, you must complete the following process for setting up your host and target:

1. Configure the network software on the host correctly (see 3.3 Configuring Your Host Machine, p.18).

2. Connect the target to the host and power it up (see 3.4 Configuring Your Target, p.20).

3. Load the boot loader onto the target (see 4.11 Loading the VxWorks Image onto the Target, p.51).

This chapter explains how to complete these tasks, including instructions on how to download a prebuilt VxWorks image and boot your target.

NOTE: Paths to Workbench directories and files are prefixed by installDir in this guide. Substitute the actual path to your Workbench installation directory.


18

3.2 Your Development Environment

The most common cross-development environment consists of the following:

■ A host machine where you do your development work.

■ A target board or simulator where you run your VxWorks kernel image and application(s).

■ A compiler and other development tools (such as those shipped with your Platform) that are designed for cross development.

■ One or more communication connections running between the host and the target.

If you work in a native development environment, also known as self-hosted, you develop applications that run on your development machine rather than on a target. For this type of development, you must acquire a native tool chain, preferably GNU, since this is not shipped with Workbench.

Regardless of what your development environment looks like, make sure you have all the necessary hardware and software elements configured before you begin using Workbench for your development.

3.3 Configuring Your Host Machine

The first phase of the configuration process consists of setting up your development host. The host is the system on which you do most, if not all, of your development. In most cases, you will need to perform the following tasks once on each development host:

■ Task 1: Install Workbench and other Platform products.

■ Task 2: Configure TCP/IP.

■ Task 3: Set up FTP.

■ Task 4: Enable logging.

Task 1: Install Workbench and other Platform products.

This guide does not cover the details of installation and licensing. This task points you to the place where you can find the information you need.

To install Workbench and other platform products, do the following:

1. Install Wind River, including Workbench, as described in the following document: http://www.windriver.com/support/site_configuration/

2. Resolve all licensing requirements.

You can launch Wind River Workbench and the Welcome screen appears.

NOTE: You must install Wind River platform, including Workbench, to be able complete the tasks in this guide. All licensing requirements must be resolved.

3 Setting Up Your Host & Target3.3 Configuring Your Host Machine

19

Task 2: Configure TCP/IP.

Network configuration is beyond the scope of this guide. However, since configuring TCP/IP on the host is necessary for cross-platform development, you must complete the following task.

To configure TCP/IP on the host, do one of the following:

■ Configure the networking on your host as described in your operating system documentation.

■ Consult with your local system administrator.

Task 3: Set up FTP.

You must start an FTP server on the host that the target is connected to, before you can boot VxWorks over the network. You must also create a user ID and password in the FTP server application that matches the user ID and password that you will assign to the VxWorks boot loader on your target. This allows the host to recognize the target when it tries to download the VxWorks kernel image.

You can use the following hosts:

■ Windows: This platform has an FTP server application, WFTPD.

■ Linux and Solaris: These platforms can use the rsh utility or FTP. However, this task only provides instructions for FTP.

To set up FTP on a Linux or Solaris host, do the following:

1. Start the FTP daemon on the host. For more information see the ftp manual page. This allows you to use the default VxWorks configuration and boot VxWorks over the network.

2. Authenticate the user ID and password assigned to the VxWorks target.

To set up FTP on a Windows host, do the following:

1. On the Windows host, manually create a home directory such as C:\TEMP, with enough disk space for the VxWorks boot loader to read the boot image.

2. Start the FTP server on the host by selecting Start > Programs > Wind River > VxWorks 6.x and General Purpose Technologies > FTP Server.

3. Configure a user name and password for the VxWorks boot loader on the target, in the following way:

a. From the WFTPD toolbar, select Security > Users/rights.

b. In the User/Rights Security Dialog, click New User.

c. In the New User dialog, enter a user ID, then click OK. Be sure to use this same user ID when you assign the user VxWorks boot parameter described in 3.5 Booting a Target with VxWorks, p.24.

d. In the Change Password dialog, enter and verify a password, then click OK. Be sure to use this same password when you assign the ftp password VxWorks boot parameter.

NOTE: Remember the path for this home directory for later use in this task.


20

Your password must not be an empty string. If it is, the boot loader will try to use the UNIX rsh utility instead of FTP to load the kernel image, and rsh is not available on Windows.

e. Back in the User/Rights Security Dialog, enter the path for the Home Directory you created in step 1. WFTPD refuses to connect to a client unless you specify a home directory.

f. Close the User / Rights Security Dialog by clicking Done.

The FTP client connects to the FTP server.

Task 4: Enable logging.

Enabling logging is optional. You enable logging to store records of FTP activities.

To enable logging, do the following:

1. Select Logging > Log Options.

2. Select the types of activities you want to log.

3. When you are finished, click OK.

The log file is saved in the home directory you specified earlier.

Where to Go Next

Continue with Configuring Your Target.

3.4 Configuring Your Target

The next phase of the configuration process consists of setting up your target. You must perform the following tasks for each new target that connects to your host:

■ Task 1: Assign the VxWorks target a name and IP address.

■ Task 2: Set up a serial connection between the host and target.

■ Task 3: Set up an Ethernet connection between the host and target.

■ Task 4: Configure the Terminal view to open a serial connection.

■ Task 5: Set board switches and jumpers.

■ Task 6: Connect a power supply.

NOTE: Leave the FTP server running. It must be running when the boot loader on your target tries to access the VxWorks image on your host.

3 Setting Up Your Host & Target3.4 Configuring Your Target

21

Task 1: Assign the VxWorks target a name and IP address.

There are two ways you coordinate target names and IP addresses:

■ Using a Domain Name Service (DNS) server.

■ Using a hosts file. This file records the names and IP addresses of systems accessible on the network from the local system (otherwise, you would have to identify targets by IP address).

To assign a target name and IP address using a DNS server, do the following:

■ Configure your computer to use the DNS server to translate system names to network IP addresses. Consult your operating system documentation, or your system administrator.

To assign a target name and IP address using a hosts file, do the following:

1. Open the hosts file on your system, in one of the following ways:

■ On Linux and Solaris it is located in /etc/hosts.

■ On Windows it is located in C:\Windows\system32\drivers\etc\hosts).

2. Map machine names to IP addresses.

Each line consists of an IP address and the name (or names) of the system at that address.

3. Another entry that should appear in your hosts file is for localhost.

Workbench expects localhost to resolve to 127.0.0.1. If it has been misconfigured (if, for example, it points to the IP address of the development machine) you may have problems with the interaction between Workbench, the debugger, and wtxregd.

For example, suppose your host system is called mars and has Internet address 90.0.0.1, and you want to name your VxWorks target phobos and assign it address 90.0.0.50. The hosts file must then contain the following lines:

90.0.0.1 mars90.0.0.50 phobos

! CAUTION: You should always discharge the static electricity that may have collected on your body before you touch integrated circuit boards, including targets and network interface cards (NICs).

Electrostatic discharge (ESD) precautions include:

■ Touching the metal enclosure of a plugged-in piece of electrical equipment (such as a PC or a power supply in a metal case).

■ Placing your equipment on, or standing on, an anti-static mat.

■ Wearing an ESD wrist strap.

Failure to take proper ESD precautions can degrade target hardware over time, leading to intermittent errors or hardware failure.

! CAUTION: If you are in a networked environment, do not pick arbitrary IP addresses for your host and target, as they could be assigned to someone else. Contact with your system administrator for available IP addresses.


22

This configuration is represented in Figure 3-1.

Task 2: Set up a serial connection between the host and target.

The host uses the serial connection to communicate with the boot loader on the target.

To set up a serial connection between a host and target, do the following:

■ Connect a serial cable between the serial ports on the host and target. Most targets include at least one on-board serial port.

Task 3: Set up an Ethernet connection between the host and target.

The host uses the network connection to transfer files, including the VxWorks system image.

NOTE: Always use the recommended (correct) cable.

To establish an Ethernet connection between the host and target, do the following:

Make sure you use the correct cable:

■ To connect your board directly to your host, use a crossover cable.

■ To connect your board to a LAN, use a non-crossover cable.

Task 4: Configure the Terminal view to open a serial connection.

You can use the Terminal view and open a serial connection from within Workbench. The Terminal view connection is similar to any other terminal emulation program such as hyperterminal, minicom, or telnet.

To configure the Terminal view, do the following:

1. Stop any other program already using the Serial Port.

2. If it is not already running, start Workbench.

Figure 3-1 Boot Configuration Example

TARGET

phobos

HOST

mars

90.0.0.50:ffffff0090.0.0.1

c:\temp\vxWorks

user: fred

Ethernet

90.0.0.x subnet

3 Setting Up Your Host & Target3.4 Configuring Your Target

23

■ On a Windows host, select Start > Programs > Wind River > Workbench 3.2 > Workbench 3.2.

■ On a Linux or Solaris host, make sure your path environment variable is set to include the path to your compiler. Typically, which gcc should yield /usr/bin/gcc. Then, from your Workbench installation directory, issue the following command:

$ ./startWorkbench.sh

3. Open the Terminal view (select Window > Show View > Terminal).

4. To get a better view of what is happening in the Terminal view, double-click the tab at the top of the view. The view will expand to fill the Workbench window.

5. To adjust the settings for your connection, click the square Settings button to open the Terminal Settings dialog. Configure the terminal settings as appropriate for your system. For information about each option, press the help key for your host.

6. When you are finished, click OK to open a connection to your target.

7. Click Toggle Command Input Field to open a text inset field at the bottom of the Terminal view where you can enter and edit text. The contents of the text field are sent to the target when you press ENTER, and you can use the up and down arrows on your keyboard to navigate through previously entered text.

8. Click Toggle Command Input Field to hide the text inset field again.

9. To disconnect from your target click Disconnect, and to reopen the connection with the existing settings click Connect.

Task 5: Set board switches and jumpers.

CPU and Ethernet controller boards can have configuration options that are selected by hardware jumpers, although this is less common than in the past. These jumpers must be correctly set for your development environment forVxWorks to boot successfully.

To set board switches and jumpers, do the following:

■ You can determine the correct jumper configuration for your target CPU from the target reference for your BSP and the documentation provided by your target system’s manufacturer. For an example, see the following: installDir/vxworks-6.x/target/config/bsp/target.ref

Task 6: Connect a power supply.

This procedure assumes you are using a standalone target.

To connect a power supply, do the following:

■ Use the power supply recommended by the board manufacturer, and connect it according to the manufacturer’s directions.

NOTE: If you are using a Wind River ICE or Wind River Probe emulator to connect to your target, see the Wind River ICE SX for Wind River Workbench Hardware Reference or Wind River Probe for Wind River Workbench Hardware Reference for information about how to connect to your target.


24

Where to Go Next

You are ready to boot a prebuilt VxWorks kernel image. Continue with Booting a Target with VxWorks.

3.5 Booting a Target with VxWorks

Once you have configured your host software and target hardware, you are ready to boot VxWorks on the target.

You must start and then interrupt the default boot loader on the target to get a VxWorks Boot prompt. Then, you can provide new boot parameters and download a new VxWorks kernel image.

This process requires that you complete the following tasks:

■ Task 1: Initiate, then interrupt, the boot process on the target.

■ Task 2: Enter new boot parameters.

■ Task 3: Boot the target with new parameters.

Task 1: Initiate, then interrupt, the boot process on the target.

This procedure assumes the following conditions:

■ You are using a VxWorks image configured for a network connection (which is the default).

■ The FTP server you started in Task 3: Set up FTP., p.19 is still running on the host where the VxWorks image is stored.

To initiate and interrupt the boot process, do the following:

1. With your target connected to your host and a Serial connection open in the Terminal view (see 3.4 Configuring Your Target, p.20), click Connect on the Terminal view toolbar.

2. Reset your target in any of the following ways:

■ Pressing the reset button.

■ Powering off the target then powering it on again.

■ In the Terminal view, type CTRL+X. Other Windows terminal emulators do not pass CTRL+X to the target, because of its standard Windows meaning.

■ Invoke reboot( ) from the host shell.

The boot program displays a banner page in the Terminal view, and starts a seven-second countdown.

3. Press any key on the keyboard during that seven-second period to interrupt the boot process. The boot program displays the VxWorks boot prompt:

[VxWorks Boot]:

3 Setting Up Your Host & Target3.5 Booting a Target with VxWorks

25

4. To print the current (default) boot parameters, type p at the boot prompt:

[VxWorks Boot]: p

A display similar to the following appears.

boot device : lnunit number : 0processor number : 0host name : marsfile name : c:\temp\vxWorksinet on ethernet (e) : 90.0.0.50:ffffff00host inet (h) : 90.0.0.1user (u) : fredftp password (pw)(blank=use rsh) :secrettarget name (tn) : phobos

This example corresponds to the configuration shown in Figure 3-1. Each of these parameters is described in VxWorks Kernel Programmer’s Guide: Boot Loader, available in the Workbench help system.

Task 2: Enter new boot parameters.

This procedures assumes that you are changing the boot parameters to match the settings for your system.

To enter new boot parameters, do the following:

1. Type the following at the boot prompt:

[VxWorks Boot]: c

2. The boot program prompts you for each new parameter.

– If a particular field already has the correct value, press ENTER.

– To clear a field, type a period ( . ), then press ENTER.

– To back up and change the previous parameter, type a hyphen (-), then press ENTER.

– If you want to quit before completing all parameters, type CTRL+D.

3. The first parameter you probably need to change is the host name, so press ENTER a couple of times to get past the first few parameters, then type in the name of the host machine to boot from. Press ENTER.

4. In the file name field, type the full host side path name of the VxWorks image you want to boot on the target (if you want to use one of the pre-built VxWorks images, they are located in installDir/vxworks-6.x/target/proj/bsp-toolchain/default).

5. In the inet on ethernet field, type the IP address of the target, then a colon, then the subnet mask.

6. In the host inet field, type the IP address of the host. Remember that the host and target IP addresses must match those in your hosts file, or those known to your DNS server (for details, see Task 1: Assign the VxWorks target a name and IP address., p.21).


26

7. In the user field, type the user ID used to access the host for the purpose of loading the VxWorks image file specified in the file name parameter. The following conditions apply:

■ On a Windows host, you must have FTP access to the host. Use the user name you created in 3.3 Configuring Your Host Machine, p.18.

■ On a UNIX host, you must have either FTP or rsh access. For rsh, you must be granted access by adding the user ID to the host's /etc/host.equiv file, or more typically to the user's .rhosts file (~userName/.rhosts).

8. In the ftp password field, type the password you created in 3.3 Configuring Your Host Machine, p.18. For rsh access leave this field blank.

9. In the target name field, type the name of the target.

Task 3: Boot the target with new parameters.

This procedure assumes that you completed the task of changing the boot parameters.

To boot the target with the new parameters, do the following:

1. Initiate booting by typing the @ command:

[VxWorks Boot]: @

The VxWorks boot program prints the boot parameters you entered, and the boot process begins.

The following information appears during the boot process:

a. The boot program first initializes its network interfaces.

b. After the system is completely loaded, the boot loader displays the entry address and transfers control to the loaded VxWorks system.

c. When VxWorks starts up, it begins just as the boot loader did, by initializing its network interfaces. The network-initialization messages appear again, sometimes accompanied by other messages about optional VxWorks facilities.

2. After this point, the [VxWorks Boot] prompt appears. This means VxWorks is ready to attach to the Workbench tools.

Task 4: Reboot VxWorks as necessary.

Rebooting also restarts the attached target server on the host.

To reboot VxWorks, do any of the following:

■ Type CTRL+X in the Terminal view. Other Windows terminal emulators do not pass CTRL+X to the target, because of its standard Windows meaning.

■ Invoke reboot( ) from the host shell.

■ Press the reset button on the target system.

■ Turn the target’s power off and on.

The VxWorks auto-boot sequence begins again from the countdown.

3 Setting Up Your Host & Target3.6 Troubleshooting VxWorks Boot Problems

27

Where to Go Next

Continue with Troubleshooting VxWorks Boot Problems, as necessary.

3.6 Troubleshooting VxWorks Boot Problems

If you encountered problems booting or exercising VxWorks, there are many possible causes. This section discusses the most common sources of error.

Please read this section before contacting Wind River customer support. Often, you can locate the problem by re-checking the installation steps, your hardware configuration, and so forth.

Most often, a problem with booting and connecting to VxWorks can be traced to configuration errors in hardware or software. Consult the following checklists to locate a problem.

Hardware Configuration Checklist

This section covers the most common hardware configuration errors. Consult this list to locate a hardware configuration problem.

■ If you are using an emulator

See the Wind River ICE SX for Wind River Workbench Hardware Reference or the Wind River Probe for Wind River Workbench Hardware Reference for information on troubleshooting those connections.

■ Limit the number of variables

Start with a minimal configuration of a single target.

■ Check that the RS-232 cables are correctly constructed

In most cases, the documentation accompanying your target system describes its cabling requirements. A NULL modem cable may be necessary, if that is what your target requires.

■ Check the boot ROM(s) for correct insertion

If the target seems completely dead when applying power (some have front panel LEDs) or shows some error condition (for example, red lights), the boot ROMs may be inserted incorrectly.

■ Press the RESET button if required

Some system controller boards do not reset completely on power-on; you must reset them manually. Consult the target documentation if necessary.

NOTE: If you need to use a gender converter to connect your serial cable, it is most likely not the right kind of cable. NULL modem cables tend to have same gender connectors on each end, such as both female or both male. Straight through cables tend to have one male and one female connector. Changing the gender of a cable rarely has the desired results.


28

■ Make sure all boards are jumpered properly

Refer to the target information reference for your BSP and the target documentation to determine the correct dip switch and jumper settings for your target and Ethernet boards.

Software Configuration Checklist for Booting Problems

Software configuration errors usually result in booting problems. This section covers the most common software configuration errors. Consult this checklist to locate a software configuration problem.

■ VxWorks Boot Display

Check the VxWorks boot display, in the following ways:

■ If Attaching network interface is displayed without the corresponding done, verify that the system controller is configured properly and the network interface card is properly jumpered. This error may also indicate a problem with the network driver in the newly loaded VxWorks image.

■ If Loading... is displayed for more than 30-45 seconds without the size of the VxWorks image appearing, this may indicate problems with the Ethernet cable or connection, or an error in the network configuration (for example, a bad host or gateway Internet address).

■ If the line Starting at is printed and there is no further indication of activity from VxWorks, this generally indicates there is a problem with the boot image.

■ Check the Ethernet transceiver site

For example, connect a known working system to the Ethernet cable and check whether the network functions.

■ Verify IP addresses

An IP address consists of a network number and a host number. There are several different classes of Internet addresses that assign different parts of the 32-bit Internet address to these two parts, but in all cases, the network number is given in the most significant bits and the host number is given in the least significant bits. The simple configuration described in Task 3: Boot the target with new parameters., p.26 assumes that the host and target are on the same network—they have the same network number.

If the target Internet address is not on the same network as the host, the VxWorks boot program displays the following message:

Error loading file: errno = 0x33.

For a discussion of VxWorks error status values, see the errnoLib reference entry by typing errnoLib into the help view’s Search field.

■ Verify FTP server permissions

Check the FTP server configuration. See Task 3: Set up FTP., p.19 for more information on configuring the FTP server if you are using WFTPD (shipped by Wind River). Otherwise, consult your system documentation on the FTP Server shipped with it.

3 Setting Up Your Host & Target3.6 Troubleshooting VxWorks Boot Problems

29

Using the WFTPD Server Log

The WFTPD server log displays plain, helpful text messages that are useful for troubleshooting. For information about how to enable logging FTP activities, see Task 4: Enable logging., p.20.

29

PART II I

Customizing the Operating System

4 Configuring and Building VxWorks ........................................ 31

5 Working with Board Support Packages ................................. 57


30

31

4Configuring and Building VxWorks

4.1 Introduction 31

4.2 Before You Begin Creating a Kernel Image 32

4.3 Creating a Custom VxWorks Image 32

4.4 Configuring VxWorks 35

4.5 Example: Building a VIP With Sources in a Subdirectory 39

4.6 Importing and Migrating Existing VxWorks Image Projects 41

4.7 Creating a VxWorks Source Build Project 44

4.8 Configuring Custom VxWorks Libraries 46

4.9 Example: Customizing VxWorks Libraries as a Base For a VIP 47

4.10 Rebasing VSB and VIP Projects 50

4.11 Loading the VxWorks Image onto the Target 51

4.1 Introduction

A VxWorks Image project (also known as a VIP)) provides build, source analysis, and other settings that streamline creating, configuring, and building a kernel image. A VIP can contain just the files needed to create a kernel image, or you can add a VxWorks ROMFS File System project and kernel modules, applications, libraries, and data files to link a complete system into a single image.

Consider configuring and building VxWorks if the following conditions apply:

■ You are a kernel developer tasked with tailoring VxWorks to your particular system requirements.

■ You need to include a component to VxWorks to enable one of the products shipped with your Platform.

You can start by creating a VxWorks Image project (VIP) in Workbench.


32

If you only need a basic VxWorks kernel to boot your target, you can use one of the pre-built images shipped with your Platform, as discussed in 2.2 Deciding on a Kernel Image, p.10. For instructions on using these images, see 3.5 Booting a Target with VxWorks, p.24.

4.2 Before You Begin Creating a Kernel Image

Before you create a VxWorks Image project, you should consider the kernel image you will build with that project. Before you begin creating your kernel image, consider the following questions:

■ Do you want to run your image on the VxWorks simulator, or on an actual target board?

■ Do you have an existing project in your workspace whose settings you want your new VIP to inherit?

■ Do you want to include debugging or networking support from the start? Or has one of your team members used a VxWorks Source Build (VSB) project to rebuild VxWorks to include or remove particular components?

You will save time by making these decisions before you create your project. However, it is possible to configure some VIP project settings after the project is created. For details, see 4.4 Configuring VxWorks, p.35.

4.3 Creating a Custom VxWorks Image

In this task, you create a customized VxWorks image, and corresponding VxWorks Image project (VIP).

You should be able to answer the following questions before you begin creating a custom VxWorks image:

■ What will you base your project on? Consider the following before making a decision:

Project creation is faster if you base your project on an existing VIP, since the project facility copies the configuration information instead of regenerating it from BSP configuration files. For more information about Boot Loader/BSP projects, see 4.11 Loading the VxWorks Image onto the Target, p.51. For details on importing a VIP into your workspace from another workspace or from a team member, see 4.6 Importing and Migrating Existing VxWorks Image Projects, p.41.

Once your VIP is created, you cannot change the BSP it is based on. You must create a new project with the correct BSP. If you base your VIP on a BSP you must also select a tool chain (the compiler, linker, and so on that Workbench uses to build projects).

4 Configuring and Building VxWorks4.3 Creating a Custom VxWorks Image

33

The BSP and toolchain options available for your VIP are controlled by the options selected in the VSB. For details, see 4.7 Creating a VxWorks Source Build Project, p.44.

■ Do you want support for the BSP validation test suite?

Support for the BSP validation test suite is available for all non-simulator BSPs. For information about the settings and options of the BSP validation test suite, see the VxWorks BSP Validation Test Suite User’s Guide.

■ Do you want networking and multiprocessing support?

Options available to you may vary, depending on the Platform you installed and the BSP you chose for your project. The following are a few options that may be available:

IPv6 enabled kernel libraries—Creates IPv6 support.

IPv6_only enabled kernel libraries—Creates IPv6_only support.

SMP support in kernel—Creates a symmetric multiprocessing configuration of VxWorks. Once the VIP is created, you cannot change it to a uniprocessor or asymmetric multiprocessor configuration.

■ Is a kernel configuration profile right for your project?

A Profile is a preconfigured collection of kernel components that provide the described functionality. Using a profile can save you quite a bit of work, but you do not need to select one now—you can create the same configuration using the Kernel Configuration Editor (see 4.4 Configuring VxWorks, p.35).

To create a custom VxWorks image, do the following:

1. Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development.

2. Select File > New > VxWorks Image Project. The Project screen of the wizard appears.

3. Enter a name for your project, and specify a project location by selecting one of the following options, and then click Next.

Create project in workspaceTo create the project in the current workspace, leave this selected. This is a good idea if you do not have write permission to the location of your source files, or if you will create or import sources later.

Create project at external locationTo create the project outside your workspace, select this option, click Browse and navigate to the location. This is good when you have write permission to the location of your sources (so you will not have to import them later), or if your project will be version-controlled and the sources are outside your workspace.

NOTE: It is not necessary to make a selection on every screen.


34

4. Select one of the following options from the Project Setup screen to specify what to base the project on. This defines where Workbench gets the build and other settings for the project.

An existing project From the drop-down list to select another VIP or a Boot Loader/BSP project in your workspace, or click Browse and select a similar project from another location.

A source build project To base a VIP on a VxWorks source build (VSB) project, you or someone on your team must have created that project and rebuilt your VxWorks source libraries.

A board support packageSelect a BSP from the drop-down list that supports your target hardware. To run your image on the VxWorks simulator, select simpc on a Windows host, linux on a Linux host, or solaris on a Solaris host.

To use a BSP provided by someone in your organization or a third party, click Browse and navigate to the location.

Tool chainThe drop-down list displays the tool chains you have installed, such as the GNU compiler or the Wind River Compiler (known as diab).

5. (Optional) Include support for the BSP validation test suite by selecting Add support to project, click Options. Then from the dialog box, select a test suite, provide board and host configuration information, click Browse and navigate to where you want the test results to be stored. Click Close then Next.

6. (Optional) Include networking and multiprocessing support by selecting the appropriate options, and then clicking Next.

7. (Optional) Select one of the following kernel configuration profiles:

PROFILE_COMPATIBLEUsing this profile provides the minimal configuration that is compatible with VxWorks 5.5.

PROFILE_DEVELOPMENTThis profile creates a VxWorks image that includes development and debugging components.

PROFILE_ENHANCED_NETThis adds to the default image the components appropriate for typical managed network client host devices.

PROFILE_CERTUsing this profile creates an image that contains only a DO-178B Level A-certifiable API subset of the VxWorks operating system.

NOTE: SMP support is only available if your product activation file (*.install.txt) and the BSP you selected support it.

■ If you do not see the option you want, you must select a different BSP.■ If you see an option but cannot select it, your BSP supports the feature but

your product activation file did not enable it.

4 Configuring and Building VxWorks4.4 Configuring VxWorks

35

PROFILE_BOOTAPPThis profile adds boot loader functionality to a default VxWorks image.

8. (Optional) Configure the source code indexer, by selecting Enable project specific settings and then adjust the indexer settings as appropriate.

Most projects work fine if you use the general indexer settings applied to all projects (which you can examine if you click Configure Workspace Settings). For more information about selecting settings and configuring the indexer, press the help key for your host.

9. Click Finish to create your project.

Your new project appears in the Project Explorer, and displays both project files and linked resources.

For more information about boot loaders, see 4.11 Loading the VxWorks Image onto the Target, p.51 and the Customizing and Building Boot Loaders section in VxWorks Kernel Programmer’s Guide: Boot Loader. For information about selecting non-default drivers, see Specifying a Non-Default Driver, p.38.

For more information about profiles, see VxWorks Kernel Programmer’s Guide: Kernel Facilities and Kernel Configurations and the help page for vxprj::profile.

4.4 Configuring VxWorks

You can configure, include, or exclude selected components of the VxWorks kernel, depending on the requirements for your application or the phase of development.

For example, you might need to change a port number or timeout setting for a networking component, or specify a non-default driver for your system. Or you may find it useful to configure VxWorks with components to provide POSIX support.

Another reason might be to exclude selected functionality when it is time to deploy your system. For example, the WDB target agent is required during development to allow Workbench to communicate with the target. You may want to remove this functionality when you deploy the system, since the Workbench-target connection is no longer needed.

NOTE: If Workbench encounters a problem while creating the project (if, for example, you specified the diab tool chain but the selected BSP only supports gnu) Workbench will display an error describing the problem.

Clicking OK reopens the New Project wizard, complete with all the settings you chose while creating the project. This gives you an opportunity to fix just the setting causing the problem, rather than having to re-enter all the selections in the wizard.

If you do not want to fix the problem and create the project now, click Cancel.


36

4.4.1 Using the Kernel Configuration Editor

The Kernel Configuration Editor allows you to customize a kernel. The tabs for the option pages are arranged along the bottom edge of the view:

■ Overview—Provides a read-only summary of the configuration, including BSP and toolchain information and estimated size of the image.

■ Bundles—Allows you to add or remove entire bundles of components, such as those needed for specific kernel shell configurations or POSIX functionality.

Clicking a bundle shows you the components it contains (and that will be included in your kernel image by adding this bundle); to see a component in context, right-click it and select Show in Component Configuration.

■ Components—Displays a tree of bundles and, at the leaf nodes of expanded bundles, individual components and their parameters. The availability and status of a component or family is indicated by its typeface:

Bold icons indicate that a component is included in the image. A family name appears in bold type if any of its components are included.

Pale icons and plain type indicate that a component or family of components is not included in the image, but is installed and available.

Pale icons and grey italics indicate that a component is not installed.

To open the Kernel Configuration Editor, do the following:

1. In the Project Explorer, double-click a VIP to show its contents.

2. Double-click the Kernel Configuration node. Three tabs are arranged along the bottom edge of the view

NOTE: When CDF files are modified outside of Workbench, either intentionally or automatically when a patch is installed, you must physically delete the CxrCat.txt file in installDir/vxworks-6.x/target/config/comps/vxWorks and then reopen the Kernel Configuration editor.

This is necessary because the CxrCat.txt file must be regenerated and it does not happen automatically when changes are made to CDF files outside of Workbench. In such cases, you must manually delete the file, and then reopen the Kernel Configuration editor for the CDF changes to take affect.

NOTE: You must configure and build some products, such as Wind River Firewall and Wind River Network Stack, before you can include them in your image. For details, see the Wind River VxWorks Platforms User’s Guide.

4 Configuring and Building VxWorks4.4 Configuring VxWorks

37

Including Components in a Kernel Image

This example shows you how to include ping functionality in a kernel image.

You must have an existing VxWorks Image Project (VIP) to complete this task. For information on how to create a VxWorks Image project, see “Creating a Custom VxWorks Image” on page 32.

To include ping functionality in a kernel image, do the following:

1. Double-click the Kernel Configuration node of an existing VxWorks Image project. The Kernel Configuration Editor opens.

2. Search for the component to include, in the following way:

a. From the Components tab, type CTRL+F or right-click and select Find.

b. You can search for ping in two ways: by name and by description. For this example, select Description at the top of the dialog.

c. In the Pattern field, type ping. The PING Components folder and its contents appear in the Matching pane, and the parent nodes for the folder appear in the Component tree pane.

d. To navigate to the folder, double-click it or select it and click Find. The tree structure opens and the folder is highlighted.

3. To include ping in your image, right-click the PING Components folder and select Include.

4. In the Include dialog, you want both the IPCOM ping commands and the PING client, so click Select All, then click Next.

Workbench determines if there are any dependent components that must be included to support ping, and displays them along with the estimated change in the size of your image from including these components.

5. Click Finish to complete the configuration.

In the Kernel Configuration Editor, the PING Components folder is bold, indicating that ping will be included in your kernel image the next time you build it.

A star-shaped overlay icon indicates that your changes have not yet been saved. Building your project saves the changes automatically, but you might want to save them manually first. In that case, proceed with the next step.

6. To save your changes manually, do one of the following:

■ Close the Editor view and select Yes when Workbench asks to save your changes.

■ Press CTRL+S to save your changes without closing the view.

7. Build your project by right-clicking the project in the Project Explorer, and selecting Build Project. Alternatively, you can click the Build Projects icon on the toolbar.

NOTE: If you know where ping is located, you can navigate to it using the Editor’s tree structure. For convenience, this example shows you how to use the Find dialog.


38

The ping components are included in the new VxWorks kernel image.

Excluding Components in a Kernel Image

You can exclude components from a kernel image to decrease its size and streamline performance. This task is similar to the task for including components. This example shows you how to exclude networking components from an image.

You must have an existing VxWorks Image project to complete this task. For information on how to create a VxWorks Image project, see “Creating a Custom VxWorks Image” on page 32.

To exclude components from a kernel image, do the following:

1. Double-click the Kernel Configuration node of an existing VxWorks Image project to open the Kernel Configuration Editor.

2. Select the component you want to exclude. For this example, right-click Networking Components, and then select Exclude. The Exclude dialog appears.

If you wanted to keep any components in the image, you would unselect components.

3. Leave all components selected and click Next.

Workbench determines if there are any dependent components that must also be excluded along with the networking components, and displays them.

4. Click Finish, to complete the configuration.

In the Kernel Configuration Editor, the Network Components is visible, but it is no longer bold. This means that the networking components are still installed and available, but they are not included in your kernel image. There is an overlay icon indicating that the component has changed, but the change has not yet been saved. The changes are automatically saved when you build your project.

5. Build your project by right-clicking the project in the Project Explorer, and selecting Build Project. Alternatively, you can click the Build Projects icon on the toolbar.

The networking components are excluded from the resulting VxWorks kernel image.

For more information about kernel components, see the VxWorks Kernel Programmer’s Guide: Kernel. For more information about the Kernel Configuration Editor, open it and press the help key for your host.

Specifying a Non-Default Driver

Your system may require a supported driver that is not provided as the default, or a driver that is not VxBus-compliant. The way in which you specify a non-default driver depends on whether or not the driver is VxBus-compliant.

Follow these guidelines:

4 Configuring and Building VxWorks4.5 Example: Building a VIP With Sources in a Subdirectory

39

■ Add or remove VxBus-compatible drivers in the same way you include or exclude other components, as described in “Including Components in a Kernel Image” on page 37 and “Excluding Components in a Kernel Image” on page 38.

■ Add or remove drivers that are not compatible with VxBus (only) by defining or undefining the respective macros in installDir/vxworks-6.x/target/config/bspName/config.h.

For information about the VxBus drivers available for your system, see installDir/vxworks-6.x/target/src/hwif/util/cmdLineBuild.c. For information about non-VxBus drivers supported for a given BSP, see the VxWorks BSP References.

4.5 Example: Building a VIP With Sources in a Subdirectory

This example shows you how to create a VIP with sources in a subdirectory that contains a makefile fragment.

To build a VIP with sources in a subdirectory, do the following:


2. Create a VIP project by selecting File > New > VxWorks Image Project, entering a name for the project, specifying a location, and then clicking Next.

3. For this example, select the simpc BSP and the diab tool chain. You do not need to adjust any other settings, so click Next to page through the subsequent dialogs, and then click Finish.

4. Create a directory called dummy inside the VIP by right-clicking the project, and selecting New > Folder. Then in the Folder name field, type dummy, and click Finish.

5. Create a new source file in the following way:

a. Inside the folder dummy, create a file called hello.c by right-clicking the dummy folder and selecting New > File.

b. In the New File dialog, type hello.c in the File name field, then click Finish. The new hello.c file opens in the editor.

NOTE: Changes to config.h must be made before you create a VxWorks image project. Any changes made to config.h after a VIP is created are not picked up by the project.


40

c. Add the following content:

/**************************/#include "stdio.h" void helloworld(void){

printf("helloworld");}/**************************/

d. Save the file by pressing CTRL+S.

6. Create a makefile fragment, in the following way:

a. In the VIP root directory, create a makefile fragment called hello.makefile by right-clicking the VIP project and selecting New > File.

b. In the New File dialog, type hello.makefile in the File name field, then click Finish.

c. The new hello.makefile file opens in the editor. Add the following content: # Makefileall % :

cd dummy;\rm hello.o;\ccpentium hello.c -o hello.o

d. Save the file by pressing CTRL+S.

7. Right-click the VIP project name and select Build Project.

This builds the dummy/hello.c and creates a hello.o file that is later linked into the final vxWorks kernel image.

Adding Existing Sources to a VIP

It is easy to add existing sources to a VIP. When you build the VIP at a later time, the added sources are picked up automatically.

To add existing sources to a VIP, do one of the following:

■ Select the sources and drag and drop them into the VIP.

■ Select the sources and copy and paste them into the VIP.

Adjusting Link Order

When you add sources to a VIP, the object file is automatically added to the bottom of the link order. You can adjust the order of the files in the Build Properties dialog. The Content page of the Build Properties dialog allows you to manage the object files that are directly linked into the VxWorks kernel image as part of the VIP.

To adjust link order, do the following:

1. In the Project Explorer, right-click your project and select Properties > Build Properties.

2. Click the Content tab to bring that page to the foreground.

4 Configuring and Building VxWorks4.6 Importing and Migrating Existing VxWorks Image Projects

41

3. To adjust the link order of the object files, select a file, then click Up or Down. The file moves up or down in the list accordingly.

4.6 Importing and Migrating Existing VxWorks Image Projects

Importing and migrating projects achieve similar results, but how Workbench achieves these results is different. One method can change some project files.

The following rules apply:

■ Importing a project—Workbench copies an existing project from its original location into your current workspace without changing any files inside the project.

■ Migrating an older project—Workbench automatically updates its Workbench-specific files to be compatible with the current version of Workbench, and creates (or recreates) any project files that might have been added or whose format has changed since the version of Workbench that created the project.

Why Import or Migrate a Project?

There are several reasons why you might want to import or migrate a VIP into your current workspace:

■ You created a VIP in another workspace and want to incorporate it into your current workspace.

■ You created a VIP using a previous version of Workbench or VxWorks and now want to use it with the current version.

■ A member of your team wants to share a project with you, so that you will not have to recreate everything manually.

■ You created a VIP using vxprj on the command line and now you want to access it from Workbench.

For details on using vxprj to create projects, see the VxWorks Command-Line Tools User’s Guide: Working with Projects and Components and the vxprj API reference entry.

■ You want to test the functionality of a prebuilt VIP, such as the SMP-enabled VIP projects provided with the UP version of VxWorks.

Importing Projects

You can import a project from another location in the file system. Or, if a team member used Workbench to export a project to an archive file, you can import that project into your workspace. Both of these tasks are covered in this section.


42

To import a project from a file system, do the following:

1. Select File > Import > General > Existing Projects into Workspace. Click Next.

2. Click Browse next to Select root directory, then navigate to the project’s directory (which contains the project’s *.wpj file).

3. Select the project, and if it is appropriate for your task, select Copy projects into workspace. If you do not select this check box, you will create a reference to the project, rather than importing it into your current workspace.

4. Click Finish.

Your project appears in the Project Explorer.

To import a project that was exported by a team member, do the following:

1. Select File > Import > General > Existing Projects into Workspace. Click Next.

2. Click Browse next to Select archive file, then navigate to the location of the archive file and click Open.

3. Make sure the project is selected, then click Finish.

The imported project appears in the Project Explorer.

Migrating Projects

The method you use to migrate a project depends on the following conditions:

■ Whether the Makefile template was modified or not.

If you have not changed anything in the project’s .wrmakefile template, you can directly migrate the project.

If you made changes to the Makefile, you must manually migrate your changes to the new version of the file.

■ Whether the project is a prebuilt VxWorks image.

■ Whether the project was created using vxprj on the command line. If it was, you can migrate the project to Workbench using the same process.

Migrating Projects with Unmodified Makefile Templates

Use this task to directly migrate your project, if no changes were made to the .wrmakefile template for the project.

To migrate a project with unmodified Makefile templates, do the following:

1. If the project is part of the current workspace, remove it by right-clicking the project in the Project Explorer and selecting Delete.

2. In the dialog that appears, make sure Delete project contents on disk is not selected, then click OK. The project disappears from the Project Explorer, but the project files and sources remain in their original location.

3. Select File > Import > VxWorks 6.x > Existing VxWorks 6.x Image Project into Workspace. Only with this wizard are both the .wrmakefile and the

4 Configuring and Building VxWorks4.6 Importing and Migrating Existing VxWorks Image Projects

43

vxWorks.makefile templates (re)created so that they will work properly with the current build system.

4. Click Next, navigate to the project’s *.wpj file, click Open, and then click Finish.

Your project appears in the Project Explorer, updated to work with the new version of Workbench.

Migrating Projects with Modified Makefile Templates

Use this task to manually migrate your project, if changes were made to the .wrmakefile template for the project.

To migrate a project with modified Makefile templates, do the following:

1. Rename your customized .wrmakefile and vxWorks.makefile. This prevents against losing your customized changes when the new .wrmakefile and vxWorks.makefile are created, as they would overwrite the old files.

2. If the project is already part of the current workspace, remove it by right-clicking the project in the Project Explorer and selecting Delete.

3. In the dialog that appears, make sure Delete project contents on disk is not selected, then click OK. The project disappears from the Project Explorer, but the project files and sources remain in their original location.

4. Select File > Import > VxWorks 6.x > Existing VxWorks 6.x Image Project into Workspace. Only with this wizard are both the .wrmakefile and the vxWorks.makefile templates (re)created so that they will work properly with the current build system.

5. Click Next, navigate to the *.wpj file in the project, click Open, and then click Finish.

Your project appears in the Project Explorer, updated to work with the new version of Workbench.

6. Open the new version of the .wrmakefile and manually migrate the customizations from the renamed old file, and then save the file.

7. If your modifications affected VxWorks image-specific instructions, open the new version of the vxWorks.makefile, manually migrate the customizations from the renamed old file, and then save the file.

Migrating Prebuilt VxWorks Images

Use this task to experiment with one of the prebuilt SMP-enabled VIP projects provided with the UP version of VxWorks. VxWorks provides prebuilt projects so you can see the actual kernel configuration, and run your multi-threaded applications on them.

To migrate a prebuilt VxWorks image, do the following:

1. Select File > Import > VxWorks 6.x > Existing VxWorks 6.x Image Project into Workspace, and then click Next.

NOTE: These SMP-enabled VIP projects are provided in the UP product for evaluation purposes only. You can examine and modify the kernel configuration of these projects to learn how they work, but you cannot build them.


44

2. Click Browse, then navigate to the project’s *.wpj file under its directory in installDir/vxworks-6.x/target/proj. All SMP-enabled projects have directory names that end in _smp.

3. Click Open, then Finish.

The migrated project appears in the Project Explorer.

Migrating Projects from One Version of VxWorks to Another

To upgrade a VIP from a previous version of VxWorks, you must use the tcMigrate command-line migration utility. Command-line utilities are not covered in this guide, but you can find the information in the Workbench help.

For information on how to use tcMigrate, do the following:

1. Select > Help.

2. In the Help view Search field, enter tcMigrate and click Go.

4.7 Creating a VxWorks Source Build Project

You should use a VxWorks Source Build (VSB) project if you want to modify and recompile the VxWorks source code libraries, and then base a VxWorks kernel image on the modified libraries.

This section shows you how to create a VSB project. Instructions on how to modify and recompile VxWorks source code libraries follow in “Configuring Custom VxWorks Libraries” on page 46.

Before You Begin a VSB Project

Before you create a VxWorks Source Build (VSB) project, it is important that you understand your project requirements so you can calculate the changes that need to be made to the VxWorks libraries. The changes that are made to the VxWorks libraries carry down to the VIP project upon which the VSB is based.

You should be able to answer the following questions before you begin creating a VSB project:

■ Do you want to include support for networking, security, and other products shipped with your Platform?

■ Do you want to make your kernel image smaller by removing some unneeded VxWorks components? For example, if your deployed kernel image does not need to connect to Workbench tools, you can remove WDB components.

■ Do you have specific footprint or performance requirements?

■ Do you know the board support package or CPU type used by your target hardware?

4 Configuring and Building VxWorks4.7 Creating a VxWorks Source Build Project

45

■ Do you want to link to VxWorks sources? Creating a link to VxWorks sources from your project allows you to access the sources without adding them to your project. Through this link, you can also change and rebuild the sources in their original location, as necessary.

Deciding these issues before you create your project will save you time in the development phases of your project. However, it is possible to configure some VSB project settings after the project is created.

Creating a VSB Project

Use a VxWorks Source Build (VSB) project if you want to modify and recompile VxWorks source code libraries, and then base a VxWorks kernel image on the modified libraries.

To create a VSB project, do the following:


2. Select File > New > VxWorks Source Build (Kernel Library) Project. The Project screen of the wizard appears.

3. Enter a name for your project.

4. Specify a location by selecting one of the following options:

Create project in workspaceIf you want to create the project in the current workspace, leave this selected. This is a good idea if you do not have write permission to the location of your source files, or if you will create or import sources later.

Create project at external locationIf you want to create the project outside your workspace, select this then click Browse and navigate to a different location. This is good when you have write permission to the location of your sources (so you will not have to import them later), or if your project will be version-controlled and the sources are outside your workspace.

5. Click Next.

6. Select the BSP or CPU type your project will be based on by choosing one of the following options:

A board support packageSelect a BSP from the drop-down list that supports the target hardware of the VIP projects that will be based on this VSB.

To use a BSP provided by someone in your organization or a third party, click Browse and navigate to its location.

A CPU typeSelect the correct processor for your target hardware. This allows you to use the VSB project with multiple BSPs that are based on that processor and that support the specified configuration.


46

7. (Optional) To reference sources outside your project, select the Link in sources check box.

A link is created to sources outside your project. The sources remain in their original location, and are not copied into your project. The link allows you to browseVxWorks source code, APIs, and so on from your project. If necessary, you can also edit the VxWorks sources in their original location (outside of your project).

8. Click Next and accept the defaults or configure source code indexer settings.

Most projects work fine if you use the general indexer settings applied to all projects (which you can examine if you click Configure Workspace Settings), but if you need to customize your indexer settings, select Enable project specific settings and then adjust the indexer settings as appropriate.

For more information about selecting settings and configuring the indexer, press the help key for your host.

9. Click Finish to create your project.

Your new project appears in the Project Explorer.

Where to Go Next

To modify and recompile VxWorks source code libraries for your project, continue on to the next section, Configuring Custom VxWorks Libraries, p.46.

4.8 Configuring Custom VxWorks Libraries

This section shows you how to configure the components that are included in the VxWorks libraries that you will use with your project. This process is similar to configuring a VxWorks kernel image, except you make your selections using the Source Build Configuration editor (instead of Kernel Configuration editor).

Using the VxWorks Source Build Configuration Editor

The Source Build Configuration editor is an easy-to-use tool for customizing libraries. Before you begin configuring custom libraries, you should become familiar with the Source Build Configuration editor and its options.

Option Display Icons

The icon associated with an option indicates the status and type for that option. The following rules apply:

■ A multicolored cube indicates a family of options. Click the plus to view the options in that family.

■ A round green Y icon indicates that an option is (or will be) included in the library.

■ A round red N icon indicates that an option is not (or will no longer be) included in the image.

4 Configuring and Building VxWorks4.9 Example: Customizing VxWorks Libraries as a Base For a VIP

47

■ A round blue S icon indicates a string value. The same icon with an I indicates an integer value, and an H indicates a hexadecimal value.

■ A square white C icon indicates a comment on the parent item.

■ Two small circles overlaid on the icon indicates a mutually exclusive choice, selected from a drop-down list in the n/m/y column.

Option Tabs

The following tabs are arranged below the Option pane:

Help

Provides information about the option, such as additional functionality made available to a future VIP by selecting this option, default values, and so on.

Dependencies

Lists the options (if any) that this option depends on, as well as the other options (if any) that depend on this option. Also lists default values for this option.

Kconfig

Displays a tree of bundles and, at the leaf nodes of expanded bundles, individual components and their parameters.

To open the Source Build Configuration editor, do the following:

1. Double-click your VSB.

2. Double-click the Source Build Configuration node.

4.9 Example: Customizing VxWorks Libraries as a Base For a VIP

This example shows you how to identify your requirements, create and configure a source build project, and then base a custom VxWorks kernel image on that project.

This example contains the following tasks:

■ Task 1: Create a VSB project.

■ Task 2: Configure the VSB project.

■ Task 3: Build the VSB project.

■ Task 4: Create a VIP based on the VSB project.

■ Task 5: Build the VIP project.

NOTE: You must configure and build some products, such as Wind River Firewall and Wind River Network Stack, before you can include them in your image. For details, see the Wind River VxWorks Platforms User’s Guide.


48

Before You Begin

This example assumes the following conditions:

■ The resulting VxWorks kernel image will have a small footprint and good performance and debuggability. To achieve this, you must accept not having System Viewer or RTP support.

■ The target uses the MIPSI32R2 CPU.

■ You have an understanding of both the Wind River compiler and your target hardware.

■ You use the -Xalign-functions=32 option to compile the VxWorks libraries. You use this option because your memory controller is excellent at bursting in code and the footprint/performance trade-off is optimum for your system.

Task 1: Create a VSB project.

In this task, you create a VSB project based on the MIPSI32R2 CPU.

To create a VSB project, do the following:


2. Select File > New > VxWorks Source Build (Kernel Library) Project. The Project screen of the wizard appears.

3. In the Project name field, enter VSB_mipsI32R2.

4. Leave Create project in workspace selected, and click Next.

5. Because you know the specific CPU of your target system, select A CPU type, then from the drop-down menu select MIPSI32R2.

6. Click Next.

7. Click Finish. This accepts the default indexer settings, and your new VSB_mipsI32R2 project appears in the Project Explorer.

Task 2: Configure the VSB project.

In this task, you configure the VSB project you created in the previous task. This task disables support for selected functionality and compiler flags.

To configure a VSB project, do the following:

1. Double-click your project to expand it, then double-click the Source Build Configuration node to open it in the editor.

2. You want to disable System Viewer support, so right-click in the Option pane, then select Find. Type a letter or two of the option’s name into the Pattern field, using wildcard characters if necessary. In this case typing an S displays Enable System Viewer Instrumentation Support. Select it and click Find.

3. Right-click it in the Option pane and select Change value, then scroll to the right (if necessary) and from the drop-down list select n to deactivate System Viewer support.

4. In the same way, deactivate Enable Real-Time Process (RTP) Support.

4 Configuring and Building VxWorks4.9 Example: Customizing VxWorks Libraries as a Base For a VIP

49

5. At the top of the Option pane, click the plus next to CPU MIPSI32R2 Configuration Options to expand it.

6. To set advanced options such as compiler options, right-click Set advanced options and select Change value. From the drop-down list, select y.

7. Right-click optional compiler flags for MIPSI32R2_TOOL and select Change value. A blinking cursor appears in the Value column where you can type -Xalign-functions=32.

8. Save your configuration by pressing CTRL+S, or by closing the editor and selecting Yes when prompted to save.

Task 3: Build the VSB project.

In this task, you build the VSB project you created and configured in the previous tasks in this example.

Unlike a VIP, you can change the VSB’s build options or compiler flags in the future without needing to create a new project, but any changes you make will require that you recompile the project again.

To build your VSB project, do the following:

1. Right-click the project in the Project Explorer.

2. Select Build Project.

Since you are recompiling the VxWorks libraries, this can take awhile. If the project builds successfully, Build Finished in Project ‘VSB_mipsI32R2’ appears in the Build Console.

When you have successfully built a source build project, it appears as an option in the VIP’s Project drop-down list.

Task 4: Create a VIP based on the VSB project.

In this task, you create a VIP that is based on the VSB project you created in the previous tasks in this example.

To create a VIP based on a VSB project, do the following:


2. Select File > New > VxWorks Image Project. The Project screen of the wizard appears.

3. In the Project name field, type VIP_VSB_mipsI32R2.

4. Leave Create project in workspace selected, then click Next.

5. On the Project Setup screen, click the Based on drop-down list and select a source build project.

6. Select VSB_mipsI32R2 from the Project drop-down list.

If you want to use a VSB built by a team member, it would not appear in the Project list because it was not built in the same workspace. To use it, click Browse and navigate to it.


50

7. The settings in the BSP and Tool chain fields change to reflect the settings inherited from the VSB project you select. If there are variants available for the BSP or tool chain, you may choose one of them from the drop-down list.

To configure the rest of the VIP project screens, see 4.3 Creating a Custom VxWorks Image, p.32.

8. Click Finish.

Your new VIP_VSB_mipsI32R2 project appears in the Project Explorer.

Task 5: Build the VIP project.

In this task, you build the VIP project you created in the previous tasks in this example.

To build a VIP project, do the following:


2. Select Build Project. Workbench uses your custom VxWorks libraries in place of the default libraries.

If the project builds successfully, Build Finished in Project ‘VIP_VSB_mipsI32R2’ appears in the Build Console. This means you have a VxWorks kernel image that is optimized to your requirements.

3. Verify the build by double-clicking the project to expand it, and hen double-clicking the Kernel Configuration node. All of the options you disabled in the VSB should be disabled or unavailable in your VIP.

4.10 Rebasing VSB and VIP Projects

You can change the configuration of an existing VSB project without having to recreate the project. You can also base a VIP on a different VSB project, as long as their configuration settings match.

This section covers the following tasks:

■ Basing a VSB Project on a Different BSP or CPU

■ Basing a VIP on a Different VSB Project

Basing a VSB Project on a Different BSP or CPU

In this task, you change the BSP or CPU that your VSB is based on. This can be useful when requirements change for a project.

To base a VSB on a different BSP or CPU, do the following:

1. Right-click your VSB project in the Project Explorer, select Properties, then select Source Build Info.

4 Configuring and Building VxWorks4.11 Loading the VxWorks Image onto the Target

51

In addition to the project name, the Base configuration section displays the CPU or BSP that you based your project on. It also displays the BSP or BSPs supported by that configuration.

2. To base your project on a different CPU or BSP, click Change and make a selection from the dialog.

If you originally based your project on a CPU, you can change to a BSP (and the opposite is also true). However, you cannot have entries in both fields, so selecting one clears the entry in the other field.

3. Click OK.

NOTE: Basing your VSB project on a new CPU or BSP may invalidate any VIPs that are based on it. To validate VIPs after changing a VSB, continue to Basing a VIP on a Different VSB Project, p.51.

Basing a VIP on a Different VSB Project

You can retarget an existing VIP to use a new VSB, as long as their CPU or BSP types match. In this task, you to validate VIPs that are based on a VSB that has changed. This procedure is useful when requirements change for a project.

To base a VIP on a different VSB project, do the following:

1. Right-click the VIP, select Properties, then select VxWorks Info.

2. To the right of Kernel libraries, click Change. The Select Source Build Configuration dialog opens.

3. Navigate to the directory that contains the new VSB project’s vsb.config file, select the file, and click Open.

4. In the bottom right corner of the VxWorks Info screen, click Validate.

If the CPU, BSP, and other configuration settings match, the VIP will be retargeted to the new VSB project. However, if the configuration settings do not match (for example, if you are trying to base a VIP that requires SMP to a VSB that was built without SMP), an error appears telling you what the problem is.

5. When you have successfully retargeted your VIP to a new VSB project, you must rebuild the VIP and its DKM subprojects.

4.11 Loading the VxWorks Image onto the Target

Once you have a VxWorks kernel image stored on your host machine, you can use a boot loader to load it onto a hardware target.

A boot loader is useful during development, if you need to repeatedly modify and rebuild your VxWorks image. Boot loaders can also useful on production systems, where you can store both the boot loader and operating system image on a disk, though they are not required for standalone VxWorks systems stored in ROM.


52

For more information about boot loaders, see the VxWorks Kernel Programmer’s Guide: Boot Loader and the VxWorks BSP References entry for your BSP.

Creating a Default Boot Loader

This section covers the following methods for creating a bootloader for your kernel image:

■ Creating a VxWorks Boot Loader/BSP Project

■ Creating a VxWorks Image Project Using the PROFILE_BOOTAPP Configuration Profile

The VxWorks Boot Loader/BSP project type uses a special build of a basic network stack (that includes support for the IPv4 protocol, and the RSH, FTP, and TFTP file download protocols) to keep the kernel image size small. If you have NVRAM space problems, a VxWorks Boot Loader/BSP project will generate a smaller image so it can fit into flash memory.

Creating a VxWorks Boot Loader/BSP Project

In this task, you create a VxWorks Boot Loader/BSP project.

Boot loader images come in the following styles: Compressed, Uncompressed, (ROM-)Resident, and (ROM-)Resident At High Address. These are functionally the same but have different memory requirements and execution times. After the project has been created, you can change the Style by right-clicking the project and selecting Set Active Build Spec.

To create a VxWorks Boot Loader/BSP project, do the following:


2. Select File > New > VxWorks Boot Loader/BSP Project.

3. In the new project wizard, type a name for your project.

4. Specify where to create your project by selecting one of the following options, then click Next:


Create project at external locationIf you want to create the project outside your workspace, select this then click Browse and navigate to a different location. This is good when you have write permission to the location of your sources (so you will not have to import them later), or if your project will be version-controlled and the sources are outside your workspace.

5. Choose the BSP that you want to base your project on. Workbench displays all your installed BSPs in the drop-down list.

6. Select the tool chain you want to use. The available options match the BSP you selected.


53

7. Select The Style and Format of the Boot loader/BSP image.

For format, choose from ELF, Bin, or Hex.

The VxWorks Kernel Programmer’s Guide: Boot Loader chapter provides detailed information on Style and Format. BSP documentation specifies which types are available for a specific target.

8. Click Finish. The new project appears in the Project Explorer.

Creating a VxWorks Image Project Using the PROFILE_BOOTAPP Configuration Profile

Creating a VxWorks image project with the PROFILE_BOOTAPP configuration profile uses a build of the network stack that provides a larger set of networking facilities, such as IPv6 and DHCP support.

To create a VIP with the PROFILE_BOOTAPP profile, see 4.3 Creating a Custom VxWorks Image, p.32.

Creating a Customized Boot Loader

You can customize various features of the boot loader in the following ways:

■ Adding or removing VxWorks components, as described in 4.4 Configuring VxWorks, p.35. For example, you can exclude networking components if you are not going to use the network to boot your system.

■ Selecting non-default drivers. If the boot loader’s default drivers are not appropriate for your target, you need to change the driver selection for the boot loader. For more information, see Selecting Boot Loader Drivers, p.55.

■ Setting boot parameters that are appropriate for your development environment, or for deployed systems. Boot parameters specify the IP addresses of the host and target systems, FTP user names and passwords, the location of the VxWorks image to boot, and so on. For information about boot parameters, see VxWorks Kernel Programmer’s Guide: Boot Loader.

In this task, you navigate to the config.h file and change the default configuration of a boot loader.

To change the default configuration of a boot loader, do the following:

1. Navigate to the installDir/vxworks-6.x/target/config/bsp/config.h file in the Project Explorer.

2. Click the config.h file to open it in an editor.

3. Modify the configuration as necessary.

Boot Loader Build Targets

VIP projects (except those configured to run on the VxWorks simulator) have three Workbench-managed build targets whose name has the following form:


54

vxWorks.[format] [type]

Where format can be empty (the default ELF image), .bin (binary output), or .hex (Motorola S-Record output).

And type can be empty (the default RAM-based image), _rom, _romCompress, or _romResident. Type is controlled by the build spec you choose.

To switch build specs, do the following:


2. Choose Build Options > Set Active Build Spec.

To create new build targets with user-defined make rules, do the following:


2. Choose New > Build Target.

Redefining the Link Address for a PROFILE_BOOTAPP Project

When you create a standard VIP using the PROFILE_BOOTAPP configuration profile, you must change the link address used for the project to specify the correct address for a boot loader.

The link address for a VxWorks image of any type (vxWorks, vxWorks_rom, and so on) is RAM_LOW_ADRS, and the link address for a boot loader image of any type is RAM_HIGH_ADRS.

A VIP, however, uses RAM_LOW_ADRS as the link address regardless of the type of image you are creating. That is, it uses RAM_LOW_ADRS as the link address even if you are creating a boot loader image with the PROFILE_BOOTAPP configuration profile.

Therefore you must substitute the BSP’s value for RAM_LOW_ADRS with the BSP’s value for RAM_HIGH_ADRS when you create a boot loader based on PROFILE_BOOTAPP. The following task shows you how to do this.

To change the link address for a target, do the following:

1. In the Project Explorer, click the config.h file to open it in an editor.

2. If the RAM_LOW_ADRS and RAM_HIGH_ADRS link addresses are defined as macros in installDir/vxworks-6.x/target/config/bsp/config.h, comment out those definitions.

You must do so because definitions in config.h override definitions in CDF files.

3. If they are not already there, add the link address parameters to the BSP’s CDF file. This file is usually 20bsp.cdf, but for some may be 10bsp.cdf.

4. Set RAM_LOW_ADRS to the config.h value of RAM_HIGH_ADRS, using the values from config.h if they were not provided in a CDF file.

5. Set RAM_HIGH_ADRS to (RAM_LOW_ADRS + maxBootAppImageSize).


55

Be careful. If link address definitions are not made in the correct file, the boot loader will not be configured properly, it will not load to the correct place in RAM, and the boot process will fail.

The following example of CDF parameter definitions uses conditional statements to set the link addresses:

Parameter RAM_HIGH_ADRS {NAME Bootrom Copy region DEFAULT (INCLUDE_BOOT_RAM_IMAGE)::(0x01E00000) \

(INCLUDE_BOOT_APP)::(0x02000000) \(0x01C00000)

}

Parameter RAM_LOW_ADRS {NAME Runtime kernel load addressDEFAULT (INCLUDE_BOOT_RAM_IMAGE)::(0x01C00000) \

(INCLUDE_BOOT_APP)::(0x01E00000) \(0x00100000)

}

For more information about working with CDF files, see VxWorks Kernel Programmer’s Guide: Kernel Customization.

Selecting Boot Loader Drivers

If a boot loader requires a (supported) driver that is not provided as the default, you must edit installDir/vxworks-6.x/target/config/bsp/config.h to define the macro for the correct driver, and undefine the macro for the one you do not need.

For More Information

■ For information about the VxBus drivers available for your system (and the macro names to use in config.h), see installDir/target/src/hwif/util/cmdLineBuild.c.

■ For information about non-VxBus drivers supported for a given BSP, see the VxWorks BSP References entry for the BSP. The macro names for VxBus drivers do not have the leading INCLUDE_ element (for example, DRV_SIO_NS16550), whereas the names for non-VxBus drivers do (for example, INCLUDE_ELT_3C509_END).

■ For more information about boot loaders, see the VxWorks Kernel Programmer’s Guide: Boot Loader and the VxWorks BSP References entry for your BSP.

NOTE: Changes to config.h must be made before you create a VxWorks Image project. Any changes made to config.h after a VIP is created are not picked up by the project.


56

57

5Working with Board Support

Packages

5.1 Introduction 57

5.2 Creating an Experimental Default BSP 58

5.3 Example: Customizing a BSP 59

5.1 Introduction

A Board Support Package (BSP) consists primarily of the hardware-specific VxWorks 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.

Workbench provides a VxWorks Boot Loader/BSP project that makes it easy to copy the sources for one of the existing BSPs into your project, then customize them without changing the VxWorks install tree. Workbench displays a list of BSPs that were shipped with your VxWorks Platform product. You can start with any default BSP, and then modify and build it to meet your project needs.

In this chapter, you learn how to do the following:

■ Create a project and pull in the sources for a selected BSP.

■ Customize a BSP for use as the basis for a VIP.

NOTE: This chapter does not, discuss what information should be included in a BSP or how to write a BSP from scratch. For more information about those topics, see the VxWorks BSP Developer’s Guide.


58

5.2 Creating an Experimental Default BSP

The easiest way to begin working on your own BSP is to create a project and copy the BSP sources. In this task, you create a default BSP.

To create a default BSP, do the following:


2. Select File > New > VxWorks Boot Loader/BSP Project, and then type a name for your project.

3. Specify where you want to create your project by selecting one of the following options, and then click Next:

Create project in workspaceTo create the project in the current workspace, leave this selected. This is a good idea if you do not have write permission to the location of your source files, or if you will create or import sources later.

Create project at external locationTo create the project outside your workspace, select this then click Browse and navigate to a different location. This is good when you have write permission to the location of your sources (so you will not have to import them later), or if your project will be version-controlled and the sources are outside your workspace.

4. Choose the BSP that you want to work with. Workbench displays all your installed BSPs in the drop-down list.

5. Select the tool chain you want to use. The available options change to match the BSP you selected.

6. Select Copy files to project to create a standalone copy of the BSP directory. This allows you to modify the sources without changing the originals in your VxWorks installation tree.


Using the Simulator BSP

You can base your VxWorks Image project on the VxWorks simulator BSP to develop a custom BSP and application code for your product in parallel. You may also benefit from this method if your target hardware is not yet ready. The simulator BSP contains default VxWorks functionality sufficient for supporting most applications.

Using a Wind River BSP

If your BSP was installed with Workbench 3.2, you can create a VxWorks Image project from it directly. For more information, see 4.4 Configuring VxWorks, p.35.

5 Working with Board Support Packages5.3 Example: Customizing a BSP

59

Using a Custom BSP for Custom Hardware

This section covers the following topics:

■ Creating a BSP

■ Using a Pre-Existing BSP with the Workbench Project Facility

■ Using a BSP Outside of Workbench

Creating a BSP

To create your own BSP, see the VxWorks BSP Developer’s Guide and 5.2 Creating an Experimental Default BSP, p.58.

To develop the BSP and the application code in parallel, you may want to begin application development on the VxWorks Simulator. For more information, see 7.3 Creating a VxWorks Simulator Connection, p.95.

Using a Pre-Existing BSP with the Workbench Project Facility

If you have a custom BSP that is Tornado 2.x compliant, see the VxWorks Migration Guide for information on migrating to Workbench.

If you have a custom, non-compliant BSP, you need to modify it to conform to the guidelines outlined in the VxWorks BSP Developer’s Guide to be able to use it with the Workbench project facility. Once you have modified your custom, non-compliant BSP to meet these specifications, verify that it builds properly before creating a project for it.

Using a BSP Outside of Workbench

You may use a non-compliant BSP by managing its configuration manually. For information on using manual methods, see the VxWorks Command-Line Tools User’s Guide.

You can create downloadable projects to hold your application code and download them to a target booted with a non-compliant BSP.

5.3 Example: Customizing a BSP

Once you create a default BSP, you can customize its sources. In turn, you can base a VIP on your customized BSP. This example shows you how to customize a BSP using the following methods:

■ Creating a Custom BSP

■ Basing a VxWorks Image Project on a Customized BSP

NOTE: If you do not modify your BSP to make it Workbench compliant, Workbench will not be able to provide project-based support for customizing, configuring, or building it.


60

Creating a Custom BSP

In this example, you modify an existing project to increase the size of ROM space assigned in config.h, create a new VxWorks image project based on your modified BSP, and view the kernel configuration to verify that the change was reflected in the VIP.

This example includes the following tasks:

■ Task 1: Check that config.h is not read-only.

■ Task 2: Modify a value in config.h.

■ Task 3: Build your project.

Before You Begin

Before you begin this example, you must have successfully created a default VxWorks Boot Loader/BSP project containing BSP sources, as described in Creating an Experimental Default BSP, p.58.

Task 1: Check that config.h is not read-only.

In this task, you verify that the conifg.h file is writable. You must have write permissions for the config.h file to successfully complete this example.

To verify that the config.h file is not read-only, do the following:

1. In the Project Explorer, double-click the BSP project to expand it, then double-click the BSP directory to view its contents.

2. Right-click config.h and select Properties.

3. In the Properties dialog make sure the Read only check box is not selected; some BSPs in the Platform are shipped read-only. If the box is checked, select it to clear the check mark.

4. Click OK.

Task 2: Modify a value in config.h.

You can open the config.h file in an editor and customize values.

To modify a value in the config.h file, do the following:

1. Double-click config.h to open it for editing.

2. Search for the definition of ROM_SIZE by pressing CTRL+F to open the Find/Replace dialog.

3. In the Find text field, type ROM_SIZE, then click Find.

4. Increase the value of ROM_SIZE, for example from 0x00200000 to 0x00300000 (or as appropriate for your needs).

5. Close config.h and click Yes when you are prompted to save the changes.

5 Working with Board Support Packages5.3 Example: Customizing a BSP

61

Task 3: Build your project.

To integrate the changes into your project, you must perform a build.

To build the BSP project, do the following:

■ In the Project Explorer, right-click the project and select Build Project.

Basing a VxWorks Image Project on a Customized BSP

Once you have customized a BSP project, you can use it as the basis for a VxWorks Image project.


■ Task 1: Start a new VxWorks Image project.

■ Task 2: Base a new VIP on an existing BSP project.

■ Task 3: Verify that the modified ROM_SIZE appears in the VxWorks image.

Before You Begin

Before starting this procedure, you should have successfully completed the tasks outlined in Creating a Custom BSP, p.60.

Task 1: Start a new VxWorks Image project.

This task shows you how to start a new VxWorks Image project (VIP), specifying a name and location for the new project.

To start a new VxWorks Image project, do the following:


2. Select File > New > VxWorks Image Project, and then type a name for your project.

3. For this example, leave Create project in workspace selected.

4. Click Next.

Task 2: Base a new VIP on an existing BSP project.

This task shows you how to base your new VIP on a custom BSP project.

To base a new VIP on an existing BSP, do the following.

1. From the Based on drop-down list, select An existing project.

2. From the Project drop-down list, select the custom BSP project you developed in Creating a Custom BSP, p.60.

This list contains suitable projects in your workspace. If you wanted to base your VIP on a project outside the workspace, you could do that by clicking Browse and navigating to it.



62

Task 3: Verify that the modified ROM_SIZE appears in the VxWorks image.

In this task, you verify the customizations you made to the BSP project were carried over to the new VxWorks image.

To verify BSP project customizations in the VxWorks image, do the following:

1. Double-click the Kernel Configuration node to open the Kernel Configuration Editor.

2. To look for ROM_SIZE, right-click in the Component Configuration pane, then select Find.

3. In the Pattern field, start typing ROM_SIZE. By the time you have typed ROM, the list of matches will have narrowed so you can see ROM_SIZE.

4. Double-click it in the list to find it in the Component Configuration pane.

5. In the value column, you should see the modified value (0x00300000 instead of 0x00200000, or as appropriate for the change you made).

6. Close the editor when you are finished.

Where to Go Next

■ For additional information about working with BSPs, see the VxWorks BSP Developer’s Guide.

■ For information about the BSP validation test suite, including how to configure and run it to validate that your BSP is working properly, see the VxWorks BSP Validation Test Suite User’s Guide.

63

PART IV

Developing and DebuggingApplications

6 Building Applications and Libraries ....................................... 65

7 Connecting to VxWorks Targets ............................................. 93

8 Running and Debugging VxWorks Applications ................... 107


64

65

6Building Applications and Libraries

6.1 Introduction 65

6.2 Deciding on an Application Type 66

6.3 Creating a Project For Your Application 67

6.4 Example: Discussion of PowerPC Build Spec Variants 69

6.5 Example: Creating and Passing a Build Target 70

6.6 Reconfiguring Your Project Later in the Development Cycle 73

6.7 Example: Adding IPNet Support to a DKM 78

6.8 Using RTP Overlapped Virtual Memory 80

6.9 Creating Statically Linked Libraries 80

6.10 Creating Shared Libraries 81

6.11 Creating Plug-Ins 82

6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins 82

6.13 Running Applications on a Hardware Target 91

6.1 Introduction

The workflow for creating applications in Workbench is relatively consistent, whether you are creating applications that will run in kernel space or user space.

This chapter describes how to use Workbench to manage and build your applications, as well as the static or shared libraries or plug-ins that you can develop to support them. It also introduces the preconfigured VxWorks-specific projects that can help you organize your code.

This chapter does not, cover how to write code for applications or libraries, nor does it discuss the pros and cons of running your application in kernel space as compared with user space. For more information about those topics, see the VxWorks Kernel Programmer’s Guide and the VxWorks Application Programmer’s Guide.


66

For details about the editor, code assist and colorization, parameter hinting, and other Workbench features that make coding easier, see the Wind River Workbench User’s Guide, or open a Workbench feature and press the help key for your host.

Process Overview

Creating applications in Workbench follows this basic process:

1. Decide what type of application you need.

2. From the Wind River Workbench Project wizard, select the build type that will provide the necessary structure and build support for your project.

3. Write or import source files.

4. As necessary, write or import libraries to support your application.

5. Build and debug your projects.

6. Decide on a deployment method.

6.2 Deciding on an Application Type

There are two basic application types you can develop in Workbench: kernel applications and real-time process applications. Each type has specific considerations, as discussed in the following sections.

Writing Kernel Applications

Kernel applications run in kernel mode, with full access to the hardware in the system. If you are writing an application that runs in kernel space, a lot depends on the stage of the development you are in.

■ In the early stage of development, you will want a kernel module that can be downloaded and dynamically linked to the operating system, as described in 8.4 Running Your Applications, p.111. This allows you to build, run, and debug applications without having to make any changes to the operating system itself.

■ For deployed systems, you will want a kernel module that is statically linked to the operating system, making it part of the VxWorks image itself. For details, see 9.3 Adding Kernel Applications to a VxWorks Image, p.123. VxWorks can be configured to start kernel applications automatically at boot time.

In either case, you will create a VxWorks Downloadable Kernel Module (DKM) project for your application. DKM projects help you manage and build modules that execute in the kernel space. You can build each module separately, then run and debug them on a target running VxWorks—loading, unloading, and reloading on the fly.

6 Building Applications and Libraries6.3 Creating a Project For Your Application

67

You also use DKM projects to create library subprojects that are statically linked into other projects at build time. For example, using the same code in multiple downloadable or relinkable images, such as in different VIPs.

Writing Real-Time Process Applications

Real-time process (RTP) applications are developed as VxWorks executables that will execute in user space and will have a well-defined start address. When the executable is loaded, the system allocates memory address space for it, execution begins at the known start address, and all tasks in the process run within the same memory-protected address space. When the application terminates, all the resources associated with it are freed back to the system.

If you are writing an application that runs in user space, a lot depends on the stage of the development you are in.

■ In the early stage of development, you will want to store RTP applications on the host system and run them interactively. See 8.4 Running Your Applications, p.111.

■ For deployed systems, you will want to store the RTP applications in a target file system such as ROMFS. For details, see 9.4 Example: Bundling a VxWorks Image, p.125.

In either case, you will create a VxWorks Real-Time Process project for your application. Also known as RTP projects, they provide a protected, process-based, user-mode environment for developing applications.

In addition to using RTP projects to create real-time process applications, you can also use them to create library subprojects that are statically linked into other projects at build time.

6.3 Creating a Project For Your Application

The process for creating Downloadable Kernel Module (DKM) and Real-time Process (RTP) projects is essentially the same. For more information about any of the screens, press the help key for your host or click the Help question mark icon (?) in the lower left corner of the wizard.

In this task, you create a project that will be the basis for an application.

NOTE: VxWorks kernel applications must be built for either a uniprocessor (UP) or symmetric multiprocessor (SMP) configuration of VxWorks. They are not binary compatible with both, however the loader does not generate an error if a kernel module is incompatible with the system onto which it is loaded.

To create a project for your application, do the following:



68

2. Select Wind River Workbench Project from the Workbench toolbar. The New Wind River Workbench Project wizard appears.

3. Select Wind River VxWorks 6.x from the drop-down menu, and click Next.

4. On the Build Type screen, select the type of project you want from the drop-down list. Each build type displays a description to help you choose the one that is right for your task. Click Next.

5. On the Project screen, and type a name for your project and specify the location by selecting one of the following options:


Create project at external locationIf you want to create the project outside your workspace, select this then click Browse and navigate to a different location.

This is good when you have write permission to the location of your sources (so you will not have to import them later), or if your project will be version-controlled and the sources are outside your workspace, or if you will be sharing the project with your team and several developers need access to it (in that case, it could be created in a shared directory).

Create project in workspace with content at external locationIf you do not want to mix project files with your sources, or copy sources into your workspace, select this option to keep each in its place. Click Browse, then navigate to your source location.

6. Click Finish. The project appears in the Project Explorer. For information about the new files in your project, see A. What Are All These Project Files For?

Adding Application Code to a Project

After you create your project, you have the infrastructure for a kernel module or a real-time process, but often no actual application code. You can add application code to a project in the following ways:

■ Import resources

■ Add new files

■ Write source code

Importing Resources

In this task, you import existing resources into your project, by copying the resource files into your project.

To import a resource, do the following:

1. Select File > Import.

2. Select an import source and specify related options. For details on the available options, open the Import dialog and press the Help key for your host.

3. When you have completed your selections, click Finish.

6 Building Applications and Libraries6.4 Example: Discussion of PowerPC Build Spec Variants

69

Adding a New File

In this task, you add a new file to an application project to create source files.

To add a new file to a project, do the following:

1. Select the project and then select File > New > File.

2. Enter or select the parent folder, and supply a File name. The file name must be unique.

3. (Optional) For a description of the available Advanced options, press the help key for your host, then select New File Wizard. Pay particular attention to the Linked resources link under Related concepts.

Writing Source Code

Writing source code is beyond the scope of this guide. For more information, see the following resources:

■ For more information about writing real-time processes, for example that RTP applications require a main( ) function, see VxWorks Application Programmer’s Guide: RTP Applications.

■ For more information about writing source code for kernel applications, see VxWorks Kernel Programmer’s Guide: Kernel Applications.

6.4 Example: Discussion of PowerPC Build Spec Variants

Consider the following before choosing a build spec for a kernel module project:

■ PowerPC, VxWorks kernel source (everything under installDir/vxworks-6.x/target/src) is always built with CPU=PPC32 and TOOL=diab, sfdiab, or e500v2diab, depending on the floating point model being used.

■ Other PowerPC build spec variants are used when building VxWorks Boot Loader/BSP and VxWorks Image projects, from code found under installDir/vxworks-6.x/target/config.

■ For more information about PowerPC and other supported architectures, see the VxWorks Architecture Supplement available in the Workbench help system.

In particular, see the Defining the CPU and TOOL Make Variables section in Appendix A, Building Applications, for a table of CPU/Tool values and a discussion of special considerations for PowerPC processors.


70

6.5 Example: Creating and Passing a Build Target

This example shows you how to create a kernel module project that passes its build output to a VxWorks image project.


■ Task 1: Create a VIP.

■ Task 2: Create a DKM project.

■ Task 3: Create a second DKM project from which to import a source file.

■ Task 4: Create a new source file in hello_VxWorks.

■ Task 5: Add the source file to your build target.

■ Task 6: Add the DKM project as a subproject of the VIP project.

■ Task 7: Build the VIPsim project.

■ Task 8: Find the location of the kernel image file.

■ Task 9: Create a custom VxWorks simulator target connection.

■ Task 10: Test whether the Hello-Sort build target was passed to VIPsim.

Task 1: Create a VIP.

In this task you create the VIPsim project.

To create a VIP project, do the following:


2. Select File > New > VxWorks Image Project.

3. In the Project name field, type VIPsim.

4. Leave Create project in workspace selected, then click Next.

5. Leave the VxWorks simulator BSP and default toolchain selected, then click Finish.

The VIPsim project appears in the Project Explorer.

Task 2: Create a DKM project.

In this task, you create a DKM project using specific options.

To create a DKM project, do the following:

1. From the Advanced Device Development perspective, select File > New > VxWorks Downloadable Kernel Module Project.

2. In the Project name field, type DKM_pass_tgt.

3. Leave Create project in workspace selected, then click Next until you get to the Build Target screen.

4. In the Build target name field, highlight DKM_pass_tgt (the default name) then type Hello-Sort. As you type, the Binary output name is also changed.

5. Change the Build tool from Linker to Partial Image Linker.

6 Building Applications and Libraries6.5 Example: Creating and Passing a Build Target

71

6. Select Pass build target to next level.

This is important when the DKM is a subproject of a VIP, but is not necessary when the DKM is a subproject of any other type of project.

7. Click Finish.

The DKM_pass_tgt project appears in the Project Explorer.

Task 3: Create a second DKM project from which to import a source file.

In this task, you create a second DKM project that will contain the source file you then import into another project.

To create a second DKM project to hold a source file, do the following:

1. From the Advanced Device Development perspective, select File > New > VxWorks Downloadable Kernel Module Project.

2. In the Project name field, type hello_VxWorks, then click Finish.

The hello_VxWorks project appears in the Project Explorer.

Task 4: Create a new source file in hello_VxWorks.

In this task, you create a file that you will later import into another project. You create the file hello.c in the hello_VxWorks DKM project.

To create a new source file in a project, do the following:

1. Select File > New > File.

2. In the New File dialog, select the hello_VxWorks parent folder, then in the File name field type hello.c.

3. In the Use template field, select Wind River C source template from the drop-down list, then click Finish.

4. The hello.c file opens in the editor. Add the following code below the comment lines:

#include <stdio.h>

int dmain(void){

printf("Hello World!\n");return 0;

}

5. Press CTRL+S to save the file.

Task 5: Add the source file to your build target.

In this task, you import the source file you just created into the Hello-Sort build target, so it is built with the DKM_pass_tgt project.

To add a source file to your build target, do the following:

1. If Hello-Sort is not already visible, double-click DKM_pass_tgt and then double-click Build Targets.

2. Right-click Hello-Sort, then select Edit Content. The Content Definition dialog opens.


72

3. By default, just the project you are working with appears in the Workspace pane. To see hello_VxWorks, click Show all projects.

4. Click the plus next to hello_VxWorks to open it (you cannot double-click it in this case, since that adds the entire project to your build target).

5. Select hello.c, then click Add. The file appears in the Content pane.

6. Click Finish. The file appears under Hello-Sort in the DKM_pass_tgt project.

Task 6: Add the DKM project as a subproject of the VIP project.

In this task, you add a project reference to make the DKM a subproject of the VIP. This ensures that DKM_pass_tgt is built when VIPsim is built.

To add a DKM project as a subproject, do the following:

1. Right-click DKM_pass_tgt and select Project References > Add as Project Reference.

2. Select VIPsim from the list of possible superprojects, then click OK. DMK_pass_tgt seems to disappear from the project list, but if you expand VIPsim you will see it there.

Task 7: Build the VIPsim project.

In this task, you build the VIP project.

To build a VIP project, do the following:

■ Right-click the VIPsim project and select Build Project.

With the project reference in place, building VIPsim now automatically builds the Hello-Sort build target and passes the output up to VIPsim.

Task 8: Find the location of the kernel image file.

In this task, you find the location of the newly built kernel image file.

To find the kernel image file, do the following:

1. Under vxWorks (default), right-click vxWorks and select Properties.

2. Double-click the path shown as Location, then right-click it and select Copy.

3. Click OK to close the dialog.

Task 9: Create a custom VxWorks simulator target connection.

In this task, you create a VxWorks simulator connection using the vxWorks kernel image file you just created.

To create a VxWorks simulator connection, do the following:

1. In the Remote Systems view, click Define a connection on the left of the toolbar.

2. Select Wind River VxWorks 6.x Simulator Connection, then click Next.

3. Select Custom simulator, then right-click in the text field and select Paste to paste in the location of the vxWorks kernel image file. You do not need to adjust any other settings for this example, so click Finish.

6 Building Applications and Libraries6.6 Reconfiguring Your Project Later in the Development Cycle

73

A new VxWorks simulator window opens, running the vxWorks kernel image file from VIPsim.

Task 10: Test whether the Hello-Sort build target was passed to VIPsim.

In this task, you verify that the Hello-Sort build target successfully passed to the VIPsim project.

To verify that a build target successfully passed to a project, do the following:

1. Type dmain at the VxWorks simulator prompt.

2. If the build output from the subproject was correctly passed to its superproject, you should see Hello World! in the VxWorks simulator window.

Linking a Kernel Module to a VxWorks Image

In this task, you link a kernel module with a kernel and turn it into a bootable application that starts when the target is booted.

To link a kernel module to a VxWorks image, do the following:

1. Create a VxWorks Image project, as described in Configuring and Building VxWorks, p.31.

2. Configure and build the VIP, as described in Adding Kernel Applications to a VxWorks Image, p.123.

6.6 Reconfiguring Your Project Later in the Development Cycle

You can adjust the configuration options, as the needs of your application change during the course of the development cycle. For example, you might want to change the build tool or build specs so you can build the application for another target architecture.

You can perform the following tasks to reconfigure your project:

■ Task 1: Access build properties.

■ Task 2: Select build support and build spec options.

■ Task 3: Select build tools.

■ Task 4: Define build macros.

■ Task 5: Specify build paths.

■ Task 6: Specify libraries.

NOTE: All library paths should be specified on the Libraries page of the Build Properties dialog to avoid introducing errors. This page automatically checks for and corrects backward slashes (\) that can result in errors.


74

Task 1: Access build properties.

In this task, you open the Build Properties dialog and display the existing build settings for your project.

To access build properties for your project, do the following:

1. Right-click the project in the Project Explorer and select Properties.

2. In the Properties dialog, select Build Properties. You will see several tabs.

For general details about build properties, press the help key for your host.

3. Continue with the following tasks, and specify options as needed.

Task 2: Select build support and build spec options.

In this task, you set options to configure the build command and build specs for your project.

The build specs pane lists all the build specs that are available to Workbench, filtered according to project type. For example, RTP projects do not provide build specs for any PPC variants other than PPC32, because RTPs run only in the user space. The build specs for your project type are selected and therefore enabled by default.

If you enable more than one build spec, the one in the Default build spec field is used for most builds. It is the one that is saved in the project file, meaning that if you share your project with your team, and they import it into their workspace, they automatically use the same build spec that you did. The default build spec is also used to set the initial active build spec for the project.

The Active build spec setting is not stored in the project, so each team member can temporarily change it without needing to check out any project files. A change to the Active build spec field is propagated to the appropriate fields on the Build Tools, Build Macros, and Build Paths tabs.

To specify build support and specs options, do the following:

1. Select a build support type.

Both kernel module and process projects automatically use Workbench build support, so it is enabled by default.

If you are creating a project just so you can browse symbol information and you are not interested in building it, click Disabled. Click Managed build to re-enable build support.

2. Update the build command, if necessary.

Edit the build command to add or change any arguments required by your application. For example, if you wanted to take advantage of the parallel jobs functionality of make to increase build performance, you would add the -j option after the make command.

3. Enable or disable build specs, in the following ways.

■ To show only the build specs for your project, click Disable All and then select the check box next to the build spec(s) you want to enable. Highlighting the name of the build spec is not sufficient; there must be a check in the check box to enable the build spec.


75

■ To import a build spec that you defined in another project, or reset the project’s build properties to their default settings, click Import and select the source of the build settings.

■ To use an existing build spec as the basis for creating your own, click Copy, type in a name for your build spec, then click OK. The new build spec appears at the bottom of the list.

4. Select default and active build specs, considering the following options:

■ You can select a different Active build spec for a particular build. If you enabled one build spec for this project, it appears in both the Default build spec and Active build spec fields.

■ You can change the active build spec by right-clicking the project in the Project Explorer and selecting Build Options > Set Active Build Spec. This is useful, because if you want to include a kernel module in a VxWorks image, the build spec architecture and tool chain of the DKM and VIP projects must match (if they do not, the subproject will not be built).

■ Another way to change the active build spec is by selecting Build Options > Manage Active Build Specs. This allows you to apply a new active build spec (selected from a drop-down list of the project’s enabled build specs) to a set of projects rather than changing them one at a time.

■ The Subprojects tab of the VIP’s Build Properties dialog controls which build spec is used for its DKM, RTP, and shared library subprojects (RTPs and shared libraries would be in a ROMFS file system). By default, Let Workbench calculate best matches is selected. This automatically uses the VIP’s build spec when building the application or library, and ensures all subprojects are built. However, if there is a reason why you want to retain the build spec of the subproject (even if it means the subproject will not be built), select No Mapping instead.

5. Include or exclude debug information, in the following ways:

■ Select or clear the Debug Mode check box, depending on whether you want the build output to include debug information or not.

■ Select Build Options > Set Active Build Spec or Build Options > Manage Active Build Specs.

6. Continue with the following tasks, or if you have finished configuring your project, click OK.

Task 3: Select build tools.

In this task, you select build tools, build output generation, and build flags for your project.

To specify build tools for a project, do the following:

1. Select one of the following build tools from the drop-down list, or define your own.

■ C-Compiler, C++-Compiler, Assembler: These tools translate source code into machine code.

■ Linker: The linker produces a single, partially linked object that is intended for downloading. For kernel modules, this object is also munched


76

(integrated with code to call C++ static constructors and destructors). This object cannot be passed up to superprojects, although the current project’s own, unlinked object files can be passed, as can any output received from projects further down in the hierarchy.

■ Partial Image Linker: Available for kernel modules projects, this tool produces a single, partially linked, but not munched object for subproject support only; it is not intended for download. The Partial Image Linker output can be passed up to superprojects, as can the current project’s own, unlinked object files, as well as any output received from projects further down in the hierarchy

■ Librarian: The Librarian output can be passed up to superprojects, as can the current project’s own, unlinked object files, as well as any output received from projects further down in the hierarchy.

■ To define your own build tool, click New and enter a build tool name, then click OK. Your build tools appears in the drop-down list, and you can configure all build tool settings to fit your needs.

2. Specify the type of build output for Workbench to generate.

If you choose one of the compiler tools, the build output will be an object by default; if you choose one of the linker or archiver tools, the build output will be a build target. You can specify whether the build target should be passed or not.

3. Adjust specific build spec settings, as necessary.

You can select a new active build spec, add or remove entries from the Command field, or set different options for some build tools (whether or not you can edit the options for a particular build tool depends on the build spec you are using).

4. To specify options for a build tool, select the tool from the Build tool drop-down list, and click Tool Flags, Debug mode, or Non Debug mode, depending on the type of option you want to adjust.

5. Select an option from the Options list in the center of the dialog.

Some tools, such as the C- and C++-Compilers, provide the opportunity to edit several types of compiler options. For these tools, select a category (such as Debugging or Memory) from the column on the left, then select the appropriate option from the list in the center of the dialog. Your choice appears in the Selected option column on the right.

If you are working with RTP virtual overlapped memory, you will find additional information about setting the link address in 6.8 Using RTP Overlapped Virtual Memory, p.80.

6. Click OK. The selected option is appended to the Tool Flags, Debug mode, or Non Debug mode field.


Task 4: Define build macros.

In this task, you define global and build spec-specific macros that are added to the build command when executing builds, and can be used in the Tool Flags field of


77

the Build Tools tab. These macros can also be used indirectly, such as from within another build macro.

To define build macros for a project, do the following:

1. Define or edit global build macros, in the following ways:

■ To change the value of an existing global build macro, select the value in the Build macro definitions table and type in a new one, or click Edit and type in the new value, then click OK. You can define and use global build macros even if you do not select or define any build specs for your project.

■ To define a new global build macro, click New next to the table, then enter a Name and Value for the macro. Click OK.

■ To use the macro you just defined, you must refer to it in the command-line options for the compiler in the Command field of the Build Tools tab. For information on how to do this, open the Build Properties dialog, select the Build Tools tab, click in the Command field, then press the help key for your host.

2. Define or edit build spec-specific build macros, in the following ways:

■ To change the value of an existing build spec-specific macro, select the Active build spec for which the value should be applied, select the value in the Build spec-specific settings table, then type in a new one. Or click Edit and type in the new value, then click OK.

■ To define a new build spec-specific macro, click New next to the table, enter a Name for the macro, leave the Value blank, then click OK.

■ To define the value, select the macro, select the Active build spec for which the value should be applied, click Edit and enter the New value, then click OK.

■ As with global build macros, if you want to use the build spec-specific macro, refer to it in the Command field of the Build Tools tab.


Task 5: Specify build paths.

In this task, you specify a redirection root directory for your build output, add, delete, or reorder the directories searched by the build tools.

By default, build output is directed to a subdirectory in your workspace. This task shows you how to specify a new location for the build output, rename the directory, and update include paths.

To specify build paths for a project, do the following:

1. Specify a new location for the build output in the Redirection root directory field.

2. Specify a new name for the Redirection directory by entering a new directory name in the field.

The Redirection directory is a subdirectory of the Redirection root directory. By default this directory has the same name as the Active build spec.


78

3. To analyze your project and update the displayed include paths, click Generate. The Generate Include Search Paths dialog opens. The Include paths table shows the paths used by the compiler to resolve include directives.

For a complete walkthrough of the Generate Include Search Paths dialog, see the Configuring Build Paths section of Wind River Workbench User’s Guide: Building Projects.

4. (Optional) To manually add an include directory for an Active build spec, select the build spec from the drop-down list, click Add, and browse to or type in the path (be sure not to erase the -I at the beginning of the path). Click OK.

5. (Optional) To add an include path that applies to all your build specs, click Add to all and then browse to or type in the path, then click OK.


Task 6: Specify libraries.

In this task, you add a library to a particular build spec, or to all build specs.

To specify libraries for a project, do the following:

1. Click the Libraries tab to bring that page forward.

2. Click Add or Add to all to add a library search path, a library file, or a fully qualified library file.

Where to Go Next

■ For more information about writing kernel applications, see VxWorks Kernel Programmer’s Guide: Kernel Applications.

■ For more information about writing real-time process applications, see VxWorks Application Programmer’s Guide: RTP Applications.

6.7 Example: Adding IPNet Support to a DKM

This example shows you how to set the build properties for a DKM project so that it uses IPNet APIs, and includes the following tasks:

■ Task 1: Find the correct ENDIAN setting for your processor.

■ Task 2: Add the correct ENDIAN preprocessor symbol to each build spec.

■ Task 3: Add new include search paths so Workbench can find the IPNet APIs.

Task 1: Find the correct ENDIAN setting for your processor.

If you know the correct endianess for your processor, you can go directly to Task 2: Add the correct ENDIAN preprocessor symbol to each build spec.

6 Building Applications and Libraries6.7 Example: Adding IPNet Support to a DKM

79

To find the ENDIAN setting for your processor, do the following:

1. Select File > Open File.

2. Navigate to the following file, substituting the Workbench installation directory for installDir and the appropriate VxWorks version for 6.x:

installDir/components/ip_net2-6.x/ipcom/port/vxworks/gmake/ipcom_vxworks_make.mk

3. Scroll down and look for the ENDIAN section, then look for the appropriate endianess setting for your processor.

Task 2: Add the correct ENDIAN preprocessor symbol to each build spec.

In this task, you add the correct ENDIAN preprocessor symbol to a build spec.

To add the ENDIAN preprocessor symbol to a build spec, do the following:

1. Right-click the DKM project in the Project Explorer and select Properties.

2. At the bottom of the Build Macros tab, select a build spec from the drop-down list that you want to add the preprocessor symbol to.

3. Select CC_ARCH_SPEC in the Name column, and then click Edit.

4. After any other values in the text field, type -DIP_LITTLE_ENDIAN or -DIP_BIG_ENDIAN, as appropriate for the processor used by that build spec. Click OK.

5. Repeat these steps for the other build specs used by this project.

Task 3: Add new include search paths so Workbench can find the IPNet APIs.

In this task, you add include paths so that the DKM project can use the IPNet headers and correct APIs.

To add include search paths for IPNet APIs, do the following:

1. Click the Build Paths tab to bring it to the foreground.

2. Next to the Include Paths pane, click Add to all to add the paths to all build specs used by this project.

3. In the Value field, after the -I, type this path then click OK:

$(WRVX_COMPBASE)/$(COMP_IPNET2)/ipcom/port/vxworks/include

Be sure the -I appears before the path, with no space between them.

4. Complete steps 2 and 3 for the remaining required directories:

$(WRVX_COMPBASE)/$(COMP_IPNET2)/ipcom/port/vxworks/config$(WRVX_COMPBASE)/$(COMP_IPNET2)/ipcom/include$(WRVX_COMPBASE)/$(COMP_IPNET2)/ipcom/config$(WRVX_COMPBASE)/$(COMP_IPNET2)/ipnet2/include$(WRVX_COMPBASE)/$(COMP_IPNET2)/ipnet2/config

Your DKM project can now use the IPNet headers and correct APIs.


80

6.8 Using RTP Overlapped Virtual Memory

If you are using an overlapped virtual memory model, you can specify the address of the load and execution of the RTP application.

To set build options for RTP overlapped virtual memory, do the following:

1. Open the Build Properties dialog, as described in Task 1: Access build properties., p.74, and click the Build Tools tab.

2. Select Linker from the Build tool drop-down list,

3. Click Tool Flags, enter the RTP link address in the field, and click OK. The linker option and address appear in the Tool Flags field.

For more information about flat and overlapped RTP virtual memory models, see VxWorks Application Programmer’s Guide: Real-Time Processes.

6.9 Creating Statically Linked Libraries

Static libraries contain object code that is copied into the executable when your library is linked to the application at build time. This can be useful if you want to include the same code in several downloadable or relinkable images, for example in different VIPs.

In this task, you create a static library using the Wind River Workbench Project wizard.

To create a static library, do the following:

1. Click the Wind River Workbench project icon, on the left end of the Workbench toolbar.

2. From the Target operating system drop-down list, select Wind River VxWorks 6.x and then click Next.

3. From the Build type drop-down list, select one of the following:

■ Static Kernel Library, if the library is to be linked against a kernel module at build time.

■ Static User Library, if the library is to be linked against a real-time process application.

4. Click Next.

5. In the Project name field, type a name for your library.

6. Specify a location for the project.

For more information about how to choose between the location options, see 6.3 Creating a Project For Your Application, p.67.

6 Building Applications and Libraries6.10 Creating Shared Libraries

81

7. Click Finish. Your project appears in the Project Explorer, in one of the following ways:

■ As a downloadable kernel module, if you selected Static Kernel Library.

■ As a real-time process project, if you selected Static User Library.

6.10 Creating Shared Libraries

For libraries that you want to dynamically link to RTP applications at run-time, use VxWorks Shared Library projects. A shared library can be stored on a host file system, a network file system, or a local file system on the target (including ROMFS).

To create a VxWorks Shared Library project, follow these steps:

1. Select Wind River Workbench Project from the Workbench toolbar. The New Wind River Workbench Project wizard appears.

2. Select Wind River VxWorks 6.x from the drop-down menu. Click Next.

3. On the Build Type screen, select Shared User Library from the drop-down list. Click Next.

4. On the Project screen, type a name for your project.

5. Specify a location for your project. For more information, see 6.3 Creating a Project For Your Application, p.67.

6. Click Finish.

Your shared library project appears in the Project Explorer.

For information about the new files in your project, see A.8 Project Files in Shared Library Projects, p.147.

Configuring VxWorks Shared Libraries

You can create a shared library project, and later adjust its configuration options. For example, you can change the project’s build specs, build tools, and other options later in the development cycle.

NOTE: The shared library linker produces a BuildTargetName.so target that is dynamically linked to at run-time. The output product of the shared library linker is normally passed up to superprojects. If you do not pass the library target up to its superprojects, references in the superprojects’ application code cannot be resolved at compile time.

To modify the configuration options of a shared library, do the following:

1. Right-click the shared library in the Project Explorer and select Properties.

2. In the Properties dialog, select Build Properties.


82

3. Change the library build options as described in 6.6 Reconfiguring Your Project Later in the Development Cycle, p.73.

For more information about working with shared libraries, see VxWorks Application Programmer’s Guide: Static Libraries, Shared Libraries, and Plug-Ins.

Making Shared Libraries Available to RTP Applications

You can make shared libraries accessible to your applications at run-time, by configuring options for both the library and the application.

For an example of how to do this, see 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.82. This example also shows you how to add the shared library and application to a ROMFS file system, and add the file system to a VxWorks kernel image.

6.11 Creating Plug-Ins

The term plug-in has the following two meanings in Wind River documentation:

■ In Workbench, a plug-in is a third-party module that can deliver new functionality or tools without having to recompile or reinstall Workbench.

For instructions on incorporating these plug-ins into Workbench, see Wind River Workbench User’s Guide: Integrating Plug-ins.

■ In VxWorks, a plug-in is a type of dynamic shared object, similar to a shared library, that is called by an application when it is needed, rather than when the application is loaded.

You create this type of plug-in the same way you create a shared library (for details, see 6.10 Creating Shared Libraries, p.81). The same binary can be used for both. The difference is in how you code and build the application that uses the plug-in. For information, see 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.82.

For more information about VxWorks plug-ins, see VxWorks Application Programmer’s Guide: Static Libraries, Shared Libraries, and Plug-ins.

6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins

In this example, you create a pair of RTP application projects and a shared library. Then, you code and configure the applications so they call the library as a shared library at run time, or as a plug-in (when needed by the application).

6 Building Applications and Libraries6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins

83

This example contains the following sections:

■ Creating and Building RTP Applications, Shared Libraries, and Plug-ins.

■ Running RTP Applications with Shared Libraries and Plug-Ins.

■ Adding the RTP applications and library to a ROMFS that is bundled with a VxWorks kernel image, as explained in 9.4 Example: Bundling a VxWorks Image, p.125.

Creating and Building RTP Applications, Shared Libraries, and Plug-ins.

This section walks you through the process of setting up the structure for this example, and includes following tasks:

■ Task 1: Create the projects you need.

■ Task 2: Add source code to your projects.

■ Task 3: Set up a build target for fooRtpApp.

■ Task 4: Set the include path to the header file for fooRtpApp.

■ Task 5: Set the RTP applications to be built as dynamic executables.

■ Task 6: Build the projects for this example.

■ Task 7: Verify the executables.

Task 1: Create the projects you need.

In this task, you create two RTP application projects and a shared library.

To create RTP application projects and a shared library, do the following:

1. Create the RTP application project that will use the shared library, in the following way:

a. Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development.

b. Select File > New > VxWorks Real-Time Process Project.

c. On the Project screen, type fooRtpApp as the name for your project.

d. Leave Create project in workspace selected, then click Finish.

2. Create the RTP application project that will use the library as a plug-in, by following the instructions in step 1, naming the project fooPlugRtpApp.

3. Create the shared library project.

a. From the Advance Device Development perspective, select File > New > VxWorks Shared Library Project.

b. On the Project screen, type barLib as the name for your project.

c. Leave Create project in workspace selected, then click Finish.


84

Task 2: Add source code to your projects.

In this task, you add source code to the projects you created in the previous task.

To add source code to your projects, do the following:

1. Add a header file to your library project, in the following way:

a. In the Project Explorer right-click barLib, and select New > File.

b. In the File name field, type barLib.h, then click Finish.

The new file appears under the shared library, and opens for in the Editor.

c. In the Editor, type the following into barLib.h:void bar(void);

d. Close barLib.h, and click Yes to save the changes.

2. Add a source file to your library project, in the following way:

a. Right-click barLib, and select New > File.

b. In the File name field, type barLib.c, and then click Finish.

c. In the Editor, type the following into barLib.c:#include <vxWorks.h>#include <stdio.h>

void bar(void){

printf("I am bar() in barLib\n");}

d. Close barLib.c, and click Yes to save the changes.

3. Add a source file to the RTP application (that will use the shared library), in the following way:

a. Right-click fooRtpApp, then select New > File.

b. In the File name field, type fooRtpApp.c, and then click Finish.

c. In the Editor, type the following into fooRtpApp.c:#include <vxWorks.h>#include <stdio.h>#include <barLib.h>

int main(){

printf("I am main() in fooRtpApp\n");bar(); printf("I fooRtpApp just called bar() in barLib\n");return(0);

}

d. Close fooRtpApp.c, and click Yes to save your changes.

4. Add a source file to the RTP application (that will use the library as a plug-in), in the following way:

a. Right-click fooPlugRtpApp, and select New > File.

b. In the File name field, type fooPlugRtpApp.c, then click Finish.

5. Into fooPlugRtpApp.c, type the following code, changing the dlopen call to match the path in your development environment.

#include <vxWorks.h>


85

#include <stdio.h>#include <dlfcn.h>

int main(){

void *handle;void * addr;void (*funcptr)();

printf("I am main() in fooPlugRtpApp\n");

/* change the path in the dlopen call to match the one inyour development environment */

handle = dlopen("host:C:/workspace/barLib/SIMPENTIUMdiab_RTP/barLib/Debug/barLib.so", RTLD_NOW);

addr = dlsym(handle, "bar");

funcptr = (void (*)())addr;

funcptr();

dlclose(handle);

printf("I fooPlugRtpApp just called bar() in barLib as plug-inusing dlopen()\n");

return(0);

}

c. Close fooPlugRtpApp.c, and click Yes to save your changes.

NOTE: Some types of connections between target and host require modifiers to the path name. For example, NFS is transparent, but FTP requires hostname: before the path if it is not on the same system from which VxWorks was booted. The VxWorks simulator requires host: as a prefix; and so on. Also, it is important to mention that this code does no error checking.

Task 3: Set up a build target for fooRtpApp.

In this task, you set up the build-time linkage of an application, such as fooRtpApp, that uses a shared library. This creates an ELF NEEDED record in the application with the shared object name of the shared library.

The dynamic linker uses this name at run time to load the shared library when the application is loaded. For this reason, you would not perform this task for an application that uses a plug-in, such as fooPlugRtpApp.

To set up a build target for fooRtpApp, do the following:

1. In the Project Explorer, double-click fooRtpApp to view its contents.

2. Double-click Build Targets, then right-click fooRtpApp (fooRtpApp.vxe) and select Edit Content.

3. Verify that fooRtpApp - recursive appears in the Content list.

4. In the upper left corner of the Edit Content dialog, select Show all projects to see barLib.

5. Expand all the nodes within barLib (do not double-click barLib, because that will add it to the Content list).


86

6. Select barLib (barLib.so) and click Add.

7. Click Finish to create the build target under fooRtpApp (fooRtpApp.vxe).

Task 4: Set the include path to the header file for fooRtpApp.

In this task you set the include path to the header file for fooRtpApp.

You do not need to resolve include paths for fooPlugRtpApp, because it uses a plug-in, and therefore doesn’t need to include a header for the code it calls.

To set the include path for fooRtpApp, do the following:

1. Right-click fooRtpApp and select Build Options > Generate Include Search Paths.

2. In the dialog that appears, click Next.

3. On the Resolve include directives screen, click Resolve All. Notice that the entry -I%Proj-barLib% appears in the lower Include search paths pane.

4. Click Next, then Finish.

Task 5: Set the RTP applications to be built as dynamic executables.

In this task, you set the RTP applications that will be built as dynamic executables.

To specify applications to be built as dynamic executables, do the following:

1. Configure fooPlugRtpApp in the following way:

a. Under the Build Targets node of fooPlugRtpApp, right-click fooPlugRtpApp (fooPlugRtpApp.vxe) and select Properties.

b. Select the Build Tools tab to bring it forward.

c. Verify that the Build tool is set to Linker, and the active build spec is SIMPENTIUMdiab_RTP for Windows and Linux, and SIMSPARCSOLARISdiab_RTP for Solaris.

d. Click Tool Flags to open the Linker Options dialog.

e. Select Create a dynamic executable, then click OK.

-Xdynamic now appears in the field next to Tool Flags.

f. Click OK to close the Build Properties dialog.

2. Configure fooRtpApp in the following way:

a. Open the Build Properties dialog and click Build Tools.

b. Select Linker and click Tool Flags.

c. Select Create a dynamic executable, and click OK twice to close the dialog.

Task 6: Build the projects for this example.

In this task, you build the three projects you created for this example in the previous tasks.


87

To build the three projects in this example, do the following:

1. To build the shared library, right-click the project and select Build Project. The build output appears in the Build Console.

2. To build fooPlugRtpApp, right-click the project and select Build Project and click Continue when it asks to generate include paths.

3. To build fooRtpApp, right-click the project and select Build Project and click Continue when it asks to generate include paths.

All projects should build without errors.

NOTE: If errors do appear in the Build Console, make sure you changed the dlopen path in fooPlugRtpApp.c to match your development environment, and you selected Create a dynamic executable for both RTP applications.

Task 7: Verify the executables.

In this task, you verify that the appropriate records were created. You can use the program readelfarchName -d to make sure that the correct NEEDED records were created. Substitute the appropriate architecture name in the command, for example, readelfpentium.

The VxWorks distribution provides the libc.so C run-time shared library. Similar to the UNIX C run-time shared library, libc.so provides all of the basic facilities that an application might require.

To examine the executables for this example, do the following:

1. Open a terminal window, in one of the following ways:

■ On Windows, select Start > Programs > Wind River > VxWorks 6.x and General Purpose Technologies > VxWorks Development Shell.

■ On Linux and Solaris, open your preferred shell window, then set environment variables by typing the following command at the prompt, substituting the correct version number for 6.x:

$ ./wrenv.sh -p vxworks-6.x

2. For fooRtpApp, navigate to installDir/workspace/fooRtpApp/SIMPENTIUMdiab_RTP/fooRtpApp/Debug.

3. At the command prompt, type the following:

$ readelfpentium -d fooRtpApp.vxe

In the output that appears, you can see that both barLib.so and libc.so.1 are listed as NEEDED for fooRtpApp.

Dynamic section at offset 0x7f38 contains 18 entries: Tag Type Name/Value 0x00000001 (NEEDED) Shared library: [barLib.so] 0x00000001 (NEEDED) Shared library: [libc.so.1] 0x00000004 (HASH) 0xc0 0x00000006 (SYMTAB) 0x43c 0x0000000b (SYMENT) 16 (bytes) 0x00000005 (STRTAB) 0xa1c 0x0000000a (STRSZ) 1372 (bytes) 0x00000017 (JMPREL) 0x16e0 0x00000002 (PLTRELSZ) 160 (bytes) 0x00000014 (PLTREL) REL 0x00000016 (TEXTREL) 0x0


88

0x00000003 (PLTGOT) 0x1805c 0x00000011 (REL) 0xf78 0x00000012 (RELSZ) 1896 (bytes) 0x00000013 (RELENT) 8 (bytes) 0x00000015 (DEBUG) 0x0 0x00000018 (BIND_NOW) 0x00000000 (NULL) 0x0

4. For the RTP application that uses the plug-in, navigate to installDir/workspace/fooPlugRtpApp/SIMPENTIUMdiab_RTP/fooPlugRtpApp/Debug.

5. At the command prompt, type the following:

$ readelfpentium -d fooPlugRtpApp.vxe

In the output that appears, you can see that only libc.so.1 is listed as NEEDED for fooPlugRtpApp.

Dynamic section at offset 0x7e7c contains 17 entries: Tag Type Name/Value 0x00000001 (NEEDED) Shared library: [libc.so.1] 0x00000004 (HASH) 0xc0 0x00000006 (SYMTAB) 0x418 0x0000000b (SYMENT) 16 (bytes) 0x00000005 (STRTAB) 0x968 0x0000000a (STRSZ) 1248 (bytes) 0x00000017 (JMPREL) 0x15a0 0x00000002 (PLTRELSZ) 152 (bytes) 0x00000014 (PLTREL) REL 0x00000016 (TEXTREL) 0x0 0x00000003 (PLTGOT) 0x17f9c 0x00000011 (REL) 0xe48 0x00000012 (RELSZ) 1880 (bytes) 0x00000013 (RELENT) 8 (bytes) 0x00000015 (DEBUG) 0x0 0x00000018 (BIND_NOW) 0x00000000 (NULL) 0x0

Where to Go Next

Continue with Running RTP Applications with Shared Libraries and Plug-Ins.

Running RTP Applications with Shared Libraries and Plug-Ins

This section walks you through creating and booting a custom VxWorks kernel image, and then running applications that you created in Creating and Building RTP Applications, Shared Libraries, and Plug-ins.

This section covers the following tasks:

■ Task1: Create and build a custom VxWorks kernel image.

■ Task 2: Create a new VxWorks simulator target connection based on your VIP.

■ Task 3: Launch the RTP application that uses a shared library.

■ Task 4: Launch the RTP application that uses a plug-in.

■ Task 5: (Optional) Continue to debugging.

■ Task 6: Disconnect the VxWorks simulator.


89

Task1: Create and build a custom VxWorks kernel image.

In this task, you create a project using the PROFILE_DEVELOPMENT configuration profile, that includes development and debugging components. You then build the project, create a target connection, and launch the applications.

To create and build a custom VxWorks kernel image, do the following:

1. Create a VxWorks image project in the following way:

a. Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development.

b. Select File > New > VxWorks Image Project.

c. On the Project screen, type VIPsimpc as the name for your project, leave Create project in workspace selected, and click Next.

d. Since you will run your kernel image on the VxWorks simulator, make sure simpc and diab are selected as the BSP and Tool chain, then click Next twice until you reach the Configuration Profile screen.

e. From the Profile drop-down list, select PROFILE_DEVELOPMENT and click Finish. Your project appears in the Project Explorer.

2. Right-click the project and select Build Project. The build output appears in the Build Console.

NOTE: Near the bottom of the Build Console, you should see a line similar to installDir/workspace/VIPsimpc/default. This is the path to the vxWorks kernel image file. You will need this information for the next task.

Task 2: Create a new VxWorks simulator target connection based on your VIP.

In this task, you create a VxWorks simulator target connection based on the VIP from Task1: Create and build a custom VxWorks kernel image.

To create a VxWorks simulator target connection, do the following:

1. On the Remote Systems toolbar, click Define a connection.

2. In the New Connection dialog, select Wind River VxWorks 6.x Simulator Connection, and then click Next.

3. Click Custom simulator, then type the path to your kernel image file (such as installDir/workspace/VIPsimpc/default/vxWorks) or click Browse and navigate to the location.

4. Click Finish. For this example you can use the remaining default settings. The new vxsim# connection appears in the Remote Systems view (the # will vary, depending on how many previous simulator connections you created).

One of the default settings is Immediately connect to target if possible, so a VxWorks simulator window opens and displays the host shell running the boot sequence for your custom kernel image. Expand the vxsim window to see your kernel image’s symbol table being loaded near the beginning of the sequence.


90

Task 3: Launch the RTP application that uses a shared library.

In this task, you launch the RTP application you developed in Creating and Building RTP Applications, Shared Libraries, and Plug-ins.

To launch the RTP application, do the following:

1. In the vxsim window, switch the host shell from the C interpreter to the command interpreter by typing cmd. The prompt changes from -> to #.

2. Launch fooRtpApp using the following command, remembering to substitute the correct path in your environment for installDir and the correct version number for 6.x:

[vxWorks *]# rtp exec -e "LD_LIBRARY_PATH=host:installDir/workspace/barLib/SIMPENTIUMdiab_RTP/barLib/Debug;host:installDir/vxworks-6.x/target/usr/root/SIMPENTIUMdiab/bin" host:installDir/workspace/fooRtpApp/SIMPENTIUMdiab_RTP/fooRtpApp/Debug/fooRtpApp.vxe

This command uses the LD_LIBRARY_PATH environment variable to identify the run time location of your custom shared library barLib, as well as libc.so.1 from the VxWorks standard installation.

3. Verify that your RTP application launched and called the shared library in the output that appears.

Launching process 'host:installDir/workspace/fooRtpApp/SIMPENTIUMdiab_RTP/fooRtpApp/Debug/fooRtpApp.vxe' ...Process 'host:installDir/workspace/fooRtpApp/SIMPENTIUMdiab_RTP/fooRtpApp/Debug/fooRtpApp.vxe' (process Id = 0x1173a908) launched.I am main() in fooRtpAppI am bar() in barLibI fooRtpApp just called bar() in barLib[vxWorks *]#

Task 4: Launch the RTP application that uses a plug-in.

In this task, you verify that the RTP application is launched and calls the shared library. The LD_LIBRARY_PATH is used to provide the location of libc.so.1.

To launch the RTP application, do the following:

1. In the vxsim window, launch fooPlugRtpApp using the following command, remembering to substitute the correct path for installDir and the correct version number for 6.x:

$ rtp exec -e "LD_LIBRARY_PATH=host:installDir/vxworks-6.x/target/usr/root/SIMPENTIUMdiab/bin" host:installDir/workspace/fooPlugRtpApp/SIMPENTIUMdiab_RTP/fooPlugRtpApp/Debug/fooPlugRtpApp.vxe

2. Verify that your RTP application is launched and calls the shared library (as a plug-in this time) in the output that appears.

Launching process 'host:installDir/workspace/fooPlugRtpApp/SIMPENTIUMdiab_RTP/fooPlugRtpApp/Debug/fooPlugRtpApp.vxe' ...Process 'host:installDir/workspace/fooPlugRtpApp/SIMPENTIUMdiab_RTP/fooPlugRtpApp/Debug/fooPlugRtpApp.vxe' (process Id = 0x1173b640) launched.I am main() in fooPlugRtpAppI am bar() in barLibI fooPlugRtpApp just called bar() in barLib as plug-in using dlopen()[vxWorks *]#

6 Building Applications and Libraries6.13 Running Applications on a Hardware Target

91

Task 5: (Optional) Continue to debugging.

In this task, you learn where to find information on debugging applications, as well as in-depth information on other topics related to this example.

To continue on and debug your applications, do the following:

■ Go to 8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins, p.114.

The following information is also available:

■ For more information about shared libraries, including details about using the LD_LIBRARY_PATH environment variable and other methods for identifying the run time location of shared libraries (and the priorities of these methods), see VxWorks Application Programmer’s Guide: Static Libraries, Shared Libraries, and Plug-Ins.

■ For more information about the VxWorks simulator, see the Wind River VxWorks Simulator User’s Guide.

■ For more information about the host shell, see the Wind River Workbench Host Shell User’s Guide.

Task 6: Disconnect the VxWorks simulator.

In this task, you learn the different methods for disconnecting the VxWorks simulator.

To disconnect from the VxWorks simulator, do one of the following:

■ Close the vxsim# window.

■ On the Remote Systems toolbar, click Disconnect ‘vxsim#’.

6.13 Running Applications on a Hardware Target

To run your application on a hardware target, you must create a target connection. For information on how to do this, see Connecting to VxWorks Targets, p.93.


92

93

7Connecting to VxWorks Targets

7.1 Introduction 93

7.2 What Are Target Servers and Target Agents? 94

7.3 Creating a VxWorks Simulator Connection 95

7.4 Defining a New Target Server Connection 97

7.5 Example: Connecting a Target Server to a Target Agent 102

7.6 Defining a New Remote Connection 104

7.7 Troubleshooting Target Server Connections 104

7.1 Introduction

This chapter tells you how to configure, start, and manage your target connections.

You must configure and establish a connection between the Workbench tools running on your host and the target system before you can test your customized VxWorks kernel image, or run your kernel or RTP application.

Configuring and establishing a connection between the host and target includes the following:

■ Configuring the host side of the target connection (the target server) in the Remote Systems view, whether the target is an actual hardware board or the VxWorks simulator.

■ Configuring the target side of a connection (the target agent) in the Kernel Configuration Editor. For information on the Kernel Configuration Editor, see 4.4.1 Using the Kernel Configuration Editor, p.36).


94

Before You Begin

To set up communication between a host and a target, you must have already completed the following procedures:

■ Configure your host, as described in 3.3 Configuring Your Host Machine, p.18.

■ Configure your target, as described in 3.4 Configuring Your Target, p.20.

7.2 What Are Target Servers and Target Agents?

This section explains the functions of target servers and target agents. You must configure the target server and target agent that act as the interpreters between the Workbench tools running on the host and the VxWorks kernel image running on the target.

Understanding Target Servers

A target server is a program, running on the host, that allows Workbench tools such as shells and debuggers to communicate with the target agent running on the target.

If you configure and build a VxWorks kernel image with a target agent interface that understands a particular communication method (network, serial, JTAG, and so on), then your target server must be configured with settings that support the same communication protocol and transport layer. This collection of settings is known as the target server’s back end.

For host-target communication to work, the target server must be configured with a back end that matches the VxWorks kernel’s target agent interface.

Understanding Target Agents

A target agent is a program that runs on the target and acts as the interface between the VxWorks image on the target and the Workbench tools on the host. You probably need a target agent only during development. A self-booting system image does not need a target agent.

The target agent can function in one of three modes: user mode, system mode, and dual mode.

■ In user mode, the agent runs as a VxWorks task. Debugging is performed on a per-task basis: you can isolate particular tasks without affecting the rest of the target system.

■ In system mode, the agent runs externally from VxWorks, almost like a ROM monitor. This allows you to debug an application as if it, and VxWorks, were a single thread of execution. In this mode, when the target encounters a breakpoint, VxWorks and the application are stopped and interrupts are locked. One of the biggest advantages of this mode is that you can single-step through ISRs; on the other hand, it is more difficult to manipulate individual

7 Connecting to VxWorks Targets7.3 Creating a VxWorks Simulator Connection

95

tasks. Another drawback is that this mode is more intrusive; it adds significant interrupt latency to the system, because the agent runs with interrupts locked when it takes control (for example, after a breakpoint).

■ To support dual mode debugging, VxWorks images are configured with both agents by default: a user-mode agent (INCLUDE_WDB_TASK), and a system-mode agent (INCLUDE_WDB_SYS), with only one of these agents active at a time. Switching between the two can be controlled from either the Workbench debugger (see Wind River Workbench User’s Guide: Debugging Projects) or the host shell (see Wind River Workbench Host Shell User’s Guide).

To support a system-mode or dual-mode agent, the target communication path must work in polled mode (because the external agent needs to communicate to the host even when the system is suspended). The choice of communication path can affect what debugging modes are available.

7.3 Creating a VxWorks Simulator Connection

To see if your program runs properly before downloading it to a target board, you can run it on the VxWorks simulator. This simulates a connection to a standard or customized version of a VxWorks 6.x kernel, allowing you to proceed with your development work until a target board is available.

Creating a Standard VxWorks Simulator Connection

In this task, you create a VxWorks simulator connection in preparation for running the simulator.

To create a VxWorks simulator connection, do the following:

1. To open the New Connection wizard, do one of the following:

■ In the Remote Systems view, click Define a connection on the toolbar.

■ In the Remote Systems view, right-click in the view and select New > Connection.

■ In the Project Explorer, right-click a VIP project that has already been built, select Create VxWorks Simulator Connection, and then go to step 3.

2. On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Simulator Connection and click Next.

Immediately connect to target if possible is one of the default settings you should accept.

3. From the VxWorks Boot parameters screen, select Standard simulator. Because you are accepting all the default settings in this example, click Finish.

The target connection is created, and the simulator starts in one of the following ways:


96

■ For VxWorks 6.8 and later, a VxWorks simulator console automatically opens within Workbench in a Target Console view, downloading the standard VxWorks image.

■ For VxWorks 6.7 and earlier, a shell window opens, downloading the standard VxWorks image.

Customizing a VxWorks Simulator Connection

To customize a VxWorks simulator connection, you start by creating a connection the same way as you would for a default connection. For example, you would customize the simulator connection if you built a custom VxWorks kernel image or you want to adjust memory.

In this task, you open the New Connection wizard and instead of clicking Finish from the Boot parameters screen, you specify the kernel image and other parameters, and set the simulator memory options.

To customize a VxWorks simulator connection, do the following:

1. Open the New Connection wizard, in one of the following ways:

■ In the Remote Systems view, click Define a connection on the toolbar.

■ In the Remote Systems view, right-click in the view and select New > Connection.

■ In the Project Explorer, right-click a VIP project that has already been built, select Create VxWorks Simulator Connection, and then go to step 3.

2. On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Simulator Connection, then click Next.

3. Specify the kernel image file and other parameters, in the following way:

a. From the VxWorks Boot parameters screen, select Custom simulator, then click Browse and navigate to the location of the vxWorks kernel file you want to use.

b. If you want to bypass checksum comparison, select the check box.

c. Generally, Workbench does a checksum comparison to prevent you from attaching and debugging a target if the target kernel and host copy do not match, because the target will be looking at the wrong symbols, offsets, debug information, and so on. However, if you understand the system very well and wish to connect anyway, selecting this check box allows Workbench to make the connection.

d. Each new simulator connection is named vxsim#. Processor number displays the incrementing number that Workbench will assign to the simulator connection you are creating; you can adjust this if you like.

e. If you want to set specific VxWorks simulator boot parameters, click Advanced Boot Parameters. Click Next.

4. Set the simulator memory options, in the following way:

a. The options on this screen allow you to manage your memory resources.

b. Make sure the settings are adjusted the way you want, including whether you want to connect to the target now, then click Finish.

7 Connecting to VxWorks Targets7.4 Defining a New Target Server Connection

97

For more information about the settings on these screens, as well as how to use the simulator once it is running, see the Wind River VxWorks Simulator User’s Guide.

7.4 Defining a New Target Server Connection

To run your program on a target board, you first need to define a target server connection. Defining the connection includes the following tasks:

■ Task 1: Open the New Connection wizard.

■ Task 2: Select a target server back end.

■ Task 3: Specify the kernel image.

■ Task 4: Specify advanced target server options.

■ Task 5: Configure object path mappings.

■ Task 6: Specify how often Workbench should retrieve target status.

■ Task 8: Verify or modify Connection Summary settings.

Before You Begin

Before you can create a connection with a target server, you must know the kernel component for your project and it must be properly configured to interface with the target server.

The kernel component in the following table must be configured into your VxWorks kernel image. For more information, see 4.4 Configuring VxWorks, p.35.

Back End Description Compatible Kernel Component

wdbrpc The default back end.Supports any kind of IP connection. Polled-mode Ethernet drivers are available for most BSPs to support system-mode debugging.

INCLUDE_WDB_COMM_END or INCLUDE_WDB_COMM_NETWORK

wdbpipe For VxWorks target simulators.

INCLUDE_WDB_COMM_PIPE


98

Task 1: Open the New Connection wizard.

In this task, you bring up the New Connection wizard and specify a target server connection.

To open the New Connection wizard, do the following:

1. Click Define a connection on the Remote Systems view toolbar, or right-click in the view and select New > Connection.

2. On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Target Server Connection, and then click Next.

Task 2: Select a target server back end.

In this task, you specify the back end that matches the method the target server will use to communicate with the target. You can also specify any necessary information for the back end.

Each type of back end requires you to provide additional connection information. For example, Workbench can usually identify the target processor.

To specify a target server back end, do the following:

1. In the Back end settings section, select the back end that matches the method the target server will use to communicate with the target.

For connections that use a wbdserial backend setting, you can now specify a custom baud rate. To do so, select Other from the Serial device speed (bit/ss) drop-down list, enter the custom rate, and clicking OK.

2. Provide the necessary information for the back end. For example, to manually set the processor click Select and choose your processor from the list.

Task 3: Specify the kernel image.

In this task, you specify the kernel image to use with the target server. How you do this depends on where the kernel image is located.

wdbserial For serial hardware connections; does not require SLIP on the host system. With this option, also choose a Host serial device and Serial device speed.

Supports either system-level or task-level views of the target, depending on the target-agent configuration.

INCLUDE_WDB_COMM_SERIAL

wdbproxy For UDP, TCP, TIPC, and MIPC connections.

INCLUDE_WDB_PROXY_UDP (for UDP/TCP),INCLUDE_TIPC_ONLY, or INCLUDE_WDB_PROXY_MIPC


99

To identify the kernel image to use, do one of the following:

■ If the VxWorks image is running on the target, and Workbench can find it using the target path, select File path from target (if available).

■ If the VxWorks image file is not in the same location on the host that is configured into the target (or if host and target have different views of the file system), select File and navigate to the host location of the kernel image.

■ If you are using a target programmed with a vxWorks_rom.hex, vxWorks_romCompressed.hex, or any other on-board VxWorks image, you must use this option to identify the kernel file location. Otherwise, the target server will not be able to identify the target symbols.

Task 4: Specify advanced target server options.

In this task, you specify options such as, timeout, memory cache, logging, and local and global symbols.

The options shown in the Options field are passed to the tgtsvr program on the command line. You can type them in, or click Edit to configure the settings represented by these options.

To specify advanced target server options, do the following as needed:

1. Click the Common tab and select from the following to configure the target server file system (TSFS) and various timeout options:

a. Enable the TSFS if you are using Wind River System Viewer, if you are booting a target over a serial connection, or if you need to provide a target that is booted from a remote host access to files on a local host.

To use the TSFS, you must also include the WDB target server file system kernel component when you build your VxWorks kernel image.

b. Identify the root directory of the host file system. By default, this is the workspace directory.

c. Make the target server file system writable when you are using System Viewer, since this is how it uploads event data from the target to the host.

Be aware that this also allows other users to access your host file system, so you may want to set the TSFS option to read-only when you are not using System Viewer.

d. Specify timeout options, such as allowable spawn time for kernel tasks and RTPs, time to wait for a response from the agent running on the target, how often to retry, and at what intervals.

2. Click the Memory tab, to modify cache size. To avoid excessive data-transfer transactions with the target, the target server maintains a cache on the host system of up to 1 MB. You can increase this size on the Memory tab.

3. Click the Logging tab to enable output and back end logging on the Logging tab, and do the following as needed:

a. Specify the log’s location and maximum size (logs are rewritten from the beginning when they reach this maximum size, and they are deleted and recreated when the target server restarts, such as after a reboot).


100

b. For the WTX (Wind River Tool Exchange) log file, specify a filter, a regular expression that limits the type of information logged. Without a filter, the log captures all WTX communication between host and target.

4. Click the Symbols tab to specify whether to load global symbols (the default) or both global and local symbols. If you choose not to load symbols to the target server, the connection sequence may fail.

5. Click Next.

Task 5: Configure object path mappings.

In this task, you configure object path mappings for modules with symbols or modules that do not yet have symbols.

Object path mappings allow the debugger to find symbol files for processes created on the target. This is done by creating a correspondence between a path on the target and the appropriate path on the host.

You calculate target paths for processes that you want to launch, by browsing to them with a host file system browser. In most cases the default mappings that Workbench provides are correct (and are not editable).

To specify object path mappings for modules with symbols, by doing the following:

1. To download a module or start a process without loading the symbol file, uncheck Load module symbols to debug server automatically if possible. By default, the debug server attempts to load all of a module’s symbols each time a module is loaded.

2. To map a new target path prefix to a host path, click Add and enter the target path (for example, /tgtsvr/) and a full host path (for example, C:\workspace\). Do not use relative host paths here.

3. To export object path mappings to XML, click Export and provide a descriptive filename. Likewise you can import mappings by clicking Import and selecting an appropriate XML file.

4. Create mapping pairs. At the bottom of the screen, 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] will ensure that the debugger loads yourApp.vxe.unstripped when yourApp.vxe is launched on the target.

Alternately, you can create Object Path Mappings for a module that does not have symbols yet by downloading the output file (or running the executable) manually.

To specify object path mappings for modules without symbols, do the following:

1. In the Remote Systems view, right-click the file or executable and select Load/Add Symbols to Debug Server.

2. From the Load Symbols dialog, select Create path mappings for the module based on the selected symbol file and click OK.

Object path mappings are created automatically, so that after the next disconnect/reconnect sequence Workbench will find the symbols.


101

3. Click Next.

Task 6: Specify how often Workbench should retrieve target status.

In this task, you specify how often and under what conditions Workbench should refresh the Remote Systems view display. This is important, since retrieving status information from the target leads to considerable target traffic.

To specify the refresh rate for the Remote Systems display, do the following:

1. To prevent excessive delay in the update of the Remote Systems display, do not select Listen to execution context life-cycle events when there are more than 100 contexts on the target.

2. Click Next.

Task 7: Set the debug options.

In this task, you specify the debug options.

To specify debug options, do the following:

1. Specify which threads Workbench should stop when breakpoints are hit.

2. Specify whether to display an error dialog on target exceptions.

3. Click Next.

Task 8: Verify or modify Connection Summary settings.

In this task you review the Connection Summary settings and verify or modify them, as needed.

To review connection summary options, do the following:

1. To modify the Connection name, or any of the settings associated with this connection, click Back and update the appropriate screen.

2. Verify or modify the Shared option (to the right of the Connection name field) is available only for certain connection types, and serves the following purposes:

■ When you define a target connection configuration, this connection is normally visible only to you. 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; for details, see the Wind River Workbench User’s Guide).

■ Normally, when you terminate a target connection, Workbench kills the target server (and simulator) because you no longer need them. In a connection that is flagged as Shared, however, they are left running so that other users can connect to them. In other words, you can flag a connection as shared if you want to keep the target server (and simulator) running after you disconnect or exit Workbench.

3. Verify or modify the connection setting, in one of the following ways:

■ To connect to the target as soon as you finish reviewing the summary, leave Immediately connect to target if possible selected.


102

■ If you do not, clear the check box; you can connect later by right-clicking the connection and selecting Connect.

4. Click Finish. Your new target server connection definition appears in the Remote Systems view connection list.

If everything is set up properly, and Immediately connect to target is selected, you will see connected - target server running at the bottom of the Workbench window. If you have problems connecting, see 7.7 Troubleshooting Target Server Connections, p.104.

Where to Go Next

■ For more information about target servers and target agents, see the VxWorks Kernel Programmer’s Guide.

■ You can also find information about target servers in the tgtsvr reference entry, available by typing tgtsvr into the Search feature of the Workbench help system.

7.5 Example: Connecting a Target Server to a Target Agent

In this example, you configure a target server to connect to a target agent over an Ethernet connection. This example includes the following tasks:

■ Task 1: Open the New Connection wizard.

■ Task 2: Specify the target server options.

■ Task 3: Specify the object path mappings.

■ Task 4: Select the desired target state refresh frequency.

■ Task 5: Set the debug options.

■ Task 6: Review the connection summary settings.

■ Task 7: Create the target server connection definition.

Before You Begin

You can specify a name for the target server only if you added it to your hosts file in 3.4 Configuring Your Target, p.20.

Task 1: Open the New Connection wizard.

In this task, you bring up the New Connection wizard and specify a target server connection.

To open the New Connection wizard, do the following:

1. Click Define a connection on the Remote Systems view toolbar, or right-click in the view and select New > Connection.

2. On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Target Server Connection, and then click Next.

7 Connecting to VxWorks Targets7.5 Example: Connecting a Target Server to a Target Agent

103

Task 2: Specify the target server options.

In this task you specify the wdbrpc back end, the name or address of the target, and set output options.

To specify target server options, do the following:

1. Select the wdbrpc back end, and type in the name or IP address of the target.

2. Under Advanced target server options, select Verbose target server output.

Your command line should look similar to this:

tgtsvr -V -R C:/installDir/workspace -RW -Bt 3 -A ipaddress_or_name

3. Click Next.

Task 3: Specify the object path mappings.

In this task, you configure object path mappings. Object path mappings describe the relationship between the location of executables and symbol files on the target, and their location on the host.

To configure object path mappings, do the following:

1. Follow the instructions, as described in Task 5: Configure object path mappings., p.100.

2. Click Next.

Task 4: Select the desired target state refresh frequency.

In this task, you specify when and how you want Workbench to query the target state.

To specify the refresh rate for the Remote Systems display, do the following:

1. To prevent excessive delay in the update of the Remote Systems display, do not select Listen to execution context life-cycle events when there are more than 100 contexts on the target.

2. Click Next.

Task 5: Set the debug options.

In this task, you specify the debug options.

To specify debug options, do the following:

1. Specify which threads Workbench should stop when breakpoints are hit.

2. Specify whether to display an error dialog on target exceptions.

3. Click Next.

Task 6: Review the connection summary settings.

In this task you review the Connection Summary settings and verify or modify them, as needed. This screen lists all the default and customized settings associated with this target connection definition.


104

To review connection summary options, do the following:

1. Verify that the settings reflect your choices on the previous screens.

2. Verify or modify the following setting, as needed:

■ The Immediately connect to target if possible box is selected by default. This means that if your target booted successfully in 3.5 Booting a Target with VxWorks, p.24, Workbench will attempt to connect to your target.

■ If you want to create this definition but your target is not running yet, clear this check box.

Task 7: Create the target server connection definition.

In this task, you create the connection definition.

To create the target server connection definition, do the following:

■ Click Finish. Your new target server connection definition appears in the Remote Systems view connection list.

If everything is set up properly, and Immediately connect to target is selected, you will see connected - target server running at the bottom of the Workbench window.

If you have problems connecting, see 7.7 Troubleshooting Target Server Connections, p.104.

7.6 Defining a New Remote Connection

If you want to define a remote system connection such as FTP or SSH, see the following documents available from the Workbench help system:

■ Wind River Workbench User’s Guide: Building: Use Cases

■ Using Remote Connections section of RSE User Guide: Getting Started,

7.7 Troubleshooting Target Server Connections

This section provides solution suggestions if you are experiencing target server connection problems. Review these suggestions before calling technical support.

Check Back End Serial Port

If you use a WDB Serial connection to the target, make sure you have connected the serial cable to a port on the target system that matches your target agent configuration. The agent uses serial channel 1 by default, which is different from the channel used by VxWorks as a default console (channel 0). Your target’s ports

7 Connecting to VxWorks Targets7.7 Troubleshooting Target Server Connections

105

may be numbered starting at one; in that situation, VxWorks channel one corresponds to the port labeled serial 2.

Verify Path to VxWorks Image

The target server requires a host-resident image of the VxWorks run-time system. By default, it obtains a path for this image from the target agent (as recorded in the target boot parameters). In some cases (for example, if the target boots from a local device), this default is not useful.

In that situation, create a new Target Server Connection definition in the Remote Systems view. Use the -c filename option in the Advanced Target Server Options field to specify the path to a host-resident copy of the VxWorks image.

TIPC Connection Does Not Function Properly

Be careful not to choose TIPC (under WDB Proxy connection type) unless you have included the TIPC network stack (INCLUDE_TIPC_ONLY) component in your VxWorks image project.

For more information about TIPC, see Wind River TIPC for VxWorks 6 Programmer’s Guide: Building VxWorks to Include Wind River TIPC.


106

107

8Running and Debugging VxWorks

Applications

8.1 Introduction 107

8.2 How Can Workbench Help Me Run My Code? 108

8.3 How Do I Create a Launch Configuration? 108

8.4 Running Your Applications 111

8.5 Debugging Your Applications 113

8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins 114

8.7 Monitoring Semaphores During Debugging 116

8.1 Introduction

This chapter explains how to create launch configurations for VxWorks kernel tasks and real-time processes.

After you have created your projects, coded and built your kernel or application, and configured a connection to your target, you can then run and debug your code. Workbench assists you with build–connect–run–debug phase of the development cycle by providing a framework called a launch configuration.

For general information about launch configurations of all types, see Wind River Workbench User’s Guide: Launching Programs. For specific information on a tab or field, open the launch configuration dialog and press the help key for your host.


108

8.2 How Can Workbench Help Me Run My Code?

During the development cycle, you may run and rerun the same application many times in a single debugging session. Creating a launch configuration expedites running and debugging an application by allowing you to configure everything once. Then you just click the Run or Debug icon on the Workbench toolbar, or press a keyboard shortcut.

You create a launch configuration based on a launch type, specifying the appropriate attribute values. You then initiate a launch based on a launch configuration using a specific launch type.

Understanding Launch Types

Launch configurations can be of different types or modes. The mode defines the work that is done. The standard modes are Run, Debug, and Download.

■ Run-mode—connects to the target, then launches a task or process.

■ Debug-mode—connects to the target, launches a task or process, and automatically attaches the Wind River debugger.

■ Download-mode—connects to the target and downloads a module. This launch type is available for VxWorks kernel tasks and Linux application processes. For Linux it is possible to transfer files in both directions.

A launch may be initiated by the Run or Debug icons in Workbench, though launches may be initiated other ways as well.

Using a Multiple Launch Context

You can select multiple contexts within a launch configuration, to execute the launch on multiple targets. For example, if you select vxsim0 and vxsim1 for a DKM launch configuration, the launch is executed on both targets.

8.3 How Do I Create a Launch Configuration?

This section provides instructions for the following tasks:

■ Creating a Launch Configuration For an Existing Project.

■ Creating a Launch Configuration Using the Run Menu.

■ Creating a Launch Configuration From a Target Connection.

■ Attaching to Running Tasks or Processes.

Running kernel tasks and real-time processes are similar procedures. Each has its own type of launch configuration, but there are only a few options and settings that differ between the two.

NOTE: Some launch types may only be available in one mode, while other may have multiple launch types. For example, a DKM launch type is available in run, debug, and download launch mode.

8 Running and Debugging VxWorks Applications8.3 How Do I Create a Launch Configuration?

109

Attach Target Context launch configurations are different from the other launch configurations in that they do not actually run a program, but just connect a target and attach the debugger to some context that must already exist. Also, the information on the Launch Context tab is for review only, and cannot be changed. This is because it reflects information about an actual running process.

Creating a Launch Configuration For an Existing Project

This is the easiest way to create a launch configuration for your project. In this task, you select a project in the Project Explorer, then select the Run or Debug command from the context menu.

To create a launch configuration for an existing project, do the following:

1. In the Project Explorer, select a project, right-click the project folder and from the context menu, select the appropriate command for your project type:

■ For DKMs, select one of the following: Run | Debug | Download VxWorks Kernel Task.

■ For RTP applications, select one of the following: Run | Debug VxWorks Real-Time Process | Download VxWorks Real-Time Process.

The Launch Configuration wizard opens to display configuration tabs for the type of launch you are creating.

2. Give the launch configuration a name.

At the top of the wizard, the Name field reflects the information Workbench knows about your project: the executable name, and the most recently active target connection, for example helloworld.vxe - vxsim0. You can change this name to anything you want.

Since kernel tasks also require you to specify an entry point, a kernel task launch configuration name will include noEntryPoint until you specify one.

3. Configure the settings on the Launch Context tab, in the following way:

a. Verify that Workbench selected the correct target connection, or specify multiple targets for the launch.

b. In the General section, specify an Entry Point for a kernel task, and verify the Exec Path on Host for an RTP application. None of the other fields are editable unless your target connection is active.

c. To edit them, click Close to close the wizard, activate the target connect you want to use, then right-click your project and reopen the launch configuration wizard. For details on each field, press the help key for your host.

d. If this is a debug mode launch configuration, a Debug section appears:

For a kernel task—specify whether it should break on entry and if Workbench should automatically attach spawned kernel tasks.

For an RTP application—specify where it should break.

4. (Optional) Configure the settings on the following tabs. You do not need to adjust these settings, unless the defaults are not optimum for your project.


110

a. On the Projects to Build tab, the project you selected appears by default. If you want any others to be built as well, click Add and select them from the dialog.

b. On the Source tab, configure the source lookup path for your program. For details on how to do this, see Wind River Workbench User’s Guide: Debugging Projects.

c. On the Common tab, specify whether this launch should be available to you, or shared with your team. If it should be shared, type in the path or click Browse and navigate to the location where you want to store the launch configuration.

d. Also on this tab, specify whether this launch configuration should always appear in the Run, Debug (or for a kernel task, Download) Favorites menu.

e. If you are creating a kernel task launch configuration, you should see a Downloads tab. This tab displays a list of the build targets Workbench should download when you run this launch. The build target of the project you chose appears automatically. Click Add to include additional build targets.

5. Do one of the following:

■ To run your launch configuration now, click Run or Debug.

■ To save your configured launch configuration and run it later, click Apply, then Close.

Creating a Launch Configuration Using the Run Menu

The Workbench toolbar Run menu is another way to access the launch configuration wizard. In this task, you select one of the Run or Debug commands from the Workbench Run menu.

To create a launch configuration using the Run menu, do the following:

1. Select Run > Run Configurations or Run > Debug Configurations. The Create, manage, and run configurations dialog box appears.

2. Select VxWorks Kernel Task or VxWorks Real-Time Process, then click New (or double-click the launch type).

3. Continue with the steps outlined in Creating a Launch Configuration For an Existing Project, p.109, starting with step 2.

Creating a Launch Configuration From a Target Connection

You can create a launch configuration based on a specific target connection in the Remote Systems view. In this task, you select a target connection, then select the Run or Debug command.

To create a launch configuration from a target connection, do the following:

1. Right-click a target connection, then select Run or Debug, then VxWorks Kernel Task or VxWorks Real-Time Process.

8 Running and Debugging VxWorks Applications8.4 Running Your Applications

111

2. If Workbench finds an existing launch configuration whose settings match your selection, a dialog appears prompting you to select an action:

■ Use the selected launch configuration.

■ Edit the configuration, for example, to change the target.

■ Copy the configuration and then edit it (thereby preserving the original).

■ Create a new launch configuration.

3. The dialog displays one or more matching launch configurations. If one of them meets your needs, select it.

4. Click OK, and the following happens:

■ The launch configuration starts immediately, if you chose to use a selected launch configuration.

■ The launch configuration wizard appears, if you chose to edit, copy and edit, or create a new launch configuration.

5. Enter information that is appropriate for your program, as described in Creating a Launch Configuration For an Existing Project, p.109, then click Run or Debug.

Attaching to Running Tasks or Processes

Attach Target Context launch configurations are created automatically when you attach the debugger to a process or kernel task in the Remote Systems view. In this task, you right-click a running task or process in the Remote Systems view, then select Debug > Attach to name (this only works in debug mode).

To attach to a running process or kernel task, do the following:

1. Expand your target connection down to Kernel Tasks or Real-Time Processes.

2. Inside one of these nodes, find the task or process that you want to attach to, right-click it.

3. Select Debug > Attach to name (Task Mode).

The debugger attaches to the task or process, which appears in the Debug view, and an Attach Target Context launch configuration appears in the launch configuration wizard under Debug Configurations.

4. After you Attach to Target launch, you can edit it in the launch configuration wizard as described in Creating a Launch Configuration For an Existing Project, p.109. You can rename it by typing a new name in the Name field and clicking Apply, and you can add it to your Favorites menu using the Common tab.

8.4 Running Your Applications

This section covers the numerous ways in which you can run your applications, and includes a walk through example and troubleshooting information.


112

How to Run an Application

After you have created a launch configuration, you can run your program in the following ways:

■ From the Project Explorer—by expanding a project’s Wind River Launches node, then right-clicking a launch configuration and selecting Run or Debug.

■ From the Remote Systems view—by expanding a target connection’s Wind River Launches node, then expanding the type of launch configuration, right-clicking a launch configuration and selecting Run or Debug.

■ From the Workbench toolbar Run menu—by selecting Run > Run Last Launched (also available as CTRL+F11) or Run > Debug Last Launched (also available as F11).

■ To rerun a program that was used earlier, choose from a list of recently run launches by selecting Run > Run History or Run > Debug History.

■ To open the launch configuration wizard itself, select Run > Run Configurations or Run > Debug Configurations.

Running a Program Example

In this task, you run your program andWorkbench loads the output file or executable into target memory. The prname and host location appear below your target connection in the Remote Systems view.

This task assumes that you have created a launch configuration.

To run your program, do the following:

1. Select Run to launch your program.

Individual tasks associated with DKMs appear under Kernel Tasks. Tasks associated with RTP applications appear under Real-time Processes. A red S over the output file icon indicates that symbol information was downloaded to the debugger.

2. If Workbench found no symbol information, right-click the module and select Load/Add Symbols to Debug Server to load the symbols from an alternate location.

3. (Optional) You can match module paths with symbol information by selecting the Create path mappings for the module based on the selected symbol file check box in the Load Symbols dialog.

Running a Program Through Debug

You can select Debug to launch your program, and in addition to loading the output file or executable into target memory and downloading symbol information, the debugger attaches to the task or process that then appears in the Debug view.

For more information about debugging your programs, see 8.5 Debugging Your Applications, p.113. Or, you can open the Debug view, click in it, and press the help key for your host.

8 Running and Debugging VxWorks Applications8.5 Debugging Your Applications

113

Troubleshooting Execution of RTP Applications

You may get an S_rtp_INVALID_FILE error when trying to execute an RTP application.

Workbench generates this error when the path and name of the RTP executable are not provided, or when it cannot find the executable using the indicated path. Unlike with DKMs, RTP executable files are accessed and loaded from the VxWorks target, not from the host running Workbench.

The path to the executable file must be valid from the point of view of the VxWorks target itself. Specifying the correct path may involve including the proper device name in front of the path, as shown in the following example:

$ host:d:/my.vxe

8.5 Debugging Your Applications

Workbench debugger provides various types of breakpoints that allow you to stop your code at particular points or when certain conditions are met. You can step through your code, and dynamic printf event points help you to see what the code is doing at specific locations.

The debugger can operate in user mode or system mode. You may want to debug a particular task while the system and other tasks continue to execute, or you may want to stop the entire system when a breakpoint is hit.

For more information on these features, see the Wind River Workbench User’s Guide.

Before You Begin to Debug

Before you can debug your code, you must have completed the following tasks:

■ Built a VxWorks kernel image that includes the WDB agent (as described in 4.4 Configuring VxWorks, p.35).

■ Defined and established a target connection based on that kernel image, as described in 7.4 Defining a New Target Server Connection, p.97).

■ Selected Debug mode when creating your source code projects. If you did not, you can do the following:

a. Right-click the project in the Project Explorer, and select Properties, then Build Properties.

b. Select the Debug mode check box at the bottom of the Build Support and Specs tab.

■ Made the source code you want to debug accessible to Workbench.

■ If you moved the module or kernel from its original compilation path, then you need to set the host-to-target object path mappings.

Object path mappings describe the relationship between the location of executables and symbol files on the target file system and their location on


114

the host file system. For more information, see Task 5: Configure object path mappings., p.100.

■ If you moved the source code for the module or kernel from its original compilation path, then you need to set host-to-target source path mappings.

Source lookup path mappings are the mapping of source file paths retrieved from the executable’s symbol data to the correct location of the source files on the host file system, so the debugger can find the files in their new locations.

Attaching the Workbench Debugger

To debug your code using Workbench, you must first attach the debugger to your code. You can attach the debugger to your code in the following ways:

■ Create and run a debug mode launch configuration, as described in Creating a Launch Configuration For an Existing Project, p.109.

■ Manually attach the debugger to a task or process, as described in Attaching to Running Tasks or Processes, p.111.

8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins

This example is based on the project you worked with in the 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.82. In this example, you complete the debugging phase of that project in which you created two RTP applications and a library, and configured your applications to call the library either as a shared library at run time or as a plug-in when needed by the application.

In this example, you debug one of the RTP applications and the shared library to ensure they are functioning properly by completing the following tasks:

■ Task 1: Relaunch the VxWorks simulator.

■ Task 2: Create a launch configuration for your application.

■ Task 3: Launch and debug your application.

■ Task 4: Disconnect the VxWorks simulator, or continue with deployment.

Task 1: Relaunch the VxWorks simulator.

In this task, you relaunch the VxWorks simulator. If the VxWorks simulator window you used earlier is still running, you can go directly to Task 2: Create a launch configuration for your application.

To relaunch the VxWorks simulator, do the following:

■ Select the simulator in the Remote Systems view and click Connect.

8 Running and Debugging VxWorks Applications8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins

115

Task 2: Create a launch configuration for your application.

In this task, you create a launch configuration for your application. Remember that you can run more than one VxWorks simulator connection at a time. For this reason, always verify the number after vxsim in the title bar of the VxWorks simulator window.

To create a launch configuration, do the following:

1. In the Remote Systems view, right-click Real Time Processes under your vxsim# connection, then select Debug > VxWorks Real-Time Process.

The Debug Configurations dialog appears.

2. Click Select a build target and select fooRtpApp.vxe from the list. Exec path on host is selected by default

3. Click OK, and then next to the Environment field click Edit.

4. In the Edit Environment dialog click Add, and in the Name field type LD_LIBRARY_PATH.

5. In the Value field, type the same path you used earlier to launch your RTP, substituting the correct path for installDir and the correct version for 6.x:

host:installDir/workspace/barLib/SIMPENTIUMdiab_RTP/barLib/Debug;host:installDir/vxworks-6.x/target/usr/root/SIMPENTIUMdiab/bin

6. Click OK twice to save the new setting.

Task 3: Launch and debug your application.

In this task, you launch and debug your application. When you launch your application for debugging, several things happen. The process launches on the target, the debugger attaches to it and it appears in the Debug view, and fooRtpApp.c opens for debugging in the editor, with the blue program counter at the first executable line of code.

To launch and debug an application, do the following:

1. Click Debug to launch your application.

2. Perform basic debugging operations such as the following, using the corresponding icons on the Debug view toolbar:

■ Step Into

■ Step Over

■ Step Return

3. To run process to its end, click the green Play icon in the Debug view. The process finishes, and the following output appears in the Console view.

I am main() in fooRtpAppI am bar() in barLibI fooRtpApp just called bar() in barLib

Task 4: Disconnect the VxWorks simulator, or continue with deployment.

In this task, you can disconnect the VxWorks simulator, or continue with the deployment process.


116

To disconnect the VxWorks simulator, do one of the following:

■ Close the vxsim# window.

■ Click Disconnect ‘vxsim#’ on the Remote Systems toolbar.

To continue with deploying your application, do the following:

■ Follow the instructions described in 9.4 Example: Bundling a VxWorks Image, p.125.

8.7 Monitoring Semaphores During Debugging

During multi-process debugging, you can monitor multiple data structures such as kernel tasks, real-time processes, message queues, semaphores, and other resources. For example, you can monitor a semaphore used to control a device that two processes are using. Or you can set an RTP that uses a system resource to watch that resource during Step Over system calls.

In this section, you learn how to open the Kernel Objects view and view selected resources. For more information about the Kernel Objects view, as well as a guide to the icons and their meanings, open the view and press the help key for your host.

NOTE: Be aware that when you open a view using Show View, it may appear in a different location from where it usually appears in another perspective. You can move it if you like by clicking its name tab and dragging it to your preferred location

To open the Kernel Objects view and view selected resources, do the following:

1. Connect to your target in the Remote Systems view, as described in 7. Connecting to VxWorks Targets.

2. Open the Kernel Objects view, in one of the following ways:

■ In the Advanced Device Development perspective, click the Kernel Objects tab to bring it to the foreground.

■ In the Device Debug perspective, select Window > Show View > Kernel Objects.

3. Click the pull-down arrow (at the far right of the tool bar) and select your target connection.

8 Running and Debugging VxWorks Applications8.7 Monitoring Semaphores During Debugging

117

The Kernel Objects view appears. System resources are displayed in a hierarchical tree.

4. To see specific instances of a type of resource, or to display which tasks belong to which executable, click the plus sign to expand the entries in the tree.

5. Double-click a resource to examine it in the Kernel Objects view. Properties and their current values are displayed in the Properties view.


118

119

PART V

Deploying Applications

9 Deploying VxWorks Systems .................................................. 121


120

121

9Deploying VxWorks Systems

9.1 Introduction 121

9.2 Reconfiguring VxWorks for Deployment 121

9.3 Adding Kernel Applications to a VxWorks Image 123

9.4 Example: Bundling a VxWorks Image 125

9.1 Introduction

This chapter presents the different ways you can deploy your applications. You can begin planning for deployment after you have completed your development work and are satisfied that your code runs on the intended target and functions as you intended.

How you deploy an application depends on whether there is a file system on the target, or the target accesses the application on disk or on a host, or if you need to bundle the applications and libraries into a ROMFS inside your kernel image.

For more in-depth information about this topic, see the following documents:

■ VxWorks Application Programmer’s Guide: RTP Applications

■ VxWorks Kernel Programmer’s Guide: Kernel Applications

9.2 Reconfiguring VxWorks for Deployment

The tasks in this section show you how to reconfigure VxWorks for deployment. You should reconfigure VxWorks before you deploy your application if the required functionality for the deployed system is different from that needed during development.

For example, if Workbench tools do not have to communicate with the image once it is deployed, you can remove WDB agent functionality from the image. A quick


122

way to do this is to exclude the WDB components from your VIP using the Kernel Configuration Editor.

Another reason to reconfigure before deployment, is to reduce the footprint of the application. Resource-constrained or performance-driven systems may require that you exclude unnecessary VxWorks functionality, as well as all the supporting code from other components.

An example of this is System Viewer instrumentation. The System Viewer adds to the overall footprint of a kernel image, and the semaphore and other support for System Viewer increase the kernel size as well.

To exclude components across several components, you should create a VSB project, exclude the functionality, then base a VIP on your configured VSB.

Excluding Components Using the Kernel Editor

In this task, you exclude WDB agent services from a VIP using the Kernel Configuration Editor.

This process is described in Excluding Components in a Kernel Image, p.38, and is included here for convenience.

To exclude WDB agent services from a VIP, do the following:

1. Expand your VIP project, then double-click the Kernel Configuration node to open the Kernel Configuration Editor.

2. Right-click in the Component Configuration pane, then select Find from the context menu.

3. In the Find dialog’s Find Scope pane, select Description, then in the Pattern field, type WDB. The dialog displays a list of matching entries.

4. Select WDB agent components, then click Find. The Component Configuration tree displays it in context.

5. Right-click WDB agent components, then select Exclude.

The Exclude dialog displays all the WDB-related components that will be excluded from the kernel image.

6. Click Next. Workbench determines if there are any dependent components that must also be excluded along with the WDB components, and displays them.

7. To complete the configuration, click Finish.

The Kernel Configuration Editor shows the WDB agent components, but it is no longer bold. This means that the components are installed and available, but not included in your kernel image. There is also an overlay icon that indicates that the component has changed. The change has not yet been saved, however. The change will be saved automatically when your project is built.

8. In the Project Explorer, right-click your project and select Build Project, or click the Build Projects icon on the toolbar. The WDB components are excluded from the resulting VxWorks kernel image.

9 Deploying VxWorks Systems9.3 Adding Kernel Applications to a VxWorks Image

123

Excluding Components Using a VSB Project

In this task, you exclude System Viewer agent services from your VIP using the Kernel Configuration Editor.

This process is described in 4.9 Example: Customizing VxWorks Libraries as a Base For a VIP, p.47, and is included here for convenience.

To exclude System Viewer components from a project, do the following:

1. Double-click your VSB, then double-click the Source Build Configuration node.

2. Search for System Viewer components in the following way:

a. Right-click in the Option pane, then select Find.

b. Type a letter or two of the option’s name into the Pattern field, using wildcard characters if necessary.In this case, typing an S displays Enable System Viewer Instrumentation Support.

c. Select Enable System Viewer Instrumentation Support and click Find. The component appears in the Option pane.

3. In the Option pane, right-click Enable System Viewer Instrumentation Support and select Change value.

4. Scroll to the right (if necessary) and from the drop-down list select n to deactivate System Viewer support.

5. Press CTRL+S to save your changes, or close the editor and select Yes when you are prompted to save.

6. Build the project by right-clicking it in the Project Explorer, then selecting Build Project. Since you are recompiling the VxWorks libraries, this can take awhile.

If the project builds successfully, Build Finished in Project ‘project_name’ appears in the Build Console.

9.3 Adding Kernel Applications to a VxWorks Image

In this section, you learn how to add an application to a VxWorks Image project (VIP) so that VxWorks starts the application automatically. When you build a VIP with application subprojects, it helps assure correct linking and dependency-checking.

Only application projects like downloadable kernel modules or user-defined projects can be linked to a VIP this way, because they are solely source code containers. Linking object files or object codes to the VxWorks image is done differently, by editing the Makefile and setting the EXTRA_MODULE or LIBS macros.


124


■ Task 1: Link the application projects to the VIP.

■ Task 2: Add the application initialization routines to the VIP.

■ Task 3: Configure the VxWorks kernel to support your application.

■ Task 4: Build the VIP.

Before You Begin

You must have created kernel application projects, populated them with code, and successfully built the projects. Then, you can make the kernel application project a subproject of a VxWorks Image project.

NOTE: If your BSP provides a “bare-bones” VxWorks configuration, you may want to use the Kernel Configuration Editor Autoscale facility to detect and add most of the VxWorks functionality you require.

Task 1: Link the application projects to the VIP.

In this task, you establish the links between your applications and the VIP.

To link applications to the VIP, do the following:

1. Right-click the project that you want to make into a subproject and choose Project References > Add as Project Reference.

2. In the dialog, click the check box next to the superproject that should be the parent of your application. Highlighting the project is not enough.

3. Click OK to create the link. The application project appears under the VIP in the Project Explorer.

Task 2: Add the application initialization routines to the VIP.

In this task, you add the application routines to the VIP. Later, when VxWorks boots, it initializes all operating system components (as needed) and passes control to the application for initialization.

To add application initialization routines to the VIP, do the following:

1. To add kernel application initialization calls to VxWorks, double-click userAppInit.c to open the file for editing.

2. In the usrAppInit( ) function, add the necessary calls to start your application.

3. Close the file, and select Yes when prompted to save the changes.

Task 3: Configure the VxWorks kernel to support your application.

In this task, you configure VxWorks to support the calls your application makes to the kernel. This enables the application to link to your image.

To configure VxWorks to support your application, do the following:

1. Double-click the VIP to expand it.

2. Double-click the Kernel Configuration node to open the Kernel Configuration Editor.

9 Deploying VxWorks Systems9.4 Example: Bundling a VxWorks Image

125

3. Right-click in the Component Configuration pane, then select Autoscale. Click Yes to continue.

Autoscale compiles your code, analyzes the symbols in your object modules, maps them to components, and shows you those components.

4. Do one of the following, and then click OK:

■ To include specific components, click the check box next to the component.

■ To include all of the components, click Select All.

Autoscale next analyzes your code, and shows you the components that do not seem to be required by your application.

5. Do one of the following.

■ To exclude any of those components, click the check box next to them.

■ To accept Autoscale’s judgement that all are unneeded, click Select All.

Be careful when you elect the components to remove. Autoscale is not infallible. Some of the listed components may still be needed by your application.

6. Click OK. Autoscale removes the selected components, and returns to the Component Configuration pane.

Task 4: Build the VIP.

In this task, you build the VIP you configured in this example so it links to and launches your applications

There may be some components that Autoscale did not detect, or it may have suggested that you remove a component that you actually need. If you Autoscale, build, and get link errors, you need to repeat Task 3: Configure the VxWorks kernel to support your application. You can then add the necessary additional components from the Kernel Configuration Editor.

To build the VIP for this example, do the following:

■ In the Project Explorer, right-click the VIP and deselect Build Project.

Workbench automatically saves the changes you made in the Kernel Configuration Editor, then builds your project.

For more information about Autoscale and the Kernel Configuration Editor, open the editor and press the help key for your host.

9.4 Example: Bundling a VxWorks Image

In this example, you bundle RTPs and Libraries with a VxWorks image, to complete the deployment phase that follows the 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.82.

In the prerequisite example, you created two RTP applications and a library, and then configured your applications to call the library either as a shared library at run


126

time, or as a plug-in when needed by the application. You then ran the applications manually in the VxWorks simulator.

In this final phase, you create a way of statically identifying the run time location of your shared library, instead of typing the entire LD_LIBRARY_PATH command when you launch the applications. You must do this for both applications, because the application that uses the library as a plug-in also needs to be able to find libc.so.1. You must also add initialization code, so VxWorks can start your applications automatically.


■ Task 1: Set the target-side run path for an application.

■ Task 2: Change fooPlugRtpApp to reference ROMFS instead of the workspace.

■ Task 3: Rebuild your RTP applications.

■ Task 4: Create a VxWorks ROMFS File System project.

■ Task 5: Set up the ROMFS target file system.

■ Task 6: Rebuild your VxWorks image project.

■ Task 7: Restart the VxWorks simulator and view ROMFS contents.

■ Task 8: Launch the RTP applications and disconnect the VxWorks simulator.

■ Task 9: Add the application initialization routines.

■ Task 10: Verify that your application launches automatically.

Task 1: Set the target-side run path for an application.

In this task, you use the -rpath compiler option to set the target-side run path for the application.

To set the target-side run path for an application, do the following:

1. In fooRtpApp, right-click the build target fooRtpApp (fooRtpApp.vxe), then select Properties.

2. In the Build Properties dialog, select the Build Tools tab to bring it forward. Then, verify that the build tool is set to Linker and the active build spec is one of the following:

■ SIMPENTIUMdiab_RTP for Windows and Linux

■ SIMSPARCSOLARISdiab_RTP for Solaris

3. Click Tool Flags, verify that Create a dynamic executable is selected, and then click OK.

4. In the text field next to Tool Flags, append the directory that will hold the shared library on your target (this is known as the run path), in one of the following ways:

■ For the Wind River Compiler, type the following command:

-rpath /romfs/lib

■ For the Wind River GNU Compiler, type the following command:

-Wl,-rpath /romfs/lib


127

/romfs is the default root directory of the ROMFS created by the VxWorks ROMFS File System project that you will create to hold your applications and library in Task 4: Create a VxWorks ROMFS File System project.

5. Click OK to save your settings and close the dialog.

6. In fooPlugRtpApp, do the following:

a. Open the build properties for fooPlugRtpApp (fooPlugRtpApp.vxe).

b. On the Build Tools tab, make sure Linker and the correct build spec are selected.

c. Click Tool Flags and verify that Create a dynamic executable is selected.

d. Append the correct -rpath compiler option to the Tool Flags command.

e. Click OK to save your settings.

Task 2: Change fooPlugRtpApp to reference ROMFS instead of the workspace.

In this task, you modify the application so it references ROMFS instead of the workspace, as the deployed location for the applications and library.

To change the application reference to ROMFS, do the following:

1. In fooPlugRtpApp, double-click fooPlugRtpApp.c to open it in the editor.

2. Change the dlopen call to:

handle = dlopen("/romfs/lib/barLib.so", RTLD_NOW);

3. Close fooPlugRtpApp.c, and click Yes to save your changes.

Task 3: Rebuild your RTP applications.

In this task, you rebuild the RTP applications to incorporate your changes.

To rebuild the RTP applications, do the following:

1. Right-click fooPlugRtpApp and select Rebuild Project.

2. Right-click fooRtpApp and select Rebuild Project.

Both applications should build without errors.

Task 4: Create a VxWorks ROMFS File System project.

In this task, you create a VxWorks ROMFS file system project that you will use to create the target file system where your applications and library will reside.

To create a VxWorks ROMFS file system project, do the following:

1. In the Project Explorer, select VIPsimpc so the new ROMFS project will become a subproject of your VIP.

2. Select File > New > VxWorks ROMFS File System Project.

3. In the Project name field, type romfsFS.

4. Leave Create project in workspace selected, and click Finish.

Your project appears under VIPsimpc in the Project Explorer, and the File System Contents editor opens.


128

Task 5: Set up the ROMFS target file system.

In this task, you set up the ROMFS target file system and include your applications and library.

To set up the ROMFS target file system, do the following:

1. In the upper left corner of the File System Contents editor, click Show all projects.

2. In the editor, create bin and lib directories, in the following way:

a. Click New Folder, then type bin in the Name field. Click OK.

b. Click New Folder again, then type lib in the Name field.

c. Click OK.

The new directories appear in the Target contents pane.

3. Add your application binaries in the following way:

a. Click the bin directory to select it.

b. In the Host contents pane, open fooPlugRtpApp and select fooPlugRtpApp (fooPlugRtpApp.vxe).

c. Click Add.1

4. With the bin directory still selected, open fooRtpApp and select fooRtpApp (fooRtpApp.vxe), and click Add.

In the Target contents pane, the bin directory should contain fooPlugRtpApp.vxe and fooRtpApp.vxe.

5. Add your shared library in the following way:

a. Click the lib directory to select it.

b. In the Host contents pane, open barLib and select barLib (barLib.so).

c. Click Add.

6. With the lib directory still selected, add the VxWorks standard shared library in the following way:

a. Click Add External.

b. Navigate to installDir/vxworks-6.x/target/usr/root/cpuTool/bin.

Substitute the correct path for installDir, the correct version number for 6.x, and for cpuTool, and select SIMPENTIUMdiab for Windows and Linux or SIMSPARCSOLARISdiab for Solaris.

c. Select libc.so.1 and click Open. In the Target contents pane, the lib directory should contain barLib.so and libc.so.1.

7. Close the File System Contents editor, and click Yes to save the changes.

1. If you select something in the Target contents pane and then need to unselect it, click in the pane and press ESC.


129

Task 6: Rebuild your VxWorks image project.

In this task, you rebuild the VxWorks image project to include the changes you made in this example.

To rebuild the VxWorks image project, do the following:

■ In the Project Editor, right-click your VIPsimpc project, then select Rebuild Project. Build output appears in the Build Console.

Task 7: Restart the VxWorks simulator and view ROMFS contents.

In this task, you restart the VxWorks simulator and check the contents of the ROMFS you created earlier.

To restart the VxWorks simulator and check the ROMFS, do the following:

1. In the Remote Systems view, select the vxsim# connection you created earlier in this example, and click Connect ‘vxsim#’.

The VxWorks simulator window opens and displays the host shell running the boot sequence for your kernel image.

2. Switch the host shell from the C interpreter to the command interpreter by typing cmd. The prompt changes from -> to #.

3. Examine the contents of the ROMFS bin directory by running the following command:

[vxWorks *]# ls "/romfs/bin"

In the output that appears, you will see fooRtpApp.vxe and fooPlugRtpApp.vxe.

/romfs/bin/. /romfs/bin/.. /romfs/bin/fooRtpApp.vxe /romfs/bin/fooPlugRtpApp.vxe

4. Examine the contents of the ROMFS lib directory by running the following command:

[vxWorks *]# ls "/romfs/lib"

In the output, you will see both libc.so.1 and barLib.so.

/romfs/lib/. /romfs/lib/.. /romfs/lib/libc.so.1 /romfs/lib/barLib.so

Task 8: Launch the RTP applications and disconnect the VxWorks simulator.

In this task, you start your RTP applications and then disconnect the VxWorks simulator.

To launch RTP applications and disconnect the VxWorks simulator, do the following:

1. In the vxsim window, launch fooRtpApp using the following command:

rtp exec “/romfs/bin/fooRtpApp.vxe”

In the output that appears, you can see that your RTP application is launched and then calls the shared library.


130

[vxWorks *]# rtp exec "/romfs/bin/fooRtpApp.vxe"Launching process '/romfs/bin/fooRtpApp.vxe' ...Process '/romfs/bin/fooRtpApp.vxe' (process Id = 0x11739178) launched.I am main() in fooRtpAppI am bar() in barLibI fooRtpApp just called bar() in barLib

2. Launch fooPlugRtpApp using the following command:

rtp exec “/romfs/bin/fooPlugRtpApp.vxe”

In the output that appears, you can see that your RTP application is launched and then calls the shared library, but as a plug-in.

[vxWorks *]# rtp exec "/romfs/bin/fooPlugRtpApp.vxe"Launching process '/romfs/bin/fooPlugRtpApp.vxe' ...Process '/romfs/bin/fooPlugRtpApp.vxe' (process Id = 0x106af1a8) launched.I am main() in fooPlugRtpAppI am bar() in barLibI fooPlugRtpApp just called bar() in barLib as plug-in using dlopen()

3. To disconnect from the VxWorks simulator do one of the following:

■ Close the vxsim# window. ■ Click Disconnect ‘vxsim#’ on the Remote Systems toolbar.

Task 9: Add the application initialization routines.

In this task, you add the application initialization routines to the VxWorks Image project.

To add application initialization routines to a VIP, do the following:

1. Double-click userRtpAppInit.c to open the file for editing.

2. In the usrRtpAppInit( ) function, add the following commands to start fooRtpApp.vxe:

/* Includes */

#include <vxWorks.h>#include <rtpLib.h>#include <stdio.h>#include <errno.h>

/************************************************************************* usrRtpAppInit - initialize the users RTP applications.*/ void usrRtpAppInit (void)

{/* TODO - add your own application launch code here */char * vxeName = "/romfs/bin/fooRtpApp.vxe";char * argv[2];RTP_ID rtpId = NULL;

/* set the application's arguments */

argv[0] = vxeName;argv[1] = NULL;

/* Spawn the RTP. No environment variables are passed */

if ((rtpId = rtpSpawn (vxeName, argv, NULL, 220, 0x10000, 0, 0)) == NULL)

{printErr ("Impossible to start fooRtpApp.vxe (errno = %#x)", errno);}

}


131

3. Close the file and select Yes when asked to save the changes.

4. Right-click the VIP and select Rebuild Project.

Task 10: Verify that your application launches automatically.

In this task, you restart the VxWorks simulator, to make sure your application launches automatically.

To verify that your application launches automatically, do the following:

1. In the Remote Systems view, select the vxsim# connection you created earlier in this example, and click Connect ‘vxsim#’.

2. The VxWorks simulator window opens and displays the host shell running the boot sequence for your kernel image.

3. Once the boot sequence is completed, verify that the simulator launched fooRtpApp.vxe. The following output should appear:

-> I am main() in fooRtpAppI am bar() in barLibI fooRtpApp just called bar() in barLib

Where to Go Next

For more information about deploying your kernel and RTP applications, see the following documents:

■ VxWorks Application Programmer’s Guide: RTP Applications

■ VxWorks Kernel Programmer’s Guide: Kernel Applications.


132

133

PART VI

Reference

A What Are All These Project Files For? ................................... 135

B Debugging a VxWorks 5.5 Target ........................................... 149

C Glossary .................................................................................... 157


134

135

AWhat Are All These Project Files For?

A.1 Introduction 135

A.2 Files Common to Many Project Types 136

A.3 Project Files in VxWorks Image Projects 137

A.4 Project Files in VxWorks Source Build Projects 140

A.5 Project Files in Downloadable Kernel Module Projects 142

A.6 Project Files in Real-Time Process Projects 144

A.7 Project Files in Boot Loader/BSP Projects 146

A.8 Project Files in Shared Library Projects 147

A.1 Introduction

As soon as you create a new project, before you add any files or subprojects of your own, you will notice that the project contains quite a few project specific files.

This chapter explains the function of each of these files, as well as other information such as the following:

■ Whether you can add your own code to them.

■ If you should archive them with your sources

■ If the file is generated each time the project is built.

Filtering Your Display

If you applied filters to the Project Explorer display, you may not see some of these files in your project. Filtering the display can be useful, because it helps you focus on the files that are important to your project.


136

To filter your project display, do the following:

1. Click the downward arrow in the upper right corner of the view, and select Customize View.

2. Select or clear the check boxes for particular types of files.

The selected file types are filtered out of the display, though they are still part of your project. You can see them if you look in the project’s directory in your workspace.

A.2 Files Common to Many Project Types

Some project files appear in almost all Workbench projects. This section gives you an idea what these files are used for.

Container Nodes Within Your Project

.cprojectCDT project file containing CDT-specific information about the project.

.projectThis is an Eclipse platform project file that contains builder information and project nature. Without it, Eclipse and Wind River Workbench are unable to identify projects.

.wrmakefileThis file is a template that Workbench uses to generate the project’s Makefile. You can add your own build targets and make rules to this file, and they will be automatically dumped into the Makefile.

.wrprojectThis file contains common Workbench project properties such as build properties, project type specification, and platform association.

Build TargetsWorkbench creates build targets for most projects, except for VxWorks Image, VxWorks Source Build, and User-Defined projects.

Wind River LaunchesWhen you create launch configurations for your project, they appear here for easy access and reuse.

BinariesProvides easy access to the project’s binaries.

IncludesShows the project’s include files.

A What Are All These Project Files For?A.3 Project Files in VxWorks Image Projects

137

Files That Appear After You Build the Project

A.3 Project Files in VxWorks Image Projects

Workbench creates the largest number of project files for VIPs. The sections below describe what role each file plays.

This VIP is based on the wrSbcPowerQuiccII BSP and includes support for the BSP Validation Test Suite.

For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.136. Below are the files that are specific to VIPs.

To find out more about the files that are generated when you build the project, see Files That Appear After the Project is Built, p.139.

MakefileThis file is regenerated each time the project is built, so do not add custom code to this file (add it to .wrmakefile instead).

The information that Workbench uses to generate this file is taken from the build spec you selected when creating the project.

Figure A-1 VIP Just After it is Created


138

ProjectNameThe icon identifies the type of project.

Kernel ConfigurationDouble-clicking this node opens the Kernel Configuration Editor, which you can use to configure your VxWorks image. See 4.4 Configuring VxWorks, p.35.

vxWorks (default)vxWorks.bin (default)vxWorks.hex (default)

When you build your project, the vxWorks build target will be built using the project’s default build spec (the one you chose when creating the project).

VIP build targets take the form vxWorks[type].[format], where type can be empty (the default RAM-based image), _rom, _romCompress, or _romResident, and format can be empty (the default ELF image), .bin (binary output), or .hex (Motorola S-Record output).

To switch the build target type, select a new active build spec by right-clicking the build target, then selecting Build Options > Set Active Build Spec and selecting the type you want.

To create a .bin or .hex build target, you must build it explicitly by right-clicking it and selecting Build Target.

BSP nodeThis node links in BSP files used by the VIP. They are available for browsing purposes only.

linkSyms.cA configuration file that includes code from the VxWorks archive by creating references to the appropriate symbols. It contains symbols for components that do not have initialization routines.

It is dynamically generated, so do not check it in to your version control system.

prjComps.h A configuration file that contains the preprocessor definitions (macros) used to include VxWorks components.


prjConfig.c A configuration file that contains initialization code for components included in the current configuration of VxWorks.

It is dynamically generated, so do not check this file in to your version control system.

prjParams.h A configuration file that contains component parameters.


A What Are All These Project Files For?A.3 Project Files in VxWorks Image Projects

139

Files That Appear After the Project is Built

Several new files are added to the project during the build process.

romStart.cAlong with the BSP files, this file provides the other half of the sources used by the VIP. It is linked in for browsing purposes only.

usrAppInit.c A stub where you can add DKM application initialization routines.

usrRtpAppInit.c A stub where you can add RTP application initialization routines.

bspvts.makefileWorkbench uses this makefile fragment to invoke the scripts for the BSP Validation Test Suite.

creation.logProvides information related to the creation of the VIP.

Makefile.mkThis file is called from the project’s Makefile. It includes a list of components and build parameters, and connects the Workbench project to the VxWorks build system.

Do not edit this file.

projectName.wpj This file contains information about the project. Workbench uses it to generate the project’s Makefile, as well as project source files such as prjConfig.c.

vxWorks.makefileThis template contains all necessary instructions to build the VIP. Workbench invokes it from the project’s Makefile.


140

A.4 Project Files in VxWorks Source Build Projects

Workbench also creates a large number of project files for VSBs. The sections below describe what role each file plays.

This VSB is based on the MIPSI64R2 CPU, and has VxWorks sources linked in.

Figure A-2 VIP After it is Built

defaultThis is the build output folder, named after the selected build spec.

compObjs.lstThis is generated by the run-time build system during the build.

prjObjs.lstThis is generated by the run-time build system during the build, and lists the object files linked into the kernel image.

A What Are All These Project Files For?A.4 Project Files in VxWorks Source Build Projects

141

For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.136. Below are the files that are specific to VSBs.


Figure A-3 VSB Just After it is Created


Source Build ConfigurationDouble-clicking this node opens the VxWorks Source Build Configuration Editor, which you can use to configure your VxWorks libraries. See 4.7 Creating a VxWorks Source Build Project, p.44.

hThis directory contains the header files and other files that are generated during the configuration of the VSB. They contain the configuration information for the VSB used for builds, and interfaces that are used in conjunction with VIPs and DKMs.

SourcesIf you linked in the VxWorks sources when creating your project, this node provides access to the installDir/vxworks-6.x/target/h and installDir/vxworks-6.x/target/src directories.

creation.logProvides information related to the creation of the VSB.

vsb_bs.vxconfigvsb.vxconfig

These files are used as inputs to the Source Build Configuration editor.

vsb.configThis file is one of the files generated from the Source Build Configuration editor when changes are saved.


142



A.5 Project Files in Downloadable Kernel Module Projects

Workbench creates a smaller set of files for DKMs than it does for VIPs. In addition to the project files, you will notice the source files from the sample program ball. You cannot build a DKM project that does not contain sources.

vsb_comp_list.mkvsb_defs.mk

These make fragments are used for building the VSB.

vsbClean.tclvsbdefs.tcl

These are internal files used with the vxprj and Workbench interface to display and manipulate the settings of VSBs.

Figure A-4 VSB After it is Built

Archives FolderThis folder contains the generated archive files for the project.

architectureThis folder contains the binary output of the build, in other words the kernel libraries that contain the configuration information for the VSB.

objarchitectureBuildspectestThis folder contains test related object files (they are not part of any existing archive).

A What Are All These Project Files For?A.5 Project Files in Downloadable Kernel Module Projects

143

For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.136. Below are the files that are specific to DKMs.




Figure A-5 DKM Just After it is Created


TargetName.out (BuildSpec [- debug])

This partially linked and munched object, produced by the Linker build tool, is intended for downloading. The lack of an upward arrow indicates that it is not passed to the next level.

TargetName_partialImage.oThis partially linked but not munched object, produced by the Linker, is for subproject support only; it is not intended for download. The upward arrow indicates that the build target is passed to the next level.


144

When building DKM projects, the generated files that appear are determined by the build tool you chose.

For example, you will not get both a *.a archive target (produced by the Librarian) and a *.out target (produced by the Linker). In addition, whether you see an upward arrow on your build target depends on whether you chose to pass the build target up the hierarchy or not.

A.6 Project Files in Real-Time Process Projects

Workbench creates a similar set of files for RTPs as it does for DKMs. In addition to the project files, you will notice the source file from the sample program helloworld. You cannot build an RTP project that does not contain sources.

Figure A-6 DKM After it is Built

Build Output All build output is directed to this folder.

Archives FolderThis folder appears when you build using the Librarian; it contains the generated archive file for the project.

TargetName.a (BuildSpec [- debug]) This archive, produced by the Librarian build tool, has to be statically linked into an executable.

A What Are All These Project Files For?A.6 Project Files in Real-Time Process Projects

145

For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.136. Below are the files that are specific to RTPs.




When building RTP projects, the generated files that appear are determined by the build tool you chose.

For example, you will not get both a *.a archive target (produced by the Librarian) and a *.out target (produced by the Linker). In addition, whether you see an upward arrow on your build target depends on whether you chose to pass the build target up the hierarchy or not.

Figure A-7 RTP Just After it is Created


TargetName.vxe (BuildSpec [- debug])

This is a fully linked VxWorks executable.

Figure A-8 RTP After it is Built


146

A.7 Project Files in Boot Loader/BSP Projects

Workbench creates only a few files to support this type of project.

For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.136. Below are the files that are specific to boot loader and BSP projects.


Build Output

All build output is directed to this folder.

Archives FolderThis folder appears when you build using the Librarian; it contains the generated archive file for the project.

TargetName.a (BuildSpec [- debug]) This archive, produced by the Librarian build tool, has to be statically linked into an executable.

TargetName.vxe (BuildSpec [- debug])

This is a fully linked VxWorks executable.

Figure A-9 VxWorks Boot Loader/BSP Project Just After it is Created


BSPname (bootloader) This node reflects the BSP you used when creating the project, as well as the currently active build spec.

A What Are All These Project Files For?A.8 Project Files in Shared Library Projects

147


Since BSPs are prebuilt and installed with your Platform, you will not notice much difference when building this sort of project. Only one new file is created during a build of this type of project.

A.8 Project Files in Shared Library Projects

Workbench creates a similar set of files for Shared Libraries as it does for RTPs.

For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.136. Below are the files that are specific to shared libraries.




BSP nodeIf you selected Copy files to project, this contains a standalone copy of the BSP sources (in installDir/workspace/project_name/BSP_name). You may modify and build these sources without altering the VxWorks install tree.

BSP nodeIf you did not select Copy files to project, this folder will display an upward arrow overlay, and will reference the original BSP sources (in installDir/vxworks-6.x/target/config/BSP_name).

Figure A-10 Shared Library Just After it is Created


TargetName.so The shared library used by the VxWorks executable.


148

Whether you see an upward arrow on your build target depends on whether you chose to pass the build target up the hierarchy or not.

Figure A-11 Shared Library After it is Built

Build OutputAll build output is directed to this folder.

149

B Debugging a VxWorks 5.5 Target

B.1 Introduction 149

B.2 Before You Begin 149

B.3 Creating a VxWorks 5.5 DKM Project 150

B.4 Creating a VxWorks 5.5.x Target Server Connection 151

B.5 Launching a Kernel Task and Attaching the Debugger 151

B.6 Using Existing Tornado 2.x Projects 154

B.1 Introduction

This tutorial explains how to use Workbench to create a Tornado 2.x target server connection and debug a VxWorks 5.5.x target.

B.2 Before You Begin

To use these instructions, you must have Workbench 3.x, VxWorks 5.5.x, and Tornado 2.x installed.

In the following task, you set an environment variable, provide the path to your Tornado installation for Workbench, and then run a script to update your install.properties file.

NOTE: You must have built your VxWorks 5.5.x image in Tornado before you can work with it in Workbench.


150

To allow Workbench to find your Tornado installation, do the following

1. Open a command shell window, navigate to the Workbench root installation directory (InstallDir/), and enter the following commands:

wrenv -p workbench-3.2workbench-3.2/x86-win32/bin/wrregistert22x.bat

2. When the script asks for the location of your Tornado installation, type the path and press Enter. The script updates your install.properties file.

B.3 Creating a VxWorks 5.5 DKM Project

In this example, you use the VxWorks 5.5 Downloadable Kernel Module Sample Project as the basis for your project, debug an error, and then rebuild the project.

To create and debug a VxWorks 5.5 DKM project, do the following:


2. Select File > New > Example, then select VxWorks 5.5 Downloadable Kernel Module Sample Project and click Next.

3. Select the Cobble demo, then click Finish. The project appears in the Project Explorer.

4. Right-click the new cobble_55 project, then select Build Options > Set Active Build Spec. From the dialog that appears, change the active build spec to PPC603diab, select Debug mode, and click OK.

5. Right-click the project and select Build Project, or press CTRL+SHIFT+A. The Build Console displays a warning about a bug in the code.

6. Double-click the error symbol to open cobble.c to line 280, then fix the bug.

7. Edit line 133 and change the priority of task tCrunch to 210. If you do not do this, it will appear that breakpoints are not hit.1

8. Right-click the project folder and select Rebuild Project. Workbench saves your changes before starting the build. Your project should build cleanly.

9. Continue on with Creating a VxWorks 5.5.x Target Server Connection.

1. You can display line numbers by right-clicking in the Editor, selecting Preferences, then selecting Show line numbers, or you can scroll up or down and click in the file. The line number and column position of the cursor is displayed at the bottom of the window.

B Debugging a VxWorks 5.5 TargetB.4 Creating a VxWorks 5.5.x Target Server Connection

151

B.4 Creating a VxWorks 5.5.x Target Server Connection

In this task, you create a target server connection for the project you created in Creating a VxWorks 5.5 DKM Project.

To create a VxWorks 5.5 target server connection, do the following:

1. From the Remote Systems view toolbar, click Define a connection to remote system. The New Connection wizard opens.

2. From the Connection Type list, select Wind River VxWorks 5.5.x Target Server Connection, and click Next.

3. Click Next through the next few screens, reviewing and customizing the target server options as necessary.

4. Click Finish to create your connection definition.

Once the connection to the Tornado target server is established, it appears under default(localhost) followed by [Target Server running].

5. To connect to the Tornado 2.x target, right-click the target server and select Connect. The target connection appears under the target server connection2.

6. Continue on with Launching a Kernel Task and Attaching the Debugger.

B.5 Launching a Kernel Task and Attaching the Debugger

This example is a continuation of Creating a VxWorks 5.5.x Target Server Connection, and includes the following tasks:

■ Configuring the Debug Launch Configuration

■ Setting and Running to a Breakpoint

■ Debugging in System Mode

■ Analyzing Core Dump Files

Configuring the Debug Launch Configuration

In this task, you modify the debug launch configuration so that the debugger is attached.

NOTE: If you get a target server connection error, it could be caused by a long delay in checking out a license for the Tornado 2.x target server. To lengthen the timeout, select Window > Preferences > Target Management and increase the time in the Workbench timeout till target server must be connected field.

2. You can click next to Kernel Tasks to display the list of kernel tasks running in the system, as well as the name of the core file.


152

You use the Debug Launch Configuration dialog to define which downloadable module to load, which entry point to call, which debugging options to implement, and what the source lookup path should be.

To configure the debug launch configuration, do the following:

1. In the Remote Systems view, right-click your target, then select Target Mode. Make sure Task is selected.

2. Right-click your target again, and this time select Debug Kernel Task.

The Debug Launch Configuration dialog appears. The Name field displays your project’s build target and target name, but as yet no entry point is defined.

3. Click Browse next to the Entry Point field, select Downloads > cobble_55.out > progStart, and then click OK.

4. Click the Download tab to bring it to the foreground, then click Add.

5. In the Download dialog, browse to the location of your project’s build target (installDir/workspace/cobble_55/PPC603diab_DEBUG/cobble_55.out). Make sure Load Symbols to Debug Server is selected, and then click OK.

6. Click the Debug Options tab to bring it to the foreground, and then select Automatically attach spawned Kernel Tasks. The launch configuration is now complete.

7. Click Debug to launch the task and attach the debugger. Workbench changes to the Device Debug perspective, displays the task in the Debug view, and opens cobble.c in the Editor (if it is not already open) with the focus in progStart.

Setting and Running to a Breakpoint

This task is a continuation of Configuring the Debug Launch Configuration.

In this task, you set a breakpoint and then run to it. You use the Outline view to find a function so you can place a breakpoint on it. The Outline view does not appear by default in the Device Debug perspective.

When adding a breakpoint, you can specify the breakpoint’s scope: either the task that is selected in the Debug view (here, tProgStart) or every task (Unrestricted).

Workbench also allows you to specify the stop scope: either Stop Triggering Thread, or to Stop All. However, in VxWorks 5.5, Stop All (is not supported) behaves the same as Stop Triggering Thread. In this example, you do not specify this option.

To set and run to a breakpoint, do the following:

1. Open the Outline view by selecting Window > Show View > Outline.

2. Select the function cosmos. The Editor shows that section of cobble.c, with cosmos highlighted.

3. Scroll down to line 166 (containing nadaNichtsIdx) and right-click in the left Editor gutter and select Breakpoints to open the Breakpoints submenu.

B Debugging a VxWorks 5.5 TargetB.5 Launching a Kernel Task and Attaching the Debugger

153

4. In this example, the code is run by the task tCosmos, not tProgStart, so select Add Breakpoint (Scope = Unrestricted).

If you had selected Scope = tProgStart, the breakpoint would never have been triggered.

5. With your breakpoint set, select tProgStart in the Debug view and click Resume.

The task tProgStart disappears from the Debug view. Its only purpose was to launch the tCrunch, tCosmos, and tMonitor tasks that now appear in the Debug view and under Kernel Tasks in the Remote Systems view.

6. Select the task tCrunch in the Debug view to set the scope, then select the function crunch in the Outline view. The Editor highlights the function.

7. Several lines below crunch, right-click in the gutter beside line 268 (beginning while) and select Breakpoints > Add Breakpoint (Scope = tCrunch).

8. Return to the Debug view, select tCosmos, and click Resume.

9. When tCosmos hits its breakpoint, click Resume again 9 more times. At this point the task tCrunch hits its breakpoint and both tasks stop.

Debugging in System Mode

This task is a continuation of the previous task, Setting and Running to a Breakpoint.

In this task, you switch to system mode and continue with debugging. In system mode, when a breakpoint is hit, the whole system stops, and you can get the backtrace of the tasks you have attached.

To debug in system mode, do the following:

1. Before switching to system mode, highlight tCrunch and tCosmos in the Debug view, click Resume, then click Disconnect (not Terminate).

2. In the Remote Systems view, right-click your target (which should still be running), then select Target Mode > System to switch into system mode.

3. Open the target console by right-clicking your target and selecting Target Tools > Target Console.

4. At the prompt, type i to display the list of running tasks. If you clicked Disconnect (and not Terminate), tCosmos and tCrunch are still running.

5. In the Remote Systems view, right-click your target and select Attach to Kernel (System Mode).

6. Right-click system tasks as needed, and then select Attach to Kernel Task (System Mode).

7. Right-click tCosmos and tCrunch and select Attach to Kernel Task. The tasks appear in the Debug view.

8. Select monitor in the Outline view to switch the Editor display to that part of cobble.c.

9. Set a breakpoint by right-clicking in the gutter next to line 302 (beginning if).


154

If you select Breakpoints > Add Breakpoint (Scope = tCosmos), the breakpoint will not be triggered because the code is only run by the tMonitor task. Therefore, set the breakpoint using either Scope = Unrestricted or Scope = tMonitor (you must select tMonitor in the Debug view before you can choose it as the breakpoint scope).

When the breakpoint is triggered, the whole system stops, as shown in the Remote Systems view and in the Debug view. If you type in the target console, nothing appears because the whole target is stopped.

10. Remove the breakpoint by right-clicking it in the Breakpoints view and selecting Remove. In the Debug view, select tMonitor and click Resume to resume the system.

Analyzing Core Dump Files

This task is a continuation of Debugging in System Mode. In this task, you analyze core dump files to view backtraces of various tasks.

To analyze core dump files for backtraces, do the following:

1. On the Remote Systems view toolbar, click Define a connection to remote system.

2. In the New Connection wizard, select Wind River VxWorks 5.5.x Core Dump Connection, then click Next.

3. On the next screen, navigate to the location of your core dump file and the VxWorks kernel image.

4. Click Next through the next few screens, adjusting settings if necessary, and then click Finish.

Since Immediately connect to target if possible is selected by default, the connection definition appears in the Remote Systems view and Workbench connects.

A dialog appears telling you that the core dump was successfully attached, but since Workbench cannot determine the cause for a VxWorks 5.5 core dump the cause is listed as UNKNOWN. The dialog also displays the program counter of the current execution context.

5. Go to the Debug view. The backtrace of the current execution context appears. Note that the run control icons are disabled.

6. (Optional) Attach to other tasks and see their backtraces.

B.6 Using Existing Tornado 2.x Projects

In this task, you import an existing Tornado 2.x project into Workbench. Workbench provides added value over Tornado in your ability to use the Search view, the Outline view, and the very powerful source analysis tools to manage your projects.

B Debugging a VxWorks 5.5 TargetB.6 Using Existing Tornado 2.x Projects

155

To import an existing Tornado project into Workbench, do the following:


2. Create a new user-defined project by selecting File > New > User-Defined Project.

3. In the Target Operating System dialog, select Wind River VxWorks 5.5 (this allows you to use the Tornado 2.x compilers), and then click Next.

4. On the next screen, type a descriptive name into the Project name field, then select Create project at external location.

5. Navigate to the location of your existing Tornado 2.x project, and click Finish.

A dialog appears telling you that the directory you pointed to already contains project information.

6. Click Yes to overwrite existing project information. Your project appears in the Project Explorer.

7. Right-click the new project and select Build Project, or press CTRL+SHIFT+A. Since this is a user-defined project, the build calls the Makefile generated by Tornado 2.x tools.

8. (Optional) To add or remove files, use the Tornado 2.x IDE or edit the Makefile manually.

9. Launch Tornado from Workbench, by selecting Target > Launch Wind River Tornado.

To debug a kernel module, proceed as described in B.5 Launching a Kernel Task and Attaching the Debugger, p.151. You can also import and rebuild a kernel project.

Limitations and Known Issues

For module synchronization, you must specify the -s option to the target server.

When the target loads a module, it appears in the Remote Systems view. You can select and delete it, and it will disappear from the Remote Systems view, but the module is still running on the target. This is because the target server cannot remove a module loaded by the target. This is a limitation of Tornado 2.x, and the Workbench debugger cannot overcome this limitation.


156

157

C Glossary

C.1 Introduction 157

C.2 Searching for Terms in Online Documentation 157

C.3 Terms 158

C.1 Introduction

This glossary contains terms used in the VxWorks version of Wind River Workbench.

C.2 Searching for Terms in Online Documentation

If the term you want is not listed in this glossary, you can search for it throughout all online documentation.

1. If it is not already open, open the Help view by pressing the help key for your host.

2. At the bottom of the view, select Search.

3. Type the term you are looking for into the Search expression field.

4. Click Go. Links to topics containing the term will appear, along with a short example of the surrounding text.

5. To open the document containing a topic, click the topic in the list.

■ To switch from the document you were reading back to the search results, click Back.

■ To see where this topic’s document appears in the help Table of Contents, click the Show in All Topics icon in the upper right corner of the help view.


158

If the result set is very large, the information you are looking for might not appear in the top 10 or 15 results.

To refine a search to reduce the number of results, you can create a Search Scope Set that will search only Wind River documentation:

1. Click Search at the bottom of the Help view.

2. Click the Default link next to Search Scope.

3. In the Select Search Scope Sets dialog box, click New.

4. Type in a name for your new Scope Set, for example WR Documentation. Click OK.

5. Select your new Search Scope Set, then click Edit.

6. In the Search Scope dialog box, click Search only the following topics.

7. From the Working set content pane, select the document sets to which you want to narrow the search, for instance Wind River Documentation > References.

8. Click OK twice to return to the help browser, where your new search scope appears next to the Search scope link.

9. Click Go. The results will appear in the Search list.

For more information about online help, click All Topics, then navigate to Wind River Partner Documentation > Eclipse Workbench User Guide > Tasks > Accessing help.

C.3 Terms

active view

The view that is currently selected, as shown by its highlighted title bar. Many menus change based on which is the active view, and the active view is the focus of keyboard and mouse input.

back end

Functionality configured into a target server on the host determines how it will communicate with a particular target agent on the target.

For example, you use a wdbrpc back end for Ethernet connections, wdbpipe for VxWorks simulators, wdbserial for serial connections, and wdbproxy for UDP, TCP, and TIPC connections.

The target server must be configured with a back end that matches the target agent interface with which VxWorks has been configured and built.

board support package (BSP)

A Board Support Package (BSP) consists primarily of the hardware-specific VxWorks code for a particular target board. A BSP includes facilities for hardware

C GlossaryC.3 Terms

159

initialization, interrupt handling and generation, hardware clock and timer management, mapping of local and bus memory space, and so on.

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.

color context

The color assigned to a particular process in the Debug view; this color carries over to breakpoints in the Editor and to other views that derive their context from the Debug view.

cross-development

The process of writing code on one system, known as the host, that will run on another system, known as the target. The target is generally hardware that you would have no other convenient way to program, such as a chip destined for a mobile phone.

DKM

VxWorks Downloadable Kernel Module.

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, but with the appropriate debug flags (for example with -g, or -g-dwarf-2). They can not be stripped of symbols.

editor

The editor is a visual component within Wind River Workbench. It is typically used to edit or browse a file or other resource. Each Workbench perspective displays the Editor area even when no files are open.

Modifications made in the Editor follow an open-save-close life cycle model. Multiple instances of an Editor type may exist within a Workbench window.

element

An element is an entity that holds source analysis information of any kind, standing for a declaration or occurrence of a constant, preprocessor option, variable, function, method, type, or namespace in a parsed source code file.

gutter

The left vertical border of the editor view where breakpoints and the program counter appear.


160

help key

The help key (or combination of keys) is determined by your host platform: press F1 on Windows, or Ctrl+F1 on Linux and Solaris to get context-sensitive help.

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.

JDT

Java Development Toolkit provided by the Eclipse organization (http://www.eclipse.org) and included with Workbench.

kernel configuration editor

The editor that allows you to configure the kernel of a VxWorks Image project.

kernel module

A piece of code that can be loaded and unloaded without the need to rebuild and reboot the kernel.

launch configuration

A run-mode launch configuration is a set of instructions that instructs Workbench to connect to your target and launch a process or application. A debug-mode launch configuration completes these actions and then attaches the debugger.

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 target. In Workbench, this is set within the Remote Systems view’s Target Connection Properties.

overview ruler

The vertical borders on each side of the Editor view. Breakpoints, bookmarks, and other indicators appear in the overview ruler.

perspective

A perspective is a group of views and Editors. One or more perspectives can exist in a single Workbench window, each perspective containing one or more views and Editors. Within a window, each perspective may have a different set of views but all perspectives share the same set of Editors.

Default Workbench perspectives include the Application Development and Device Debug perspectives, but if you click Window > Open Perspective > Other, additional perspectives (such as those installed with Run-Time Analysis Tools) are available to you.

NOTE: The Help button on Solaris keyboards does not open Workbench help due to a problem in Solaris/GTK+. Instead, use Ctrl+F1 to access help.

http://www.eclipse.org

C GlossaryC.3 Terms

161

plug-in

An independent module, available from Wind River, the Eclipse Foundation, or from many Internet Web sites, that delivers new functionality to Workbench without the need to recompile or reinstall it.

program counter

The address of the current instruction when a process is suspended.

project

A collection of source code files, build settings, and binaries used to create a downloadable application or bootable system image, a kernel or RTP application, and so on.

Projects can be linked together in a hierarchical structure (displayed as a project/subproject tree in the Project Explorer) that reflects their inner dependencies, 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.

real-time process (RTP)

A VxWorks process that is specifically designed for real-time systems.

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.

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.

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.

target server

The target server runs on the host, and connects Wind River Workbench tools to the target agent. There is one server for each target; all host tools access the target through this server.

title bar

A view’s title bar contains the view name, its icon, and the view toolbar. A highlighted title bar denotes the active view.


162

toolbar

A view’s toolbar contains actions that apply only to that view (for example, Step Over in the Debug view). The toolbar also contains a context menu that contains other actions for that view.

The main Workbench toolbar contains actions such as Search that apply to Workbench as a whole, or that reflect the components that are installed.

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.

view

A view is a visual component within Workbench, typically used to navigate a hierarchy of information (such as the resources in your workspace). Only one view has focus (is active) at a time.

VIP

VxWorks Image Project.

WDB target agent

The WDB target agent runs on the target, and is the interface between VxWorks and all other Wind River Workbench tools running on the host or target.

window

The desktop development environment as a whole—the space Workbench takes up on your screen. A Workbench window can contain more than one perspective, but only one is displayed at a time.

working set

Resources you select to view or operate on as a group. For example, you can create a working set to speed up a search by restricting its scope. A working set can also help you focus by reducing the number of projects visible in the Project Explorer, the number of symbols displayed in the Outline view, and so on.

workspace

A workspace is the central location for all the resources you see in Workbench: your projects, folders, and files.

Workbench also uses the workspace to store settings that describe your working environment: which projects and views are currently open, how you have your views arranged within the perspective, whether you have breakpoints set, and so on.

The default location of the workspace is installDir/workspace, but it can be located anywhere. To keep your projects completely isolated from each other, you can create more than one workspace.

C GlossaryC.3 Terms

163

NOTE: This use of the term workspace is entirely different from the flash workspace, which is a small area of RAM needed to run the flash algorithm; that sense of the term is restricted to flash programming.


164

165

Index

Aapplication initialization routines 124applications

adding routines to VIPs 124adding to VIPs 123deploying 13how to run 112kernel 11, 123launch RTP 129rebuild RTP 127user 11writing in Workbench 11

Autoscale 124

Bback end, target server 98basename mappings 100board support package 57

creating 59customizing 12customizing manually 59for VIP 34simulator 58Wind River Workbench 58

board switches, set 23boot display, VxWorks 28boot loader

creating 51default 52redefine link address 54select drivers 55

boot parametersboot target, VxWorks 26display current 24enter new 25

boot problems, troubleshooting 27boot ROMs,ROMs, boot 27booting

configuration example 22

initiate on VxWorks 24reboot VxWorks 26

BSPSee board support package

buildredirection root directory 77spec

default and active 75PowerPC variants 69Subprojects tab of VIP 75

target, passing up to superproject 70bundle, VxWorks image 125

Ccables, connecting 22command line, import VIPs from 42components, including 37config.h

make writable 60modify 60

configuringhost machine 18jumpers 23target 20target board 22VxWorks image project 124VxWorks kernel components 36VxWorks source libraries 46

core dump, connecting to VxWorks 5.5.x 154

Ddebug server, loading symbols 100debugging

applications 113attaching the debugger 114before you begin 113dual mode 95multi-process 116


166

run program 112VxWorks 5.5 target 149

dependency checking 123development environment 18downloadable kernel module (DKM) 67driver, non-default 38dual mode debugging 95dynamic executable 126

EExamples

Adding IPNet Support to a DKM 78Building a VIP With Sources in a Subdirectory 39Bundling RTPs and Libraries with a VxWorks

Image 125Connecting a Target Server to a Target Agent 102Creating and Passing a Build Target 70Customizing a BSP 59Customizing VxWorks Libraries as a Base For a

VIP 47Debugging a VxWorks 5.5 Target 149Debugging RTPs, Shared Libraries, and Plug-ins

114Discussion of PowerPC Build Spec Variants 69Working with RTPs, Shared Libraries, and Plug-

Ins 82executable, dynamic 126exporting, object path mappings 100EXTRA_MODULE 123

FFile Transfer Protocol

See FTP serverFind dialog 37FTP server

configuring 19permissions 28

Hhardware configuration checklist 27host, configure 18hosts file, set up 21

Iimage

custom kernel 10kernel 10pre-built 10

system, deploying 13importing

object path mappings 100VIP, SMP-enabled sample 41

include search path 77INCLUDE_WDB_SYS 95INCLUDE_WDB_TASK 95indexer, source code 35IP address, verify 28IPCOM ping commands 37IPNet APIs, adding support to a DKM 78IPV6, kernel libraries 33

Jjumper

settings for target 27jumpers

how to set 23

KKconfig 47kernel

applications 11, 123booting and loading 12image 10, 37

kernel configuration editor 36, 122kernel configuration profiles 34kernel image, creating 32kernel libraries, IPv6 33Kernel Objects view, multi-process debugging 116kernel, SMP support 33

Llaunch configuration

attach task or process 111create for existing project 109create with Run menu 110from target connection 110

LD_LIBRARY_PATH 126libraries, custom VxWorks 46LIBS 123link address, redefine 54link order, adjusting 40Linker 126loading symbols to debug server 100logging, enable 20

Index

167

Mmacros

EXTRA_MODULE 123LIBS 123

Makefile templatesmigrate modified 43migrate unmodified 42

memoryoverlapped virtual 80target server cache size 99

MIPC, target server back end 98multi-process debugging 116

Nnew connection wizard 98new project wizard 13non-default driver 38

Oobject path mappings

comparison with source lookup path 113creating automatically 100exporting 100importing 100

overlapped virtual memory 80

Pping

client 37commands, IPCOM 37functionality 37search for 37support 37

polled mode 95power supply, connect 23PowerPC, discussion of build spec variants 69pre-built image 10processes, RTPs 112PROFILE_BOOTAPP 54profiles 33project

benefits of 13bsp, getting a functioning 58create in workspace 58create VSB 45DKM 67import or migrate 41importing Tornado 2.x 154in external location 58linking application projects to VxWorks image 124

rebase VSB and VIP 50ROMFS file system 127RTP 67VSB 123VxWorks

importing command line-generated 42kernel configuration profiles 33

Workbench example 15

Rreal-time process

See also RTPsrebase, VSB and VIP projects 50reboot, VxWorks 26redirection root directory 77Remote Systems view 93

basename mappings 100define a VxWorks Simulator connection 95shared connection configuration 101

ROM_SIZE 62ROMFS 127, 129RTPs

launch 129rebuild 127running 112troubleshooting 113writing 67

run path, set target-side 126

SS_rtp_INVALID_FILE error 113search path, include 77semaphores, monitoring 116serial connection

open 22set up 22

server log, WFTPD 28simulator

establishing a new connection 95VxWorks 58

SMP-enabled sample VIPs, importing 41source build

changing BSP or CPU 50configuration editor 46project, base VIP on 34project, VSB 44

source code indexer 35source lookup path, compare with object path 113starting Workbench 22Subprojects tab, setting build spec of VIP subprojects 75system image 13system mode 94System Viewer 99, 123


168

system-mode agent 95

Ttarget

agentdual mode 95polled mode 95system mode 94user mode 94

boardconfiguring 22jumpers, setting 23serial port 22Terminal view 22

booting with VxWorks 24confiugre 20file system, ROMFS 128server

back end settings 98connections

establishing new 97ethernet 97Tornado 151

definition 94file system (TSFS) 99

making writable 99memory cache size 99timeout options 99troubleshooting 104WDB Pipe back end 97WDB Proxy back end 98WDB RPC back end 97WDB Serial back end 98

Terminal viewconfigure 22entering text 23

TIPCtarget server back end 98troubleshooting connection 105

tool chain, for VIP 34Tornado

creating a target server connection 151importing Tornado 2.x projects 154Workbench finding an installation of 149

troubleshootinghardware configuration 27software configuration errors 28target server problems 104VxWorks boot problems 27

TSFSSee target server, file system 99

Uuser mode 94userAppInit.c 124user-mode agent 95

Vvirtual memory, overlapped 80VSB

See VxWorks source build projectVxWorks

boot display 28booting 24bundling RTPs and libraries 125configure 35core dump, connecting to VxWorks 5.5 154define simulator connection 95deployment 121image

configuring with Autoscale 124create custom 32pre-built 25

image projectbase on custom BSP 61base on different VSB 51based on VSB 49build 125bundle 125importing and migrating 41importing command line-generated 42kernel configuration profiles 33linking application projects to 124sources in a subdirectory 39

kernel, configuring 36libraries, configuring 46reboot 26reconfigure for deployment 121simulator 58, 95source build project 44

configuring 46target server connection, 5.5.x 151troubleshooting boot problems 27tutorial, VxWorks 5.5 149

WWDB back end

agent components 122Pipe 97Proxy 98RPC 97Serial 98

WFTPD FTP server 19WFTPD server log 28

Index

169

wizardnew connection 98new project 13

Workbenchfinding a Tornado installation 149Kernel Objects view 116starting 22

Documents

Wind River Workbench (VxWorks 6 Version) By Example, 3read.pudn.com/downloads305/sourcecode/embedded/1358019/wr_w… · ClearCase. This guide also includes troubleshooting information