Unofficial VxWorks & Tornado FAQ

This document attempts to answer VxWorks related questions.
This indexed HTML version is generated from raw text file via a PERL script which creates index and tag links.
Last Updated: Fri Jan 7 09:05:10 PST 2000

1. Introduction

2. Public resources on VxWorks

3. General VxWorks programming topics

4. VxWorks OS component related topics

5. I/O and filesystem related topics

6. Networking related itopics

7. CPU, bus architecture and BSP related topics

8. Graphical User Interfaces

9. Tools related topics

10. Tornado IDE and host tools specific topics

11. Other Misc. stuff

1. Introduction

1.1. Some notes about this Unofficial FAQ

This Unofficial FAQ was compiled by Hwa Jin Bae, but is now maintained by Johan Borkhuis. It is a free service offered by PSO Systems Inc in the interest of promoting free exchange of information on use of VxWorks.

This FAQ is "unofficial", meaning that it is produced independently of Wind River Systems. Wind River Systems has nothing to do with this FAQ. It is not the intent of this FAQ to duplicate any information that can be obtained from reading documentation provided by VxWorks and Wind River Systems. The content of this FAQ is to be used as is, and without any express or implied warranties, including, without limitation, the implied warranties of merchantability and fitness for a particular purpose.

All trademarks belong to respective holders.

1.2. Where is the old VxWorks USENET FAQ

The Old VxWorks FAQ has not been kept up to date. However it contains a lot of information, some of which might be still useful.

A somewhat more readable HTML version of the same OLD vxWorks FAQ is located here.

1.3. What is VxWorks?

VxWorks, made and sold by Wind River Systems of Alameda, CA, USA, is a real-time operating system. Similar real-time operating systems are available from other vendors: QNX, LynxOS, VRTX, pSOS, Windows-CE, Nucleus RTX, etc.

VxWorks requires a host workstation for program development. Unlike systems such as UNIX and QNX, VxWorks development is done on a "host" machine running UNIX or Windows, cross-compiling target software to run on various target CPU architectures.

It is a good idea to get a copy of VxWorks manuals before purchasing the system. WRS can provide you with such documentation. As far as I know there is no "VxBook" in the bookstores.

1.4. What kind of products have been developed using VxWorks?

Some examples:

2. Public resources on VxWorks

2.1. Where can I find documentation for VxWorks?

Wind River can supply you with printed documentation. On Internet you can view some documentation here.

2.2. Where is the archive site for user-contributed code?

2.3. What USENET groups are VxWorks related ?

2.4. Is there a VxWorks mailing list?

Lawrence Berkeley Labs maintains an automated mailing list which is bi-directionally gatewayed to comp.os.vxworks

It is called the 'VxWorks Exploder'.

Mail to is automatically mailed to subscribed users and gatewayed to USENET comp.os.vxworks.

The archive of this mailing list since 1991 is available from vxwexplo Archive

Send subscription request to

2.5. VxWorks World

VxWorks World has some links related to VxWorks.

Note: this site does not exist anymore.

2.6. Wind River's WindWord magazine articles

Here is a page that contains index of all VxWorks related articles published in WindWord, a magazine by Wind River. You can also read the articles starting from the index page.

3. General VxWorks programming topics

3.1. Where can I find some programming examples?

You can read some stuff at this site.

3.2. How do I manually decode VxWorks style errno numbers (e.g. 0xd0003)

VxWorks errno is composed of upper 16 bits indicating the library the error originates from, followed by 16 bits indicating specific error within that library.

The definition of upper 16 bit library categories is located in header file target/h/vwModNum.h. Once you find this module number, in our example 0xd0003 the upper 16 bit would be 0xd (decimal 13) which corresponds to M_iosLib, you can then look up the specific error number in the library's own header -- in our example, we look up target/h/iosLib.h to find out what error 3 in iosLib means.

Alternatively, if you have INCLUDE_STAT_SYM_TBL configured for your running target image you can look up the error by using printErrno() routine from the shell.

3.3. Some bootrom related handy tips

3.4. Some target shell related handy tips

3.5. Redirecting standard I/O

You can use ioGlobalStdSet() to redirect stdin, stdout, stderr console I/O devices. A frequent use of this is when using windsh under Tornado. You can use ioGlobalStdSet() along with virtual console I/O channel opened via open("/vio/0",2,0).

3.6. Porting UNIX software to VxWorks

Here is an article that contains some general information about differences you should be aware of when porting applications from UNIX to VxWorks.

3.7. How does VxWorks system calls work?

VxWorks does not have concept of "system call". Unlike Operating Systems such as pSOS, VRTX, Unix and many others, VxWorks calls are C function subroutines just like any other function call you may implement yourself. There is really no distinction between a "system call" and a generic C subroutine call.

3.8. Why can't I call printf() inside interrupt service routines?

In general, within an interrupt service routine, you cannot call any routines that can potentially block waiting for resources. Nor would you really want to (think about it). The printf() routine can block on a semaphore trying to get access to output device until it becomes available. A workaround is to call logMsg(). The logMsg() routine works by queueing your message content via message queue. It is sent to logTask, which prints it out at a task level when logTask gets to run as deemed proper by the scheduler.

4. VxWorks OS component related topics

4.1. Is there a better malloc/free replacement that does not fragment as badly?

There is a port of malloc library that consists of two algorithms that are different than original VxWorks memLib. VxHacks archive contains this port which has BSD and Doug Lea's malloc libraries.

4.2. Saving and restoring floating point registers per context switch and in an ISR?

To indicate that your task is using floating point registers which should be saved and restored per context switch, you should not forget to set VX_FP_TASK option in your task. Your ISR (Interrupt Service Routines) should call fppSave() and fppRestore() if it uses floating point registers. Depending on your compiler, it might be necessary to encapsulate your ISR in another dummy routine. For example, certain version of m68040 GNU compilers generate references to floating point registers even before your C code is generated. To avoid problems with these cases, you can create a C function that calls fppSave() and then calls your real ISR routine, and then calls fppRestore(), as a workaround.

4.3. VxWorks "watchdog" related common errors

The watchdog timer (wdLib) is a generic timer and not necessarily closely related to hardware watchdog facility available in many systems. It can certainly be used in association with a hardware watchdog resetting mechanism, but the name is a little bit of a misnomer.

A common error in using watchdog timer has to do with calling routines that can block. Since watchdog timer routine itself runs at interrupt level, you should not call any routines that can block. A frequent mistak is to call printf() inside a watchdog timer handler routine. You can use logMsg() instead.

5. I/O and filesystem related topics

5.1. What is RT-11 filesystem?

VxWorks implementation of RT-11 filesystem is a simple filesystem that is similar to original filesystem of RT-11 RTOS for PDP-11 computers. It is no longer supported by WRS. However this filesystem is very simple and can be useful for realtime data logging into contiguous file space. It does not support hierarchical directories or long filenames (6 char + 3 suffix).

5.2. What filesystems are available for VxWorks

The VxWorks/Tornado includes support for DOS filesystem, RT-11, netDrv filesystem (emulated filesystem lookalikes over FTP and RSH protocols), nfsDrv filesystem (NFS client filesystem).

There are third party products that provide more Unix like filesystems. Ask WRS.

5.3. Why does ls() not work uniformly over different filesystems

In truth, VxWorks does not really have a general filesystem layer. Each filesystem driver is implemented as I/O driver. The ioLib API which allows descriptor based open, close, read, write, ioctl, etc. is used to provide functionalities that are similar to the ones provided by filesystems in Unix.

However, not all filesystem drivers implement things uniformly. Some implement more (DOSFS) while others do less (netDrv). There is lsOld() which provides directory listing services for filesytems such as netDrv.

6. Networking related itopics

6.1. Where can I get source code for VxWorks port of PPP?

A public domain port of ppp-2.1.2 to VxWorks was available via anonymous ftp from as /pub/da/dab/ppp-2.1.2.tar.gz, but this site seems to be down.

6.2. More information on use of SO_KEEPALIVE to detect disconnected TCP channel?

The KEEPALIVE was introduced into original BSD UNIX TCP/IP implementation. Since VxWorks uses a port of BSD UNIX TCP/IP, users can find the implementation details by reading BSD UNIX original software source code. The VxWorks versin of software works the same way as BSD.

There were at least two different ways of handing KEEPALIVE. Because KEEPALIVE was not part of original TCP/IP RFC specification, and only added by BSD implementors as convenience, it has gone through different changes. The 4.2 BSD TCP/IP implementation sent out a packet with sequence number set to snd_una - 1. That is "send unacknowledged sequence number minus 1". It then set the ack number to rcv_next - 1. This forced a response from a remote TCP implementation either in the form of a ACK or RST packet, depending on the connection's status.

The 4.3 BSD changed this to be a little more robust. It sent a packet with the sequence number set to snd_una - 1 and ack set to rcv_next. The same behavior is usually triggered on the remote end.

The intent behind KEEPALIVE is to consistently get either ACK or RST, depending on whether connection is still alive. RST (reset packet) will indicate that the remote peer is no longer there, indicating that connection probably should be shutdown on local side. This provides a way to terminate the TCP connection.

Unfortunately, the KEEPALIVE method will start after connection has been idle for about 75 seconds and KEEPALIVE probe will continue for about 2 hours. The dection of bad connection can therefore take a long time, perhaps inappropriate for realtime systems. However, this feature is in adherence to the spirit of TCP in that you should not randomly decide to drop connections unless you are really absolutely sure. In the old days of Internet (sometimes even nowadays) the noisy and congested traffic links caused inter packet delays that were very slow. TCP is designed to cover cases that cause 10 minute delays between each keystroke in a telnet session to remote regions of the world, for example.

Adjusting KEEPALIVE packet intervals is only possible using global variables in most BSD based implementations. You can tune the following variables: tcp_keepidle, tcp_keepintvl, tcp_maxidle. Please take a look at the source code for TCP/IP stack before making any global adjustments.

6.3. Common questions related to use of netDrv

The netDrv is a very useful facility but it can also confuse some users. One can think of netDrv as an imcomplete filesystem emulation facility that sits on top of FTP or RSH protocol. The netDrv provides a pseudo file I/O interface to the users but it does so by first copying the entire file content to local buffer (RAM). If you are interfacing to a large file, using netDrv can eat up a lot of your memory. The protocol selection is done by password. If you provide password to your bootline, default VxWorks bootrom will create a netDrv device for the booting directory on the host via FTP. If no password is provided, it is assumed that you are using RSH protocol.

Because of the pseudo nature of netDrv, not all of the filesystem I/O semantics that are present in other filesystems are implemented transparently. For example, you may find that ls() often may not work over netDrv. However, you can also write a simple C function that sends a "ls" command to the host. For example, you can use rcmd() to send "ls" to the host side, if you are using RSH.

6.4. Use of RPC on VxWorks

Here is an article that describes general steps to using RPC on VxWorks.

6.5. How can I disable NFS client side caching on VxWorks?

VxWorks NFS cache can be completely disabled by setting global variable nfsCacheSize to 0. To just flush the write cache as needed, nfsCacheFlush() can be used. You can also try using ioctl() with FIOSYNC.

6.6. "Cannot Boot. Error 0x1a9" message while booting

This is usually due to the built-in 'feature' inside UNIX inetd program. The inetd tries to protect itself against clients that tries to connect too often too quick as a security measure, and disallows more than a certain number of connections per given period. When this happens, you will usually see some error messages about "looping..." in syslog (if your syslog is configured correctly) on your UNIX server (where inetd is running). You can either try "kill -HUP inetd_process_id" to get out of this looping mode by sending HUP signal to inetd, or try and install the patched version of inetd that has larger default limit for looping detection (some OS vendors will supply this to you), or just get a copy of BSD UNIX distribution of inetd source code and compile it with larger default values for looping and use it instead. Or you can consult the manual pages for your inetd program since it may already provide options to turn off the looping detection.

6.7. Information on VxWorks Port of NTP (Network Time Protocol)

Some information on VxWorks port of NTP code can be found at this site.

6.8. Common parameters to tune for better network performance

Using setsockopt() call, you can change the socket level buffer sizes of TCP sockets. This can affect the sizes of buffer windoes TCP protocol uses which can have different performance impact. The options are SO_SNDBUF and SO_RCVBUF.

You can also tune global variables: tcp_sendspace, tcp_recvspace, udp_sendspace, and udp_recvspace. Read original BSD TCP/IP code before attempting to change these globals.

To get around some latency related problems, you may turn on TCP_NODELAY option on TCP sockets which disables Nagle's algorithm.

Additionally there are various mbuf pool parameters in various configurable source files in your BSP.

6.9. How to get around EADDRINUSE when using bind() call?

Use setsockopt() with SO_REUSEADDR on your socket. If bind() still fails with EADDRINUSE, it is probable that you indeed do have another socket using that port you are trying to bind. You can use inetstatShow() to list out all the used sockets on your system to track it down.

6.10. Can I get multiple target shell sessions via telnet?

VxWorks target shell is non-reentrant and only single instance is allowed to run at a time. The telnet daemon in VxWorks only allows single login session at a time. This is due to the way single console descriptor is shared globally, among other things.

An alternative is to use winsh from Tornado which will allow multiple target shell-like sessions. However winsh does not have all the facilities one might expect and it is not entirely compatible with original target shell. Some of the commands available in target shell are not available in winsh and vice versa.

6.11. Using "default" route

A default route is a route table entry with destination field set to 0. To do the equivalent of "route add default gateway metric" in VxWorks, do: routeAdd("0",addr_of_gateway);

6.12. How to configure socket level buffer size used by FTP daemon for better performance?

There is a global variable called ftpdWindowSize that can be tweaked.

6.13. Does FTP daemon worker tasks go away?

Eventually KEEPALIVE will detect dead clients and tasks will be cleaned up. However, this takes a while (about 2 hours). See KEEPALIVE related FAQ entries above.

7. CPU, bus architecture and BSP related topics

7.1. Where can I find supported CPU and BSP list?

Look on the WindRiver site, there this information can be found. Or contact WindRiver directly.

7.2. How to disable cache on m68040 or m68030 using TT registers

	/* for 68030 (e.g. mv147) */
	/* 2 large areas, R/W, cache disabled */
	#define TT0_VALUE   0x403f8507  /* from $40000000 -> $77ffffff */
	#define TT1_VALUE   0x03018507  /* from $02000000 -> $03ffffff */
	test_tt ()
	    register int *pVal;
	    int ttVal;
	    pVal = &ttVal;
	    ttVal = TT0_VALUE;
	    asm ("pmove %0,tt0" : : "g" (*pVal));
	    ttVal = TT1_VALUE;
	    asm ("pmove %0,tt1" : : "g" (*pVal));
	/* for 68040 (e.g. mv167) */
	/* 2 large areas, R/W, cache disabled */
	#define TT0_VALUE   0x403f8507  /* from $40000000 -> $77ffffff */
	#define TT1_VALUE   0x03018507  /* from $02000000 -> $03ffffff */
	test_dtt ()
	    asm ("movec %0,dtt0" : : "r" (DTT0_VALUE));
	    asm ("movec %0,dtt1" : : "r" (DTT1_VALUE));

7.3. VME Bus arbitration settings

In the VMEbus, there are 4 levels of arbitration (0-3) where level 3 is the highest priority. By default, virtually all manufacturers ship their boards configured for BG3. Sometimes it is necessary to make adjustments. Within the 4 BG levels, there are two modes of operation: 1) priority and 2) round robin. Priority mode means that requests at level 3 will be honored before requests at level 2. Level 2 before level 1 and so on. This means that with priority mode arbitration, put your highest priority boards at level 3 and distribute the other boards at the other levels according to their relative priorities.

The round robin arbitration mode means that all 4 BG levels are treated equally and each level gets a fair slice of the pie so to speak. Use this mode when you have lots of boards, but no one has an inherently higher priority than any other. Remember, just because the boards are at different BG levels doesn't circumvent the implied priorities of the CPUs at the same level based on the bus daisy chain.

Typically, these modes are configurable on the system controller either through a jumper, PAL or software bit twiddling. However, there are boards that are hardwired for arbitration level 3 and they can't be changed. This means that you'll have to use these boards sparingly in VxWorks VME chassis (i.e., probably no more than 3-4 booting up from the backplane but probably more if you boot each of them up from local Ethernet).

7.4. Where is the VME FAQ?

This site has an excellent FAQ for the VME bus.

7.5. Where is the Compact PCI FAQ?

This site has a brief FAQ on Compact PCI bus.

8. Graphical User Interfaces

8.1. RtX information

There is a RtX FAQ at Visicom Labs site.

8.2. Is there a free Graphics library for VxWorks?

There is a freely available SDL (standard drawing library) which can be used to create graphical interfaces like bar guages, arc guages, text gauges, block diagram and random filled polygons. Try RGI web page for more info.

9. Tools related topics

9.1. Linux x86 -> VxWorks target GNU toolchain

Some basic information on building custom cross compile toolchain based on GNU software kit was available at a Sparta web site , but this site is (also) gone.

9.2. DOS and Win32 x86 cross target generic GNU toolchain

Although not quite VxWorks specific, generic GNU toolchain binaries for various CPU architectures are available and can be useful alternative to Tornado host tools.

This site has precompiled versions of gcc and gdb for m68k, PowerPC and ColdFire hosted on DOS and Win32.

9.3. Linux based GNU cross toolchain for x86 and m68k

Details can be found in this web page

9.4. Building GNAT GNU cross compilers

This page has good information on building cross compilers using GNU toolchain source code in general. Specifically it documents details of GNAT ADA cross compiler generation.

10. Tornado IDE and host tools specific topics

10.1. Do winsh and target resident shell provide the same functionalities?

The winsh commands are implemented in TCL. The target shell running in the target has access to all subroutines that are in the symbol table. Winsh can run TCL commands that are currently implemented. This means that sometimes you will not be able to run some of the commands you are used to running in winsh. This only applies if you are an old VxWorks user who is used to doing things in target shell. Winsh does provide a '@' prefix which tells it to send a whole string to target and run in as a target side command, which can be useful for most things.

11. Other Misc. stuff

11.1. What happened with Mars Lander/Pathfinder software error related to VxWorks?

Amusing details can be found here

VxWorks Homepage
© J.A. Borkhuis, 2000 - 2005
Send me an e-mail if this page was helpfull