blueDonkey.org

This Web

All Webs

blueDonkey.org

Other Sites

Working with VxWorks

• Introduction
• Basic Tools
  • Tools Overview
  • Target Server
  • Host Shell (WindSh)
  • Source Level Debugger
  • Target Shell & Loader
• Building a Kernel Image
• Booting a Target System
  • Bootline Settings
  • Common Network Booting Problems
    • Problems Attaching the Network Interface
    • Problems Loading the VxWorks Image
    • Problems Transferring Control to VxWorks
    • Problems Re-attaching the Network Interface
    • Problems Loading the Symbol Table
• Building and Running a Program
  • Compiling a Simple Module
  • Downloading a Module
  • Executing a Function
  • Decoding errno Values

Introduction

This book is not intended to give you detailed information about getting started with VxWorks, nor programming for embedded or real-time systems. That said, this chapter will provide some basic background information on using VxWorks, and a subset of the associated tools. It will look mainly at the command line tools since they are more likely to be useful to an intermediate or advanced user, and also are less well covered by the Wind River documentation.

Basic Tools

Tools Overview

Every installation of VxWorks comes with some tools. Since version 5.3, they have been described by the name Tornado; before that, they were simply part of the installed product. The binaries for the tools can be found in the installed tree under host/host-type/bin (e.g. .../host/sun4-solaris2/bin, ...\host\x86-win32\bin or .../host/x86-linux2/bin).

The compiler most commonly supplied with VxWorks is a variant of GNU's gcc C/C++ compiler. For releases prior to VxWorks AE and VxWorks 5.5, the version was usually 2.7.2. Confusingly, some releases of Tornado 2, which carried versions greater and 2.0 and less than 2.2, used other versions. To check your compiler's version invoke the compiler with the --version option (note the double dash prefix). It is not a good idea to mix binaries from different versions of VxWorks. There have been a number of changes to the binary formats, e.g. fixes to the compiler to comply better with EABI or ABI conventions for a given CPU. Upgrading to VxWorks AE or VxWorks 5.5 also changes the format to ELF for almost all the architectures that weren't already ELF. There are also occasional changes to internal data structures that can cause compatibility problems for older binaries.

Other compilers are available (e.g. Green Hills or Diab, which is now owned by Wind River). In general though, these offer little gain over the GNU compiler. The author would strongly recommend only paying for one of these after a careful evaluation of the benefits on the actual application code. Both are capable of generating smaller and faster code than GNU in some circumstances, but not all, and not usually by a significant margin.

The table below contains a list of the architecture-specific tools provided with VxWorks. For clarity the table omits the architecture name suffix that should be added to each tool, for example, when using PowerPC targets cc would be invoked as ccppc. Check in the documentation for your architecture's suffix if you don't already know it. Note also that not all of these are shipped with every version of Tornado/VxWorks, so do not be surprised if some of the more obscure ones are not in your installation.

Tool	Purpose
addr2line	Converts an address in an executable into a source filename and line number
ar	Archiver tool - used for creating and manipulating .a files
as	GNU assembler
c++	C++ compiler
c++filt	C++ symbol demangler utility
cc	Main C compiler (will also compile C++ files)
cpp	C pre-processor
g++	Alias for c++
gasp	GNU assembler macro pre-processor
ld	Linker
nm	Symbol listing tool for object files.
objcopy	Object file manipulation tool - can perform many transformations on object files
objdump	Object file analysis tool
ranlib	Obsolete tool for generating an index in an archive - handled automatically by ar now
readelf	ELF-specific object file analysis tool
size	Reports the actual sizes of the segments within an object file
strings	Extracts printable strings from a binary file
strip	Strips unwanted information from an object file (e.g. debug information, or symbol names)

There are also a number of architecture independent tools in the bin directory of your Tornado installation. The table below explains some of the most important of these for the command line user. Some of these will be looked at in more detail in the next few sections.

Tool	Purpose
binToAsm	TBD
deflate	Compression tool used when building compressed ROM images.
elfToRelf	VxWorks AE tool for converting ELF to R-ELF (re-ordered for stream oriented loading).
expect	TBD
make	A version of GNU make (usually quite an old version).
memdrvbuild	Tool for creating memDrv images.
munch	C++ compilation tool for generating static object c'tor and d'tor arrays.
refgen	Documentation generation tool (processes Wind River coding standard file and function headers to generate HTML format documentation).
romsize	Calculates the size of a ROM image, and will warn if larger than the specified ROM device size.
smsToBin	VxWorks AE tool for creating a composite binary version of each bootable domain image.
tclsh	TCL shell.
tgtsvr	The target server; can be run from the command line to allow other tools to communicate with the target system.
torVars.bat	Environment initialization script for Windows hosts; should be executed once by each command prompt window prior to using any other command line tools.
torVars.csh	Environment initialization script for Unix C shell (or tcsh) users. Should be sourced (not executed) prior to using any other command line tools.
torVars.sh	Environment initialization script for Unix Bourne shell (or bash) users. Should be sourced (not executed) prior to using any other command line tools.
vxencrypt	Version of Unix crypt command for generating encrypted password strings needed by the target's rlogin and telnet services when authentication is enabled.
vxsize	Calculates the size of a VxWorks image, and determines whether it will fit in memory between RAM_LOW_ADRS and RAM_HIGH_ADRS, i.e. whether it will be bootable by a VxWorks bootrom.
windsh	Command line version of the host-based VxWorks shell. Requires a target server to be running in order to connect with the target system (see tgtsvr above).
windview	Standalone version of the WindView runtime analysis tool.
wish	TCL/Tk windowing shell
wtxregd	Target registry daemon. One of these must be running on the machine pointed to by WIND_REGISTRY for target server(s) to register with. Most often running locally, but can be on another machine. A central registry allows sharing of target server connections between multiple users on different host computers.
wtxtcl	WTX-aware version of TCL shell
wtxwish	WTX-aware version of wish

Target Server

The target server provides a connection between the tools running on the host computer, and the target system. The target must be running the WDB agent for this to work (look at all the configuration macros/components starting INCLUDE_WDB, as well as configuration parameters starting WDB_). Perhaps a less well known fact is that the target server does not need to be running on the same machine as the tools. Each target server has a name, and that name is registered in the target registry (see documentation for wtxregd and the environment variable WIND_REGISTRY).

To start a target server, first make sure that WIND_REGISTRY points to a machine on your network that is running the WTX registry daemon (service in Windows terminology). Then run tgtsvr with just the name, or IP address of the target system (if your target IP addresses are not in your computer's hosts file, or on your LAN's DNS server if you have one, then you must use the IP address assigned to the target system here).

tgtsvr -n target-99 target-99 &

tgtsvr -n target-99 192.168.1.99 &

Notice that in these examples the server was run in the background by using the Unix shell feature of adding the '&' symbol to the end of the command line. Windows users you might want to set up a shortcut somewhere with the commands in them which can simply be double-clicked to start the server, or use the start command to start the new target server in its own window from a command prompt:

start tgtsvr -n target-99 192.168.1.99

In all of these examples we used the -n option to specify a name for the target server. If left off, it will default to the target name or IP address. Assuming that the host computer has the full name host.somecompany.com, then the target server's full name is target-99@host.somecompany.com. On that host, the short form target-99 may be used; on other machines in the same domain target-99@host could be used. In theory, if the system was on an open connection to the internet, tools running anywhere in the world could connect to the target server using the full name.

Having a target server visible over the internet could be a serious security risk.

This naming scheme allows tools running on potentially any computer to connect to this target server, and from there to the target system itself. This allows targets to be shared between multiple developers. Since VxWorks was not designed to be a multi-user system, it is not wise to have multiple users sharing a target system simultaneously. That said, it can be useful to let another engineer, perhaps at a remote site, access a target to help debug something. Another common use for this is when the targets need to be isolated on their own subnet. A single machine can then act as host for all target servers, allowing tools on any machine to connect to the targets while essentially hiding them from the rest of the network (as long as the gateway machine is not set up to forward packets between the networks).

Figure 1.1 - Hiding Targets from the Corporate LAN

It may be desirable to effectively hide the target systems on a private LAN this way for a number of reasons, including applications where the target systems are going to be generating a lot of network traffic which could interfere with the day-to-day use of the corporate LAN.

The target server has a number of other options that might be useful. To see the full list, start the target server with the -help option. The table below shows some of the more commonly useful ones (note that target server command line options are case sensitive):

Option	Description
-A	Include local symbols as well as globals for all modules. This will allow you to see the symbols declared as static in your code. It will not see automatic variable symbols (i.e. those declared inside a function scope).
-B	Select a different connection backend. The default is the network RPC backend, but your system may need to use something else. Connections over JTAG probes, as well as connections to simulator sessions will need to use this option
-c	Specify the location of the target's core file (i.e. the boot image). This is essential when the target is running a ROM'd version of the kernel, but can also be useful when booting the target from a different machine to the one the target server is running on.
-n	Specify a name for the target server. See above for more on this.
-N	Do not load any symbols from the core file.
-R root	Enabled the target server file system with the specified root.
-RW	Make target server file system read/write
-V	Turn on verbose mode. This is especially when debugging problems starting the target server.

Host Shell (WindSh)

Source Level Debugger

Target Shell & Loader

Building a Kernel Image

Booting a Target System

To boot a target system over a network, you will need to make sure that you have the following:

• A target board with a VxWorks bootrom (other firmware, or even JTAG tools, can be used to boot VxWorks, but using a VxWorks bootrom is usually simpler for software development purposes).

• A host running an appropriate server. FTP, TFTP and, on unix systems, RSH may be used for transferring the boot image over the network.

• A VxWorks image to boot.

There are other ways to boot a target system, including having the kernel image directly programmed into the board's flash or PROM or loading from a local file system, such as a hard disc or flash file system.

If you are using COTS hardware or a manufacturer's reference board, check in your BSP for documentation describing how to program the bootrom image included with the BSP onto your board. Most modern board support programming of on-board flash parts using either the network or a serial link to transfer the data to the target system. Older boards may require the image to be programmed into flash or EPROM parts using an external device programmer.

For those using custom hardware, the situation is a little more complex. In these cases, it is recommended that you have some kind of external hardware debugger, such as a JTAG based debugger. This will be useful when creating the BSP for the custom hardware, though not essential. Once you have the BSP working, then the bootrom image can be programmed onto the target's flash (using whatever technique is available).

Bootline Settings

The bootline contains all the information that the VxWorks bootrom needs to load a VxWorks kernel image into the target's memory. The table below describes the parameters and also the abbeviation used in the actual boot string. The boot string is the format used to store the information in non-volatile RAM (assuming the target has support for non-volatile RAM), and in the bootrom's image for the default line. The bootrom presents these in a more human-readable format with the p command.

Parameter	Boot String Variable	Description
Boot Device	N/A	The device to boot from. These are abbreviated names that represent the driver. For example, ene, fei or scsi.
Unit Number	N/A	Unit number in case there is more than one of the specified devices on the target. Normally this will be zero.
Processor Number	N/A	Processor number on a backplane (not required for boards that are not in a backplane).
Host Name	N/A	Name of host system for network booting.
File Name	N/A	Pathname of VxWorks image to boot.
Inet on Ethernet	e	IP address for the target system on the ethernet interface used to boot from (or the one specified in the Other field if booting from local disc, but initialising the network). Optionally, the address can contain the netmask in hexadecimal format, e.g. 192.168.1.1:ffffff00.
Inet on Backplane	b	IP address on the backplane network (if using backplane network).
Host Inet	h	IP address of the host computer when network booting.
Gateway Inet	g	Gateway to host computer if not on the same subnet as the target. Note: this address is not used to set the default route; it only creates an explicit route to the specified host computer.
User	u	Username to use for network booting.
FTP Password	pw	If the FTP password is specified, the network boot protocol is switched from RSH to FTP. Ignored for non-network boots, or for TFTP booting.
Flags	f	Special boot options (see table below).
Target Name	tn	Name of the target system (optional).
Startup Script	s	Startup script that will be executed by the target shell assuming that the target shell is included in the kernel image, and it is set to automatically run the startup script.
Other	o	Used for passing miscellaneous parameters to the main kernel image.

The first five in the table do not have variables associated with them as they are described by the initial portion of the boot string: "device(unit,processor)host:filename [variables]". Here are two examples of boot strings (they are split on two lines to fit the page; to work they must be a single string):

    ene(0,0)host:/home/vxworks/target/config/assabet/vxWorks h=192.168.1.1 
      e=192.168.1.100 u=vxworks tn=assabet

    dc(0,0)host:/home/vxworks/target/config/mv2604/vxWorks h=192.168.1.1
      e=192.168.1.101 u=vxworks f=0x8 tn=mv2604

The boot flags can change the behaviour of the bootrom, or the behaviour of the booted kernel system (since the booted kernel also parses the bootline to initialise certain features of the OS). The table below shows the available options:

Value	Description
0x01	Do not be a system controller (only applies to some boards)
0x02	Load local symbols from boot image as well as globals (only used if the target symbol table component is included in the kernel).
0x04	Do not autoboot; instead, stop at the bootrom's prompt on reset or reboot.
0x08	Quick autoboot; reduce the countdown from 10 seconds to 1 second.
0x20	Disable login security (networking option).
0x40	Autoconfigure parametere; uses BOOTP or DHCP depending on what is configured in the bootrom image.
0x80	Use TFTP to download the boot image instead of RSH or FTP.
0x100	Use proxy ARP.

Common Network Booting Problems

There are a number of problems that people commonly encounter when booting a target system over a network. This section covers a few of these.

Problems Attaching the Network Interface

If the Attached TCP/IP interface to xxx does not appear on the console, then there was a problem either detecting or initialising the network interface card (NIC). Check the following:

• Check that the selected boot device abbreviation matches the actual controller.

• Check that the driver for the selected device is included in the bootrom (you can do this by checking the list of available boot devices displayed at the end of the bootrom's help output).

• Check that the NIC is inserted correctly, and any jumpers or switches are set correctly (older cards only)

• Check whether the card is becoming live - look on the card itself, or the hub that it is connected to for status indicators.

• Check for compatibility with the hub or switch the NIC is connected to (e.g. 10/100 speed selection).

• If possible, try the NIC in a different system (e.g. a PC), or try booting an different board.

Problems Loading the VxWorks Image

If the Loading boot filename message appears, but nothing more happens (or it times out after a long delay), check the following:

• If the host and target systems are on different subnets, check that the following are correctly specified:
   
  1. Gateway address
      
  2. Subnet mask

• Try snooping on the network from the host machine, or another machine on the same physical portion of the network (if you have a switch between the machines, then this will not work - use a hub to connect the three machines to the each other if you wish to use a third machine).
   
  • If there are ARP requests from the target, but no responses, then check that the ARP table on the host shows the correct MAC (ethernet) address for the target board. There can be problems with this if you have changed the physical target board, but are using the same IP address. If it is incorrect, use arp -d hostname on unix machines, or arp -d IP address on a Windows box to delete the old entry.

• If you are using FTP, and rebooting frequently, be aware that due to the way that FTP port numbers are assigned, there might be significant delays introduced as the target attempts to establish a data connection with the host. Where possible, use RSH.

• If loading simply stops mid way through (i.e. you see some of the section sizes, but not all of them), then check the values of RAM_LOW_ADRS and RAM_HIGH_ADRS to make sure that there is enough space between them to load the imege. If RAM_HIGH_ADRS is changed, remember to rebuild bootrom and reprogram it into the board's flash/PROM.

If you get an error number, and the message is not clear, check the following table:

Error Number	Possible Cause
0x3c	Timeout error. Check the cables, and, if applicable, the gateway address. Also, check for any personal firewall software running on the host computer that might be blocking access by the target.
0x212	An incorrect FTP password was supplied in the boot line information.
0xd0003	Device error. This means that there was some problem accessing the boot device. Check that the device you have specified is correct, and that the driver for it is built into the bootrom. Also check that the driver is compatible with your version of the controller (this is especially true for PCI network cards, where OEMs can often change the PCI vendor/device ID pair).
0x250002	The host is not accepting RSH connection from the target. Check the user's .rhosts file and/or the host's /etc/hosts.equiv file.
0x290010	The boot filename is incorrect. Check that the name was typed correctly, and that the path is correct for the host system (especially on Windows systems where the FTP server may have a restricted view of the PC's file system.
0x320001	Check the bootline username and password parameters. If correct, check that the host is configured correctly to accept the type of connection selected (i.e. RSH or FTP).

Problems Transferring Control to VxWorks

If the Starting at xxx message is displayed, but the system does not start correctly, check the following:

• If characters typed at the console are echoed back correctly, then check that any code added to the initialisation sequence are correctly returning control to the main initialisation sequence (the root task). Applications should be started by spawning them as separate tasks from the initialisation sequence, rather than executing them directly in the context of the root task.

• If the system freezes totally, try reducing the configuration to a minimum working system. Alternatively, add calls to the reboot() function to the initialisation sequence to see how far through it is getting. If one is available, use a JTAG based debugger to see what is causing the failure.

• If an exception message, or other error message is displayed and control is returned to the bootrom, use the address of the exception, or the information in the error message, to determine the source of the error and correct it.

Problems Re-attaching the Network Interface

If the main kernel fails to re-attach the network interface, check the following:

• Ensure that the system was configured to attach the network interface. Standalone configurations do not automatically initialise the network stack).

• Ensure that the correct network driver was included in the kernel configuration.

• If the system does not have its MAC (ethernet) address stored permanently on the NIC, check that the value programmed into the device by the main kernel is the same as the one used by the bootrom.

Problems Loading the Symbol Table

Assuming that the target system has been configured to include the target symbol table, and to initialise it from the network (as opposed to the built in initialisation method), check the following:

• If there are many symbols in the table, or the vxWorks.sym file is very large, the system may run out of memory loading the symbols from the file. Try the standalone symbol table configuration if this is the case, or use host tools to strip unnecessary symbols (e.g. local symbols) from the file.

• If the file is not found, check that the vxWorks.sym is stored in the same location as the vxWorks boot image file. If the name of the boot file has been changed, ensure that the symbol table file matches this name (it is constructed by simply adding the .sym extension to the boot file name).

• If there is a very long delay loading the symbol table, but it does eventually succeed, the problem could be:
  • Mismatched MAC (ethernet) address between the bootrom and main kernel
  • Problems establishing the FTP data connection (see comments above about FTP data connections and frequent reboots).

Building and Running a Program

Compiling a Simple Module

Downloading a Module

Executing a Function

Decoding errno Values

VxWorks errno values are encoded in such a way as to make them relatively simple to decode when displayed in hexadecimal notation. The most significant 16 bits of the number are a module number, the least significant an error number specific to that module. So, to decode an errno value, convert the upper 16 bits to decimal, and look in the header file vwModNum.h. This header file contains definitions of module names for each number.

Once you have the module name, look in the corresponding header file for the error numbers specific to that module. These will always be of the form S_moduleName_ERROR_NAME and will be defined as the module name plus the error number.

Take the errno value of 0x3d0004 as an example:

1. Take the upper 16 bits of this number, 0x3d, and convert to decimal giving 61.
    
2. Look this up in the vwModNum.h header file giving M_objLib.
    
3. Look in objLib.h for the value of the lower 16 bits of the errno value, in this case 4, giving S_objLib_OBJ_TIMEOUT as the error's name.

There is a quicker way to get to this value assuming that you are using the host-based WindSh shell, or the target shell on a system that has the INCLUDE_STAT_SYM_TBL component included in its kernel configuration. In either of these cases, printErrno() will convert a numeric errno value into one of the macro names (like S_objLib_OBJ_TIMEOUT from the example).

-> printErrno 0x3d0004

Important Note: You should only use the value of errno to tell you more about an error condition that has been reported by a function you have called. Never use a non-zero value in errno as indication that an error has occurred. There are many places within the VxWorks system code where errno will be set to a non-zero value, but the overall operation will not fail. In order to preserve as much performance, and minimise the footprint of the OS, the errno value is not cleared in these cases. Since no error was reported to the application code, it should not check the errno value.

Likewise, when looking at a running system using the shell's i command, it will frequently be the case, especially for tasks that are making use of the networking facilities, that errno is non-zero. This is nothing to be concerned about: something internal to the OS has taken note of the error, and handled it. If it was an unexpected error, then that function would have returned ERROR or NULL (as appropriate) to indicate the failure.

-- JohnGordon - 16 Apr 2003

Attachment:	Action:	Size:	Date:	Who:	Comment:
figure-1-1.draw	action	5770	16 Mar 2003 - 23:03	JohnGordon	TWikiDraw? draw file
figure-1-1.gif	action	3169	16 Mar 2003 - 23:03	JohnGordon	TWikiDraw? GIF file