PART III: CUSTOMIZING THE OPERATING SYSTEM
4.5 Example: Building a VIP With Sources in a Subdirectory
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 guide. Substitute the actual path to your Workbench installation directory.
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
HOST
mars
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 information about how to connect to your target.
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:
[VxWorks Boot]: c
2. The boot program prompts you for each new parameter.
– If a particular field already has the correct value, press ENTER. – To clear a field, type a period ( . ), then press ENTER.
– To back up and change the previous parameter, type a hyphen (-), then press ENTER.
– If you want to quit before completing all parameters, type CTRL+D. 3. The first parameter you probably need to change is the host name, so press
ENTER a couple of times to get past the first few parameters, then type in the name of the host machine to boot from. Press ENTER.
4. In the file name field, type the full host side 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
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