Tornado host tools such as the shell and debugger communicate with the target system through a target server. A target server can be configured with a variety of back ends, which provide for various modes of communication with the target agent. On the target side, VxWorks can be configured and built with a variety of target agent communication interfaces.

Your choice of target server back end and target agent communication interface is based on the mode of communication that you establish between the host and target (network, serial, and so on). In any case, the target server must be configured with a back end that matches the target agent interface with which VxWorks has been configured and built. See Figure 2-4 for a detailed diagram of host-target communications.

The default configurations for both the VxWorks target agent and Tornado target servers are for a network connection. If you are using a network connection, you can proceed with booting your target (2.6 Booting VxWorks).

	WARNING: If you are using a connection other than network (the default), you must rebuild VxWorks with the appropriate target agent communication interface, and configure a target server with the corresponding back end, before you can use Tornado tools with your target. See 4.6 Configuring the Target-Host Communication Interface and 2.5 Host-Target Communication Configuration.

All of the standard back ends included with Tornado connect to the target through the WDB target agent. Thus, in order to understand the features of each back end, you must understand the modes in which the target agent can execute. These modes are called task mode, system mode, and dual mode.   

Figure 2-4:  Tornado Host-Target Communication

 

• In task mode, the agent runs as a VxWorks task. Debugging is performed on a per-task basis: you can isolate the task or tasks of interest 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 run-time 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).

• In dual mode, two agents are configured into the run-time simultaneously: a task- mode agent, and a system-mode agent. Only one of these agents is active at a time; switching between the two can be controlled from either the debugger (see 7.5 System-Mode Debugging) or the shell (5.2.6 Using the Shell for System Mode Debugging). In order to support a system-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). Thus, the choice of communication path can affect what debugging modes are available.

The most common VxWorks communication path--both for server-agent communications during development, and for applications--is IP networking over Ethernet. That connection method provides a very high bandwidth, as well as all the advantages of a network connection.

Nevertheless, there are situations where you may wish to use a non-network connection, such as a serial line without general-purpose IP, or a NetROM connection. For example, if you have a memory-constrained application that does not require networking, you may wish to remove the VxWorks network code from the target system during development. Also, if you wish to perform system-mode debugging, you need a communication path that can work in polled mode. VxWorks network interface drivers that do not support polled operations (older versions) cannot be used as a connection for system-mode debugging.

Note that the target-server back end connection is not always the same as the connection used to load the VxWorks image into target memory. For example, you can boot VxWorks over Ethernet, but use a serial line connection to perform system-mode debugging. You can also use a non-default method of getting the run-time system itself into your target board. For example, you might burn your VxWorks run-time system directly into target ROM, as described in VxWorks Programmer's Guide: Configuration and Build. Alternatively, you can use a ROM emulator such as NetROM to quickly download new VxWorks images to the target's ROM sockets. Another possibility is to boot from a disk locally attached to the target; see VxWorks Programmer's Guide: Local File Systems. You can also boot from a host disk over a serial connection using the Target Server File System; see 2.6.7 Booting a Target Without a Network. Certain BSPs may provide other alternatives, such as flash memory. See the reference information for your BSP; Help>Manuals contents>BSP Reference in the Tornado Launcher (or the file wind/docs/BSP_Reference.html).

Connecting the target server to the target requires a little work on both the host and target. The next few subsections describe the details for the standard target-server back end connections.

A network connection is the easiest to set up and use, because most VxWorks targets already use the network (for example, to boot); thus, no additional target set-up is required. Furthermore, a network interface is typically a board's fastest physical communication channel.

When VxWorks is configured and built with a network interface for the target agent (the default configuration), the target server can connect to the target agent using the default wdbpipe back end (see 5.2 Configuring and Starting a Target Server).

The target agent can receive requests over any device for which a VxWorks network interface driver is installed. The typical case is to use the device from which the target was booted; however, any device can be used by specifying its IP address to the target server.

The default VxWorks system image is configured for a networked target. See 4.6 Configuring the Target-Host Communication Interface for information about configuring VxWorks for various target agent communications interfaces.

An END (Enhanced Network Driver) connection supports dual mode agent execution. This connection can only be used if the BSP uses an END driver (which has a polled interface). With an END connection, the agent uses an END driver directly, rather than going through the UDP/IP protocol stack.

See Configuration for an END Driver Connection for information about configuring the VxWorks target agent for an END connection.

A raw serial connection has some advantages over an IP connection. The raw serial connection allows you to scale down the VxWorks system (even during development) for memory-constrained applications that do not require networking: you can remove the VxWorks network code from the target system.

When working over a serial link, use the fastest possible line speed. The Tornado tools--especially the browser and the debugger--make it easy to set up system snapshots that are periodically refreshed. Refreshing such snapshots requires continuing traffic between host and target. On a serial connection, the line speed can be a bottleneck in this situation. If your Tornado tools seem unresponsive over a serial connection, try turning off periodic updates in the browser, or else closing any debugger displays you can spare.

To configure the target agent for a raw serial communication connection, reconfigure and rebuild VxWorks with a serial communication interface for the target agent (see Configuration for Serial Connection).

When you connect the host and target exclusively over serial lines, you must configure and build a boot program for the serial connection because the default boot configuration uses an FTP download from the host (see 4.7 Configuring and Building a VxWorks Boot Program). The simplest way to boot over a serial connection is by using the Target Server File System. See 2.6.7 Booting a Target Without a Network.

Be sure to use the right kind of cable to connect your host and target.Use a simple Tx/Tx/GND serial cable because the host serial port is configured not to use handshaking. Many targets require a null-modem cable; consult the target-board documentation. Configure your host-system serial port for a full-duplex (no local echo), 8-bit connection with one stop bit and no parity bit. The line speed must match whatever is configured into your target agent.

Before trying to attach the target server for the first time, test that the serial connection to the target is good. To help verify the connection, the target agent sends the following message over the serial line when it boots (with WDB_COMM_SERIAL):

WDB READY

To test the connection, attach a terminal emulator¹ to the target-agent serial port, then reset the target. If the WDB READY message does not appear, or if it is garbled, check the configuration of the serial port you are using on your host.

As a further debugging aid, you can also configure the serial-mode target agent to echo all characters it receives over the serial line. This is not the default configuration, because as a side effect it stops the boot process until a target server is attached. If you need this configuration in order to set up your host serial port, edit wind/target/src/config/usrWdb.c. Look for the following lines:

#ifdef  INCLUDE_WDB_TTY_TEST 
    /* test in polled mode if the kernel hasn't started */ 
 
    if (taskIdCurrent == 0) 
        wdbSioTest (pSioChan, SIO_MODE_POLL, 0); 
    else 
        wdbSioTest (pSioChan, SIO_MODE_INT, 0); 
#endif  /* INCLUDE_WDB_TTY_TEST */

In both calls to wdbSioTest( ), change the last argument from 0 to 0300.

With this configuration, attach any terminal emulator on the host to the tty port connected to the target to verify the serial connection. When the serial-line settings are correct, whatever you type to the target is echoed as you type it.

	WARNING: Because this configuration change also prevents the target from completing its boot process until a target server attaches to the target, it is best to change the wdbSioTest( ) third argument back to the default 0 value as soon as you verify that the serial line is set up correctly.

After successfully testing the serial connection, you can connect the target server to the agent by following these steps:

1. Close the serial port that you opened for testing (if you do not close the port, then it will be busy when the target server tries to use it).

1. Start the target server with the serial back end to connect to the agent. Use the tgtsvr -B option to specify the back end, and also specify the line speed to match the speed configured into your target:

% tgtsvr -V targetname -B wdbserial -bps 38400 &

You can also use the Tornado GUI to configure and start a target server (see 3.5 Managing Target Servers).

The agent can be configured to communicate with the target server using the target board's ROM socket. Tornado supports this configuration for NetROM, a ROM emulator produced by Applied Microsystems Corporation. Contact your nearest Wind River Systems office (listed on the back cover) for information about support for other ROM emulators. Figure 2-5 illustrates this connection method.

Figure 2-5:  Connecting a Target through NetROM

The NetROM acts as a liaison between the host and target. It communicates with the host over Ethernet, and with the target through ROM emulation pods that are plugged into the target board's ROM sockets. The NetROM allows you to download new ROM images to the target quickly. In addition, a 2 KB segment of the NetROM's emulation pod is dual-port RAM, which can be used as a communication path. The target agent uses the NetROM's read-only protocol to transfer data up to the host. It works correctly even on boards that do not support write access to the ROM banks.

This communication path has many benefits: it provides a connection which does not intrude on any of your board's I/O ports, it supports both task-mode and system-mode debugging, it is faster than a serial-line connection, and it provides an effective way to download new VxWorks images to the target.

	NOTE: The information about NetROM in this section is a summary of NetROM documentation, with some supplementary remarks. This section is not a replacement for the NetROM documentation. In particular, refer to that documentation for full information about how to connect the NetROM to the network and to your target board.

For information about booting a target without a network, see 2.6.7 Booting a Target Without a Network.

To configure the target agent for a NetROM communication connection, reconfigure and rebuild VxWorks with a NetROM interface for the target agent. Several configuration macros are used to describe a board's memory interface to its ROM banks. You may need to override some of them for your board. See Configuration for NetROM Connection.

Before a target server on your host can connect to the target agent over NetROM, some hardware and software configuration is necessary. The following steps outline this process.

Step 1:   Configure the NetROM IP address from your host system.

When it powers up, the NetROM knows its own Ethernet address, but does not know its internet (IP) address.

There are two ways of establishing an IP address for the NetROM:

• Connect a terminal to the NetROM serial console, and specify the IP address manually when you power up the NetROM for Step 2. This solution is simple, but you must repeat it each time the NetROM is powered up or restarted.

• Configure a network server to reply to RARP or BOOTP requests from the NetROM. On power-up, the NetROM automatically broadcasts both requests. This solution is preferable, because it permits the NetROM to start up without any interaction once the configuration is working.

Since the RARP and BOOTP requests are broadcast, any host connected to the same subnet can reply. Configure only one host to reply to NetROM requests.

Step 2:   Prepare a NetROM startup file.

After the NetROM obtains its IP address, it loads a startup file. The pathname for this file depends on which protocol establishes the IP address:

• BOOTP: A startup-file name is part of the BOOTP server's reply to the BOOTP request. Record your choice of startup-file pathname in the BOOTP table (typically /etc/bootptab).

• RARP: When the IP address is established by a reply to the RARP request, no other information accompanies the IP address. In this case, the NetROM derives a file name from the IP address. The file name is constructed from the numeric (dot-decimal) IP address by converting each address segment to two hexadecimal digits. For example, a NetROM at IP address 147.11.46.164 expects a setup file named 930B2EA4 (hexadecimal digits from the alphabet are written in upper case). The NetROM makes three attempts to find the startup file, with each of the following pathnames: ./filename, /tftpboot/filename, and filename without any other path information.

The startup file contains NetROM commands describing the emulated ROM, the object format, path and file names to download, and so on. The following example NetROM startup file configures the Ethernet device, adds routing information, records the object-file name to download and the path to it, and establishes ROM characteristics.

Example 2-1:  Sample NetROM Startup File

begin 
    ifconfig le0 147.11.46.164 netmask 255.255.255.0 broadcast 147.11.46.0 
    setenv filetype srecord 
    setenv loadpath /tftpboot 
    setenv loadfile vxWorks_rom.hex 
    setenv romtype 27c020 
    setenv romcount 1  
    setenv wordsize 8 
    setenv debugpath readaddr 
    set udpsrcmode on 
    tgtreset 
end

	NOTE: The environment variable debugpath should be set to dualport (rather than to readaddr) if you are using the 500-series NetROM boxes.

When you create a NetROM startup file, remember to set file permissions to permit the TFTP file server to read the file.

For more information regarding NetROM boot requirements, refer to NetROM documentation. Consult your system administrator to configure your host to reply to RARP or BOOTP requests (or see host-system documentation for bootpd or rarpd).

Step 3:   Connect NetROM to Ethernet network; plug NetROM pods into target ROM sockets.

	WARNING: Do not power up either the NetROM or the target yet. Pod connections and disconnections should be made while power is off on both the NetROM and the target board.

	WARNING: Some board sockets are designed to support either ROM or flash PROM. On this kind of socket, a 12V potential is applied to pin 1 each time the processor accesses ROM space. This potential may damage the NetROM. In this situation, place an extra ROM socket with pin 1 removed between the NetROM pod and the target-board socket.

	WARNING: Take great care when you plug in NetROM pod(s). Double check the pod connections, especially pin 1 position and alignment. A pod connection error can damage either the NetROM itself, the target board, or both. The pins coming out of the NetROM's DIP emulation pods are very easy to break, and the cables are expensive to replace. It is a good idea to use a DIP extender socket, because they are much cheaper and faster to replace if a pin breaks.

NetROM pod 0 differs from other pods because it implements the dual-port RAM. This special port is used by NetROM both to send data to the board and to receive data from the board: that is, the dual port is the communication path between the NetROM and the board.

Step 4:   Power up the NetROM (but not the target).

Once the required NetROM address and boot information is configured on a host, the NetROM can be powered up. To verify that the NetROM has obtained its IP address and loaded and executed the startup file, you can connect to a NetROM command line with a telnet session.

The following example shows the expected response from a NetROM at IP address 147.11.46.164:

% telnet 147.11.46.164 
Trying 147.11.46.164 
Connected to 147.11.46.164 
Escape character is `^]' 
 
NETROM TELNET 
NetROM>

At the NetROM prompt, you can display the current configuration by entering the command printenv to verify that the startup file executed properly.

Step 5:   Download test code to the NetROM.

One method is to type the newimage command at the NetROM prompt. This command uses the TFTP protocol to download the image specified by the loadfile environment variable from the path specified by the loadpath environment variable (which is /tftpboot/vxWorks_rom.hex if you use the startup script in Example 2-1). After the NetROM configuration is stable, you can include this command in the startup file to download the image automatically. Wait to be certain the image is completely downloaded before you power up your target. This method takes about 30 seconds to transfer the image.

A faster method is to use two host utilities from AMC: rompack packs a ROM image into a compact file (with the default name outfile.bin); download ships the packed file to the NetROM. This method takes only about five seconds to transfer a new image to the target. This UNIX shell script shown in uses these utilities to send an image to the NetROM whose IP address is recorded in the script variable ip:

#! /bin/sh 
if [ $# != 1 ]; then 
    echo "Usage: $0 <filename>" 
    exit 1 
fi

 
file=$1 
ip=t46-154

 
if [ -r "$file" ];  then 
    echo "Downloading $file to the NetROM at $ip." 
    rompack -c 1 -r 27c020 -x $file 0 0 
    download outfile.bin $ip 
else 
    echo "$0: \"$file\" not found" 
    exit 1 
fi

 
echo Done. 
exit 0

The rompack option flags specify how to pack the image within the emulator pods. The -c 1 option specifies a ROM count of one, which means that the image goes in a single ROM socket. The -r 27c020 option specifies the type of ROM. The two trailing numbers are the base and offset from the start of ROM space. Both are typically zero.

Step 6:   Power up your target.

The target CPU executes the object code in the emulated ROM. Make sure the code is running correctly. For example, you might want to have it flash an LED.

Start the target server as in the following example, using the -B option to specify the NetROM back end.

% tgtsvr -V 147.11.46.164 -B netrom &

In this example, 147.11.46.164 is the IP address of the NetROM. (You can also use the Tornado GUI to configure and start a target server; see Tornado Getting Started Guide.)

If the connection fails, try typing the following command at the NetROM prompt:

NetROM> set debugecho on

With this setting, all packets sent to and from the NetROM are copied to the console. You may need to hook up a connector to the NetROM serial console to see the debugecho output, even if your current console with NetROM is attached through Telnet (later versions of NetROM software may not have this problem). If you see packets sent from the host, but no reply from the target, you must modify the target NetROM configuration parameters described in section Configuration for Network Connection.

    NetROM> tgtreset  

	NOTE: With a NetROM connection, you must inform the NetROM when you reboot the target. You can do this as follows at the NetROM prompt:

If the target server fails to connect to the target, the following troubleshooting procedures can help isolate the problem.

Download Configuration

It is possible that the NetROM is not correctly configured for downloading code to the target. Make sure you can download and run a simple piece of code (for example, to blink an LED -- this code should be something simpler than a complete VxWorks image).

Initialization

If you can download code and execute it, the next possibility is that the board initialization code is failing. In this case, it never reaches the point of trying to use the NetROM for communication. The code in target/src/config/usrWdb.c makes a call to wdbNetromPktDevInit( ). If the startup code does not get to this point, the problem probably lies in the BSP. Contact the vendor that supplied the BSP for further troubleshooting tips.

RAM Configuration

If the NetROM communication initialization code is being called but is not working, the problem could be due to a mis-configuration of the NetROM. To test this, modify the file wdbNetromPktDrv.c. Change the following line:

int wdbNetromTest = 0;

to:

int wdbNetromTest = 1;

	NOTE: There are two versions of wdbNetromPktDrv.c. The one for the 400 series is located in target/src/drv/wdb and the one for the 500 series is located in target/src/drv/wdb/amc500. Be sure to edit the appropriate one.

When you rerun VxWorks with this modification, the wdbNetromPktDevInit( ) routine attempts to print a message to NetROM debug port. The initialization code halts until you connect to the debug port (1235), which you can do by typing:

% telnet NetROM_IPaddress 1235

If the debug port successfully connects, the following message is displayed in the telnet window:

WDB NetROM communication ready 

If you do not see this message, the NetROM dual-port RAM has not been configured correctly. Turn off the processor cache; if that does not solve the problem, contact AMC for further trouble shooting tips:

AMC web page:		http://www.amc.com/
AMC tech-support:		1-800-ask-4amc
		support@amc.com

If everything has worked up to this point, reset wdbNetromTest back to zero and end your telnet session.

Communication

Type the following at the NetROM prompt:

NetROM> set debugecho on

This causes data to be echoed to the NetROM console when packets are transmitted between the host and target. If you have a VxWorks console available on your target, edit wdbNetromPktDrv.c by changing the following line:

int wdbNetromDebug = 0;

to:

int wdbNetromDebug = 1;

This causes messages to be echoed to the VxWorks console when packets are transmitted between the host and target.

	NOTE: You may need to hook up a connector to the NetROM serial console to see the debugecho output, even if your current console with NetROM is attached through telnet.

Retry the connection:

1. Kill the target server.

1. Type tgtreset at the NetROM prompt.

1. Reboot your target.

1. Start the target server using the -Bd option to log transactions between the target server and the agent to a log file. Use the target server -Bt option to increase the timeout period. (This is necessary whenever the NetROM debug echo feature is enabled, because debugecho slows down the connection.)

At this point, you have debugging output on three levels: the target server is recording all transactions between it and the NetROM box; the NetROM box is printing all packets it sees to its console; and the WDB agent is printing all packets it sees to the VxWorks console. If this process does not provide enough debug information to resolve your problems, contact WRS technical support for more troubleshooting assistance.

1:  Commonly available terminal emulators are tip, cu, and kermit; consult your host reference documentation.