WR Workbench Vxworks 6 by Example 3.3

Wind River Workbench (VxWorks 6 Version) By Example, 3.
Wind River Workbench
BY EXAMPLE
3.3
VxWorks 6 Version Edition 2
Copyright 2011 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 one of the following locations: installDir/product_name/3rd_party_licensor_notice.pdf installDir/legal-notices/ Wind River may refer to third-party documentation by listing publications or providing links to third-party Web sites for informational purposes. Wind River accepts no responsibility for the information provided in such third-party documentation.
Corporate Headquarters Wind River 500 Wind River Way Alameda, CA 94501-1153 U.S.A. Toll free (U.S.A.): 800-545-WIND Telephone: 510-748-4100 Facsimile: 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 Workbench By Example 3.3 VxWorks 6 Version Edition 2 8 Jun 11
Contents
PART I: INTRODUCTION
1 Overview ......................................................................................................
1.1 1.2 1.3 Introduction ...................................................................................................................... How This Guide is Organized ...................................................................................... Related Documentation .................................................................................................
3
3 3 4
PART II: SETTING UP YOUR ENVIRONMENT

2 Getting Started With Workbench ...............................................................
2.1 2.2 2.3 2.4 2.5 2.6 2.7 2.8 2.9 2.10 2.11 Introduction ...................................................................................................................... The Benefits of Projects ................................................................................................. Deciding on a Kernel Image ......................................................................................... Writing Applications in Workbench ............................................................................ Creating a Library to Use With an Application ......................................................... Loading and Booting a Kernel Image .......................................................................... Customizing a Board Support Package ....................................................................... Deploying an Application with a System Image ...................................................... Using the Wind River Workbench New Project Wizard .......................................... Walkthrough Examples .................................................................................................. Workbench Example Projects ........................................................................................
9
9 10 10 11 12 12 13 13 13 14 15
iii
Wind River Workbench By Example, 3.3
Setting Up Your Host & Target ...................................................................

3.1 3.2 3.3 3.4 3.5 3.6 Introduction ...................................................................................................................... What Should Your Development Environment Look Like? ................................... Configuring Your Host Machine .................................................................................. Configuring Your Target ................................................................................................ Booting a Target with VxWorks .................................................................................... Troubleshooting VxWorks Boot Problems .................................................................
17
17 18 18 20 23 25
PART III: CUSTOMIZING THE OPERATING SYSTEM

4 Configuring and Building VxWorks ..........................................................
4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8 4.9 4.10 4.11 Introduction ...................................................................................................................... Before You Begin Creating a Kernel Image ................................................................ Creating a Custom VxWorks Image ............................................................................. Configuring VxWorks .................................................................................................... Example: Building a VIP With Sources in a Subdirectory ...................................... Importing and Migrating Existing VxWorks Image Projects ................................. Creating a VxWorks Source Build Project .................................................................. Configuring Custom VxWorks Libraries .................................................................... Example: Customizing VxWorks Libraries as a Base For a VIP ............................. Rebasing VSB and VIP Projects ................................................................................... Loading the VxWorks Image onto the Target ............................................................
31
31 32 32 37 41 43 47 49 50 53 54
Working with Board Support Packages ....................................................

5.1 5.2 5.3 Introduction ...................................................................................................................... Creating an Experimental Default BSP ....................................................................... Example: Customizing a BSP ........................................................................................
59
59 59 61
PART IV: DEVELOPING AND DEBUGGING APPLICATIONS
iv
Contents
Building Applications and Libraries .........................................................

6.1 6.2 6.3 6.4 6.5 6.6 6.7 6.8 6.9 6.10 6.11 6.12 6.13 Introduction ...................................................................................................................... Deciding on an Application Type ................................................................................ Creating a Project For Your Application ..................................................................... Example: Discussion of PowerPC Build Spec Variants ........................................... Example: Creating and Passing a Build Target .......................................................... Reconfiguring Your Project Later in the Development Cycle ................................ Example: Adding IPNet Support to a DKM .............................................................. Using RTP Overlapped Virtual Memory .................................................................... Creating Statically Linked Libraries ........................................................................... Creating Shared Libraries .............................................................................................. Creating Plug-Ins ............................................................................................................ Example: Working with RTPs, Shared Libraries, and Plug-Ins ............................. Running Applications on a Hardware Target ............................................................
67
67 68 69 71 72 75 81 82 82 83 84 85 93
Connecting to VxWorks Targets ................................................................

7.1 7.2 7.3 7.4 7.5 7.6 7.7 Introduction ...................................................................................................................... What Are Target Servers and Target Agents? ............................................................. Creating a VxWorks Simulator Connection ............................................................... Defining a New Target Server Connection ................................................................
95
95 96 97 99
Example: Connecting a Target Server to a Target Agent .......................................... 104 Defining a New Remote Connection .......................................................................... 106 Troubleshooting Target Server Connections .............................................................. 106
Running and Debugging VxWorks Applications ..................................... 109

8.1 8.2 8.3 8.4 Introduction ...................................................................................................................... 109 How Can Workbench Help Me Run My Code? ........................................................ 109 How Do I Create a Launch Configuration? ................................................................ 110 Running Your Applications .......................................................................................... 113
8.5 8.6 8.7
Debugging Your Applications ...................................................................................... 115 Example: Debugging RTPs, Shared Libraries, and Plug-ins .................................. 116 Monitoring Semaphores During Debugging ............................................................ 118
PART V: DEPLOYING APPLICATIONS

9 Deploying VxWorks Systems .................................................................... 123
9.1 9.2 9.3 9.4 Introduction ...................................................................................................................... 123 Reconfiguring VxWorks for Deployment .................................................................. 123 Adding Kernel Applications to a VxWorks Image ................................................... 125 Example: Bundling RTPs and Libraries with a VxWorks Image ........................... 128
PART VI: REFERENCE

A What Are All These Project Files For? ...................................................... 137
A.1 A.2 A.3 A.4 A.5 A.6 A.7 A.8 Introduction ...................................................................................................................... 137 Files Common to Many Project Types ......................................................................... 138 Project Files in VxWorks Image Projects .................................................................... 139 Project Files in VxWorks Source Build Projects ........................................................ 142 Project Files in Downloadable Kernel Module Projects ......................................... 144 Project Files in Real-Time Process Projects ................................................................ 146 Project Files in Boot Loader/BSP Projects .................................................................. 148 Project Files in Shared Library Projects ...................................................................... 149
Debugging a VxWorks 5.5 Target ............................................................. 151

B.1 B.2 B.3 B.4 B.5 B.6 Introduction ...................................................................................................................... 151 Before You Begin ............................................................................................................. 151 Creating a VxWorks 5.5 DKM Project ......................................................................... 152 Creating a VxWorks 5.5.x Target Server Connection ................................................ 153 Launching a Kernel Task and Attaching the Debugger .......................................... 153 Using Existing Tornado 2.2.x Projects ......................................................................... 157
vi
Contents
Glossary ..................................................................................................... 159

C.1 C.2 C.3 Introduction ...................................................................................................................... 159 Searching for Terms in Online Documentation ........................................................ 159 Terms .................................................................................................................................. 160
Index ..................................................................................................................... 167
vii
viii
PAR T I
Introduction
1 Overview ................................................................................... 3
1
Overview
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. By performing these tasks, you learn how to use Wind River Workbench to develop, debug, and deploy VxWorks images and applications.
NOTE: This guide does not cover installation and licensing issues. Before using this
guide, install your Wind River platform, including Workbench, and complete all licensing requirements. For information about how to accomplish this, refer to the installation and licensing guides on 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 the develop, debug, and deploy project life cycle. The following task map lists the topics covering each life-cycle development phase, and shows where you can find the relevant information.
VxWorks By Example Task Map

Topic Description Where to Find the Information
2. Getting Started With Setting up your How to set up your host environment system and target, and how to Workbench to get started using 3. Setting Up Your Host & Target Workbench. Developing How to create various projects, 4. Configuring and Building build applications, and VxWorks libraries. 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 9. Deploying VxWorks Systems and add kernel applications to an image in the process of deployment. A. What Are All These Project Provides information on Files For? VxWorks project file types, how to debug a VxWorks 5.5 B. Debugging a VxWorks 5.5 target, and a glossary of terms. Target C. Glossary
Reference
1.3 Related Documentation

The Wind River Workbench documentation set includes the following: Wind River Workbench By Example (this guide) Wind River Workbench Users Guide Context-sensitive help.
Wind River Workbench By Example Guide
This guide provides solutions to common VxWorks-related issues that can occur in everyday development. By working through the tasks in this guide, you learn how to use Wind River Workbench to develop, debug, and deploy VxWorks images and applications.
1 Overview 1.3 Related Documentation
Wind River Workbench Users Guide
Refer to the Wind River WorkbenchUsers Guide for general information about Workbench, including how to work with projects, build your applications, connect to and download your applications to targets, and work with version control systems, such as ClearCase. The Users Guide also includes troubleshooting information and a glossary of terms.
Context-Sensitive Help
You can display context-sensitive help for a Workbench feature, and perform a keyword search for information about a feature.
To find information about a Workbench feature, complete the following steps:
1. 2.
In Workbench, navigate to the view, dialog, or feature for which you want help or information. Press the help key for your host:
On Windows, press F1
On Linux and Solaris, press CTRL-F1 The Help view opens and displays a list of links to related documentation.
To perform a keyword search, complete the following steps:
1. 2.
In the Workbench menu, click Help > Search. In the Help view, search Expression field, type a term or phrase; then click GO. The Help view displays a list of links to related documentation.
PA R T II
Setting Up Your Environment

2 3 Getting Started With Workbench ............................................ 9
Setting Up Your Host & Target ................................................ 17
2
Getting Started With Workbench
2.1 Introduction 9 2.2 The Benefits of Projects 10 2.3 Deciding on a Kernel Image 10 2.4 Writing Applications in Workbench 11 2.5 Creating a Library to Use With an Application 12 2.6 Loading and Booting a Kernel Image 12 2.7 Customizing a Board Support Package 13 2.8 Deploying an Application with a System Image 13 2.9 Using the Wind River Workbench New Project Wizard 13 2.10 Walkthrough Examples 14 2.11 Workbench Example Projects 15
2.1 Introduction
This chapter discusses the decisions you need to make before you start to work with a development project in Workbench. Subsequent chapters show you how to use Workbench to attain your development goals. Before you start using Workbench, 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 pre-built VxWorks image on which to run your applications, or a customized VxWorks kernel image that automatically starts your application at boot time? 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 The Benefits of Projects

Workbench supports a variety of project types, each of which creates a supportive framework for a specific task. The Workbench project structure helps you to perform the following tasks: 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). Using a build spec, you can build the same sources for different target architectures or different toolchains by changing the active build spec of a project.Workbench projects provide specific build support, which varies from one project type to another. This means that you cannot change the type of a project after you create it. If, after creating a project, you find that you chose the wrong project type, you must create a new project. Workbench provides a New Project Wizard that guides you through the steps required to create Workbench projects; see 2.9 Using the Wind River Workbench New Project Wizard, p.13. The examples in this guide show you the type of project best suited to the tasks they demonstrate.
2.3 Deciding on a Kernel Image

A kernel image is necessary for a target to function properly. Before you choose a kernel image, you must understand when to use pre-built or custom kernel images, and when to rebuild VxWorks libraries and build a kernel image. When to Use a Pre-built Image When to Use a Custom Kernel Image When to Rebuild VxWorks Libraries and Build a Kernel Image
When to Use a Pre-built Image
If your application does not require a specially configured kernel image, you can use one of the default, or pre-built, images. Your Platform ships pre-built VxWorks kernel images for all supported board support packages (BSPs). If you are responsible for writing applications, you need a kernel to test and run your applications.
10
2 Getting Started With Workbench 2.4 Writing Applications in Workbench
You can find the pre-built kernel images, which are tested and ready to run, 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 more detailed information about how to use default images, see 3.5 Booting a Target with VxWorks, p.23.
When to Use a Custom Kernel Image
Use a custom 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 create to contain your sources is a VxWorks image project (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 ROM file system (ROMFS) and real-time processes. Fore more information about projects in general, see 2.2 The Benefits of Projects, p.10. For more information about VxWorks image projects in particular, see 4. Configuring and Building VxWorks.
When to Rebuild VxWorks Libraries and Build a Kernel Image
Build VxWorks libraries and build a kernel image if you want your kernel image to support products, such as networking or security products, that are shipped with your Platform. If you want to reduce the size of a VxWorks kernel image, you can build a kernel image and exclude components you do not need. To rebuild libraries and build a kernel image, create and configure a VxWorks Source Build project (VSB) and then base your VIP on that project. For information about VxWorks Source Build projects, see 4.7 Creating a VxWorks Source Build Project, p.47.
2.4 Writing Applications in Workbench

You can develop kernel space and user space applications in Workbench using similar develop-debug-deploy workflows. Workbench requires that you create project types based on the kind of application you are developingkernel applications and user applications use different project types.
11
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. You can configure kernel applications to link statically into the kernel at build time, or as freestanding modules that download and link dynamically to the kernel at run time. If you are developing kernel applications, then a Downloadable Kernel Module (DKM) project provides the build support you need. For more information about DKMs, both static and dynamic, see Writing Kernel Applications, p.68.
About User Applications
User applications 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 (RTP) applications. If you are developing user applications, use a Real-Time Process project (RTP project). For more information about RTPs, see Writing Real-Time Process Applications, p.69.
2.5 Creating a Library to Use With an Application

The type of application you are developing and its associated library determine the kind of Workbench project you must create. Use the following guidelines to decide on the project type: If you are developing a library that links statically to a kernel application at build time, create a Downloadable Kernel Module (DKM) project. If you are developing a library that links statically to a user application at build time, create a VxWorks Real-Time Process project. For information about how to do this, see 6.9 Creating Statically Linked Libraries, p.82. If you are developing a library that links dynamically to a user application at run time, create a VxWorks Shared Library project. For information about how to do this, see 6.10 Creating Shared Libraries, p.83.
2.6 Loading and Booting a Kernel Image

To load and boot a kernel image, you can use the default boot loader that matches the BSP you installed with your Platform. You can also customize a boot loader to suite your specific needs.
12
2 Getting Started With Workbench 2.7 Customizing a Board Support Package
Wind River provides default boot loaders with your Platform to boot your target automatically with VxWorks. For more information, see VxWorks Kernel Programmers Guide: Boot Loader. A custom boot loader can include a driver for a specific piece of hardware, or support for a new target board. To create a custom boot loader, create a VxWorks Boot Loader/BSP project. For information about how to do this, see 4.11 Loading the VxWorks Image onto the Target, p.54.
2.7 Customizing a Board Support Package

Some projects might require features that are not included in the board support packages (BSPs) that shipped with your Platform. For such projects, you can create a VxWorks Boot Loader/BSP project and work with copies of existing BSP source files. This gives you a starting point from which to develop a custom BSP, 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.8 Deploying an Application with a System Image

In preparation for deployment, you can create a a read-only memory file system (ROMFS) that includes your RTP application, libraries, and other files. Incorporate the ROMFS into a VxWorks kernel image and deploy the application and kernel image as a single unit. To do this, create a VxWorks ROMFS File System project and configure the system to run your application automatically at boot time. For more information about how to do this, see 9.4 Example: Bundling RTPs and Libraries with a VxWorks Image, p.128. You can also deploy a kernel application with your VxWorks system. Link the application directly with the kernel and then configure the system to start it automatically at boot time. For details, see 9.3 Adding Kernel Applications to a VxWorks Image, p.125.
2.9 Using the Wind River Workbench New Project Wizard

This section shows you how to create a new project using the Wind River Workbench New Project wizard.
13
Workbench manages all application code in projects of one type or another. You can create projects in any location, but usually you create them in a workspace directorythe directory where Workbench stores all of your work. Workbench saves project administration files in the project directory, so if you create projects outside the workspace, you must have write permission for that location. To gain access to context-sensitive help from the New Project wizard, press the help key for your host: On Windows, press F1 On Linux and Solaris, press CTRL-F1
To create a project using the New Project wizard, complete the following steps:
1.
In the Workbench menu, click File > New > Wind River Workbench Project. Workbench opens the New Wind River Workbench Project wizard.
2. 3.
On the Target Operating System page, from the Target operating system drop-down menu, select a target operating system; then click Next. On the Build Type page, from the Build Type drop-down menu, select a build type; then click Next. The build type options available to you depend on your installed software. Platform developers have access to kernel source and kernel tools, whereas application developers do not.
4. 5.
On the Project page, in the Project name field, type a unique name for your project. Under Location, choose one of the following options: Create project in workspace Create project in external location; then click Browse to locate a directory outside your workspace. Create project in workspace with content at external location; then click Browse to locate a directory outside your workspace.
6.
Click Finish. Workbench shows your new project in the Project Explorer.
NOTE: The Advanced Device Development perspective provides shortcuts for creating common project types. To use the shortcuts for creating projects if you work in this perspective, in the Workbench menu, click File > New.
2.10 Walkthrough Examples

The following list shows the examples in this guide that illustrate procedures common in many development environments:
14
2 Getting Started With Workbench 2.11 Workbench Example Projects
4.5 Example: Building a VIP With Sources in a Subdirectory, p.41 4.9 Example: Customizing VxWorks Libraries as a Base For a VIP, p.50 5.3 Example: Customizing a BSP, p.61 6.4 Example: Discussion of PowerPC Build Spec Variants, p.71 6.5 Example: Creating and Passing a Build Target, p.72 6.7 Example: Adding IPNet Support to a DKM, p.81 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins, p.85 7.5 Example: Connecting a Target Server to a Target Agent, p.104 8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins, p.116 9.4 Example: Bundling RTPs and Libraries with a VxWorks Image, p.128 B. Debugging a VxWorks 5.5 Target
2.11 Workbench Example Projects

Workbench provides several sample projects that you can use to gain experience with the development environment.
To locate and open a Workbench sample project, complete the following steps:
1. 2. 3.
In the Workbench menu. click File > New > Example. In the New Example dialog, in the Wizards list, click a project type; then click Next. In the New Project Sample dialog, under Available Examples, click an example program; then click Finish.
15
16
3
Setting Up Your Host & Target
3.1 Introduction 17 3.2 What Should Your Development Environment Look Like? 18 3.3 Configuring Your Host Machine 18 3.4 Configuring Your Target 20 3.5 Booting a Target with VxWorks 23 3.6 Troubleshooting VxWorks Boot Problems 25
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. In order to work with VxWorks applications, kernel images, or libraries, you need to configure your host and target: The network software on the host must be correctly configured (see 3.3 Configuring Your Host Machine, p.18). Your target must be connected and powered up (see 3.4 Configuring Your Target, p.20). The boot loader must be loaded onto your target (see 4.11 Loading the VxWorks Image onto the Target, p.54). This chapter explains how to do these tasks, including 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.
17
3.2 What Should Your Development Environment Look Like?

The most common cross-development environment consists of 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, and one or more communication connections running between the host and the target. If you want to do native, also known as self-hosted, development (in other words, you want to develop applications that will run on your development machine rather than on a target) 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 your development work.
3.3 Configuring Your Host Machine

The first configuration tasks you need to complete are on your host machine. You generally need to do these tasks only once per host. 1. 2. 3. 4.
Step 1:
Install Workbench and other Platform products. Configure TCP/IP. Set up FTP on the host. Decide whether to enable logging.
Install Workbench and other Platform products.
As mentioned earlier, this guide does not address installation and licensing issues. Before you can continue, you or someone in your organization must have installed your Wind River platform, including Workbench, and resolved all licensing requirements. For information on how to do that, see http://www.windriver.com/support/site_configuration/.
Step 2: Configure TCP/IP.
If you need help configuring the networking on your host, consult your operating system documentation or your local system administrator.
Step 3: Set up FTP on the host.
Before you can boot VxWorks over the network, you must start an FTP server on the host that the target is connected to. In addition, you must 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.
18
3 Setting Up Your Host & Target 3.3 Configuring Your Host Machine
On Linux or Solaris Hosts
To use the default VxWorks configuration and boot VxWorks over the network, you must have an FTP daemon running on the host, and the network must be able to authenticate the user ID and password that you assign to the VxWorks target. If you like, you can use the rsh utility on Solaris instead of FTP.
On Windows Hosts
Your Platform includes an FTP server application, WFTPD. Before an FTP client can connect to the FTP server, you must complete the following steps: 1. 2. Start the FTP server on the host by selecting Start > Programs > Wind River > VxWorks 6.x and General Purpose Technologies > FTP Server. Configure a user name and password for the VxWorks boot loader on the target. a. b. c. From the WFTPD toolbar, select Security > Users/rights. In the User/Rights Security Dialog, click New User. 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.23.
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. e. 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. Back in the User/Rights Security Dialog, enter a valid path for Home Directory, such as C:\TEMP (WFTPD refuses to connect to a client unless you specify a home directory). Any directory is fine, as long as you permit sufficient disk access for the VxWorks boot loader to read the boot image on your Windows disk.
f.
g.
h. Close the User / Rights Security Dialog by clicking Done.

Step 4: Decide whether to enable logging.
1.
If you want to log FTP activities, select Logging > Log Options and select the types of activities you want to log. The log file will be saved in the home directory you specified above. When you are finished, click OK. When you have finished configuring your FTP settings, 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.
2.
19
3.4 Configuring Your Target

The next configuration tasks you need to complete are on your target. You need to perform these tasks for each new target you want to connect to. 1. 2. 3. 4. 5. 6. ! Assign the VxWorks target a name and IP address. Set up a serial connection between the host and target. Set up an Ethernet connection between host and target. Configure the Terminal view to open a serial connection. Set board switches and jumpers. Connect a power supply.
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.
Step 1: Assign the VxWorks target a name and IP address.
The way you coordinate target names and IP addresses depends on whether your site runs a Domain Name Service (DNS) or not.
Using a DNS Server
If you have DNS at your site, you can configure your computer to use the DNS server to translate system names to network IP addresses. Consult your operating system documentation on how to configure your system to take advantage of DNS.
Using a Hosts File
If you do not have a DNS server at your site, you can map machine names to IP addresses in a hosts file (on Linux and Solaris it is /etc/hosts, on Windows it is C:\Windows\system32\drivers\etc\hosts). 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). Each line consists of an IP address and the name (or names) of the system at that address. 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 90.0.0.50 mars phobos
20
3 Setting Up Your Host & Target 3.4 Configuring Your Target
This configuration is represented in Figure 3-1.

Figure 3-1 Boot Configuration Example
c:\temp\vxWorks HOST TARGET
mars
user: fred
90.0.0.1
phobos
90.0.0.50:ffffff00
Ethernet 90.0.0.x subnet
Another entry that should appear in your hosts file is for localhost. Workbench expects localhost to resolve to 127.0.0.1, so 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. !
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. Set up a serial connection between the host and target.
Step 2:
Connect a serial cable between the serial ports on the host and target. Most targets include at least one on-board serial port. The host uses the serial connection to communicate with the boot loader on the target.
Step 3: Set up an Ethernet connection between host and target.
Always make sure you use the correct cable: when connecting your board directly to your host, use a crossover cable when connecting your board to a LAN, use a non-crossover cable The host uses the network connection to transfer files, including the VxWorks system image.
Step 4: Configure the Terminal view to open a serial connection.
You can use the Terminal view to open a serial connection from within Workbench, just as you would open a connection with any other terminal emulation program such as hyperterminal, minicom, or telnet. 1. 2. Stop any other program already using the serial port. If it is not already running, start Workbench.
21
On a Windows host, select Start > Programs > Wind River > Workbench 3.3 > Workbench 3.3. 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. 4.
Open the Terminal view (select Window > Show View > Terminal). 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. 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. When you are finished, click OK to open a connection to your target. 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. Click Toggle Command Input Field to hide the text inset field again. To disconnect from your target, click Disconnect. To reopen the connection with the existing settings, click Connect.
5.
6. 7.
8. 9.
Step 5:
Set board switches and jumpers.
Many CPU and Ethernet controller boards still have configuration options that are selected by hardware jumpers, although this is less common than in the past. These jumpers must be set correctly for your particular development environment before VxWorks can boot successfully. You can determine the correct jumper configuration for your target CPU from the target reference for your BSP (such as installDir/vxworks-6.x/target/config/bsp/target.ref) and the documentation provided by your target systems manufacturer.
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. Step 6: Connect a power supply.
For standalone targets, use the power supply recommended by the board manufacturer. You are now ready to boot a prebuilt VxWorks kernel image.
22
3 Setting Up Your Host & Target 3.5 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 in order to get a VxWorks Boot prompt; from there, you can provide new boot parameters and download a new VxWorks kernel image. Here is a summary of the steps you will follow: 1. 2. 3.
Step 1:
Initiate, then interrupt, the boot process on the target. Enter new boot parameters. Boot the target with new parameters.
Initiate, then interrupt, the boot process on the target.
1.
If you are using a VxWorks image configured for a network connection (which is the default), make sure the FTP server you started in Step 3:Set up FTP on the host., p.18 is still running on the host where the VxWorks image is stored. 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. Reset your target by pressing the reset button, or by powering off the target then powering it on again. The boot program displays a banner page in the Terminal view, and then starts a seven-second countdown. 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]:
2.
3.
4.
5.
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 : ln unit number : 0 processor number : 0 host name : mars file name : c:\temp\vxWorks inet on ethernet (e) : 90.0.0.50:ffffff00 host inet (h) : 90.0.0.1 user (u) : fred ftp password (pw)(blank=use rsh) :secret target name (tn) : phobos
This example corresponds to the configuration shown in Figure 3-1. Each of these parameters is described in VxWorks Kernel Programmers Guide: Boot Loader, available in the Workbench help system.
Step 2: Enter new boot parameters.
1.
To change the boot parameters to match the settings for your system, type c at the boot prompt:
[VxWorks Boot]: c
23
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 pathname 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). In the inet on ethernet field, type the IP address of the target, then a colon, then the subnet mask. 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 Assign the VxWorks target a name and IP address., p.20). 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. On a Windows host, the user 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, the user must have either FTP or rsh access. For rsh, the user 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).
5. 6.
7.
8. 9.
Step 3:
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. In the target name field, type the name of the target.
Boot the target with new parameters.
1.
After entering the boot parameters, initiate booting by typing the @ command:
[VxWorks Boot]: @
The VxWorks boot program prints the boot parameters you entered, and the boot process begins. You will see the following information during the boot process: a. b. c. The boot program first initializes its network interfaces. After the system is completely loaded, the boot loader displays the entry address and transfers control to the loaded VxWorks system. 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.
24
3 Setting Up Your Host & Target 3.6 Troubleshooting VxWorks Boot Problems
2.
After this point, you will see a [VxWorks Boot] prompt. VxWorks is up and ready to attach to the Workbench tools.
Step 4:
Reboot VxWorks when necessary.
When VxWorks is running, there are several ways you can reboot it. Rebooting by any of these methods also restarts the attached target server on the host. 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 targets power off and on.
When you reboot VxWorks in any of these ways, the auto-boot sequence begins again from the countdown.
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 just by re-checking the installation steps, your hardware configuration, and so forth.
What to Check
Most often, a problem with booting and connecting to VxWorks can be traced to configuration errors in hardware or software. Consult the following checklist to locate a problem.
Hardware Configuration 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.
25
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.
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.
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.
Booting Problems Check the VxWorks boot display
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 Boot the target with new parameters., p.24 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.
26
3 Setting Up Your Host & Target 3.6 Troubleshooting VxWorks Boot Problems
For a discussion of VxWorks error status values, see the errnoLib reference entry by typing errnoLib into the help views Search field.
Verify FTP server permissions
Check the FTP server configuration. See Set up FTP on the host., p.18 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.
Check the WFTPD Server Log
The WFTPD server log displays very helpful plain text messages. For information about how to enable logging FTP activities, see Decide whether to enable logging., p.19.
27
28
PA R T I II
Customizing the Operating System

4 5 Configuring and Building VxWorks ........................................ 31 Working with Board Support Packages ................................. 59
29
30
4
Configuring 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 37 4.5 Example: Building a VIP With Sources in a Subdirectory 41 4.6 Importing and Migrating Existing VxWorks Image Projects 43 4.7 Creating a VxWorks Source Build Project 47 4.8 Configuring Custom VxWorks Libraries 49 4.9 Example: Customizing VxWorks Libraries as a Base For a VIP 50 4.10 Rebasing VSB and VIP Projects 53 4.11 Loading the VxWorks Image onto the Target 54
4.1 Introduction
A VxWorks Image project (VIP) provides build, source analysis, and other settings that streamline tasks such as creating, configuring, and building a kernel image. A VIP can contain only the files needed to create a kernel image, or you can add a VxWorks ROM file system (ROMFS) 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 inVxWorks to enable one of the products shipped with your Platform. Start by creating a VxWorks Image project in Workbench. If you need only a basic VxWorks kernel to boot your target, use one of the pre-built images shipped with your Platform, see 2.3 Deciding on a Kernel Image,
31
p.10. For instructions about how to use these images, see 3.5 Booting a Target with VxWorks, p.23. !
CAUTION: Code built for variants of VxWorks or for different releases of VxWorks
is not binary compatible between variants or releases. Code must be built specifically for uniprocessor (UP) VxWorks, VxWorks SMP, 32-bit VxWorks, 64-bit VxWorks, or for a VxWorks system based on variant libraries produced with a VxWorks source build (VSB) projector for any supported combination of these variants. The only exception to this rule is that RTP application executables can be run on both UP VxWorks and VxWorks SMP (when all else is the same).
4.2 Before You Begin Creating a Kernel Image

Before you create a VxWorks Image project, consider the kernel image you plan to build with the project, and answer 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 can save time by answering these questions before you create your project although it is possible to configure some VIP project settings at a later stage. For details, see 4.4 Configuring VxWorks, p.37.
4.3 Creating a Custom VxWorks Image

In this section you learn how to create a custom VxWorks image, a corresponding VxWorks Image project (VIP), and how you can change the build spec and build target for an existing VIP.
Prerequisites
Consider the following questions before you create a custom VxWorks image: Upon what is your project based? Project creation is faster if you base your project on an existing VIP, because the project facility copies 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.54. For details on
32
4 Configuring and Building VxWorks 4.3 Creating a Custom VxWorks Image
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.43. Once your VIP is created, you cannot change the BSP it is based upon. 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. The options you select in the VxWorks Source Build (VSB) project determine the BSP and tool chain options available for your VIP. For details, see 4.7 Creating a VxWorks Source Build Project, p.47. The address mode (ILP32 support or LP64 support in the kernel) you choose for your VIP depends on the BSP on which you want to base your project, and the address mode in turn determines the tool chain you can use. Workbench manages its UI components, and presents only the settings appropriate for your BSP and address mode choices. 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 Users Guide. Do you want networking and multiprocessing support? Options available to you can vary depending on the Platform you installed and the BSP you chose for your project. The following are a few options that might be available: IPv6 enabled kernel librariesCreates IPv6 support. IPv6_only enabled kernel librariesCreates IPv6_only support. SMP support in kernelCreates 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? Your BSP and address mode choices determine the profiles that Workbench offers. Profiles are preconfigured collections of kernel components that provide the described capabilities. Using a profile can save you work, but you do not need to select one nowyou can create the same configuration using the Kernel Configuration Editor (see 4.4 Configuring VxWorks, p.37).
Creating a Custom VxWorks Image and VIP
This task shows you how to create a custom VxWorks image and a corresponding VIP.
NOTE: It is not necessary to make a selection on every screen. To create a custom VxWorks image, do the following:
1.
In Workbench, change to the Advanced Device Development perspective.
33
If you have not opened this perspective before, in the Workbench menu click Window > Open Perspective > Advanced Device Development. 2. In the Workbench menu, click File > New > VxWorks Image Project. Workbench starts the New VxWorks Image Project wizard. 3. 4. On the Project page, type a name for your project. Under Location, select a location to store your project files; then click Next. To create the project in the current workspace, select Create project in workspace. This is a good idea if you do not have write permission to the location of your source files, or if you plan to create or import sources later. To create the project outside your workspace, select Create project at external location; then click Browse to navigate to the new location. Choose this option if you have write permission to the location of your sources (so you do not have to import them later), or if you plan to add your project to source control and the sources are outside your workspace. 5. On the Project Setup page, under Set up the project, from the Based on drop-down list, select the project type or package on which to base your project. This step defines the location from which Workbench retrieves the build settings and other settings for the project. To base your VIP on another VIP or a Boot Loader/BSP project, select an existing project; then from the Project drop-down list, select a project in your workspace or click Browse to select a similar project from another location. To base a VIP on a VxWorks source build (VSB) project, select a source build project; then from the Project drop-down list, select a project in your workspace or click Browse to select a similar project from another location. You, or someone on your team, must have created the VSB project and rebuilt your VxWorks source libraries. To base a VIP on a BSP, select a board support package that supports your target hardware, then from the BSP drop-down list select the VxWorks simulator on which to run your image. On a Windows host, select simpc On a Linux host, select linux On a Solaris host, select solaris To use a BSP provided by someone in your organization or a third party, click Browse to locate the package. In the Address mode drop-down list, select the address mode support you want to use in the kernel either 32-bit kernel or 64-bit kernel. From the Tool chain drop-down list, select one of the tool chains you have installed, such as the GNU compiler (gnu), the Wind River Compiler (diab), or the Intel C++ Compiler (icc) if your project is based on an Intel CPU.
34
4 Configuring and Building VxWorks 4.3 Creating a Custom VxWorks Image
NOTE: The address mode you can choose for your project depends on the BSP on which your project is based, and the address mode in turn determines the tool chain you can use.
6.
(Optional) Under Target Agent, click Enable WDB Target Agent if you plan to use Workbench debugging tools to debug your target applications. The WDB Target agent is disabled by default unless you are working with a simulated target. The WDB Target Agent is a software component that resides on your target system and that makes it possible to use Workbench debugging tools with your target applications.
7.
(Optional) Under BSP validation test suite, click Add support to project; then click Options. This step includes support for the BSP validation test suite. a. b. c. In the dialog box, select a test suite and provide board and host configuration information. Click Browse to navigate to the location in which to store the test results. Click Close; then click Next.
8.
(Optional) On the Options page, under Options, select the networking and multiprocessing support you want to use in your VIP; then click Next.
NOTE: SMP support is available only if it is supported by your product activation file (*.install.txt) and the BSP you selected.
If you do not see the option you want, select a different BSP. If you see an option but cannot select it, your BSP supports the feature, but the option is not enabled in your product activation file. 9. (Optional) On the Configuration Profile page, in the Profile drop-down box, select one of the following kernel configuration profiles: PROFILE_COMPATIBLE This profile provides a minimal configuration. PROFILE_DEVELOPMENT This profile creates a VxWorks image that includes development and debugging components. PROFILE_ENHANCED_NET This profile adds to the default image the components appropriate for typical managed network client host devices. PROFILE_BOOTAPP This profile adds boot loader capabilities to a default VxWorks image. 10. (Optional) On the Indexer page, click Enable project specific settings; then under Select indexer, choose an indexer and the settings you want to use. Most projects work properly if you use the general indexer settings applied to all projects. Click Configure Workspace Settings to examine these settings. Press the help key for your host for more information about selecting settings and configuring the indexer.
35
11.
Click Finish. Workbench displays your new project in the Project Explorer, and shows both project files and linked resources.
NOTE: If Workbench encounters a problem while creating the project (for example, you might have specified the diab tool chain, but the selected BSP supports only gnu) Workbench displays an error that describes the problem.
Click OK to 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 that caused the problem, rather than resetting all the selections in the wizard. If you do not want to fix the problem and would rather create the project now, click Cancel. For more information about boot loaders, see 4.11 Loading the VxWorks Image onto the Target, p.54 and the Customizing and Building Boot Loaders section in VxWorks Kernel Programmers Guide: Boot Loader. For information about selecting non-default drivers, see Specifying a Non-Default Driver, p.41. For more information about profiles, see VxWorks Kernel Programmers Guide: Kernel Facilities and Kernel Configurations and the help page for vxprj::profile.
Changing the Image Type for a VIP
This section shows you how to change the build spec and build target for an existing VIP. Doing so creates a different image type for the project. There are four types of vxWorks images: vxWorks (default) vxWorks_rom vxWorks_romCompress vxWorks_romResident For more information about these image types, see the VxWorks Kernel Programmers
Guide.
When you create a VIP, Workbench sets the default build spec and build target to default. vxWorks and a vxWorks target node appear in the project. The target node name includes the suffix (default), which shows that the default build spec is set for the project.
NOTE: The build spec and build target must match for any given image type. For
example, to build a vxWorks_rom image successfully, the build spec default_rom must be used with the build target vxWorks_rom. You must have an existing VIP before you begin this task. For more information, see Creating a Custom VxWorks Image and VIP, p.33.
To change the image type for a project, complete the following steps:
1.
In the Project Explorer, right-click the project name; then click New > Build Target.
36
4 Configuring and Building VxWorks 4.4 Configuring VxWorks
2.
In the Build Target dialog, on the Build Target page, in the Build target name text field, type a new name for the build target (for example, vxWorks_rom); then click Finish. Workbench displays the new target node in the Project Explorer.
3.
In the Project Explorer, right-click the project name; then click Build Options > Set Active Build Spec > vxWorks_rom. This step sets the build spec that is appropriate for the build target you just created. The build spec and build target must match for any given image type.
4.
Right-clicking the new target name (for example, vxWorks_rom for example); then click Build Target.
NOTE: A mismatched spec and build target result in a build failure. If you receive a build failure message, repeat Step 2 and Step 3 to make sure that the build target and build spec are compatible. For example, to build a vxWorks_rom image successfully, the build spec default_rom must be used with the build target vxWorks_rom.
4.4 Configuring VxWorks

The VxWorks kernel is a flexible operating system made up of many different components. You can configure, include, or exclude components, depending on the requirements and stage of development of your application. 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 might find it useful to configure VxWorks with components to provide POSIX support. During the development cycle, Workbench needs the WDB target agent to communicate with the target. But you might want to remove it when you deploy the system, since you no longer need the Workbench-target connection.
NOTE: The WDB Target Agent is disabled by default, unless you are working with
a simulated target. To enable the WDB Target Agent, see Creating a Custom VxWorks Image and VIP, p.33. If you are working with an existing VIP, enable the WDB Target Agent in the Kernel Configuration Editor, see 4.4.1 Configuring VxWorks Using the Kernel Configuration Editor, p.38. !
CAUTION: When VxWorks is configured with the WDB target agent, it is enabled
on UDP port 17185. This service provides full access to VxWorks memory, and allows for writing to memory as well as for calling routines. Wind River recommends removing WDB from VxWorks for production systems.
37
NOTE: When CDF files are modified outside Workbench, either intentionally or automatically when a patch is installed, you must delete the CxrCat.txt file in installDir/vxworks-6.x/target/config/comps/vxWorks and then reopen the Kernel Configuration editor, Configuring VxWorks Using the Kernel Configuration Editor, p.38
This action is necessary because the CxrCat.txt file must be regenerated, which does not happen automatically when changes are made to CDF files outside Workbench. In such cases, delete the file, and then reopen the Kernel Configuration editor for the CDF changes to take affect.
4.4.1 Configuring VxWorks Using the Kernel Configuration Editor

Workbench provides the Kernel Configuration Editor as a quick way to customize your kernel. To open it, double-click your VIP, then double-click the Kernel Configuration node. You will see three tabs arranged along the bottom edge of the view:
The Overview Tab
Provides a read-only summary of the configuration, including BSP and toolchain information and estimated size of the image.
The Bundles Tab
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.
The Components tab
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. You can also right-click a component and, in the context menu, click Check to open a Check dialog that provides information about the component its type and whether or not it is installed and available for use. When you click a component, it is highlighted. The Synopsis tab shows a brief description of the purpose of the highlighted component and (if you are working with VxWorks 6.9 or later) hypertext links to the CDF file, or files, that define the component. To open a CDF file in a text editor at the line that defines the component, click the hypertext link.
38
4 Configuring and Building VxWorks 4.4 Configuring VxWorks
NOTE: You must configure and build certain 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 Users Guide.
Including Components in a Kernel Image
Say for example that you would like to include ping functionality in your kernel image. To do that, follow these steps: 1. 2. 3. 4.
Step 1:
Open the Kernel Configuration Editor. Search for the component to include. Include the component in your image. Build your project.
Open the Kernel Configuration Editor.
Double-click the Kernel Configuration node of an existing VxWorks Image project to open the Kernel Configuration Editor.
Step 2: Search for the component to include.
If you know where ping is located you can navigate to it using the Editors tree structure. But if you are not sure where it is, or just for convenience, you can use the Find dialog. 1. 2. 3. From the Components tab, type CTRL+F or right-click and select Find. You can search for ping in two ways: by name and by description. For this example, select Description at the top of the dialog. 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. To navigate to the folder, double-click it or select it and click Find. The tree structure opens and the folder is highlighted.
4.
Step 3:
Include the component in your image.
1. 2. 3.
To include ping in your image, right-click the PING Components folder and select Include. 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 it must also include to support ping, and displays them along with the estimated change in the size of your image from including these components. If you accept the changes, click Finish to complete the configuration. In the Kernel Configuration Editor you will see that the PING Components folder is now bold, indicating that ping will be included in your kernel image the next time you build it. You will also see a star-shaped overlay icon, indicating that your changes have not yet been saved. Building your project saves the changes automatically, but
4.
39
you can save them manually by closing the Editor view and selecting Yes when Workbench asks to save your changes, or you can press CTRL+S to save them without closing the view.
Step 4: Build your project.
In the Project Explorer, right-click your project and select Build Project, or click the Build Projects icon on the toolbar. The ping components are included in the resulting VxWorks kernel image.
Excluding Components from a Kernel Image
You can exclude components from a kernel image to decrease its size and streamline performance. To complete this task, the Project Explorer must include an existing VxWorks Image Project (VIP) in its list of projects. For information about how to create a VxWorks Image project, Creating a Custom VxWorks Image, p.32. This task is similar to the task for including components, but shows you how to exclude networking components from an image. To do this, follow these steps: 1. 2. 3.
Step 1:
Open the Kernel Configuration Editor. Select the component to exclude. Build your project.
Open the Kernel Configuration Editor.
Double-click the Kernel Configuration node of an existing VxWorks Image project to open the Kernel Configuration Editor.
Step 2: Select the component to exclude.
1. 2.
Since Networking Components is a top level component, it is immediately visible. Right-click it, then select Exclude. The Exclude dialog appears. The Exclude dialog displays all the networking components that will be excluded from the kernel image. If you wanted to keep any components in the image, you could clear components at this point. For now, leave all components selected, then click Next. Workbench determines if there are any dependent components that must also be excluded along with the networking components, and displays them. To complete the configuration, click Finish. In the Kernel Configuration Editor you will see that Network Components is still 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. You will also see an overlay icon indicating that the component has changed, but the change has not yet been saved (it will be saved automatically when you build your project).
3.
Step 3:
Build your project.
In the Project Explorer, right-click your project and select Build Project, or click the Build Projects icon on the toolbar. The networking components will be excluded from the resulting VxWorks kernel image.
40
4 Configuring and Building VxWorks 4.5 Example: Building a VIP With Sources in a Subdirectory
For more information about kernel components, see the VxWorks Kernel Programmers 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 might require a supported driver that is not provided as the default, or a driver that is not VxBus-compliant. To specify a non-default driver, choose one of the following options: Refer to Including Components in a Kernel Image, p.39 and Excluding Components from a Kernel Image, p.40 to add or remove VxBus-compatible drivers in the same way you include or exclude other components from a kernel image. Add or remove drivers that are not compatible with VxBus (only) in installDir/vxworks-6.x/target/config/bspName/config.h using the #define or #undef preprocessor directives to define or undefine the respective macros.
NOTE: Make changes to config.h before you create a VxWorks image project. The project does not recognize any changes you make to config.h after you have created a VIP.
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, complete the following steps:
1.
In Workbench, change to the Advanced Device Development perspective. If you have not opened this perspective before, in the Workbench menu click Window > Open Perspective > Advanced Device Development.
2. 3.
Create a VIP project by selecting File > New > VxWorks Image Project, entering a name for the project, specifying a location, and then clicking Next. In the Workbench menu, click File > New > VxWorks Image Project. Workbench starts the New VxWorks Image Project wizard.
4. 5.
On the Project page, type a name for your project. Under Location, select a location to store your project files; then click Next.
41
To create the project in the current workspace, select Create project in workspace. This is a good idea if you do not have write permission to the location of your source files, or if you plan to create or import sources later. To create the project outside your workspace, select Create project at external location; then click Browse to navigate to the new location. Choose this option if you have write permission to the location of your sources (so you do not have to import them later), or if you plan to add your project to source control and the sources are outside your workspace. 6. On the Project Setup page, under Setup the project, from the Based on drop-down list, select the project type or package on which to base your project. In this case, select the simpc BSP and the diab tool chain. You do not need to adjust any other settings.
NOTE: The WDB Target Agent is disabled by default, unless you are working with a simulated target.
To enable the WDB Target Agent, see Creating a Custom VxWorks Image and VIP, p.33. If you are working with an existing VIP, enable the WDB Target Agent in the Kernel Configuration Editor, see 4.4.1 Configuring VxWorks Using the Kernel Configuration Editor, p.38 7. 8. Click Next to step through subsequent dialogs pages; then click Finish. Create a new project folder: a. b. 9. In the Project Explorer, right-click your VIP; then click New > Folder. In the Folder name field, type dummy; then click Finish.
Create a new source file: a. b. Right-click the dummy folder; then click New > File. In the New File dialog, in the File name field, type hello.c, then click Finish. The new hello.c file opens in the editor. c. Add the following content to hello.c:
/**************************/ #include "stdio.h" void helloworld(void) { printf("helloworld"); } /**************************/
d. Press CTRL+S to save the file. 10. Create a makefile fragment: a. b. Right-click the VIP root directory, then click New > File. In the New File dialog, in the File name field, type hello.makefile; then click Finish. The new hello.makefile file opens in the editor. c. Add the following content to hello.makefile:
42
4 Configuring and Building VxWorks 4.6 Importing and Migrating Existing VxWorks Image Projects
# Makefile all % : cd dummy;\ rm hello.o;\ ccpentium hello.c -o hello.o
d. Press CTRL+S to save the file. 11. Right-click the VIP project name; then click Build Project.
These steps build the dummy/hello.c source file and creates a hello.o object file that Workbench later links into the final vxWorks kernel image.
Adding Existing Sources to a VIP
If you add existing source files to a VIP, the VIP picks up the new files next time you build the project.
To add existing sources to a VIP, choose one of the following steps:
Select the source files and drag and drop them into the VIP. Select the source files and copy and paste them into the VIP.
Adjusting Link Order
When you add source files to a VIP, Workbench automatically adds the object file to the bottom of the link order. You can adjust the link order of object files in the Build Properties dialog. The Content page of the Build Properties dialog allows you to manage object files that are directly linked into the VxWorks kernel image as part of the VIP.
To adjust link order, complete the following steps:
1. 2. 3.
In the Project Explorer, right-click your project; then click Properties > Build Properties. In the Properties dialog, on the Build Properties page, click the Content tab. On the Content tab, under Object files, click the name of the file whose link order you want to change; then click Up or Down. The file moves up or down in the list and link order accordingly. Click OK, to save the build properties.
4.
4.6 Importing and Migrating Existing VxWorks Image Projects

Importing and migrating projects into your workspace achieve similar results, but when migrating projects, Workbench can change project files. The following rules apply to these operations: Importing a projectWorkbench copies an existing project from its original location into your workspace without changing any files inside the project.
43
Migrating an older projectWorkbench 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 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 gain access to it from Workbench. For details on using vxprj to create projects, see the VxWorks Command-Line Tools Users Guide: Working with Projects and Components and the vxprj API reference entry. You want to test the capabilities 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. If a team member used Workbench to export a project to an archive file, you can import that project into your workspace. This section describes both of these tasks.
To import a project from a file system, complete the following steps:
1. 2. 3.
In the Workbench menu, click File > Import. In the Import dialog, on the Select page, under Select an import source, click General > Existing Projects into Workspace; then click Next. On the Import Projects page, click Select root directory, click Browse to locate the projects directory (the directory that contains the projects *.wpj file); then click OK. In the Projects pane, select the project, and if it is appropriate for your task, select Copy projects into workspace. If you do not select this check box, Workbench creates a reference to the project, rather than importing it into your workspace.
4.
5.
Click Finish.
Project Explorer now displays the imported project.
44
4 Configuring and Building VxWorks 4.6 Importing and Migrating Existing VxWorks Image Projects
To import a project exported by a team member, complete the following steps:
1. 2. 3. 4.
In the Workbench menu, click File > Import. In the Import dialog, on the Select page, under Select an import source, click General > Existing Projects into Workspace; then click Next. On the Import Projects page, click Select archive file, click Browse to locate the file; then click Open. In the Projects pane, select the project; then click Finish.
Project Explorer now displays the imported project.
Migrating Projects
You can use several methods to migrate a project. The method you choose depends on the following conditions: Whether or not the Makefile template was modified. If you have not changed anything in the projects .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 or not the project is a prebuilt VxWorks image. Whether or not 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. 2.
If the project is part of the current workspace, remove it by right-clicking the project in the Project Explorer and selecting Delete. 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. 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. Click Next, navigate to the projects *.wpj file, click Open, and then click Finish.
3.
4.
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.
45
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. If the project is already part of the current workspace, remove it by right-clicking the project in the Project Explorer and selecting Delete. 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. 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. 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.
2. 3.
4.
5.
6. 7.
Open the new version of the .wrmakefile and manually migrate the customizations from the renamed old file, and then save the file. 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.
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. To migrate a prebuilt VxWorks image, do the following:
1. 2.
Select File > Import > VxWorks 6.x > Existing VxWorks 6.x Image Project into Workspace, and then click Next. Click Browse, then navigate to the projects *.wpj file under its directory in installDir/vxworks-6.x/target/proj. All SMP-enabled projects have directory names that end in _smp. Click Open, then Finish.
3.
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.
46
4 Configuring and Building VxWorks 4.7 Creating a VxWorks Source Build Project
For information on how to use tcMigrate, do the following:
1. 2.
Select > Help. 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 49.
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? 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.
47
To create a VSB project, do the following:
1. 2. 3. 4.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Source Build (Kernel Library) Project. The Project screen of the wizard appears. Enter a name for your project. Specify a location by selecting one of the following options: Create project in workspace If 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 location If 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. 6.
Click Next. Select the BSP or CPU type your project will be based on by choosing one of the following options: A board support package Select 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 type Select 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.
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.
48
4 Configuring and Building VxWorks 4.8 Configuring Custom VxWorks Libraries
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.49.
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. 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.
49
Kconfig
Displays a tree of bundles and, at the leaf nodes of expanded bundles, individual components and their parameters.
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 Users Guide. To open the Source Build Configuration editor, do the following:
1. 2.
Double-click your VSB. 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.
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.
50
4 Configuring and Building VxWorks 4.9 Example: Customizing VxWorks Libraries as a Base For a VIP
To create a VSB project, do the following:
1. 2. 3. 4. 5. 6. 7.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Source Build (Kernel Library) Project. The Project screen of the wizard appears. In the Project name field, enter VSB_mipsI32R2. Leave Create project in workspace selected, and click Next. Because you know the specific CPU of your target system, select A CPU type, then from the drop-down menu select MIPSI32R2. Click Next. 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. 2.
Double-click your project to expand it, then double-click the Source Build Configuration node to open it in the editor. You want to disable System Viewer support, so right-click in the Option pane, then select Find. Type a letter or two of the options name into the Pattern field, using wildcard characters if necessary. In this case typing an S displays Enable System Viewer Instrumentation. Select it and click Find. 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. In the same way, deactivate Enable Real-Time Process (RTP). At the top of the Option pane, click the plus next to VxWorks Global Configuration Options for CPU MIPSI32R2 to expand it. To set advanced options such as compiler options, right-click Set advanced options and select Change value. From the drop-down list, select y. 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. Save your configuration by pressing CTRL+S, or by closing the editor and selecting Yes when prompted to save.
3.
4. 5. 6. 7.
8.
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. You can change the VSBs 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.
51
To build your VSB project, do the following:
1. 2.
Right-click the project in the Project Explorer. 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 VIPs 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:
1. 2. 3. 4. 5. 6.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Image Project. The Project screen of the wizard appears. In the Project name field, type VIP_VSB_mipsI32R2. Leave Create project in workspace selected, then click Next. On the Project Setup screen, click the Based on drop-down list and select a source build project. 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. In the Address mode drop-down list, select the address mode support you want to use. 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.
7. 8.
To configure the remaining VIP project screens, see 4.3 Creating a Custom VxWorks Image, p.32. 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:
1. 2.
Right-click the project in the Project Explorer. Select Build Project. Workbench uses your custom VxWorks libraries in place of the default libraries.
52
4 Configuring and Building VxWorks 4.10 Rebasing VSB and VIP Projects
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. 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.53.
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 validate VIPs that are based on a VSB that has changed. This procedure is useful when requirements change for a project.
53
To base a VIP on a different VSB project, do the following:
1. 2. 3. 4.
Right-click the VIP, select Properties, then select VxWorks Info. To the right of Kernel libraries, click Change. The Select Source Build Configuration dialog opens. Navigate to the directory that contains the new VSB projects vsb.config file, select the file, and click OK. 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. For more information about boot loaders, see the VxWorks Kernel Programmers 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.
54
4 Configuring and Building VxWorks 4.11 Loading the VxWorks Image onto the Target
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:
1. 2. 3. 4.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Boot Loader/BSP Project. In the new project wizard, type a name for your project. Specify where to create your project by selecting one of the following options, then click Next: Create project in workspace If 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 location If 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. 6. 7.
Choose the BSP that you want to base your project on. Workbench displays all your installed BSPs in the drop-down list. Select the tool chain you want to use. The available options match the BSP you selected. Select The Style and Format of the Boot loader/BSP image. For format, choose from ELF, Bin, or Hex. The VxWorks Kernel Programmers 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:
55
Adding or removing VxWorks components, as described in 4.4 Configuring VxWorks, p.37. 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 loaders 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.58. 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 Programmers 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. 2. 3.
Navigate to the installDir/vxworks-6.x/target/config/bsp/config.h file in the Project Explorer. Click the config.h file to open it in an editor. Modify the configuration as necessary.
Boot Loader Build Targets
In a VIP project (except one configured to run on the VxWorks simulator) you can use a build spec to specify one of three types of VxWorks images. A VxWorks image s specified by its type and format: vxWorks.[type] [format] type can be empty (the default RAM-based image), _rom, _romCompress, or _romResident. The build spec format can be empty (the default ELF image), .bin (binary output), or .hex (Motorola S-Record output). For more information about VxWorks images, see the VxWorks Kernel Programmers Guide: VxWorks Configuration.
To switch build specs, do the following:
1. 2.
Right-click the project in the Project Explorer. Select Build Options > Set Active Build Spec > build_spec.
NOTE: The build spec and build target must match for any given image type.
For example, the build spec default_rom must be used with the build target vxWorks_rom to build a vxWorks_rom image.
To create new build targets with user-defined make rules, do the following:
1. 2. 3.
Right-click the project in the Project Explorer. Choose New > Build Target. Enter an appropriate Build target name, such as vxWorks_rom.
56
4 Configuring and Building VxWorks 4.11 Loading the VxWorks Image onto the Target
4.
From the Build tool pull-down menu, select (User-defined) and click Finish.
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 BSPs value for RAM_LOW_ADRS with the BSPs 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. 2.
In the Project Explorer, click the config.h file to open it in an editor. 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. 4. 5.
If they are not already there, add the link address parameters to the BSPs CDF file. This file is usually 20bsp.cdf, but for some may be 10bsp.cdf. 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. Set RAM_HIGH_ADRS to (RAM_LOW_ADRS + maxBootAppImageSize). 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 address DEFAULT (INCLUDE_BOOT_RAM_IMAGE)::(0x01C00000) \ (INCLUDE_BOOT_APP)::(0x01E00000) \ (0x00100000) }
57
For more information about working with CDF files, see VxWorks Kernel Programmers 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.
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.
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 Programmers Guide: Boot Loader and the VxWorks BSP References entry for your BSP.
58
5
Working with Board Support Packages
5.1 Introduction 59 5.2 Creating an Experimental Default BSP 59 5.3 Example: Customizing a BSP 61
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 Developers Guide.
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.
59
To create a default BSP, do the following:
1. 2. 3.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Boot Loader/BSP Project, and then type a name for your project. Specify where you want to create your project by selecting one of the following options, and then click Next: Create project in workspace 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 location 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.
4. 5. 6.
Choose the BSP that you want to work with. Workbench displays all your installed BSPs in the drop-down list. Select the tool chain you want to use. The available options change to match the BSP you selected. 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. Click Finish. The new project appears in the Project Explorer.
7.
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.
NOTE: You cannot use the VxWorks simulator BSP in a VxWorks Boot Loader/BSP
project to create a boot loader. In the New VxWorks Boot Loader/BSP Project wizard, on the Project Setup page, select a BSP for your project from the Board support package drop-down list.
Using a Wind River BSP
If your BSP was installed with Workbench 3.3, you can create a VxWorks Image project from it directly. For more information, see 4.4 Configuring VxWorks, p.37.
60
5 Working with Board Support Packages 5.3 Example: Customizing a BSP
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 Developers Guide and 5.2 Creating an Experimental Default BSP, p.59. 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.97.
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 Developers 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.
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. 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 Users 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
61
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.59.
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. 2. 3.
In the Project Explorer, double-click the BSP project to expand it, then double-click the BSP directory to view its contents. Right-click config.h and select Properties. 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. Click OK.
4.
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. 2. 3. 4. 5.
Double-click config.h to open it for editing. Search for the definition of ROM_SIZE by pressing CTRL+F to open the Find/Replace dialog. In the Find text field, type ROM_SIZE, then click Find. Increase the value of ROM_SIZE, for example from 0x00200000 to 0x00300000 (or as appropriate for your needs). Close config.h and click Yes when you are prompted to save the changes.
Task 3: Build your project.
To integrate the changes into your project, you must perform a build.
62
5 Working with Board Support Packages 5.3 Example: Customizing a BSP
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. This example includes the following tasks: 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.62.
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:
1. 2. 3. 4.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Image Project, and then type a name for your project. For this example, leave Create project in workspace selected. 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. 2.
From the Based on drop-down list, select An existing project. From the Project drop-down list, select the custom BSP project you developed in Creating a Custom BSP, p.62. 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.
To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. 3. Click Finish. The new project appears in the Project Explorer.
63
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. 2. 3. 4. 5. 6.
Double-click the Kernel Configuration node to open the Kernel Configuration Editor. To look for ROM_SIZE, right-click in the Component Configuration pane, then select Find. 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. Double-click it in the list to find it in the Component Configuration pane. In the value column, you should see the modified value (0x00300000 instead of 0x00200000, or as appropriate for the change you made). Close the editor when you are finished.
Where to Go Next
For additional information about working with BSPs, see the VxWorks BSP Developers 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 Users Guide.
64
PA R T I V
Developing and Debugging Applications

6 7 8 Building Applications and Libraries ....................................... 67 Connecting to VxWorks Targets ............................................. 95 Running and Debugging VxWorks Applications ................... 109
65
66
6
Building Applications and Libraries
6.1 Introduction 67 6.2 Deciding on an Application Type 68 6.3 Creating a Project For Your Application 69 6.4 Example: Discussion of PowerPC Build Spec Variants 71 6.5 Example: Creating and Passing a Build Target 72 6.6 Reconfiguring Your Project Later in the Development Cycle 75 6.7 Example: Adding IPNet Support to a DKM 81 6.8 Using RTP Overlapped Virtual Memory 82 6.9 Creating Statically Linked Libraries 82 6.10 Creating Shared Libraries 83 6.11 Creating Plug-Ins 84 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins 85 6.13 Running Applications on a Hardware Target 93
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 Programmers Guide and the VxWorks Application Programmers Guide.
67
For details about the editor, code assist and colorization, parameter hinting, and other Workbench features that make coding easier, see the Wind River Workbench Users Guide, or open a Workbench feature and press the help key for your host. !
CAUTION: Code built for variants of VxWorks or for different releases of VxWorks
is not binary compatible between variants or releases. Code must be built specifically for uniprocessor (UP) VxWorks, VxWorks SMP, 32-bit VxWorks, 64-bit VxWorks, or for a VxWorks system based on variant libraries produced with a VxWorks source build (VSB) projector for any supported combination of these variants. The only exception to this rule is that RTP application executables can be run on both UP VxWorks and VxWorks SMP (when all else is the same).
Process Overview
Creating applications in Workbench follows this basic process: 1. 2. 3. 4. 5. 6. Decide what type of application you need. From the Wind River Workbench Project wizard, select the build type that will provide the necessary structure and build support for your project. Write or import source files. As necessary, write or import libraries to support your application. Build and debug your projects. 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.113. 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.125. VxWorks can be configured to start kernel applications automatically at boot time.
68
6 Building Applications and Libraries 6.3 Creating a Project For Your Application
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 VxWorksloading, unloading, and reloading on the fly. 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.113. 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 RTPs and Libraries with a VxWorks Image, p.128. 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.
69
CAUTION: VxWorks kernel applications must be built specifically for the type of system on which they will run, whether uniprocessor (UP), symmetric multiprocessor (SMP), 32-bit, 64-bit, or a system based on variant libraries produced with a VxWorks source build (VSB) project. They are otherwise binary incompatible. The kernel object-module loader rejects a module if it is not compatible with the VxWorks system and prints an error message. See the VxWorks Kernel Programmers Guide for more details. To create a project for your application, do the following:
1. 2. 3. 4.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select Wind River Workbench Project from the Workbench toolbar. The New Wind River Workbench Project wizard appears. Select Wind River VxWorks 6.x from the drop-down menu, and click Next. 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. On the Project screen, and type a name for your project and specify the location by selecting one of the following options: Create project in workspace If 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 location If 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 location If 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.
5.
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
70
6 Building Applications and Libraries 6.4 Example: Discussion of PowerPC Build Spec Variants
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. 2. 3.
Select File > Import. 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. When you have completed your selections, click Finish.
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. 2. 3.
Select the project and then select File > New > File. Enter or select the parent folder, and supply a File name. The file name must be unique. (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 Programmers Guide: RTP Applications. For more information about writing source code for kernel applications, see VxWorks Kernel Programmers 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.
71
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.
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. This example includes the following tasks: 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:
1. 2. 3. 4. 5.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > VxWorks Image Project. In the Project name field, type VIPsim. Leave Create project in workspace selected, then click Next. Leave the VxWorks simulator BSP and default toolchain selected, then click Finish.
To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. The VIPsim project appears in the Project Explorer.
72
6 Building Applications and Libraries 6.5 Example: Creating and Passing a Build Target
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. 2. 3. 4. 5. 6.
From the Advanced Device Development perspective, select File > New > VxWorks Downloadable Kernel Module Project. In the Project name field, type DKM_pass_tgt. Leave Create project in workspace selected, then click Next until you get to the Build Target screen. 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. Change the Build tool from Linker to Partial Image Linker. 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. 2.
From the Advanced Device Development perspective, select File > New > VxWorks Downloadable Kernel Module Project. 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. 2. 3. 4.
In the Project Explorer, right-click anywhere; then click File > New > File from Template. In the New File dialog, select the hello_VxWorks parent folder, then in the File name field type hello.c. In the Use template drop-down list, select Wind River C source template from the drop-down list, then click Finish. The hello.c file opens in the editor. Add the following code below the comment lines:
#include <stdio.h> int dmain(void) {
73
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. 2. 3. 4. 5. 6.
If Hello-Sort is not already visible, double-click DKM_pass_tgt and then double-click Build Targets. Right-click Hello-Sort, then select Edit Content. The Content Definition dialog opens. By default, just the project you are working with appears in the Workspace pane. To see hello_VxWorks, click Show all projects. 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). Select hello.c, then click Add. The file appears in the Content pane. 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. 2.
Right-click DKM_pass_tgt and select Project References > Add as Project Reference. 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. 2.
Under vxWorks (default), right-click vxWorks and select Properties. Double-click the path shown as Location, then right-click it and select Copy.
74
6 Building Applications and Libraries 6.6 Reconfiguring Your Project Later in the Development Cycle
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. 2. 3.
In the Remote Systems view, click Define a connection on the left of the toolbar. Select Wind River VxWorks 6.x Simulator Connection, then click Next. 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. 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. 2.
Type dmain at the VxWorks simulator prompt. 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. 2.
Create a VxWorks Image project, as described in Configuring and Building VxWorks, p.31. Configure and build the VIP, as described in Adding Kernel Applications to a VxWorks Image, p.125.
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.
75
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.
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.
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. 2.
Right-click the project in the Project Explorer and select Properties. 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.
76
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. To import a build spec that you defined in another project, or reset the projects 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 projects enabled build specs) to a set of projects rather than changing them one at a time. The Subprojects tab of the VIPs 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 VIPs 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.
77
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 (integrated with code to call C++ static constructors and destructors). This object cannot be passed up to superprojects, although the current projects 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 projects 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 projects 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. 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
5.
78
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.82. 6. 7. Click OK. The selected option is appended to the Tool Flags, Debug mode, or Non Debug mode field. Continue with the following tasks, or if you have finished configuring your project, click OK.
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 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 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.
3.
Continue with the following tasks, or if you have finished configuring your project, click OK.
79
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. 2.
Specify a new location for the build output in the Redirection root directory field. 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.
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 Users 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. (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. Continue with the following tasks, or if you have finished configuring your project, click OK.
5. 6.
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. 2.
Click the Libraries tab to bring that page forward. 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 Programmers Guide: Kernel Applications. For more information about writing real-time process applications, see VxWorks Application Programmers Guide: RTP Applications.
80
6 Building Applications and Libraries 6.7 Example: Adding IPNet Support to a DKM
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.
To find the ENDIAN setting for your processor, do the following:
1. 2.
Select File > Open File. Navigate to the following file, substituting the Workbench installation directory for installDir and the appropriate VxWorks version for 6.x: Scroll down and look for the ENDIAN section, then look for the appropriate endianess setting for your processor.
installDir/components/ip_net2-6.x/ipcom/port/vxworks/gmake/ipcom_vxworks_make.mk
3.
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. 2. 3. 4.
Right-click the DKM project in the Project Explorer and select Properties. At the bottom of the Variables tab, select a build spec from the drop-down list that you want to add the preprocessor symbol to. Select CC_ARCH_SPEC in the Name column, and then click Edit. 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. Repeat these steps for the other build specs used by this project.
5.
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. 2. 3.
Click the Paths tab to bring it to the foreground. Next to the Include Paths pane, click Add to all to add the paths to all build specs used by this project. 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.
81
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.
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. 2. 3.
Open the Build Properties dialog, as described in Task 1: Access build properties., p.76, and click the Tools tab. Select Linker from the Build tool drop-down list, 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 Programmers 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. 2. 3.
Click the Wind River Workbench project icon, on the left end of the Workbench toolbar. From the Target operating system drop-down list, select Wind River VxWorks 6.x and then click Next. 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.
82
6 Building Applications and Libraries 6.10 Creating Shared Libraries
Static User Library, if the library is to be linked against a real-time process application. 4. 5. 6. Click Next. In the Project name field, type a name for your library. 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.69. 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. 2. 3. 4. 5. 6.
Select Wind River Workbench Project from the Workbench toolbar. The New Wind River Workbench Project wizard appears. Select Wind River VxWorks 6.x from the drop-down menu. Click Next. On the Build Type screen, select Shared User Library from the drop-down list. Click Next. On the Project screen, type a name for your project. Specify a location for your project. For more information, see 6.3 Creating a Project For Your Application, p.69. 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.149.
Configuring VxWorks Shared Libraries
You can create a shared library project, and later adjust its configuration options. For example, you can change the projects build specs, build tools, and other options later in the development cycle.
83
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. 2. 3.
Right-click the shared library in the Project Explorer and select Properties. In the Properties dialog, select Build Properties. Change the library build options as described in 6.6 Reconfiguring Your Project Later in the Development Cycle, p.75.
For more information about working with shared libraries, see VxWorks Application Programmers 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.85. 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 Users 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.83). 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.85. For more information about VxWorks plug-ins, see VxWorks Application Programmers Guide: Static Libraries, Shared Libraries, and Plug-ins.
84
6 Building Applications and Libraries 6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins
6.12 Example: Working with RTPs, Shared Libraries, and Plug-Ins

This example shows you how to create a pair of RTP application projects and a shared library, and then code and configure the applications so they call the library either as a shared library at run time, or as a plug-in when needed by the application. The example accesses a non-NFS file system on the host, but the procedure it describes is similar if you are working with an NFS file system. For information about setting up VxWorks with NFS support, see the Vxworks Kernel Programmer's Guide: Network File System. 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 RTPs and Libraries with a VxWorks Image, p.128.
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. Select File > New > VxWorks Real-Time Process Project. On the Project screen, type fooRtpApp as the name for your project.
b. c.
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.
85
3.
Create the shared library project. a. b. c. From the Advance Device Development perspective, select File > New > VxWorks Shared Library Project. On the Project screen, type barLib as the name for your project. Leave Create project in workspace selected, then click Finish.
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. b. In the Project Explorer right-click barLib, and select New > File. 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. b. c. Right-click barLib, and select New > File. In the File name field, type barLib.c, and then click Finish. 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. b. c. Right-click fooRtpApp, then select New > File. In the File name field, type fooRtpApp.c, and then click Finish. 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.
86
4.
Add a source file to the RTP application (that will use the library as a plug-in), in the following way: a. b. Right-click fooPlugRtpApp, and select New > File. In the File name field, type fooPlugRtpApp.c, then click Finish.
5.
Into fooPlugRtpApp.c, type the following code and change the dlopen() call so that it matches the path to the barLib.so file on your host system. For the VxWorks simulator, the path must be prefixed by the host: string (as in the code below). For information about accessing remote file systems from VxWorks (including other prefix requirements), see the VxWorks Application Programmer's Guide: I/O System.
#include <vxWorks.h> #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 in your 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-in using dlopen()\n"); return(0); }
6.
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.
87
To set up a build target for fooRtpApp, do the following:
1. 2. 3. 4. 5. 6. 7.
In the Project Explorer, double-click fooRtpApp to view its contents. Double-click Build Targets, then right-click fooRtpApp (fooRtpApp.vxe) and select Edit Content. Verify that fooRtpApp - recursive appears in the Content list. In the upper left corner of the Edit Content dialog, select Show all projects to see barLib. Expand all the nodes within barLib (do not double-click barLib, because that will add it to the Content list). Select barLib (barLib.so) and click Add. 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 doesnt need to include a header for the code it calls.
To set the include path for fooRtpApp, do the following:
1. 2. 3. 4.
Right-click fooRtpApp and select Build Options > Generate Include Search Paths. In the dialog that appears, click Next. On the Resolve include directives screen, click Resolve All. Notice that the entry -I%Proj-barLib% appears in the lower Include search paths pane. 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. b. c. Under the Build Targets node of fooPlugRtpApp, right-click fooPlugRtpApp (fooPlugRtpApp.vxe) and select Properties. Select the Tools tab to bring it forward. 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. 2. Click OK to close the Build Properties dialog.
Configure fooRtpApp in the following way: a. Open the Build Properties dialog and click Build Tools.
88
b. c.
Select Linker and click Tool Flags. 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.
To build the three projects in this example, do the following:
1. 2. 3.
To build the shared library, right-click the project and select Build Project. The build output appears in the Build Console. To build fooPlugRtpApp, right-click the project and select Build Project and click Continue when it asks to generate include paths. 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. At the command prompt, type the following:
$ readelfpentium -d fooRtpApp.vxe
3.
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:
89
Tag 0x00000001 0x00000001 0x00000004 0x00000006 0x0000000b 0x00000005 0x0000000a 0x00000017 0x00000002 0x00000014 0x00000016 0x00000003 0x00000011 0x00000012 0x00000013 0x00000015 0x00000018 0x00000000
Type (NEEDED) (NEEDED) (HASH) (SYMTAB) (SYMENT) (STRTAB) (STRSZ) (JMPREL) (PLTRELSZ) (PLTREL) (TEXTREL) (PLTGOT) (REL) (RELSZ) (RELENT) (DEBUG) (BIND_NOW) (NULL)
Name/Value Shared library: [barLib.so] Shared library: [libc.so.1] 0xc0 0x43c 16 (bytes) 0xa1c 1372 (bytes) 0x16e0 160 (bytes) REL 0x0 0x1805c 0xf78 1896 (bytes) 8 (bytes) 0x0 0x0
4.
For the RTP application that uses the plug-in, navigate to installDir/workspace/fooPlugRtpApp/SIMPENTIUMdiab_RTP/ fooPlugRtpApp/Debug. At the command prompt, type the following:
$ readelfpentium -d fooPlugRtpApp.vxe
5.
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.
90
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.
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. Select File > New > VxWorks Image Project. On the Project screen, type VIPsimpc as the name for your project, leave Create project in workspace selected, and click Next.
b. c.
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. If you are running a Linux host or a Solaris host, select linux or solaris, respectively, as your BSP.
To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. e. 2. From the Profile drop-down list, select PROFILE_DEVELOPMENT and click Finish. Your project appears in the Project Explorer.
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. 2.
On the Remote Systems toolbar, click Define a connection. In the New Connection dialog, select Wind River VxWorks 6.x Simulator Connection, and then click Next.
91
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. 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 images symbol table being loaded near the beginning of the sequence.
4.
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. 2.
In the vxsim window, switch the host shell from the C interpreter to the command interpreter by typing cmd. The prompt changes from -> to #. 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/Deb ug;host:installDir/vxworks-6.x/target/lib/usr/root/SIMPENTIUMdiab/bin" host:installDir/workspace/fooRtpApp/SIMPENTIUMdiab_RTP/fooRtpApp/Debug/fooRtpAp p.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/fooRtpA pp.vxe' ... Process 'host:installDir/workspace/fooRtpApp/SIMPENTIUMdiab_RTP/fooRtpApp/Debug/fooRtpA pp.vxe' (process Id = 0x1173a908) launched. I am main() in fooRtpApp I am bar() in barLib I 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:
92
6 Building Applications and Libraries 6.13 Running Applications on a Hardware Target
$ rtp exec -e "LD_LIBRARY_PATH=host:installDir/vxworks-6.x/target/lib/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 fooPlugRtpApp I am bar() in barLib I fooPlugRtpApp just called bar() in barLib as plug-in using dlopen() [vxWorks *]#
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.116. 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 Programmers Guide: Static Libraries, Shared Libraries, and Plug-Ins. For more information about the VxWorks simulator, see the Wind River VxWorks Simulator Users Guide. For more information about the host shell, see the Wind River Workbench Host Shell Users 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.95.
93
94
7
Connecting to VxWorks Targets
7.1 Introduction 95 7.2 What Are Target Servers and Target Agents? 96 7.3 Creating a VxWorks Simulator Connection 97 7.4 Defining a New Target Server Connection 99 7.5 Example: Connecting a Target Server to a Target Agent 104 7.6 Defining a New Remote Connection 106 7.7 Troubleshooting Target Server Connections 106
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 Configuring VxWorks Using the Kernel Configuration Editor, p.38).
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.
95
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 servers back end. For host-target communication to work, the target server must be configured with a back end that matches the VxWorks kernels 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 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, you can configure VxWorks images with both agents: a user-mode agent (INCLUDE_WDB_TASK), and a system-mode
96
7 Connecting to VxWorks Targets 7.3 Creating a VxWorks Simulator Connection
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 Users Guide: Debugging Projects) or the host shell (see Wind River Workbench Host Shell Users Guide).
To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. If you are working with an existing VIP, enable the WDB Target Agent in the Kernel Configuration Editor, see 4.4.1 Configuring VxWorks Using the Kernel Configuration Editor, p.38 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.
NOTE: To simulate 64-bit VxWorks, you must run the VxWorks simulator on a 64-bit host operating system. Your 64-bit host must be a supported version of Windows or Linux. Solaris is not a siupported host OS for 64-bit simulation. 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.
97
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: 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. 3.
On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Simulator Connection, then click Next. 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. If you want to bypass checksum comparison, select the check box. 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.
b. c.
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.
98
7 Connecting to VxWorks Targets 7.4 Defining a New Target Server Connection
4.
Set the simulator memory options, in the following way: a. b. The options on this screen allow you to manage your memory resources. Make sure the settings are adjusted the way you want, including whether you want to connect to the target now, then click Finish.
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 Users 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.37.
Back End Description Compatible Kernel Component
wdbrpc
The default back end. INCLUDE_WDB_COMM_END or Supports any kind of IP INCLUDE_WDB_COMM_NETWORK connection. Polled-mode Ethernet drivers are available for most BSPs to support system-mode debugging. For VxWorks target simulators.
INCLUDE_WDB_COMM_PIPE
wdbpipe
99
INCLUDE_WDB_COMM_SERIAL 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. wdbproxy For UDP, TCP, TIPC, and MIPC connections.
INCLUDE_WDB_PROXY_UDP (for
UDP/TCP),
INCLUDE_TIPC_ONLY, or INCLUDE_WDB_PROXY_MIPC
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. 2.
Click Define a connection on the Remote Systems view toolbar, or right-click in the view and select New > Connection. 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.
100
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. c. Identify the root directory of the host file system. By default, this is the workspace directory. 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. Click the Logging tab to enable output and back end logging on the Logging tab, and do the following as needed: a. Specify the logs 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).
3.
101
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. Click Next.
5.
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 modules symbols each time a module is loaded. 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. 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. 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.
2.
3.
4.
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. 2.
In the Remote Systems view, right-click the file or executable and select Load/Add Symbols to Debug Server. 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.
102
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. Click Next.
2.
Task 7: Set the debug options.
In this task, you specify the debug options.

To specify debug options, do the following:
1. 2. 3.
Specify which threads Workbench should stop when breakpoints are hit. Specify whether to display an error dialog on target exceptions. 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. 2.
To modify the Connection name, or any of the settings associated with this connection, click Back and update the appropriate screen. 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 Users 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.
103
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.106.
Where to Go Next
For more information about target servers and target agents, see the VxWorks Kernel Programmers 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.
a simulated target. To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. If you are working with an existing VIP, enable the WDB Target Agent in the Kernel Configuration Editor, see 4.4.1 Configuring VxWorks Using the Kernel Configuration Editor, p.38
Task 1: Open the New Connection wizard.
In this task, you bring up the New Connection wizard and specify a target server connection.
104
7 Connecting to VxWorks Targets 7.5 Example: Connecting a Target Server to a Target Agent
To open the New Connection wizard, do the following:
1. 2.
Click Define a connection on the Remote Systems view toolbar, or right-click in the view and select New > Connection. On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Target Server Connection, and then click Next.
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. 2.
Select the wdbrpc back end, and type in the name or IP address of the target. 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. 2. Follow the instructions, as described in Task 5: Configure object path mappings., p.102. 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. Click Next.
2.
Task 5: Set the debug options.
In this task, you specify the debug options.

To specify debug options, do the following:
1. 2. 3.
Specify which threads Workbench should stop when breakpoints are hit. Specify whether to display an error dialog on target exceptions. Click Next.
105
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.
To review connection summary options, do the following:
1. 2.
Verify that the settings reflect your choices on the previous screens. 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.23, 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.106.
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 Users 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.
106
7 Connecting to VxWorks Targets 7.7 Troubleshooting Target Server Connections
a simulated target. To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. If you are working with an existing VIP, enable the WDB Target Agent in the Kernel Configuration Editor, see 4.4.1 Configuring VxWorks Using the Kernel Configuration Editor, p.38
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 targets ports 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 Programmers Guide: Building VxWorks to Include Wind River TIPC.
107
108
8
Running and Debugging VxWorks Applications
8.1 Introduction 109 8.2 How Can Workbench Help Me Run My Code? 109 8.3 How Do I Create a Launch Configuration? 110 8.4 Running Your Applications 113 8.5 Debugging Your Applications 115 8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins 116 8.7 Monitoring Semaphores During Debugging 118
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 buildconnectrundebug 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 Users Guide: Launching Programs. For specific information on a tab or field, open the launch configuration dialog and press the help key for your host.
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
109
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-modeconnects to the target, then launches a task or process. Debug-modeconnects to the target, launches a task or process, and automatically attaches the Wind River debugger. Download-modeconnects 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.
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. 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. 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.
110
8 Running and Debugging VxWorks Applications 8.3 How Do I Create a Launch Configuration?
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. b. Verify that Workbench selected the correct target connection, or specify multiple targets for the launch. 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. 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.
c.
d. If this is a debug mode launch configuration, a Debug section appears: For a kernel taskspecify whether it should break on entry and if Workbench should automatically attach spawned kernel tasks. For an RTP applicationspecify 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. 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. On the Source tab, configure the source lookup path for your program. For details on how to do this, see Wind River Workbench Users Guide: Debugging Projects.
b.
111
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. 2. 3.
Select Run > Run Configurations or Run > Debug Configurations. The Create, manage, and run configurations dialog box appears. Select VxWorks Kernel Task or VxWorks Real-Time Process, then click New (or double-click the launch type). Continue with the steps outlined in Creating a Launch Configuration For an Existing Project, p.111, 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. 2.
Right-click a target connection, then select Run or Debug, then VxWorks Kernel Task or VxWorks Real-Time Process. 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).
112
8 Running and Debugging VxWorks Applications 8.4 Running Your Applications
Create a new launch configuration. 3. 4. The dialog displays one or more matching launch configurations. If one of them meets your needs, select it. 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.111, 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. 2. 3.
Expand your target connection down to Kernel Tasks or Real-Time Processes. Inside one of these nodes, find the task or process that you want to attach to, right-click it. 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.111. 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.
How to Run an Application
After you have created a launch configuration, you can run your program in the following ways:
113
From the Project Explorerby expanding a projects Wind River Launches node, then right-clicking a launch configuration and selecting Run or Debug. From the Remote Systems viewby expanding a target connections 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 menuby 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. (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.
3.
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.115. Or, you can open the Debug view, click in it, and press the help key for your host.
Troubleshooting Execution of RTP Applications
You may get an S_rtp_INVALID_FILE error when trying to execute an RTP application.
114
8 Running and Debugging VxWorks Applications 8.5 Debugging Your Applications
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 Users 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.37).
To enable the WDB Target Agent, see 4.3 Creating a Custom VxWorks Image, p.32. If you are working with an existing VIP, enable the WDB Target Agent in the Kernel Configuration Editor, see 4.4.1 Configuring VxWorks Using the Kernel Configuration Editor, p.38 Defined and established a target connection based on that kernel image, as described in 7.4 Defining a New Target Server Connection, p.99). Selected Debug mode when creating your source code projects. If you did not, you can do the following: a. b. Right-click the project in the Project Explorer, and select Properties, then Build Properties. 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.
115
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 the host file system. For more information, see Task 5: Configure object path mappings., p.102. 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 executables 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.111. Manually attach the debugger to a task or process, as described in Attaching to Running Tasks or Processes, p.113.
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.85. 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.
116
8 Running and Debugging VxWorks Applications 8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins
To relaunch the VxWorks simulator, do the following:
Select the simulator in the Remote Systems view and click Connect.
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 Project Explorer, right-click the build target fooRtpApp (fooRtpApp.vxe); then click Debug VxWorks Real Time Process. The Debug Congfigurations dialog appears.
2. 3. 4.
On the Launch Context tab, under General, click the Edit button next to the Environment field. In the Edit Environment dialog click Add, and in the Name field type LD_LIBRARY_PATH. 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/vx works-6.x/target/usr/root/SIMPENTIUMdiab/bin
5.
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. 2.
Click Debug to launch your application. 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 fooRtpApp I am bar() in barLib I 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.
117
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 RTPs and Libraries with a VxWorks Image, p.128.
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. 2.
Connect to your target in the Remote Systems view, as described in 7. Connecting to VxWorks Targets. 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.
118
8 Running and Debugging VxWorks Applications 8.7 Monitoring Semaphores During Debugging
The Kernel Objects view appears. System resources are displayed in a hierarchical tree. 4. 5. 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. Double-click a resource to examine it in the Kernel Objects view. Properties and their current values are displayed in the Properties view.
119
120
PA R T V
Deploying Applications
9 Deploying VxWorks Systems .................................................. 123
121
122
9
Deploying VxWorks Systems
9.1 Introduction 123 9.2 Reconfiguring VxWorks for Deployment 123 9.3 Adding Kernel Applications to a VxWorks Image 125 9.4 Example: Bundling RTPs and Libraries with a VxWorks Image 128
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 Programmers Guide: RTP Applications VxWorks Kernel Programmers 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
123
way to do this is to exclude the WDB components from your VIP using the Kernel Configuration Editor. !
on UDP port 17185. This service provides full access to VxWorks memory, and allows for writing to memory as well as for calling routines. Wind River recommends removing WDB from VxWorks for production systems. To disable the WDB Target Agent, use the Kernel Configuration Editor to exclude the WDB components from your kernel image; see Excluding Components from a Kernel Image, p.40. 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 from a Kernel Image, p.40, and is included here for convenience.
To exclude WDB agent services from a VIP, do the following:
1. 2. 3. 4. 5.
Expand your VIP project, then double-click the Kernel Configuration node to open the Kernel Configuration Editor. Right-click in the Component Configuration pane, then select Find from the context menu. In the Find dialogs Find Scope pane, select Description, then in the Pattern field, type WDB. The dialog displays a list of matching entries. Select WDB agent components, then click Find. The Component Configuration tree displays it in context. 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. 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,
7.
124
9 Deploying VxWorks Systems 9.3 Adding Kernel Applications to a VxWorks Image
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.
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.50, and is included here for convenience.
To exclude System Viewer components from a project, do the following:
1. 2.
Double-click your VSB, then double-click the Source Build Configuration node. Search for System Viewer components in the following way: a. b. Right-click in the Option pane, then select Find. Type a letter or two of the options name into the Pattern field, using wildcard characters if necessary.In this case, typing an S displays Enable System Viewer Instrumentation Support. Select Enable System Viewer Instrumentation Support and click Find. The component appears in the Option pane.
c. 3. 4. 5. 6.
In the Option pane, right-click Enable System Viewer Instrumentation Support and select Change value. Scroll to the right (if necessary) and from the drop-down list select n to deactivate System Viewer support. Press CTRL+S to save your changes, or close the editor and select Yes when you are prompted to save. 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.
125
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. This example includes the following tasks: 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. 2. 3.
Right-click the project that you want to make into a subproject and choose Project References > Add as Project Reference. 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. 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. 2. 3.
To add kernel application initialization calls to VxWorks, double-click userAppInit.c to open the file for editing. In the usrAppInit( ) function, add the necessary calls to start your application. 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.
126
9 Deploying VxWorks Systems 9.3 Adding Kernel Applications to a VxWorks Image
To configure VxWorks to support your application, do the following:
1. 2. 3.
Double-click the VIP to expand it. Double-click the Kernel Configuration node to open the Kernel Configuration Editor. 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 Autoscales 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.
127
9.4 Example: Bundling RTPs and Libraries with 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.85. 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 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. Here are the steps you will follow: 1. 2. 3. 4. 5. 6. 7. 8. 9. 10.
Step 1:
Set the target-side run path for an application. Change fooPlugRtpApp to reference ROMFS instead of the workspace. Rebuild your RTP applications. Create a VxWorks ROMFS File System project. Set up the ROMFS target file system. Rebuild your VxWorks image project Restart the VxWorks simulator and view ROMFS contents. Launch the RTP applications and disconnect the VxWorks simulator. Add the application initialization routines. Verify that your application launches automatically.
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. 2.
In fooRtpApp, right-click the build target fooRtpApp (fooRtpApp.vxe), then select Properties. 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.
128
9 Deploying VxWorks Systems 9.4 Example: Bundling RTPs and Libraries with a VxWorks Image
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
/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 Step 4:Create a VxWorks ROMFS File System project., p.129. 5. 6. Click OK to save your settings and close the dialog. In fooPlugRtpApp, do the following: a. b. c. Open the build properties for fooPlugRtpApp (fooPlugRtpApp.vxe). On the Build Tools tab, make sure Linker and the correct build spec are selected. 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.
Step 2:
Click OK to save your settings.
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. 2. 3.
Step 3:
In fooPlugRtpApp, double-click fooPlugRtpApp.c to open it in the editor. Change the dlopen call to:
handle = dlopen("/romfs/lib/barLib.so", RTLD_NOW);
Close fooPlugRtpApp.c, and click Yes to save your changes.
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. 2.
Right-click fooPlugRtpApp and select Rebuild Project. Right-click fooRtpApp and select Rebuild Project. Both applications should build without errors.
Step 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.
129
To create a VxWorks ROMFS file system project, do the following:
1. 2. 3. 4.
In the Project Explorer, select VIPsimpc so the new ROMFS project will become a subproject of your VIP. Select File > New > VxWorks ROMFS File System Project. In the Project name field, type romfsFS. 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.
Step 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. 2.
In the upper left corner of the File System Contents editor, click Show all projects. In the editor, create bin and lib directories, in the following way: a. b. c. Click New Folder, then type bin in the Name field. Click OK. Click New Folder again, then type lib in the Name field. Click OK.
The new directories appear in the Target contents pane.

NOTE: To add a folder, its contents and subfolders to the target, under Host contents click to highlight a folder that contains files; then click Add Folder recursive.
You can also drag and drop folders and files from the Host contents tree to the Target contents tree. You cannot add empty folders to the Target contents using these techniques. 3. Add your application binaries in the following way: a. b. c. 4. Click the bin directory to select it. In the Host contents pane, open fooPlugRtpApp and select fooPlugRtpApp (fooPlugRtpApp.vxe). Click Add.1
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.
1. If you select something in the Target contents pane and then need to unselect it, click in the pane and press ESC.
130
b. c. 6.
In the Host contents pane, open barLib and select barLib (barLib.so). Click Add.
With the lib directory still selected, add the VxWorks standard shared library in the following way: a. b. Click Add External. 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.
Step 6:
Close the File System Contents editor, and click Yes to save the changes.
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.
Step 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. 3.
Switch the host shell from the C interpreter to the command interpreter by typing cmd. The prompt changes from -> to #. 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"
131
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
Step 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.
[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 fooRtpApp I am bar() in barLib I 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 fooPlugRtpApp I am bar() in barLib I 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.
Step 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. 2.
Double-click userRtpAppInit.c to open the file for editing. In the usrRtpAppInit( ) function, add the following commands to start fooRtpApp.vxe:
/* Includes #include #include #include #include */
<vxWorks.h> <rtpLib.h> <stdio.h> <errno.h>
/*********************************************************************** *
132
* 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); } }
3. 4.
Step 10:
Close the file and select Yes when asked to save the changes. Right-click the VIP and select Rebuild Project.
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. 2. 3.
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. Once the boot sequence is completed, verify that the simulator launched fooRtpApp.vxe. The following output should appear:
-> I am main() in fooRtpApp I am bar() in barLib I 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 Programmers Guide: RTP Applications VxWorks Kernel Programmers Guide: Kernel Applications.
133
134
PA R T VI
Reference
A B C What Are All These Project Files For? ................................... 137 Debugging a VxWorks 5.5 Target ............................................ 151 Glossary .................................................................................... 159
135
136
A
What Are All These Project Files For?
A.1 Introduction 137 A.2 Files Common to Many Project Types 138 A.3 Project Files in VxWorks Image Projects 139 A.4 Project Files in VxWorks Source Build Projects 142 A.5 Project Files in Downloadable Kernel Module Projects 144 A.6 Project Files in Real-Time Process Projects 146 A.7 Project Files in Boot Loader/BSP Projects 148 A.8 Project Files in Shared Library Projects 149
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.
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.
137
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 projects 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. .cproject CDT project file containing CDT-specific information about the project. .project This 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. .wrmakefile This file is a template that Workbench uses to generate the projects Makefile. You can add your own build targets and make rules to this file, and they will be automatically dumped into the Makefile. .wrproject This file contains common Workbench project properties such as build properties, project type specification, and platform association.
Container Nodes Within Your Project
Build Targets Workbench creates build targets for most projects, except for VxWorks Image, VxWorks Source Build, and User-Defined projects. Wind River Launches When you create launch configurations for your project, they appear here for easy access and reuse. Binaries Provides easy access to the projects binaries. Includes Shows the projects include files.
138
A What Are All These Project Files For? A.3 Project Files in VxWorks Image Projects
Files That Appear After You Build the Project
Makefile This 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.
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.
Figure A-1 VIP Just After it is Created
For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.138. 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.141.
139
ProjectName The icon identifies the type of project. Kernel Configuration Double-clicking this node opens the Kernel Configuration Editor, which you can use to configure your VxWorks image. See 4.4 Configuring VxWorks, p.37. vxWorks (default) vxWorks.bin (default) vxWorks.hex (default) When you build your project, the vxWorks build target will be built using the projects 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 node This node links in BSP files used by the VIP. They are available for browsing purposes only. linkSyms.c A 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. It is dynamically generated, so do not check it in to your version control system. 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. It is dynamically generated, so do not check it in to your version control system.
140
A What Are All These Project Files For? A.3 Project Files in VxWorks Image Projects
romStart.c Along 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.makefile Workbench uses this makefile fragment to invoke the scripts for the BSP Validation Test Suite. creation.log Provides information related to the creation of the VIP. Makefile.mk This file is called from the projects 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 projects Makefile, as well as project source files such as prjConfig.c. vxWorks.makefile This template contains all necessary instructions to build the VIP. Workbench invokes it from the projects Makefile.
Files That Appear After the Project is Built
Several new files are added to the project during the build process.
141
Figure A-2
VIP After it is Built
default This is the build output folder, named after the selected build spec. compObjs.lst This is generated by the run-time build system during the build. prjObjs.lst This is generated by the run-time build system during the build, and lists the object files linked into the kernel image.
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.
142
A What Are All These Project Files For? A.4 Project Files in VxWorks Source Build Projects
Figure A-3
VSB Just After it is Created
For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.138. Below are the files that are specific to VSBs. 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.141. ProjectName The icon identifies the type of project. Source Build Configuration Double-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.47. h This 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. Sources If 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.log Provides information related to the creation of the VSB. vsb_bs.vxconfig vsb.vxconfig These files are used as inputs to the Source Build Configuration editor. vsb.config This file is one of the files generated from the Source Build Configuration editor when changes are saved.
143
vsb_comp_list.mk vsb_defs.mk These make fragments are used for building the VSB. vsbClean.tcl vsbdefs.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 Folder This folder contains the generated archive files for the project. architecture This folder contains the binary output of the build, in other words the kernel libraries that contain the configuration information for the VSB. objarchitectureBuildspectest This folder contains test related object files (they are not part of any existing archive).
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.
144
A What Are All These Project Files For? A.5 Project Files in Downloadable Kernel Module Projects
Figure A-5
DKM Just After it is Created
For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.138. Below are the files that are specific to DKMs. 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.145. ProjectName The icon identifies the type of project. 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.o This 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.
145
Figure A-6
DKM After it is Built
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. Build Output All build output is directed to this folder. Archives Folder This 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.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.
146
A What Are All These Project Files For? A.6 Project Files in Real-Time Process Projects
Figure A-7
RTP Just After it is Created
For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.138. Below are the files that are specific to RTPs. 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.147. ProjectName The icon identifies the type of project. TargetName.vxe (BuildSpec [- debug]) This is a fully linked VxWorks executable.
Figure A-8 RTP After it is Built
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.
147
Build Output All build output is directed to this folder. Archives Folder This 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.
A.7 Project Files in Boot Loader/BSP Projects

Workbench creates only a few files to support this type of project.
Figure A-9 VxWorks Boot Loader/BSP Project Just After it is Created
For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.138. Below are the files that are specific to boot loader and BSP projects. 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.149. ProjectName The icon identifies the type of project. BSPname (bootloader) This node reflects the BSP you used when creating the project, as well as the currently active build spec.
148
A What Are All These Project Files For? A.8 Project Files in Shared Library Projects
BSP node If 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 node If 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).
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.
Figure A-10 Shared Library Just After it is Created
For the files that are common to most projects, see A.2 Files Common to Many Project Types, p.138. Below are the files that are specific to shared libraries. 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.149. ProjectName The icon identifies the type of project. TargetName.so The shared library used by the VxWorks executable.
149
Figure A-11
Shared Library After it is Built
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. Build Output All build output is directed to this folder.
150
B
Debugging a VxWorks 5.5 Target
B.1 Introduction 151 B.2 Before You Begin 151 B.3 Creating a VxWorks 5.5 DKM Project 152 B.4 Creating a VxWorks 5.5.x Target Server Connection 153 B.5 Launching a Kernel Task and Attaching the Debugger 153 B.6 Using Existing Tornado 2.2.x Projects 157
B.1 Introduction
This tutorial explains how to use Workbench to create a Tornado 2.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.2.x installed.
NOTE: You must have built your VxWorks 5.5.x image in Tornado before you can
work with it in Workbench. IMPORTANT: You must disable the Tornado 2.2.x registry service (or process) before working with this tutorial. Workbench automatically launches a registry that can communicate with the Tornado 2.2.x target server. 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.
151
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.2 workbench-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:
1. 2. 3. 4.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Select File > New > Example, then select VxWorks 5.5 Downloadable Kernel Module Sample Project and click Next. Select the Cobble demo, then click Finish. The project appears in the Project Explorer. 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.
NOTE: This procedure supports only PowerPC and Pentium CPUs.
5.
Right-click the project and select Build Project, or press CTRL+B, CTRL+P. The Build Console displays a warning about a bug in the code.
6. 7.
Double-click the error symbol to open cobble.c to line 280, then fix the bug. 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
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.
152
B Debugging a VxWorks 5.5 Target B.4 Creating a VxWorks 5.5.x Target Server Connection
8. 9.
Right-click the project folder and select Rebuild Project. Workbench saves your changes before starting the build. Your project should build cleanly. Continue on with Creating a VxWorks 5.5.x Target Server Connection.
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. 2. 3. 4.
From the Remote Systems view toolbar, click Define a connection to remote system. The New Connection wizard opens. From the Connection Type list, select Wind River VxWorks 5.5.x Target Server Connection, and click Next. Click Next through the next few screens, reviewing and customizing the target server options as necessary. Click Finish to create your connection definition.
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.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. Once the connection to the Tornado target server is established, it appears under default(localhost) followed by [Target Server running]. 5. 6. To connect to the Tornado 2.2.x target, right-click the target server and select Connect. The target connection appears under the target server connection2. 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
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.
153
Analyzing Core Dump Files
Configuring the Debug Launch Configuration
In this task, you modify the debug launch configuration so that the debugger is attached. 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. 2.
In the Remote Systems view, right-click your system node, then select Target Mode. Make sure Task is selected. Right-click your target again, and this time select Debug Kernel Task. The Debug Launch Configuration dialog appears. The Name field displays your projects build target and target name, but as yet no entry point is defined.
3. 4. 5.
Click Browse next to the Entry Point field, select Downloads > cobble_55.out > progStart, and then click OK. Click the Download tab to bring it to the foreground, then click Add. In the Download dialog, browse to the location of your projects build target (installDir/workspace/cobble_55/PPC603diab_DEBUG/cobble_55.out). Make sure Load Symbols to Debug Server is selected, and then click OK. 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. 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.
6.
7.
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 breakpoints 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.
154
B Debugging a VxWorks 5.5 Target B.5 Launching a Kernel Task and Attaching the Debugger
To set and run to a breakpoint, do the following:
1. 2. 3. 4.
Open the Outline view by selecting Window > Show View > Outline. Select the function cosmos. The Editor shows that section of cobble.c, with cosmos highlighted. Scroll down to line 166 (containing nadaNichtsIdx) and right-click in the left Editor gutter and select Breakpoints to open the Breakpoints submenu. 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. 7. 8. 9.
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. Several lines below crunch, right-click in the gutter beside line 268 (beginning while) and select Breakpoints > Add Breakpoint (Scope = tCrunch). Return to the Debug view, select tCosmos, and click Resume. 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. 2. 3. 4. 5. 6.
Before switching to system mode, highlight tCrunch and tCosmos in the Debug view, click Resume, then click Disconnect (not Terminate). In the Remote Systems view, right-click your system node (which should still be running), then select Target Mode > System to switch into system mode. Open the target console by right-clicking your target and selecting Target Tools > WTX Console. 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. In the Remote Systems view, right-click your target and select Attach to Kernel (System Mode). Right-click system tasks as needed, and then select Attach to Kernel Task (System Mode).
155
7. 8. 9.
Right-click tCosmos and tCrunch and select Attach to Kernel Task. The tasks appear in the Debug view. Select monitor in the Outline view to switch the Editor display to that part of cobble.c. Set a breakpoint by right-clicking in the gutter next to line 302 (beginning if). 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. 2. 3. 4.
On the Remote Systems view toolbar, click Define a connection to remote system. In the New Connection wizard, select Wind River VxWorks 5.5.x Core Dump Connection, then click Next. On the next screen, navigate to the location of your core dump file and the VxWorks kernel image. 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. 6.
Go to the Debug view. The backtrace of the current execution context appears. Note that the run control icons are disabled. (Optional) Attach to other tasks and see their backtraces.
156
B Debugging a VxWorks 5.5 Target B.6 Using Existing Tornado 2.2.x Projects
B.6 Using Existing Tornado 2.2.x Projects

In this task, you import an existing Tornado 2.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.
To import an existing Tornado project into Workbench, do the following:
1. 2. 3. 4. 5.
Switch to the Advanced Device Development perspective, or if it is not open, select Window > Open Perspective > Advanced Device Development. Create a new user-defined project by selecting File > New > User-Defined Project. In the Target Operating System dialog, select Wind River VxWorks 5.5 (this allows you to use the Tornado 2.2.x compilers), and then click Next. On the next screen, type a descriptive name into the Project name field, then select Create project at external location. Navigate to the location of your existing Tornado 2.2.x project, and click Finish. A dialog appears telling you that the directory you pointed to already contains project information.
6. 7.
Click Yes to overwrite existing project information. Your project appears in the Project Explorer. Right-click the new project and select Build Project, or press CTRL+B, CTRL+P. Since this is a user-defined project, the build calls the Makefile generated by Tornado 2.2.x tools. (Optional) To add or remove files, use the Tornado 2.2.x IDE or edit the Makefile manually. Launch Tornado from Workbench, by selecting Target > Launch Wind River Tornado.
8. 9.
To debug a kernel module, proceed as described in B.5 Launching a Kernel Task and Attaching the Debugger, p.153. 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.2.x, and the Workbench debugger cannot overcome this limitation.
157
158
C
Glossary
C.1 Introduction 159 C.2 Searching for Terms in Online Documentation 159 C.3 Terms 160
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. 2. 3. 4. 5. If it is not already open, open the Help view by pressing the help key for your host. At the bottom of the view, select Search. Type the term you are looking for into the Search expression field. Click Go. Links to topics containing the term will appear, along with a short example of the surrounding text. 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 topics document appears in the help Table of Contents, click the Show in All Topics icon in the upper right corner of the help view.
159
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. 2. 3. 4. 5. 6. 7. Click Search at the bottom of the Help view. Click the Default link next to Search Scope. In the Select Search Scope Sets dialog box, click New. Type in a name for your new Scope Set, for example WR Documentation. Click OK. Select your new Search Scope Set, then click Edit. In the Search Scope dialog box, click Search only the following topics. From the Working set content pane, select the document sets to which you want to narrow the search, for example Wind River Documentation > Workbench. Click OK twice to return to the help browser, where your new search scope appears next to the Search scope link. Click Go. The results will appear in the Search list.
8. 9.
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
160
C Glossary C.3 Terms
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.
161
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.
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. 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 views 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.
162
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 servers name with the network address needed to connect to that target server, thereby allowing you to select a target server by a convenient name.
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 views title bar contains the view name, its icon, and the view toolbar. A highlighted title bar denotes the active view.
163
toolbar
A views 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. A VIP provides build support, source code analysis, and other capabilities that simplify the creation, configuration, and building of a kernel image. A VIP is one of the primary means for configuring VxWorks (the other is the VSB project). To work with (configure and build) a VIP, you can use the Workbench development suite (IDE) or the vxprj command line development tool.
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. !
on UDP port 17185. This service provides full access to VxWorks memory, and allows for writing to memory as well as for calling routines. Wind River recommends removing WDB from VxWorks for production systems.
window
The desktop development environment as a wholethe 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.
164
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.
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.
165
166
Index
A
application initialization routines 126 applications adding routines to VIPs 126 adding to VIPs 125 deploying 13 how to run 113 kernel 12, 125 launch RTP 132 rebuild RTP 129 user 12 writing in Workbench 11 Autoscale 126
default and active 77 PowerPC variants 71 Subprojects tab of VIP 77 target, passing up to superproject bundle, VxWorks image 128
72
C
cables, connecting 21 command line, import VIPs from 45 components including 39 config.h make writable 62 modify 62 configuring jumpers 22 target hardware 21 VxWorks image project 126 VxWorks kernel components 38 VxWorks source libraries 49 core dump, connecting to VxWorks 5.5.x 156
B
back end, target server 100 basename mappings 102 board support package 59 creating 61 customizing 13 customizing manually 61 simulator 60 Wind River Workbench 60 boot loader creating 54 default 54 redefine link address 57 select drivers 58 booting parameters displaying current, at boot time 23 VxWorks 24 rebooting VxWorks 25 troubleshooting 26 BSP See board support package build redirection root directory 80 spec
D
debug server, loading symbols 102 debugging applications 115 attaching the debugger 116 before you begin 115 dual mode 96 multi-process 118 run program 114 VxWorks 5.5 target 151 dependency checking 125 Domain Name Service (DNS) 20 downloadable kernel module (DKM) driver, non-default 41 dual mode debugging 96
69
167
dynamic executable
128
IPV6, kernel libraries 33
E
Examples Adding IPNet Support to a DKM 81 Building a VIP With Sources in a Subdirectory 41 Bundling RTPs and Libraries with a VxWorks Image 128 Connecting a Target Server to a Target Agent 104 Creating and Passing a Build Target 72 Customizing a BSP 61 Customizing VxWorks Libraries as a Base For a VIP 50 Debugging a VxWorks 5.5 Target 151 Debugging RTPs, Shared Libraries, and Plug-ins 116 Discussion of PowerPC Build Spec Variants 71 Working with RTPs, Shared Libraries, and PlugIns 85 executable, dynamic 128 exporting, object path mappings 102 EXTRA_MODULE 126
J
jumpers 22
K
Kconfig 50 kernel applications 12, 125 booting and loading 12 image 10 kernel configuration editor 38, 124 kernel configuration profiles 35 kernel image, creating 32 kernel libraries, IPv6 33 Kernel Objects view, multi-process debugging 118 kernel, SMP support 33
L
launch configuration attach task or process 113 create for existing project 111 create with Run menu 112 from target connection 112 LD_LIBRARY_PATH 128 libraries, custom VxWorks 49 LIBS 126 link address, redefine 57 link order, adjusting 43 Linker 128 loading symbols to debug server 102
F
File Transfer Protocol See FTP server Find dialog 39 FTP server configuring 19
H
hosts file, setting up 20
I
image custom kernel 11 kernel 10 pre-built 10 system, deploying 13 image type VxWorks 36 importing object path mappings 102 VIP, SMP-enabled sample 44 include search path 80 INCLUDE_WDB_SYS 97 INCLUDE_WDB_TASK 96 IPNet APIs, adding support to a DKM 81
M
macros EXTRA_MODULE 126 LIBS 126 Makefile templates migrate modified 45 migrate unmodified 45 memory overlapped virtual 82 target server cache size 101 MIPC, target server back end 100 multi-process debugging 118
168
Index
N
new connection wizard 100 new project wizard 13 non-default driver 41
O
object path mappings comparison with source lookup path creating automatically 102 exporting 102 importing 102 overlapped virtual memory 82 115
ROMFS 129, 130, 131 RTPs launch 132 rebuild 129 running 114 troubleshooting 114 writing 69 run path, set target-side 128
S
S_rtp_INVALID_FILE error 114 search path, include 80 semaphores, monitoring 118 simulator establishing a new connection 97 VxWorks 60 SMP-enabled sample VIPs, importing 44 source build changing BSP or CPU 53 configuration editor 49 project, VSB 47 source lookup path, compare with object path 115 starting Workbench 21 Subprojects tab, setting build spec of VIP subprojects 77 system image 13 system mode 96 System Viewer 101, 125 system-mode agent 96
P
polled mode 97 PowerPC, discussion of build spec variants 71 pre-built image 10 processes, RTPs 114 PROFILE_BOOTAPP 57 profiles 33 project benefits of 10 bsp, getting a functioning 60 create in workspace 60 create VSB 47 DKM 69 import or migrate 44 importing Tornado 2.x 157 in external location 60 linking application projects to VxWorks image 126 rebase VSB and VIP 53 ROMFS file system 130 RTP 69 VSB 125 VxWorks importing command line-generated 45 kernel configuration profiles 33 Workbench example 15
T
target agent dual mode 96 polled mode 97 system mode 96 user mode 96 board configuring 21 jumpers, setting 22 serial port 21 Terminal view 21 file system, ROMFS 130 server back end settings 100 connections establishing new 99 ethernet 99 Tornado 153 definition 96 file system (TSFS) 101 making writable 101 memory cache size 101 timeout options 101
R
real-time process See also RTPs rebase, VSB and VIP projects 53 rebooting VxWorks 25 redirection root directory 80 Remote Systems view 95 basename mappings 102 define a VxWorks Simulator connection shared connection configuration 103 ROM_SIZE 64
97
169
troubleshooting 106 WDB Pipe back end 99 WDB Proxy back end 100 WDB RPC back end 99 WDB Serial back end 100 Terminal view 21 entering text 22 TIPC target server back end 100 troubleshooting connection 107 Tornado creating a target server connection 153 importing Tornado 2.x projects 157 Workbench finding an installation of 151 troubleshooting booting problems 26 hardware configuration 25 target server problems 106 VxWorks 25 TSFS See target server, file system 101
image type 36 kernel, configuring 38 libraries, configuring 49 rebooting 25 reconfigure for deployment 123 simulator 60, 97 source build project 47 configuring 49 target server connection, 5.5.x 153 tutorial, VxWorks 5.5 151
W
WDB back end agent components 124 Pipe 99 Proxy 100 RPC 99 Serial 100 WFTPD FTP server 19 wizard new connection 100 new project 13 Workbench finding a Tornado installation 151 Kernel Objects view 118 starting 21
U
user mode 96 userAppInit.c 126 user-mode agent 96
V
virtual memory, overlapped 82 VSB See VxWorks source build project VxWorks booting 23 bundling RTPs and libraries 128 configure 37 core dump, connecting to VxWorks 5.5 156 define simulator connection 97 deployment 123 image configuring with Autoscale 126 create custom 32 pre-built 24 image project base on custom BSP 63 base on different VSB 53 based on VSB 52 build 127 bundle 128 importing and migrating 43 importing command line-generated 45 kernel configuration profiles 33 linking application projects to 126 sources in a subdirectory 41
170

WR Workbench Vxworks 6 by Example 3.3

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

WR Workbench Vxworks 6 by Example 3.3

Caricato da

Copyright:

Formati disponibili

Wind River Workbench (VxWorks 6 Version) By Example, 3.

Wind River Workbench

VxWorks 6 Version Edition 2

Wind River Workbench By Example 3.3 VxWorks 6 Version Edition 2 8 Jun 11

PART II: SETTING UP YOUR ENVIRONMENT

Wind River Workbench By Example, 3.3

Setting Up Your Host & Target ...................................................................

PART III: CUSTOMIZING THE OPERATING SYSTEM

Working with Board Support Packages ....................................................

PART IV: DEVELOPING AND DEBUGGING APPLICATIONS

Building Applications and Libraries .........................................................

Connecting to VxWorks Targets ................................................................

Running and Debugging VxWorks Applications ..................................... 109

Wind River Workbench By Example, 3.3

8.5 8.6 8.7

PART V: DEPLOYING APPLICATIONS

PART VI: REFERENCE

Debugging a VxWorks 5.5 Target ............................................................. 151

Glossary ..................................................................................................... 159

Index ..................................................................................................................... 167

Wind River Workbench By Example, 3.3

Wind River Workbench By Example, 3.3

1.2 How This Guide is Organized

Wind River Workbench By Example, 3.3

VxWorks By Example Task Map

1.3 Related Documentation

1 Overview 1.3 Related Documentation

Wind River Workbench Users Guide

Wind River Workbench By Example, 3.3

Setting Up Your Environment

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

Wind River Workbench By Example, 3.3

Wind River Workbench By Example, 3.3

2.2 The Benefits of Projects

2.3 Deciding on a Kernel Image

When to Use a Pre-built Image

2 Getting Started With Workbench 2.4 Writing Applications in Workbench

When to Use a Custom Kernel Image

When to Rebuild VxWorks Libraries and Build a Kernel Image

2.4 Writing Applications in Workbench

Wind River Workbench By Example, 3.3

About Kernel Applications

About User Applications

2.5 Creating a Library to Use With an Application

2.6 Loading and Booting a Kernel Image

2 Getting Started With Workbench 2.7 Customizing a Board Support Package

2.7 Customizing a Board Support Package

2.8 Deploying an Application with a System Image

2.9 Using the Wind River Workbench New Project Wizard

Wind River Workbench By Example, 3.3

2.10 Walkthrough Examples

2 Getting Started With Workbench 2.11 Workbench Example Projects

2.11 Workbench Example Projects

Wind River Workbench By Example, 3.3

Wind River Workbench By Example, 3.3

3.2 What Should Your Development Environment Look Like?

3.3 Configuring Your Host Machine

Install Workbench and other Platform products.

On Linux or Solaris Hosts

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

Wind River Workbench By Example, 3.3

3.4 Configuring Your Target

3 Setting Up Your Host & Target 3.4 Configuring Your Target