Application Note

 

 

Altia® Design

Human Interface Design Software

Using Altia Design with VxSim/VxWorks from Wind River Systems

This application note describes Altia's ability to interface with tasks executing in the Wind River System's VxSim environment. It provides information about the connection as well as instructions for installing and executing the integration demonstrations that have been developed.

VxSim Overview

VxSim is a SunOS or Solaris based version of the VxWorks realtime operating system that executes as a standard user process under SunOS or Solaris. Because the SUN SPARC processor is one of the VxWorks supported targets, VxSim actually executes native SPARC instructions rather than using an interpreted or emulated approach. This gives VxSim quite good performance.

VxSim also supports TCP/IP sockets using the UNIX ULIP (User Level IP) drivers. This allows modules executing in VxSim to open sockets and communicate in a standard fashion with processes running on the local host system.

Altia/VxSim Connection Overview

Because Altia Design's client API (application programming interface) library uses TCP/IP sockets as the underlying mechanism for Altia interface and client program communications, it was possible to port the API library to VxSim. This allows VxWorks users to develop software before hardware is available and run that software in VxSim while communicating to a virtual user interface developed with Altia Design. A large portion of an embedded system's code can be developed, debugged, and tested without physical hardware!

Connection Details

Two versions of the Altia client API library have been compiled for VxSim (actually, they have been cross compiled for a SPARC target so these libraries could also be used with VxWorks running in a SPARC based target system).

The first version of the library, liblan.o, is a relocatable module ready for loading into VxSim. Normally, a second module would also be loaded that calls functions in liblan.o to open a connection to an Altia interface and send and receive data. For example, assume a module has been written to provide logic for a cruise control system. For the VxSim environment, it can be designed to listen for events from an Altia interface and send its outputs to the interface as well. If the module is compiled as cruise.o, then both liblan.o and cruise.o would be loaded into VxSim before executing the functions defined in cruise.o.

The second version of the library, liblan.a, is in archive format. It cannot be directly loaded into VxSim. Instead, it must first be linked to another module and then the resulting module may be loaded. The link is performed with ldsparc using the -r option. For example, if you wish to create a complete module from liblan.a and cruise.o, you might use the following command:

ldsparc -r -o cruise.out cruise.o liblan.a

The result would be a relocatable module named cruise.out which could be loaded into VxSim and executed. The advantage to this approach is that only the necessary portions of liblan.a are added to the cruise.out relocatable. This can save target memory space if the user module (cruise.o in this case) only uses a limited number of functions from liblan.a. However, any functions not referenced by cruise.o will NOT be in cruise.out. So, other modules may not be able to call functions that they would normally find if liblan.o had been independently loaded.

Installing Files and Preparing for Execution

Demonstration files and copies of the liblan.o and liblan.a libraries are available on SUN SPARC floppy or as part of a full Altia Design product distribution on QIC-150 tape.

If you receive the files on floppy, then insert the floppy into a SPARC floppy drive and execute the following commands:

tar xvf /dev/rfd0

zcat vxdemos.tar.Z | tar xvf -

rm vxdemos.tar.Z

eject /dev/rfd0

Where fd0 is the appropriate device identifier for your floppy drive.

After executing the appropriate command sequence, you will have a directory named vxdemos located under the current working directory.

The vxdemos directory can be located anywhere on your system disk. If you have a full Altia Design product installation or evaluation, you may wish to move the directory to the standard altia directory (for example, execute: mv vxdemos /usr/altia/vxdemos). This will allow you to execute the Altia Design editor in addition to Altia Runtime. When you execute in edit mode, you can customize an interface design while it is connected to a client application (in this case a VxSim task)! This allows for very quick edit/run cycles.

If you receive the files with a full Altia Design product distribution on cartridge tape, follow the product installation procedures supplied with the tape. After successfully completing the installation, the demonstration files will reside in altia/vxdemos.

The vxdemos directory contains compiled versions of the Altia API library for VxSim running on SUN SPARC SunOs or Solaris. It also contains several demonstration modules that have been compiled. This directory does NOT contain the VxSim product. You must already have VxSim properly installed in order to operate the demonstrations. If the demo installation is from a floppy disk, the full Altia Design product software is optional because a trial version of the Altia Runtime software is provided on the floppy.

Executing the Demonstrations

After all preparations have been made, cd to the vxdemos directory from within a SunOS or Solaris shell tool or command tool window and simply execute the go script found in the directory. If you have a full Altia Design product installation or evaluation and you wish to execute in edit mode, execute go -edit. The go script will make its best attempt to find the editor. If it cannot find it, it will print a detailed error message to help you remedy the problem.

The go script will give you three unique demonstrations to choose from. After making a choice, the script will start the Altia interface portion of the demonstration. It will provide further instructions for starting VxSim, loading the necessary modules into VxSim, and spawning a task to control the Altia interface. The script does not attempt to start VxSim for you or execute any VxSim commands. It is therefore important that you carefully follow the instructions provided by the script.

When you are finished with a particular demonstration, just close the associated Altia interface window. This is done by choosing Close or Quit from the window border menu or by pressing <Control>-c while your window cursor is over the Altia interface window. When the interface process exits, the socket will immediately close. This will force an exit of the task in VxSim. You can also choose to only terminate the VxSim task by typing:

altiaDisconnect

at the VxSim shell prompt. The Altia interface window will remain open and a new task can be started for the same window by reissuing the sp (spawn) command that was described by the go script.

To run a different demonstration, simply execute the go script again and make a new demo choice when the script requests a response. Follow the script's instructions, but don't reload the liblan.o module into VxSim if it is already loaded.

If you choose to execute a particular demo again, you shouldn't need to load any new modules into VxSim. If the associated Altia interface window is still open, you don't even need to execute the go script. Just reissue the sp (spawn) command in VxSim as it was previously described by the go script.

You can have all of the demonstration modules loaded into VxSim at the same time because each has a unique entry point name (cruise() for cruise.o, stress() for stress.o, and vcr() for vcr.o). Just follow the syntax mentioned by the go script to spawn a task again. Please note that the syntax is different for each demo task and it should be entered exactly as described by the go script each time the task is spawned.

DO NOT ATTEMPT TO SPAWN MORE THAN ONE TASK AT A TIME! If you wish to spawn a demo module as a new task, you must first terminate any current demo task as described above. This restriction is a result of library reentrancy issues which are discussed in more detail in the Warnings section of this note.

Exercising the Cruise Control Demonstration

To exercise the cruise control interface, first click the left mouse button on the ignition key to turn on the vehicle. Dragging the mouse over the gas pedal with the left button pressed will adjust the car's speed. It must be over 30 mph to set the cruise control. Press the ON button found on the steering wheel to enable cruise control. Then press the SET button to set it to the current speed. The UP/DOWN buttons are used to adjust the SET speed. Raising the gas pedal will not change the speed, but lowering it will increase the speed. Click on the brake to stop the car and disengage the cruise control. Also note that the steering wheel can be turned by dragging the mouse over its outer rim with the left button pressed. The odometer, fuel, and temperature gauges are not functional.

Exercising the Stress Analyzer Demonstration

The stress analyzer only has 3 working controls - the power button, gain knob, and rate adjust slider. The power must be on to get any kind of response. Depress and drag the left mouse button over the gain knob to change the height of the waveform spike. Depress and drag the mouse over the slider to change the frequency of the spike.

Exercising the VCR Demonstration

The VCR unit can load, play, fast forward, reverse, pause, slow play, record and eject a tape. Click the left mouse button on the front of the tape to load it. The unit will automatically turn on and you can click on the various buttons to exercise the imaginary tape transport mechanism. Click on the eject button to unload the tape. Besides the tape transport buttons and POWER button, only the RESET, MEMORY, STANDBY and OTR buttons are functional. You cannot set the clock on the unit, but then, who can!

Rebuilding the Demonstration Modules

The source files for cruise.o, stress.o, and vcr.o as well as a make file have been provided for recompiling the demo modules for the SPARC target. You can modify the sources, remake, and try out your changes in VxSim. If you do modify the sources, you may wish to save the originals (for example, copy cruise.c, stress.c, and vcr.c to cruise.bak, stress.bak, and vcr.bak).

Sources for liblan.o and liblan.a are not provided with this demonstration; however, the header file which declares the functions available in the library is installed as altia.h. It also includes detailed comments with each function declaration.

Unusual Capabilities Made Possible by VxSim/VxWorks

When modules are loaded into VxSim, all global functions within the module are visible to all other modules in the system and they can be called from the VxSim/VxWorks shell prompt. For example, you can do the following from the VxSim/VxWorks shell prompt:

altiaConnect("host:2222")

altiaSendEvent("power",1)

altiaDisconnect()

The first command would open a connection to the Altia interface that is serving socket number 2222 and is running on the system named host. The second command would send an event to the interface to request a change of the power animation to state 1. The third and final command would close the connection. These API functions and many more are available for direct execution from the VxSim/VxWorks shell prompt. This is quite helpful during debugging.

Warnings for VxSim/VxWorks Users - PLEASE READ BEFORE PROGRAMMING WITH THE API

Only one copy of the Altia API library module is loaded into a particular VxSim/VxWorks session. Multiple user modules can make calls into the library module, but it should be remembered that all tasks are sharing the same code and data space for the library module and the current version IS NOT REENTRANT! If two or more tasks are spawned that randomly make calls to the library, a failure will most likely occur at some point during execution. To avoid problems, the tasks must coordinate their use of the library via semaphores or a similar facility.

When a task is finished with an Altia interface connection, it should explicitly close the connection to insure that data structures within the library are properly deallocated. If a connection is opened with altiaConnect(), then it should be closed with altiaDisconnect(). If a connection is opened with AtOpenConnection(), it should be closed with AtCloseConnection(). If part of a task's job is to open a connection for other tasks to use, than the task might not close the connection when it exits. In this case, another task should be responsible for closing the connection when it is no longer in use.

When AtOpenConnection() is called to open a connection to an Altia interface, the library's internal retry count is set to 1. This means that the library will call exit() if the connection fails. This typically occurs when the interface is closed by the user while the task is still running. If you do not want a task to exit automatically, you must call AtRetryCount() after calling AtOpenConnection(). A retry count of 0 tells the library not to call exit upon a connection close. It's then the responsibility of user code to close the connection gracefully.

If altiaConnect() is called to open a connection, it chooses 0 as the default retry count (i.e., the library will not call exit() if the connection fails). If a retry count of 1 is desirable, then altiaRetryCount() must be called.

Where to Find More Information on the API

For a complete description of all Altia API library functions, please refer to the Altia Reference Manual that is part of the Altia User's Manual. Or, look at the Altia API header file, altia.h, that is found in the vxdemos directory.

Restrictions for VxSim/VxWorks Users

Because of the remote nature of the VxSim/VxWorks connection, several functions found in the standard version of the Altia API library are not supported. Those functions are:

AtStartInterface()/altiaStartInterface()

AtStopInterface()/altiaStopInterface()

AtCreateMotifWidget()

AtCreateOpenlookWidget()

AtUnrealizeWidget()

AtXtOpenConnection()

AtXtAppOpenConnection()

The start and stop functions require the ability to fork and execute an Altia interface process which is not possible from within the VxSim/VxWorks environment. The other functions provide integration of an Altia interface with a Motif or Openlook interface. The X and Xt libraries necessary to cross compile these functions are not provided with the standard VxSim installation.

Source Available for Cross Compiling to Other VxWorks Targets

If you would like to compile the Altia API library for your own target system, the source can be purchased from Altia to do so. Because this source has already been compiled and tested on the SPARC implementation of VxWorks (i.e., VxSim), it should be fully compatible with your VxWorks target environment. Please note that TCP/IP socket support is required so that the library module executing in the target system can communicate with an Altia interface process running on a host computer. Altia supports SUN SPARC, HP9000/700, IBM RS/6000, SGI, Windows and Windows/NT systems as host computers.