How to write software for the IOTA VxWorks system

1) Introduction

2) Launching Tornado

3) Your first VxWorks application

4) The WindSh window

5) Projects with several files

6) Setting the priority level of a task

7) Shared memory

-1) Introduction

This short manual is intended for people who have already an experience of C or C++ programming and who know the basis of Unix or Linux. It has been written especially for the IOTA context and should not be used as a universal VxWorks tutorial.

VxWorks is the operating system (OS) used for the new control system of IOTA. Like Linux, VxWorks is a multi-task OS and is a "real-time" OS because the programmer can have control on the way the tasks are executed (the "scheduling").

VxWorks is a "preemptive" multi-task OS: each task has a priority level ranging from 0 (for the highest priority) to 255 (for the lowest priority). Let’s suppose that the CPU is running a task T1 of priority P1. If a task T2 of priority P2>P1 (actually the number used for representing the priority level of T2 is smaller than T1’s) is called, either by the user or by a taskSpawn (see part 6), then T1 is suspended right away and T2 is executed. When a resource needed for T2 is missing, T2 is turned in "pending" state. If the execution of T2 has been completed, T2 is discarded from the schedule. In either case the CPU will resume the execution of T1, unless a task T3 of priority P3 such that P3<P2 and P3>P1 has been spawned by T2.

When two tasks with the same priority level must be managed, VxWorks can use the "Round-Robin" scheduling: the CPU will spend alternatively a certain amount of time ("time slice") on each task until they are completed. The time slice length can be defined by the programmer.

A VxWorks software consists therefore of one or several tasks that must be developed on a dedicated computer (a Sun workstation for the IOTA environment) using preferably a development environment called "Tornado" (the version we describe here is Tornado 2.0 for Solaris). Once compiled and linked, the tasks are then loaded into the memory of the VxWorks computer (a 350 MHz PowerPC CPU plugged in a VME crate for the IOTA environment).

-2) Launching Tornado

To start, log on the IOTA Sun workstation under the login iota, password ________. If you are logged from a remote machine (host), type what is printed in boldface:

host$ xhost+

...

host$ telnet iota_IP

...

login: iota

Password: password

...

[home/iota]> setenv DISPLAY host_IP:0.0

 

iota_IP is the current IP name (e.g. iota.astro.umass.edu) of the IOTA Sun workstation and host_IP, the IP name of your host (e.g. iota0.sao.arizona.edu). Now, type:

Reminder: ‘&’ runs a task in the background and will not block your shell window). This command starts the Tornado environment. It’s the environment used for creating VxWorks code from the host. The Tornado window displays a bar of menus at the top, a target window, and a bar of icons at the bottom.

An online help in HTML format is available by clicking Help -> Manual contents. (click on menu Help, then on item Manual contents in this menu). Click on VxWorks Programmer’s Guide to know more details on the VxWorks OS (multi-tasking, task scheduling, inter-task communication...). Go to VxWorks Reference Manual -> Libraries to learn about special C functions of VxWorks that are gathered in libraries.

The target window displays information regarding the "target", i.e. the computer running under VxWorks for which you want to write software. Normally, only one target is attached (the PowerPC VME computer, that we call in this document the "VxWorks machine").

-3) Your first VxWorks application

Now, click on the Project icon. You will be asked to select a "workspace", i.e. a set of projects. For now, select one already existing. The Workspace window displays a list of projects. A "project" is a set of C or C++ source files (.c, .cpp, or .cxx) and header files (.h). You can open any project to check its source files. The headers are stored in a sub-folder called "external dependencies".

For creating a new project, click in the Workspace window File -> New Project... Select Create downloadable... option (icon with ".o"). Enter information regarding the project by filling the forms. After you have filled a form, click Next > at the bottom. Among the options, select Add to current workspace in the first form, and toolchain (specify PPC604gnu) in the second form.

Now, create a new text file on the IOTA Sun, in your directory (create a directory for your practice programs before venturing into IOTA code modification):

Confirm the creation of a new file and type in the textedit window:

#include <stdio.h>

 

int first_test(void)

{

  printf("hello world!\n");

}

Save the file and, in the workspace window, click on your project icon in the list, and click Project -> Add/Include -> File. Select test.cxx with the browser. The file name appears in the Workspace window as a sub-item of the project. You can now edit your file by double-clicking on the icon (textedit will be used). Notice that there is a sub-folder called External dependencies. It will contain all the .h files of your project. It is automatically filled by clicking Build -> Dependencies..., and then OK in the Dependencies window (select All Project files option before).

Select the Builds sub-window (bottom tab) in the Workspace window. Click on the ‘+’ at the left of the icon of your project. A triangle icon appears. Click on it and then on View -> Properties. A new window is displayed. Click on the C/C++ compiler tab. The compiler options are displayed. Set the optimization level to 2, and disable the debugger (click Include debug info button to have it released). Click Apply, OK, and go back the Files sub-window by clicking on its tab.

You can now build the executable code for VxWorks. Click Build -> Build. The compiler window is displayed, giving eventual errors. If no error has been found, you can download your application in the memory of the VxWorks system. First, in the workspace window, specify the target (empty line at the top), usually named iota-ppc@iota. Still in the Workspace window (Files sub-window), click on the icon of your project with the right button of the mouse. Select Download Project.out. The executable code is then transfered in the memory of the VxWorks machine. Each time you reset the VxWorks machine, you must then re-download the software you wrote prior to use it.

-4) The WindSh window

In the Tornado window, click on the WindSh icon. This will open a shell on the VxWorks system. From there, type:

Your application is executed and when it is finished, you have access to the shell.

Hello World!

value = 13 =0xd

->

 

The value returned is irrelevant because we omitted return(...); at the end of first_test(). Notice that there is no main() function in a VxWorks software. You launch only tasks represented by functions. Though you can use functions returning any type of value in a VxWorks software, only functions returning int can be used as task entries.

Here is a short list of useful WindSh commands:

To learn other commands, just type:

WindSh interprets also C functions of the VxWorks libraries. Use the normal C syntax to run a library function from WindSh.

-5) Projects with several files

Most of the projects use several source files. Create and add source files using the procedure described above for the test.cxx example.

You must now specify to the compiler the paths of your .h files. Display the compiler options window (as for setting the optimization level). To add the path of your file, type -I/header-file_path, as it has been done for the default paths.

Regenerate dependencies each time a new source file has been added in the project.

-6) Setting the priority level of a task

When you run a task by typing its name under WindSh, it is executed with the WindSh priority level (equal to 1). Hence, all the tasks are suspended. You normally want to avoid this situation and run your task according to a suitable schedule. In the previous example, edit test.cxx, and add the following lines. First, at the beginning of the file:

Then at the end:

int run_first_test(void)

{

  taskSpawn("1st_test",150,VX_FP_TASK,7000,first_test,0,0,0,0,0,0,0,0,0,0);

}

 

This will start the task first_test at the priority level 150. VX_FP_TASK is a macro indicating that floating point computing is required (it is not necessary for our example however). 7000 is a standard size for the stack to use. The task spawned is first_test and will appear in the task list (‘i’) with the name 1st_test, as specified by the first argument. The last ten parameters are the parameters of the function to spawn. Since first_test has no parameter in input, we can set all the parameters to zero.

Rebuild and download the modified code. Type from WindSh:

You notice that "Hello World!" is no longer displayed by WindSh. This is because the standard output from a task with a priority lower than WindSh’s (WindSh is actually a VxWorks task with level 1 priority -very high-) is not directed to WindSh, but directly to the Sun workstation using a serial link. Open now a second session on the IOTA Sun and type:

The output from the serial link is now displayed on the window where you typed tip a. Now, re-type on Windsh:

And look what happens... To disconnect from the serial output, type '~.' (tilde then dot). Although you can use tip a on your current Sun session, it is sometimes useful to open a second session for this purpose only.

-7) Shared memory

Intertask communication is provided by a chunk of RAM that can be accessed at any time by any task running under VxWorks, but also by the processes running on the IOTA Sun workstation. Type from the Sun:

This will display the organization of the shared memory. Each line gives the name of the block and its size. The minimal size is 4 kbytes (0x00001000). To add a new block, edit .gmem and add a line with the name of the block and its size. Suppose you named this new block MY_BLOCK. To use it in a task, define a pointer on the block in your task as following:

#include "map.h"

...

any_type *pMy_block;

...

pMy_block=(any_type *)map("MY_BLOCK",sizeof(any_type));

 

The pointer can really have any type, including pointer on a structure.

It’s important to know that only one task has the right to modify a variable stored in shared memory, in order to ensure correct intertask communication. Since no control is done by the VxWorks OS, it is the responsibility of the programmer to enforce this rule.

To Technical Info Page