PART III: CUSTOMIZING THE OPERATING SYSTEM
7.5 Example: Connecting a Target Server to a Target Agent
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.
Configure your target, as described in 3.4 Configuring Your Target, p.20.
7.2 What Are Target Servers and Target Agents?
This section explains the functions of target servers and target agents. You must configure the target server and target agent that act as the interpreters between the Workbench tools running on the host and the VxWorks kernel image running on the target.
Understanding Target Servers
A target server is a program, running on the host, that allows Workbench tools such as shells and debuggers to communicate with the target agent running on the target.
If you configure and build a VxWorks kernel image with a target agent interface that understands a particular communication method (network, serial, JTAG, and so on), then your target server must be configured with settings that support the same communication protocol and transport layer. This collection of settings is known as the target server’s back end.
For host-target communication to work, the target server must be configured with a back end that matches the VxWorks kernel’s target agent interface.
Understanding Target Agents
A target agent is a program that runs on the target and acts as the interface between the VxWorks image on the target and the Workbench tools on the host. You probably need a target agent only during development. A self-booting system image does not need a target agent.
The target agent can function in one of three modes: user mode, system mode, and dual mode.
In user mode, the agent runs as a VxWorks task. Debugging is performed on a per-task basis: you can isolate particular tasks without affecting the rest of the target system.
In system mode, the agent runs externally from VxWorks, almost like a ROM monitor. This allows you to debug an application as if it, and VxWorks, were a single thread of execution. In this mode, when the target encounters a breakpoint, VxWorks and the application are stopped and interrupts are locked. One of the biggest advantages of this mode is that you can single-step through ISRs; on the other hand, it is more difficult to manipulate individual 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
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 User’s Guide: Debugging Projects) or the host shell (see Wind River Workbench Host Shell User’s Guide).
To support a system-mode or dual-mode agent, the target communication path must work in polled mode (because the external agent needs to communicate to the host even when the system is suspended). The choice of communication path can affect what debugging modes are available.
7.3 Creating a VxWorks Simulator Connection
To see if your program runs properly before downloading it to a target board, you can run it on the VxWorks simulator. This simulates a connection to a standard or customized version of a VxWorks 6.x kernel, allowing you to proceed with your development work until a target board is available.
Creating a Standard VxWorks Simulator Connection
In this task, you create a VxWorks simulator connection in preparation for running the simulator.
To create a VxWorks simulator connection, do the following:
1. To open the New Connection wizard, do one of the following:
In the Remote Systems view, click Define a connection on the toolbar.
In the Remote Systems view, right-click in the view and select New > Connection.
In the Project Explorer, right-click a VIP project that has already been built, select Create VxWorks Simulator Connection, and then go to step 3.
2. On the initial page of the New Connection wizard, select Wind River VxWorks 6.x Simulator Connection and click Next.
Immediately connect to target if possible is one of the default settings you should accept.
NOTE: The WDB Target Agent is disabled by default, unless you are working with 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
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.
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. On the initial page of the New Connection wizard, select
Wind River VxWorks 6.x Simulator Connection, then click Next.
3. Specify the kernel image file and other parameters, in the following way:
a. From the VxWorks Boot parameters screen, select Custom simulator, then click Browse and navigate to the location of the vxWorks kernel file you want to use.
b. If you want to bypass checksum comparison, select the check box.
c. Generally, Workbench does a checksum comparison to prevent you from attaching and debugging a target if the target kernel and host copy do not match, because the target will be looking at the wrong symbols, offsets, debug information, and so on. However, if you understand the system very well and wish to connect anyway, selecting this check box allows Workbench to make the connection.
d. Each new simulator connection is named vxsim#. Processor number displays the incrementing number that Workbench will assign to the simulator connection you are creating; you can adjust this if you like.
e. If you want to set specific VxWorks simulator boot parameters, click Advanced Boot Parameters. Click Next.
7 Connecting to VxWorks Targets 7.4 Defining a New Target Server Connection
4. Set the simulator memory options, in the following way:
a. The options on this screen allow you to manage your memory resources.
b. Make sure the settings are adjusted the way you want, including whether you want to connect to the target now, then click Finish.
For more information about the settings on these screens, as well as how to use the simulator once it is running, see the Wind River VxWorks Simulator User’s Guide.
7.4 Defining a New Target Server Connection
To run your program on a target board, you first need to define a target server connection. Defining the connection includes the following tasks:
Task 1: Open the New Connection wizard.
Task 2: Select a target server back end.
Task 3: Specify the kernel image.
Task 4: Specify advanced target server options.
Task 5: Configure object path mappings.
Task 6: Specify how often Workbench should retrieve target status.
Task 8: Verify or modify Connection Summary settings.
Before You Begin
Before you can create a connection with a target server, you must know the kernel component for your project and it must be properly configured to interface with the target server.
The kernel component in the following table must be configured into your VxWorks kernel image. For more information, see 4.4 Configuring VxWorks, p.37.
Back End Description Compatible Kernel Component wdbrpc The default back end.
Supports any kind of IP connection. Polled-mode Ethernet drivers are available for most BSPs to support system-mode debugging.
INCLUDE_WDB_COMM_END or INCLUDE_WDB_COMM_NETWORK
wdbpipe For VxWorks target simulators.
INCLUDE_WDB_COMM_PIPE
Task 1: Open the New Connection wizard.
In this task, you bring up the New Connection wizard and specify a target server connection.
To open the New Connection wizard, do the following:
1. Click Define a connection on the Remote Systems view toolbar, or right-click in the view and select New > Connection.
2. On the initial page of the New Connection wizard, select
Wind River VxWorks 6.x Target Server Connection, and then click Next.
Task 2: Select a target server back end.
In this task, you specify the back end that matches the method the target server will use to communicate with the target. You can also specify any necessary
information for the back end.
Each type of back end requires you to provide additional connection information.
For example, Workbench can usually identify the target processor.
To specify a target server back end, do the following:
1. In the Back end settings section, select the back end that matches the method the target server will use to communicate with the target.
For connections that use a wbdserial backend setting, you can now specify a custom baud rate. To do so, select Other from the Serial device speed (bit/ss) drop-down list, enter the custom rate, and clicking OK.
2. Provide the necessary information for the back end. For example, to manually set the processor click Select and choose your processor from the list.
Task 3: Specify the kernel image.
In this task, you specify the kernel image to use with the target server. How you do this depends on where the kernel image is located.
wdbserial For serial hardware
connections; does not require SLIP on the host system. With this option, also choose a Host serial device and Serial device speed.
Supports either system-level or task-level views of the target, depending on the target-agent configuration.
INCLUDE_WDB_COMM_SERIAL
wdbproxy For UDP, TCP, TIPC, and MIPC connections.
INCLUDE_WDB_PROXY_UDP (for UDP/TCP),
INCLUDE_TIPC_ONLY, or INCLUDE_WDB_PROXY_MIPC
7 Connecting to VxWorks Targets 7.4 Defining a New Target Server Connection
To identify the kernel image to use, do one of the following:
If the VxWorks image is running on the target, and Workbench can find it using the target path, select File path from target (if available).
If the VxWorks image file is not in the same location on the host that is configured into the target (or if host and target have different views of the file system), select File and navigate to the host location of the kernel image.
If you are using a target programmed with a vxWorks_rom.hex,
vxWorks_romCompressed.hex, or any other on-board VxWorks image, you must use this option to identify the kernel file location. Otherwise, the target server will not be able to identify the target symbols.
Task 4: Specify advanced target server options.
In this task, you specify options such as, timeout, memory cache, logging, and local and global symbols.
The options shown in the Options field are passed to the tgtsvr program on the command line. You can type them in, or click Edit to configure the settings represented by these options.
To specify advanced target server options, do the following as needed:
1. Click the Common tab and select from the following to configure the target server file system (TSFS) and various timeout options:
a. Enable the TSFS if you are using Wind River System Viewer, if you are booting a target over a serial connection, or if you need to provide a target that is booted from a remote host access to files on a local host.
To use the TSFS, you must also include the WDB target server file system kernel component when you build your VxWorks kernel image.
b. Identify the root directory of the host file system. By default, this is the workspace directory.
c. Make the target server file system writable when you are using
System Viewer, since this is how it uploads event data from the target to the host.
Be aware that this also allows other users to access your host file system, so you may want to set the TSFS option to read-only when you are not using System Viewer.
d. Specify timeout options, such as allowable spawn time for kernel tasks and RTPs, time to wait for a response from the agent running on the target, how often to retry, and at what intervals.
2. Click the Memory tab, to modify cache size. To avoid excessive data-transfer transactions with the target, the target server maintains a cache on the host system of up to 1 MB. You can increase this size on the Memory tab.
3. Click the Logging tab to enable output and back end logging on the Logging tab, and do the following as needed:
a. Specify the log’s location and maximum size (logs are rewritten from the beginning when they reach this maximum size, and they are deleted and recreated when the target server restarts, such as after a reboot).
b. For the WTX (Wind River Tool Exchange) log file, specify a filter, a regular expression that limits the type of information logged. Without a filter, the log captures all WTX communication between host and target.
4. Click the Symbols tab to specify whether to load global symbols (the default) or both global and local symbols. If you choose not to load symbols to the target server, the connection sequence may fail.
5. Click Next.
Task 5: Configure object path mappings.
In this task, you configure object path mappings for modules with symbols or modules that do not yet have symbols.
Object path mappings allow the debugger to find symbol files for processes created on the target. This is done by creating a correspondence between a path on the target and the appropriate path on the host.
You calculate target paths for processes that you want to launch, by browsing to them with a host file system browser. In most cases the default mappings that Workbench provides are correct (and are not editable).
To specify object path mappings for modules with symbols, by doing the following:
1. To download a module or start a process without loading the symbol file, uncheck Load module symbols to debug server automatically if possible. By default, the debug server attempts to load all of a module’s symbols each time a module is loaded.
2. To map a new target path prefix to a host path, click Add and enter the target path (for example, /tgtsvr/) and a full host path (for example, C:\workspace\).
Do not use relative host paths here.
3. To export object path mappings to XML, click Export and provide a descriptive filename. Likewise you can import mappings by clicking Import and selecting an appropriate XML file.
4. Create mapping pairs. At the bottom of the screen, use square brackets to enclose each mapping of target file basenames (left element) to host file basenames (right element), separated by a semi-colon (;). Mapping pairs (in square brackets) are separated by commas. You can use an asterisk (*) as a wildcard.
For example, if debug versions of files are identified by the extension
*.unstripped, the mapping [*;*.unstripped] will ensure that the debugger loads yourApp.vxe.unstripped when yourApp.vxe is launched on the target.
Alternately, you can create Object Path Mappings for a module that does not have symbols yet by downloading the output file (or running the executable) manually.
To specify object path mappings for modules without symbols, do the following:
1. In the Remote Systems view, right-click the file or executable and select Load/Add Symbols to Debug Server.
2. From the Load Symbols dialog, select Create path mappings for the module based on the selected symbol file and click OK.
Object path mappings are created automatically, so that after the next disconnect/reconnect sequence Workbench will find the symbols.
7 Connecting to VxWorks Targets 7.4 Defining a New Target Server Connection
3. Click Next.
Task 6: Specify how often Workbench should retrieve target status.
In this task, you specify how often and under what conditions Workbench should refresh the Remote Systems view display. This is important, since retrieving status information from the target leads to considerable target traffic.
To specify the refresh rate for the Remote Systems display, do the following:
1. To prevent excessive delay in the update of the Remote Systems display, do not select Listen to execution context life-cycle events when there are more than 100 contexts on the target.
2. Click Next.
Task 7: Set the debug options.
In this task, you specify the debug options.
To specify debug options, do the following:
1. Specify which threads Workbench should stop when breakpoints are hit.
2. Specify whether to display an error dialog on target exceptions.
3. Click Next.
Task 8: Verify or modify Connection Summary settings.
In this task you review the Connection Summary settings and verify or modify them, as needed.
To review connection summary options, do the following:
1. To modify the Connection name, or any of the settings associated with this connection, click Back and update the appropriate screen.
2. Verify or modify the Shared option (to the right of the Connection name field) is available only for certain connection types, and serves the following purposes:
When you define a target connection configuration, this connection is normally visible only to you. If you define it as Shared, other users can also see the configuration in your registry, provided that they connect to
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