Wind River Workbench
BY EXAMPLE
3.3
VxWorks 6 Version
® Wind River Workbench (VxWorks 6 Version) By Example, 3.3trademarks 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 ...
3
1.1 Introduction ... 3
1.2 How This Guide is Organized ... 3
1.3 Related Documentation ... 4
PART II: SETTING UP YOUR ENVIRONMENT
2
Getting Started With Workbench ...
9
2.1 Introduction ... 9
2.2 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
3
Setting Up Your Host & Target ...
17
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
PART III: CUSTOMIZING THE OPERATING SYSTEM
4
Configuring and Building VxWorks ...
31
4.1 Introduction ... 31
4.2 Before You Begin Creating a Kernel Image ... 32
4.3 Creating a Custom VxWorks Image ... 32
4.4 Configuring VxWorks ... 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
5
Working with Board Support Packages ...
59
5.1 Introduction ... 59
5.2 Creating an Experimental Default BSP ... 59
5.3 Example: Customizing a BSP ... 61
Contents
6
Building Applications and Libraries ...
67
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
7
Connecting to VxWorks Targets ...
95
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
8
Running and Debugging VxWorks Applications ... 109
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.5 Debugging Your Applications ... 115
8.6 Example: Debugging RTPs, Shared Libraries, and Plug-ins ... 116
8.7 Monitoring Semaphores During Debugging ... 118
PART V: DEPLOYING APPLICATIONS
9
Deploying VxWorks Systems ... 123
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
PART VI: REFERENCE
A
What Are All These Project Files For? ... 137
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
B
Debugging a VxWorks 5.5 Target ... 151
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
Contents
C
Glossary ... 159
C.1 Introduction ... 159
C.2 Searching for Terms in Online Documentation ... 159
C.3 Terms ... 160
PA R T I
Introduction
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.
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.
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:
VxWorks By Example Task Map
1.3 Related Documentation
The Wind River Workbench documentation set includes the following:
Wind River Workbench By Example (this guide) Wind River Workbench User’s Guide
Context-sensitive help.
Wind River Workbench By Example Guide
This guide provides solutions to common VxWorks-related 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.
Topic Description Where to Find the Information
Setting up your environment
How to set up your host system and target, and how to to get started using
Workbench.
2. Getting Started With Workbench
3. Setting Up Your Host & Target
Developing How to create various projects, build applications, and libraries.
4. Configuring and Building VxWorks
5. Working with Board Support Packages
6. Building Applications and Libraries
Debugging How to run and debug applications on your host system and target.
7. Connecting to VxWorks Targets 8. Running and Debugging VxWorks Applications
Deploying How to reconfigure VxWorks and add kernel applications to an image in the process of deployment.
9. Deploying VxWorks Systems
Reference Provides information on VxWorks project file types, how to debug a VxWorks 5.5 target, and a glossary of terms.
A. What Are All These Project Files For?
B. Debugging a VxWorks 5.5 Target
1 Overview
1.3 Related Documentation
Wind River Workbench User’s Guide
Refer to the Wind River WorkbenchUser’s 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 User’s 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. In Workbench, navigate to the view, dialog, or feature for which you want help or information.
2. 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. In the Workbench menu, click Help > Search.
2. 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 I I
Setting Up Your Environment
2
Getting Started With Workbench ...
9
3
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.
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 developing—kernel applications and user applications use different project types.
About Kernel Applications
Kernel applications run in kernel mode, with no barriers between the memory used by the kernel application and the memory used by the kernel itself. 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.
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
Programmer’s 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.
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 directory—the 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. On the Target Operating System page, from the Target operating system drop-down menu, select a target operating system; then click Next.
3. 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. On the Project page, in the Project name field, type a unique name for your project.
5. 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.
2.10 Walkthrough Examples
The following list shows the examples in this guide that illustrate procedures common in many development environments:
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 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. In the Workbench menu. click File > New > Example.
2. In the New Example dialog, in the Wizards list, click a project type; then click
Next.
3. In the New Project Sample dialog, under Available Examples, click an example program; then click Finish.
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
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. Install Workbench and other Platform products.
2. Configure TCP/IP.
3. Set up FTP on the host.
4. Decide whether to enable logging.
Step 1: 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.
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. Start the FTP server on the host by selecting Start > Programs > Wind River >
VxWorks 6.x and General Purpose Technologies > FTP Server.
2. Configure a user name and password for the VxWorks boot loader on the target.
a. From the WFTPD toolbar, select Security > Users/rights. b. In the User/Rights Security Dialog, click New User.
c. In the New User dialog, enter a user ID, then click OK. Be sure to use this same user ID when you assign the user VxWorks boot parameter
described in 3.5 Booting a Target with VxWorks, p.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.
f. 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).
g. 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. 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.
2. 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.
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. Assign the VxWorks target a name and IP address.
2. Set up a serial connection between the host and target.
3. Set up an Ethernet connection between host and target.
4. Configure the Terminal view to open a serial connection.
5. Set board switches and jumpers.
6. Connect a power supply.
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 mars 90.0.0.50 phobos
! CAUTION: You should always discharge the static electricity that may have
collected on your body before you touch integrated circuit boards, including targets and network interface cards (NICs).
Electrostatic discharge (ESD) precautions include:
Touching the metal enclosure of a plugged-in piece of electrical equipment
(such as a PC or a power supply in a metal case).
Placing your equipment on, or standing on, an anti-static mat. Wearing an ESD wrist strap.
Failure to take proper ESD precautions can degrade target hardware over time, leading to intermittent errors or hardware failure.
3 Setting Up Your Host & Target
3.4 Configuring Your Target
This configuration is represented in Figure 3-1.
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.
Step 2: Set up a serial connection between the host and target.
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. Stop any other program already using the serial port. 2. If it is not already running, start Workbench.
Figure 3-1 Boot Configuration Example
TARGET
phobos
HOSTmars
90.0.0.50:ffffff00 90.0.0.1 c:\temp\vxWorks user:fred
Ethernet 90.0.0.x subnet! 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.
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. Open the Terminal view (select Window > Show View > Terminal).
4. To get a better view of what is happening in the Terminal view, double-click the tab at the top of the view. The view will expand to fill the Workbench window.
5. To adjust the settings for your connection, click the square Settings button to open the Terminal Settings dialog. Configure the terminal settings as appropriate for your system. For information about each option, press the help key for your host.
6. When you are finished, click OK to open a connection to your target.
7. Click Toggle Command Input Field to open a text inset field at the bottom of the Terminal view where you can enter and edit text. The contents of the text field are sent to the target when you press ENTER, and you can use the up and down arrows on your keyboard to navigate through previously entered text. 8. Click Toggle Command Input Field to hide the text inset field again. 9. To disconnect from your target, click Disconnect.
To reopen the connection with the existing settings, click Connect.
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 system’s manufacturer.
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.
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
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. Initiate, then interrupt, the boot process on the target.
2. Enter new boot parameters.
3. Boot the target with new parameters.
Step 1: 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. 2. 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.
3. 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.
4. 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]:
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 Programmer’s 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:
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).
5. In the inet on ethernet field, type the IP address of the target, then a colon, then the subnet mask.
6. In the host inet field, type the IP address of the host. Remember that the host and target IP addresses must match those in your hosts file, or those known to your DNS server (for details, see Assign the VxWorks target a name and IP address., p.20).
7. In the user field, type the user ID used to access the host for the purpose of loading the VxWorks image file specified in the file name parameter.
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).
8. In the ftp password field, type the password you created in 3.3 Configuring Your Host Machine, p.18. For rsh access leave this field blank.
9. In the target name field, type the name of the target.
Step 3: 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. The boot program first initializes its network interfaces.
b. After the system is completely loaded, the boot loader displays the entry address and transfers control to the loaded VxWorks system.
c. When VxWorks starts up, it begins just as the boot loader did, by initializing its network interfaces; the network-initialization messages appear again, sometimes accompanied by other messages about optional VxWorks facilities.
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 target’s 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.
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.
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.
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 view’s 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.
PA R T I I I
Customizing the Operating System
4
Configuring and Building VxWorks ... 31
5
Working with Board Support Packages ... 59
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,
p.10. For instructions about how to use these images, see 3.5 Booting a Target with VxWorks, p.23.
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
! 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) project—or 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 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 User’s 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 libraries—Creates IPv6 support.
IPv6_only enabled kernel libraries—Creates IPv6_only support. SMP support in kernel—Creates a symmetric multiprocessing
configuration of VxWorks.
Once the VIP is created, you cannot change it to a uniprocessor or asymmetric multiprocessor configuration.
Is a kernel configuration profile right for your project?
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 now—you 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.
To create a custom VxWorks image, do the following:
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. In the Workbench menu, click File > New > VxWorks Image Project.
Workbench starts the New VxWorks Image Project wizard. 3. On the Project page, type a name for your project.
4. 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.
4 Configuring and Building VxWorks
4.3 Creating a Custom VxWorks Image
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. In the dialog box, select a test suite and provide board and host configuration information.
b. Click Browse to navigate to the location in which to store the test results. c. 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.
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.
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.
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
11. Click Finish.
Workbench displays your new project in the Project Explorer, and shows both project files and linked resources.
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 Programmer’s 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 Programmer’s 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 Programmer’s 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.
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.
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.
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.
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.
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: A mismatched spec and build target result in a build failure. If you
receive a build failure message, repeat Step2 and Step3 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.
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.