Modern real-time systems are based on the complementary concepts of multitasking and intertask communications. A multitasking environment allows a real-time application to be constructed as a set of independent tasks, each with its own thread of execution and set of system resources. The intertask communication facilities allow these tasks to synchronize and communicate in order to coordinate their activity. In VxWorks, the intertask communication facilities range from fast semaphores to message queues and from pipes to network-transparent sockets.

Another key facility in real-time systems is hardware interrupt handling, because interrupts are the usual mechanism to inform a system of external events. To get the fastest possible response to interrupts, interrupt service routines (ISRs) in VxWorks run in a special context of their own, outside any task's context.

This chapter discusses the tasking facilities, intertask communication, and the interrupt handling facilities that are at the heart of the VxWorks run-time environment. You can also use POSIX real-time extensions with VxWorks. For more information, see 3. POSIX Standard Interfaces.

It is often essential to organize applications into independent, though cooperating, programs. Each of these programs, while executing, is called a task. In VxWorks, tasks have immediate, shared access to most system resources, while also maintaining enough separate context to maintain individual threads of control.

Multitasking provides the fundamental mechanism for an application to control and react to multiple, discrete real-world events. The VxWorks real-time kernel, wind, provides the basic multitasking environment. Multitasking creates the appearance of many threads of execution running concurrently when, in fact, the kernel interleaves their execution on the basis of a scheduling algorithm. Each task has its own context, which is the CPU environment and system resources that the task sees each time it is scheduled to run by the kernel. On a context switch, a task's context is saved in the task control block (TCB).

A task's context includes:

• a thread of execution; that is, the task's program counter

• the CPU registers and (optionally) floating-point registers

• a stack for dynamic variables and function calls

• I/O assignments for standard input, output, and error

• a delay timer

• a time-slice timer

• kernel control structures

• signal handlers

• debugging and performance monitoring values

In VxWorks, one important resource that is not part of a task's context is memory address space: all code executes in a single common address space. Giving each task its own memory space requires virtual-to-physical memory mapping, which is available only with the optional product VxVMI; for more information, see 12. Virtual Memory Interface.

The kernel maintains the current state of each task in the system. A task changes from one state to another as a result of kernel function calls made by the application. When created, tasks enter the suspended state. Activation is necessary for a created task to enter the ready state. The activation phase is extremely fast, enabling applications to pre-create tasks and activate them in a timely manner. An alternative is the spawning primitive, which allows a task to be created and activated with a single function. Tasks can be deleted from any state.

Table 2-1 describes the state symbols that you see when working with Tornado development tools. Figure 2-1 shows the corresponding state diagram of the wind kernel states.

Multitasking requires a scheduling algorithm to allocate the CPU to ready tasks. The default algorithm in wind is priority-based preemptive scheduling. You can also select to use round-robin scheduling for your applications. Both algorithms rely on the task's priority. The wind kernel has 256 priority levels, numbered 0 through 255. Priority 0 is the highest and priority 255 is the lowest. Tasks are assigned a priority when created. You can also change a task's priority level while it is executing by calling taskPrioritySet( ). The ability to change task priorities dynamically allows applications to track precedence changes in the real world.

The routines that control task scheduling are listed in Table 2-2. .

POSIX also provides a scheduling interface. For more information, see 3.5 POSIX Scheduling Interface.

A preemptive priority-based scheduler preempts the CPU when a task has a higher priority than the current task running. Thus, the kernel ensures that the CPU is always allocated to the highest priority task that is ready to run. This means that if a task- with a higher priority than that of the current task- becomes ready to run, the kernel immediately saves the current task's context, and switches to the context of the higher priority task. For example, in Figure 2-2, task t1 is preempted by higher-priority task t2, which in turn is preempted by t3. When t3 completes, t2 continues executing. When t2 completes execution, t1 continues executing.

The disadvantage of this scheduling algorithm is that, when multiple tasks of equal priority must share the processor, if a single task is never blocked, it can usurp the processor. Thus, other equal-priority tasks are never given a chance to run. Round-robin scheduling solves this problem.

A round-robin scheduling algorithm attempts to share the CPU fairly among all ready tasks of the same priority. Round-robin scheduling uses time slicing to achieve fair allocation of the CPU to all tasks with the same priority. Each task, in a group of tasks with the same priority, executes for a defined interval or time slice.

Round-robin scheduling is enabled by calling kernelTimeSlice( ), which takes a parameter for a time slice, or interval. This interval is the amount of time each task is allowed to run before relinquishing the processor to another equal-priority task. Thus, the tasks rotate, each executing for an equal interval of time. No task gets a second slice of time before all other tasks in the priority group have been allowed to run.

In most systems, it is not necessary to enable round-robin scheduling, the exception being when multiple copies of the same code are to be run, such as in a user interface task.

If round-robin scheduling is enabled, and preemption is enabled for the executing task, the system tick handler increments the task's time-slice count. When the specified time-slice interval is completed, the system tick handler clears the counter and the task is placed at the tail of the list of tasks at its priority level. New tasks joining a given priority group are placed at the tail of the group with their run-time counter initialized to zero.

Enabling round-robin scheduling does not affect the performance of task context switches, nor is additional memory allocated.

If a task blocks or is preempted by a higher priority task during its interval, its time-slice count is saved and then restored when the task becomes eligible for execution. In the case of preemption, the task will resume execution once the higher priority task completes, assuming that no other task of a higher priority is ready to run. In the case where the task blocks, it is placed at the tail of the list of tasks at its priority level. If preemption is disabled during round-robin scheduling, the time-slice count of the executing task is not incremented.

Time-slice counts are accrued by the task that is executing when a system tick occurs, regardless of whether or not the task has executed for the entire tick interval. Due to preemption by higher priority tasks or ISRs stealing CPU time from the task, it is possible for a task to effectively execute for either more or less total CPU time than its allotted time slice.

Figure 2-3 shows round-robin scheduling for three tasks of the same priority: t1, t2, and t3. Task t2 is preempted by a higher priority task t4 but resumes at the count where it left off when t4 is finished.

The wind scheduler can be explicitly disabled and enabled on a per-task basis with the routines taskLock( ) and taskUnlock( ). When a task disables the scheduler by calling taskLock( ), no priority-based preemption can take place while that task is running.

However, if the task explicitly blocks or suspends, the scheduler selects the next highest-priority eligible task to execute. When the preemption-locked task unblocks and begins running again, preemption is again disabled.

Note that preemption locks prevent task context switching, but do not lock out interrupt handling.

Preemption locks can be used to achieve mutual exclusion; however, keep the duration of preemption locking to a minimum. For more information, see 2.3.2 Mutual Exclusion.

When using taskLock( ), consider that it will not achieve mutual exclusion. Generally, if interrupted by hardware, the system will eventually return to your task. However, if you block, you lose task lockout. Thus, before you return from the routine, taskUnlock( ) should be called.

When a task is accessing a variable or data structure that is also accessed by an ISR, you can use intLock( ) to achieve mutual exclusion. Using intLock( ) makes the operation "atomic" in a single processor environment. It is best if the operation is kept minimal, meaning a few lines of code and no function calls. If the call is too long, it can directly impact interrupt latency and cause the system to become far less deterministic.

All application tasks should be priority 100 - 250. However, driver "support" tasks (tasks associated with an ISR) can be in the range of 51-99. These tasks are crucial; for example, if a support task fails while copying data from a chip, the device loses that data.¹ The system netTask( ) is at priority 50, so user tasks should not be assigned priorities below that task; if they are, the network connection could die and prevent debugging capabilities with Tornado.

The following sections give an overview of the basic VxWorks task routines, which are found in the VxWorks library taskLib. These routines provide the means for task creation and control, as well as for retrieving information about tasks. See the VxWorks API Reference entry for taskLib for further information.

For interactive use, you can control VxWorks tasks from the host or target shell; see the Tornado User's Guide: Shell and 6. Target Tools in this manual.

The routines listed in Table 2-3 are used to create tasks.

The arguments to taskSpawn( ) are the new task's name (an ASCII string), the task's priority, an "options" word, the stack size, the main routine address, and 10 arguments to be passed to the main routine as startup parameters:

id = taskSpawn ( name, priority, options, stacksize, main, arg1, arg10 );

The taskSpawn( ) routine creates the new task context, which includes allocating the stack and setting up the task environment to call the main routine (an ordinary subroutine) with the specified arguments. The new task begins execution at the entry to the specified routine.

The taskSpawn( ) routine embodies the lower-level steps of allocation, initialization, and activation. The initialization and activation functions are provided by the routines taskInit( ) and taskActivate( ); however, we recommend you use these routines only when you need greater control over allocation or activation.

It is hard to know exactly how much stack space to allocate, without reverse-engineering the system configuration. To help avoid a stack overflow, and task stack corruption, you can take the following approach. When initially allocating the stack, make it much larger than anticipated; for example, from 20KB to up to 100KB, depending upon the type of application. Then, periodically monitor the stack with checkStack( ), and if it is safe to make them smaller, modify the size.

When a task is spawned, you can specify an ASCII string of any length to be the task name. VxWorks returns a task ID, which is a 4-byte handle to the task's data structures. Most VxWorks task routines take a task ID as the argument specifying a task. VxWorks uses a convention that a task ID of 0 (zero) always implies the calling task.

VxWorks does not require that task names be unique, but it is recommended that unique names be used in order to avoid confusing the user. Furthermore, to use the Tornado development tools to their best advantage, task names should not conflict with globally visible routine or variable names. To avoid name conflicts, VxWorks uses a convention of prefixing all task names started from the target with the character t and task names started from the host with the character u.

You may not want to name some or all of your application's tasks. If a NULL pointer is supplied for the name argument of taskSpawn( ), then VxWorks assigns a unique name. The name is of the form tN, where N is a decimal integer that is incremented by one for each unnamed task that is spawned.

The taskLib routines listed in Table 2-4 manage task IDs and names.

When a task is spawned, you can pass in one or more option parameters, which are listed in Table 2-5. The result is determined by performing a logical OR operation on the specified options.

You must include the VX_FP_TASK option when creating a task that:

• Performs floating-point operations.

• Calls any function that returns a floating-point value.

• Calls any function that takes a floating-point value as an argument.

For example:

tid = taskSpawn ("tMyTask", 90, VX_FP_TASK, 20000, myFunc, 2387, 0, 0, 
                0, 0, 0, 0, 0, 0, 0);

Some routines perform floating-point operations internally. The VxWorks documentation for each of these routines clearly states the need to use the VX_FP_TASK option.

After a task is spawned, you can examine or alter task options by using the routines listed in Table 2-6. Currently, only the VX_UNBREAKABLE option can be altered.

The routines listed in Table 2-7 get information about a task by taking a snapshot of a task's context when the routine is called. Because the task state is dynamic, the information may not be current unless the task is known to be dormant (that is, suspended).

Tasks can be dynamically deleted from the system. VxWorks includes the routines listed in Table 2-8 to delete tasks and to protect tasks from unexpected deletion.

The routines listed in Table 2-9 provide direct control over a task's execution.

VxWorks debugging facilities require routines for suspending and resuming a task. They are used to freeze a task's state for examination.

Tasks may require restarting during execution in response to some catastrophic error. The restart mechanism, taskRestart( ), recreates a task with the original creation arguments.

Delay operations provide a simple mechanism for a task to sleep for a fixed duration. Task delays are often used for polling applications. For example, to delay a task for half a second without making assumptions about the clock rate, call:

taskDelay (sysClkRateGet ( ) / 2);

The routine sysClkRateGet( ) returns the speed of the system clock in ticks per second. Instead of taskDelay( ), you can use the POSIX routine nanosleep( ) to specify a delay directly in time units. Only the units are different; the resolution of both delay routines is the same, and depends on the system clock. For details, see 3.2 POSIX Clocks and Timers.

As a side effect, taskDelay( ) moves the calling task to the end of the ready queue for tasks of the same priority. In particular, you can yield the CPU to any other tasks of the same priority by "delaying" for zero clock ticks:

taskDelay (NO_WAIT);     /* allow other tasks of same priority to run */ 

A "delay" of zero duration is only possible with taskDelay( ); nanosleep( ) considers it an error.

To allow additional task-related facilities to be added to the system, VxWorks provides hook routines that allow additional routines to be invoked whenever a task is created, a task context switch occurs, or a task is deleted. There are spare fields in the task control block (TCB) available for application extension of a task's context

These hook routines are listed in Table 2-10; for more information, see the reference entry for taskHookLib. .

When using hook routines, be aware of the following restrictions:

• Task switch hook routines must not assume any VM context is current other than the kernel context (as with ISRs).

• Task switch and swap hooks must not rely on knowledge of the current task or invoke any function that relies on this information; for example, taskIdSelf( ).

• A switch or swap hook must not rely on the taskIdVerify(pOldTcb) mechanism to determine if the delete hook, if any, has already executed for the self-destructing task case. Instead, some other state information needs to be changed; for example, using a NULL pointer in the delete hook to be detected by the switch hook.

The taskCreateAction hook routines execute in the context of the creator task, and any new objects are owned by the creator task's home protection domain, or the creator task itself. It may, therefore, be necessary to assign the ownership of new objects to the task that is created in order to prevent undesirable object reclamation in the event that the creator task terminates.

User-installed switch hooks are called within the kernel context and therefore do not have access to all VxWorks facilities. Table 2-11 summarizes the routines that can be called from a task switch hook; in general, any routine that does not involve the kernel can be called.

By convention, C library functions set a single global integer variable errno to an appropriate error number whenever the function encounters an error. This convention is specified as part of the ANSI C standard.

In VxWorks, errno is simultaneously defined in two different ways. There is, as in ANSI C, an underlying global variable called errno, which you can display by name using Tornado development tools; see the Tornado User's Guide. However, errno is also defined as a macro in errno.h; this is the definition visible to all of VxWorks except for one function. The macro is defined as a call to a function __errno( )that returns the address of the global variable, errno (as you might guess, this is the single function that does not itself use the macro definition for errno). This subterfuge yields a useful feature: because __errno( )is a function, you can place breakpoints on it while debugging, to determine where a particular error occurs.

Nevertheless, because the result of the macro errno is the address of the global variable errno, C programs can set the value of errno in the standard way:

errno = someErrorNumber;

As with any other errno implementation, take care not to have a local variable of the same name.

In VxWorks, the underlying global errno is a single predefined global variable that can be referenced directly by application code that is linked with VxWorks (either statically on the host or dynamically at load time). However, for errno to be useful in the multitasking environment of VxWorks, each task must see its own version of errno. Therefore errno is saved and restored by the kernel as part of each task's context every time a context switch occurs. Similarly, interrupt service routines (ISRs) see their own versions of errno.

This is accomplished by saving and restoring errno on the interrupt stack as part of the interrupt enter and exit code provided automatically by the kernel (see 2.6.1 Connecting Routines to Interrupts). Thus, regardless of the VxWorks context, an error code can be stored or consulted with direct manipulation of the global variable errno.

Almost all VxWorks functions follow a convention that indicates simple success or failure of their operation by the actual return value of the function. Many functions return only the status values OK (0) or ERROR (-1). Some functions that normally return a nonnegative number (for example, open( ) returns a file descriptor) also return ERROR to indicate an error. Functions that return a pointer usually return NULL (0) to indicate an error. In most cases, a function returning such an error indication also sets errno to the specific error code.

The global variable errno is never cleared by VxWorks routines. Thus, its value always indicates the last error status set. When a VxWorks subroutine gets an error indication from a call to another routine, it usually returns its own error indication without modifying errno. Thus, the value of errno that is set in the lower-level routine remains available as the indication of error type.

For example, the VxWorks routine intConnect( ), which connects a user routine to a hardware interrupt, allocates memory by calling malloc( ) and builds the interrupt driver in this allocated memory. If malloc( ) fails because insufficient memory remains in the pool, it sets errno to a code indicating an insufficient-memory error was encountered in the memory allocation library, memLib. The malloc( ) routine then returns NULL to indicate the failure. The intConnect( ) routine, receiving the NULL from malloc( ), then returns its own error indication of ERROR. However, it does not alter errno leaving it at the "insufficient memory" code set by malloc( ). For example:

if ((pNew = malloc (CHUNK_SIZE)) == NULL) 
    return (ERROR);

It is recommended that you use this mechanism in your own subroutines, setting and examining errno as a debugging technique. A string constant associated with errno can be displayed using printErrno( ) if the errno value has a corresponding string entered in the error-status symbol table, statSymTbl. See the reference entry errnoLib for details on error-status values and building statSymTbl.

VxWorks errno values encode the module that issues the error, in the most significant two bytes, and uses the least significant two bytes for individual error numbers. All VxWorks module numbers are in the range 1-500; errno values with a "module" number of zero are used for source compatibility.

All other errno values (that is, positive values greater than or equal to 501<<16, and all negative values) are available for application use.

See the reference entry on errnoLib for more information about defining and decoding errno values with this convention.

Errors in program code or data can cause hardware exception conditions such as illegal instructions, bus or address errors, divide by zero, and so forth. The VxWorks exception handling package takes care of all such exceptions. The default exception handler suspends the task that caused the exception, and saves the state of the task at the point of the exception. The kernel and other tasks continue uninterrupted. A description of the exception is transmitted to the Tornado development tools, which can be used to examine the suspended task; see the Tornado User's Guide: Shell for details.

Tasks can also attach their own handlers for certain hardware exceptions through the signal facility. If a task has supplied a signal handler for an exception, the default exception handling described above is not performed. A user-defined signal handler is useful for recovering from catastrophic events. Typically, setjmp( ) is called to define the point in the program where control will be restored, and longjmp( ) is called in the signal handler to restore that context. Note that longjmp( ) restores the state of the task's signal mask.

Signals are also used for signaling software exceptions as well as hardware exceptions. They are described in more detail in 2.3.7 Signals and in the reference entry for sigLib.

In VxWorks, it is common for a single copy of a subroutine or subroutine library to be invoked by many different tasks. For example, many tasks may call printf( ), but there is only a single copy of the subroutine in the system. A single copy of code executed by multiple tasks is called shared code. VxWorks dynamic linking facilities make this especially easy. Shared code makes a system more efficient and easier to maintain; see Figure 2-4.

Shared code must be reentrant. A subroutine is reentrant if a single copy of the routine can be called from several task contexts simultaneously without conflict. Such conflict typically occurs when a subroutine modifies global or static variables, because there is only a single copy of the data and code. A routine's references to such variables can overlap and interfere in invocations from different task contexts.

Most routines in VxWorks are reentrant. However, you should assume that any routine someName( ) is not reentrant if there is a corresponding routine named someName_r( ) -- the latter is provided as a reentrant version of the routine. For example, because ldiv( ) has a corresponding routine ldiv_r( ), you can assume that ldiv( ) is not reentrant.

VxWorks I/O and driver routines are reentrant, but require careful application design. For buffered I/O, we recommend using file-pointer buffers on a per-task basis. At the driver level, it is possible to load buffers with streams from different tasks, due to the global file descriptor table in VxWorks.

This may or may not be desirable, depending on the nature of the application. For example, a packet driver can mix streams from different tasks because the packet header identifies the destination of each packet.

The majority of VxWorks routines use the following reentrancy techniques:

• dynamic stack variables

• global and static variables guarded by semaphores

• task variables

We recommend applying these same techniques when writing application code that can be called from several task contexts simultaneously.

Many subroutines are pure code, having no data of their own except dynamic stack variables. They work exclusively on data provided by the caller as parameters. The linked-list library, lstLib, is a good example of this. Its routines operate on lists and nodes provided by the caller in each subroutine call.

Subroutines of this kind are inherently reentrant. Multiple tasks can use such routines simultaneously, without interfering with each other, because each task does indeed have its own stack. See Figure 2-5.

Some libraries encapsulate access to common data. This kind of library requires some caution because the routines are not inherently reentrant. Multiple tasks simultaneously invoking the routines in the library might interfere with access to common variables. Such libraries must be made explicitly reentrant by providing a mutual-exclusion mechanism to prohibit tasks from simultaneously executing critical sections of code. The usual mutual-exclusion mechanism is the mutex semaphore facility provided by semMLib and described in Mutual-Exclusion Semaphores.

Some routines that can be called by multiple tasks simultaneously may require global or static variables with a distinct value for each calling task. For example, several tasks may reference a private buffer of memory and yet refer to it with the same global variable.

To accommodate this, VxWorks provides a facility called task variables that allows 4-byte variables to be added to a task's context, so that the value of such a variable is switched every time a task switch occurs to or from its owner task. Typically, several tasks declare the same variable (4-byte memory location) as a task variable. Each of those tasks can then treat that single memory location as its own private variable; see Figure 2-6. This facility is provided by the routines taskVarAdd( ), taskVarDelete( ), taskVarSet( ), and taskVarGet( ), which are described in the reference entry for taskVarLib.

Use this mechanism sparingly. Each task variable adds a few microseconds to the context switching time for its task, because the value of the variable must be saved and restored as part of the task's context. Consider collecting all of a module's task variables into a single dynamically allocated structure, and then making all accesses to that structure indirectly through a single pointer. This pointer can then be the task variable for all tasks using that module.

With VxWorks, it is possible to spawn several tasks with the same main routine. Each spawn creates a new task with its own stack and context. Each spawn can also pass the main routine different parameters to the new task. In this case, the same rules of reentrancy described in Task Variables apply to the entire task.

This is useful when the same function needs to be performed concurrently with different sets of parameters. For example, a routine that monitors a particular kind of equipment might be spawned several times to monitor several different pieces of that equipment. The arguments to the main routine could indicate which particular piece of equipment the task is to monitor.

In Figure 2-7, multiple joints of the mechanical arm use the same code. The tasks manipulating the joints invoke joint( ). The joint number (jointNum) is used to indicate which joint on the arm to manipulate.

Depending on its configuration, VxWorks may include a variety of system tasks. These are described below.

The complement to the multitasking routines described in 2.2 VxWorks Tasks is the intertask communication facilities. These facilities permit independent tasks to coordinate their actions.

VxWorks supplies a rich set of intertask communication mechanisms, including:

• Shared memory, for simple sharing of data.

• Semaphores, for basic mutual exclusion and synchronization.

• Mutexes and condition variables for mutual exclusion and synchronization using POSIX interfaces.

• Message queues and pipes, for intertask message passing within a CPU.

• Sockets and remote procedure calls, for network-transparent intertask communication.

• Signals, for exception handling.

The optional products VxMP and VxFusion provide for intertask communication between multiple CPUs. See 11. Shared-Memory Objects and 10. Distributed Message Queues.

The most obvious way for tasks to communicate is by accessing shared data structures. Because all tasks in VxWorks exist in a single linear address space, sharing data structures between tasks is trivial; see Figure 2-8. Global variables, linear buffers, ring buffers, linked lists, and pointers can be referenced directly by code running in different contexts.

While a shared address space simplifies exchange of data, interlocking access to memory is crucial to avoid contention. Many methods exist for obtaining exclusive access to resources, and vary only in the scope of the exclusion. Such methods include disabling interrupts, disabling preemption, and resource locking with semaphores.

For information about POSIX mutexes, see 3.7 POSIX Mutexes and Condition Variables.

The most powerful method available for mutual exclusion is the disabling of interrupts. Such a lock guarantees exclusive access to the CPU:

funcA () 
    { 
    int lock = intLock(); 
    . 
    .   /* critical region of code that cannot be interrupted */ 
    . 
    intUnlock (lock); 
    }

While this solves problems involving mutual exclusion with ISRs, it is inappropriate as a general-purpose mutual-exclusion method for most real-time systems, because it prevents the system from responding to external events for the duration of these locks. Interrupt latency is unacceptable whenever an immediate response to an external event is required. However, interrupt locking can sometimes be necessary where mutual exclusion involves ISRs. In any situation, keep the duration of interrupt lockouts short.

Disabling preemption offers a somewhat less restrictive form of mutual exclusion. While no other task is allowed to preempt the current executing task, ISRs are able to execute:

funcA () 
    { 
    taskLock (); 
    . 
    .  /* critical region of code that cannot be interrupted */ 
    . 
    taskUnlock (); 
    }

However, this method can lead to unacceptable real-time response. Tasks of higher priority are unable to execute until the locking task leaves the critical region, even though the higher-priority task is not itself involved with the critical region. While this kind of mutual exclusion is simple, if you use it, make sure to keep the duration short. A better mechanism is provided by semaphores, discussed in 2.3.3 Semaphores.

VxWorks semaphores are highly optimized and provide the fastest intertask communication mechanism in VxWorks. Semaphores are the primary means for addressing the requirements of both mutual exclusion and task synchronization, as described below:

• For mutual exclusion semaphores interlock access to shared resources. They provide mutual exclusion with finer granularity than either interrupt disabling or preemptive locks, discussed in 2.3.2 Mutual Exclusion.

• For synchronization semaphores coordinate a task's execution with external events.

There are three types of Wind semaphores, optimized to address different classes of problems:

The fastest, most general-purpose semaphore. Optimized for synchronization or mutual exclusion.

A special binary semaphore optimized for problems inherent in mutual exclusion: priority inheritance, deletion safety, and recursion.

Like the binary semaphore, but keeps track of the number of times a semaphore is given. Optimized for guarding multiple instances of a resource.

VxWorks provides not only the Wind semaphores, designed expressly for VxWorks, but also POSIX semaphores, designed for portability. An alternate semaphore library provides the POSIX-compatible semaphore interface; see 3.6 POSIX Semaphores.

The semaphores described here are for use on a single CPU. The optional product VxMP provides semaphores that can be used across processors; see 11. Shared-Memory Objects.

Instead of defining a full set of semaphore control routines for each type of semaphore, the Wind semaphores provide a single uniform interface for semaphore control. Only the creation routines are specific to the semaphore type. Table 2-12 lists the semaphore control routines.

The semBCreate( ), semMCreate( ), and semCCreate( ) routines return a semaphore ID that serves as a handle on the semaphore during subsequent use by the other semaphore-control routines. When a semaphore is created, the queue type is specified. Tasks pending on a semaphore can be queued in priority order (SEM_Q_PRIORITY) or in first-in first-out order (SEM_Q_FIFO).

The general-purpose binary semaphore is capable of addressing the requirements of both forms of task coordination: mutual exclusion and synchronization. The binary semaphore has the least overhead associated with it, making it particularly applicable to high-performance requirements. The mutual-exclusion semaphore described in Mutual-Exclusion Semaphores is also a binary semaphore, but it has been optimized to address problems inherent to mutual exclusion. Alternatively, the binary semaphore can be used for mutual exclusion if the advanced features of the mutual-exclusion semaphore are deemed unnecessary.

A binary semaphore can be viewed as a flag that is available (full) or unavailable (empty). When a task takes a binary semaphore, with semTake( ), the outcome depends on whether the semaphore is available (full) or unavailable (empty) at the time of the call; see Figure 2-9. If the semaphore is available (full), the semaphore becomes unavailable (empty) and the task continues executing immediately. If the semaphore is unavailable (empty), the task is put on a queue of blocked tasks and enters a state of pending on the availability of the semaphore.

When a task gives a binary semaphore, using semGive( ), the outcome also depends on whether the semaphore is available (full) or unavailable (empty) at the time of the call; see Figure 2-10. If the semaphore is already available (full), giving the semaphore has no effect at all. If the semaphore is unavailable (empty) and no task is waiting to take it, then the semaphore becomes available (full). If the semaphore is unavailable (empty) and one or more tasks are pending on its availability, then the first task in the queue of blocked tasks is unblocked, and the semaphore is left unavailable (empty).

The mutual-exclusion semaphore is a specialized binary semaphore designed to address issues inherent in mutual exclusion, including priority inversion, deletion safety, and recursive access to resources.

The fundamental behavior of the mutual-exclusion semaphore is identical to the binary semaphore, with the following exceptions:

• It can be used only for mutual exclusion.

• It can be given only by the task that took it.

• It cannot be given from an ISR.

• The semFlush( ) operation is illegal.

Priority inversion arises when a higher-priority task is forced to wait an indefinite period of time for a lower-priority task to complete. Consider the scenario in Figure 2-11: t1, t2, and t3 are tasks of high, medium, and low priority, respectively. t3 has acquired some resource by taking its associated binary guard semaphore. When t1 preempts t3 and contends for the resource by taking the same semaphore, it becomes blocked. If we could be assured that t1 would be blocked no longer than the time it normally takes t3 to finish with the resource, there would be no problem because the resource cannot be preempted. However, the low-priority task is vulnerable to preemption by medium-priority tasks (like t2), which could inhibit t3 from relinquishing the resource. This condition could persist, blocking t1 for an indefinite period of time.

The mutual-exclusion semaphore has the option SEM_INVERSION_SAFE, which enables a priority-inheritance algorithm. The priority-inheritance protocol assures that a task that holds a resource executes at the priority of the highest-priority task blocked on that resource. Once the task priority has been elevated, it remains at the higher level until all mutual-exclusion semaphores that the task holds are released; then the task returns to its normal, or standard, priority. Hence, the "inheriting" task is protected from preemption by any intermediate-priority tasks. This option must be used in conjunction with a priority queue (SEM_Q_PRIORITY).

In Figure 2-12, priority inheritance solves the problem of priority inversion by elevating the priority of t3 to the priority of t1 during the time t1 is blocked on the semaphore. This protects t3, and indirectly t1, from preemption by t2.

The following example creates a mutual-exclusion semaphore that uses the priority inheritance algorithm:

semId = semMCreate (SEM_Q_PRIORITY | SEM_INVERSION_SAFE);

Counting semaphores are another means to implement task synchronization and mutual exclusion. The counting semaphore works like the binary semaphore except that it keeps track of the number of times a semaphore is given. Every time a semaphore is given, the count is incremented; every time a semaphore is taken, the count is decremented. When the count reaches zero, a task that tries to take the semaphore is blocked. As with the binary semaphore, if a semaphore is given and a task is blocked, it becomes unblocked. However, unlike the binary semaphore, if a semaphore is given and no tasks are blocked, then the count is incremented. This means that a semaphore that is given twice can be taken twice without blocking. Table 2-13 shows an example time sequence of tasks taking and giving a counting semaphore that was initialized to a count of 3.

Counting semaphores are useful for guarding multiple copies of resources. For example, the use of five tape drives might be coordinated using a counting semaphore with an initial count of 5, or a ring buffer with 256 entries might be implemented using a counting semaphore with an initial count of 256. The initial count is specified as an argument to the semCCreate( ) routine.

The uniform Wind semaphore interface includes two special options. These options are not available for the POSIX-compatible semaphores described in 3.6 POSIX Semaphores.

Priority ordering better preserves the intended priority structure of the system at the expense of some overhead in semTake( ) in sorting the tasks by priority. A FIFO queue requires no priority sorting overhead and leads to constant-time performance. The selection of queue type is specified during semaphore creation with semBCreate( ), semMCreate( ), or semCCreate( ). Semaphores using the priority inheritance option (SEM_INVERSION_SAFE) must select priority-order queuing.

This section describes using VxWorks events with semaphores. You can also use VxWorks events with other VxWorks objects. For more information, see 2.4 VxWorks Events.

Modern real-time applications are constructed as a set of independent but cooperating tasks. While semaphores provide a high-speed mechanism for the synchronization and interlocking of tasks, often a higher-level mechanism is necessary to allow cooperating tasks to communicate with each other. In VxWorks, the primary intertask communication mechanism within a single CPU is message queues. (The VxWorks distributed message queue component provides for sharing message queues between processors across any transport media; see 10. Distributed Message Queues).

Message queues allow a variable number of messages, each of variable length, to be queued. Tasks and ISRs can send messages to a message queue, and tasks can receive messages from a message queue.

Multiple tasks can send to and receive from the same message queue. Full-duplex communication between two tasks generally requires two message queues, one for each direction; see Figure 2-14.

There are two message-queue subroutine libraries in VxWorks. The first of these, msgQLib, provides Wind message queues, designed expressly for VxWorks; the second, mqPxLib, is compatible with the POSIX standard (1003.1b) for real-time extensions. See 3.5.1 Comparison of POSIX and Wind Scheduling for a discussion of the differences between the two message-queue designs.

Wind message queues are created, used, and deleted with the routines shown in Table 2-14. This library provides messages that are queued in FIFO order, with a single exception: there are two priority levels, and messages marked as high priority are attached to the head of the queue.

A message queue is created with msgQCreate( ). Its parameters specify the maximum number of messages that can be queued in the message queue and the maximum length in bytes of each message. Enough buffer space is allocated for the specified number and length of messages.

A task or ISR sends a message to a message queue with msgQSend( ). If no tasks are waiting for messages on that queue, the message is added to the queue's buffer of messages. If any tasks are already waiting for a message from that message queue, the message is immediately delivered to the first waiting task.

A task receives a message from a message queue with msgQReceive( ). If messages are already available in the message queue's buffer, the first message is immediately dequeued and returned to the caller. If no messages are available, then the calling task blocks and is added to a queue of tasks waiting for messages. This queue of waiting tasks can be ordered either by task priority or FIFO, as specified in an option parameter when the queue is created.

The VxWorks show( ) command produces a display of the key message queue attributes, for either kind of message queue. For example, if myMsgQId is a Wind message queue, the output is sent to the standard output device, and looks like the following:

-> show myMsgQId 
Message Queue Id  : 0x3adaf0  
Task Queuing      : FIFO  
Message Byte Len  : 4  
Messages Max      : 30  
Messages Queued   : 14 
Receivers Blocked : 0  
Send timeouts     : 0  
Receive timeouts    : 0 

Real-time systems are often structured using a client-server model of tasks. In this model, server tasks accept requests from client tasks to perform some service, and usually return a reply. The requests and replies are usually made in the form of intertask messages. In VxWorks, message queues or pipes (see 2.3.5 Pipes) are a natural way to implement this.

For example, client-server communications might be implemented as shown in Figure 2-15. Each server task creates a message queue to receive request messages from clients. Each client task creates a message queue to receive reply messages from servers. Each request message includes a field containing the msgQId of the client's reply message queue. A server task's "main loop" consists of reading request messages from its request message queue, performing the request, and sending a reply to the client's reply message queue.

The same architecture can be achieved with pipes instead of message queues, or by other means that are tailored to the needs of the particular application.

This section describes using VxWorks events with message queues. You can also use VxWorks events with other VxWorks objects. For more information, see 2.4 VxWorks Events.

Pipes provide an alternative interface to the message queue facility that goes through the VxWorks I/O system. Pipes are virtual I/O devices managed by the driver pipeDrv. The routine pipeDevCreate( ) creates a pipe device and the underlying message queue associated with that pipe. The call specifies the name of the created pipe, the maximum number of messages that can be queued to it, and the maximum length of each message:

status = pipeDevCreate ("/pipe/name", max_msgs, max_length);

The created pipe is a normally named I/O device. Tasks can use the standard I/O routines to open, read, and write pipes, and invoke ioctl routines. As they do with other I/O devices, tasks block when they read from an empty pipe until data is available, and block when they write to a full pipe until there is space available. Like message queues, ISRs can write to a pipe, but cannot read from a pipe.

As I/O devices, pipes provide one important feature that message queues cannot--the ability to be used with select( ). This routine allows a task to wait for data to be available on any of a set of I/O devices. The select( ) routine also works with other asynchronous I/O devices including network sockets and serial devices. Thus, by using select( ), a task can wait for data on a combination of several pipes, sockets, and serial devices; see 4.3.8 Pending on Multiple File Descriptors: The Select Facility.

Pipes allow you to implement a client-server model of intertask communications; see Servers and Clients with Message Queues.

In VxWorks, the basis of intertask communications across the network is sockets. A socket is an endpoint for communications between tasks; data is sent from one socket to another. When you create a socket, you specify the Internet communications protocol that is to transmit the data. VxWorks supports the Internet protocols TCP and UDP. VxWorks socket facilities are source compatible with BSD 4.4 UNIX.

TCP provides reliable, guaranteed, two-way transmission of data with stream sockets. In a stream-socket communication, two sockets are "connected," allowing a reliable byte-stream to flow between them in each direction as in a circuit. For this reason, TCP is often referred to as a virtual circuit protocol.

UDP provides a simpler but less robust form of communication. In UDP communications, data is sent between sockets in separate, unconnected, individually addressed packets called datagrams. A process creates a datagram socket and binds it to a particular port. There is no notion of a UDP "connection." Any UDP socket, on any host in the network, can send messages to any other UDP socket by specifying its Internet address and port number.

One of the biggest advantages of socket communications is that it is "homogeneous." Socket communications among processes are exactly the same regardless of the location of the processes in the network, or the operating system under which they are running. Processes can communicate within a single CPU, across a backplane, across an Ethernet, or across any connected combination of networks. Socket communications can occur between VxWorks tasks and host system processes in any combination. In all cases, the communications look identical to the application, except, of course, for their speed.

For more information, see VxWorks Network Programmer's Guide: Networking APIs and the reference entry for sockLib.

Remote Procedure Calls (RPC) is a facility that allows a process on one machine to call a procedure that is executed by another process on either the same machine or a remote machine. Internally, RPC uses sockets as the underlying communication mechanism. Thus with RPC, VxWorks tasks and host system processes can invoke routines that execute on other VxWorks or host machines, in any combination.

As discussed in the previous sections on message queues and pipes, many real-time systems are structured with a client-server model of tasks. In this model, client tasks request services of server tasks, and then wait for their reply. RPC formalizes this model and provides a standard protocol for passing requests and returning replies. Also, RPC includes tools to help generate the client interface routines and the server skeleton.

For more information about RPC, see VxWorks Network Programmer's Guide: RPC, Remote Procedure Calls.

VxWorks supports a software signal facility. Signals asynchronously alter the control flow of a task. Any task or ISR can raise a signal for a particular task. The task being signaled immediately suspends its current thread of execution and executes the task-specified signal handler routine the next time it is scheduled to run. The signal handler executes in the receiving task's context and makes use of that task's stack. The signal handler is invoked even if the task is blocked.

Signals are more appropriate for error and exception handling than as a general-purpose intertask communication mechanism. In general, signal handlers should be treated like ISRs; no routine should be called from a signal handler that might cause the handler to block. Because signals are asynchronous, it is difficult to predict which resources might be unavailable when a particular signal is raised. To be perfectly safe, call only those routines that can safely be called from an ISR (see Table 2-21). Deviate from this practice only when you are sure your signal handler cannot create a deadlock situation.

The wind kernel supports two types of signal interface: UNIX BSD-style signals and POSIX-compatible signals. The POSIX-compatible signal interface, in turn, includes both the fundamental signaling interface specified in the POSIX standard 1003.1, and the queued-signals extension from POSIX 1003.1b. For more information, see 3.9 POSIX Queued Signals. For the sake of simplicity, we recommend that you use only one interface type in a given application, rather than mixing routines from different interfaces.

For more information about signals, see the reference entry for sigLib.

By default, VxWorks uses the basic signal facility component INCLUDE_SIGNALS. This component automatically initializes signals with sigInit( ). Table 2-15 shows the basic signal routines.

The colorful name kill( )harks back to the origin of these interfaces in UNIX BSD. Although the interfaces vary, the functionality of BSD-style signals and basic POSIX signals is similar.

In many ways, signals are analogous to hardware interrupts. The basic signal facility provides a set of 31 distinct signals. A signal handler binds to a particular signal with sigvec( ) or sigaction( ) in much the same way that an ISR is connected to an interrupt vector with intConnect( ). A signal can be asserted by calling kill( ). This is analogous to the occurrence of an interrupt. The routines sigsetmask( ) and sigblock( ) or sigprocmask( ) let signals be selectively inhibited.

Certain signals are associated with hardware exceptions. For example, bus errors, illegal instructions, and floating-point exceptions raise specific signals.

The basic signal facility is included in VxWorks by default with INCLUDE_SIGNALS component.

VxWorks events introduce functionality similar to pSOS events into VxWorks 5.5. VxWorks events are included in the standard VxWorks facilities and are used to port pSOS events functionality to VxWorks. This section provides a brief summary of VxWorks events; then it describes pSOS events and VxWorks events in detail, comparing them and their APIs.

This section describes the functionality of pSOS events. This functionality provides the basis of VxWorks events, but does not fully describe their behavior. For details, see VxWorks Enhancements to pSOS Events.

In the pSOS operating system, events can be sent from a resource to a task, from an ISR to a task, or directly between two tasks. Tasks, ISRs, and resources all use the same ev_send( ) API to send events.

For a task to receive events from a resource, the task must register with that resource and request it to send a specific set of events when it becomes free. The resource is either a semaphore or a message queue. When the resource becomes free, it sends the set of events to the registered task. This task may, or may not be, waiting for the events.

As mentioned above, a task can also receive events from another task. For example, if two tasks agree to send events between them, taskA could send taskB a specific events set when it (taskA) finishes executing, to let taskB know that this has occurred. As with events sent from a resource, the receiving task may, or may not be, waiting for the events.

A task can wait for multiple events from one or more sources. Each source can send multiple events, and a task can also wait to receive only one event, or all events. For example, a task may be waiting for events 1 to 10, where 1 to 4 come from a semaphore, 5 to 6 come from a message queue, and 7 to 10 come from another task.

A task can also specify a timeout when waiting for events.

Only one task can register itself to receive events from a resource. If another task subsequently registers with the same resource, the previously registered task is automatically unregistered, without its knowledge. This behavior differs in VxWorks events. For details, see VxWorks Enhancements to pSOS Events.

When a task registers with a resource, events are not sent immediately, even if the resource is free at the time of registration. The events are sent the next time the resource becomes free. For example, a semaphore will send events the next time it is given, as long as no task is waiting for it. (Being given does not always mean that a resource is free; see Freeing Resources). This behavior is configurable for VxWorks events. For details, see VxWorks Enhancements to pSOS Events.

When a resource sends events to a task to indicate that it is free, it does not mean that resource is reserved. Therefore, a task waiting for events from a resource will unpend when the resource becomes free, however the resource may be taken in the meantime. There are no guarantees that the resource will still be available, if the task subsequently attempts to take ownership of it.

As mentioned above, a resource only sends events when it becomes free. This is not synonymous with being released. To clarify, if a semaphore is given, it is actually being released. However, it is not considered free if another task is waiting for it at the time it is released. Therefore, in cases where two or more tasks are constantly exchanging ownership of a resource, that resource never becomes free; thus, it may never send events.

The pSOS events API routines are listed in Table 2-16:   

The implementation of VxWorks events is based on the way pSOS events work. This section first clarifies some of the crucial terms used to discuss VxWorks events. Then it describes VxWorks events in more detail, comparing their functionality to that of pSOS events.

A key concept in understanding events sent by resources, is that resources send events when they become free. Thus, it is crucial to define what it means for a resource to be free for VxWorks events.

A mutex semaphore is considered free when it no longer has an owner and no one is pending on it. For example, following a call to semGive( ), the semaphore will not send events if another task is pending on a semTake( ) for the same semaphore.

A binary semaphore is considered free when no task owns it and no one is waiting for it.

A counting semaphore is considered free when its count is nonzero and no one is pending on it. Thus, events cannot be used as a mechanism to compute the number of times a semaphore is released or given.

A message queue is considered free when a message is present in the queue and no one is pending for the arrival of a message in that queue. Thus, events cannot be used as a mechanism to compute the number of messages sent to a message queue.

When VxWorks events were implemented, some enhancements were made to the basic pSOS functionality. This section describes those enhancements and configuration options, and compares the resulting behavior of VxWorks events with pSOS events.

• SIngle Task Resource Registration.  

As mentioned in 2.4.1 pSOS Events, under pSOS, when a task registers with a resource to send pSOS events, it can inadvertently deregister another task that had previously registered with the resource. This prevents the first task from receiving events from the resource with which it registered. Consequently, the task that first registered with the resource could stay in a pend state indefinitely.

In order to solve this problem, VxWorks events provide an option whereby the second task is not allowed to register with the resource, if another task is already registered with it. If a second task tries to register with the resource, an error is returned. In VxWorks, you can configure the registration mechanism to use either the VxWorks or the pSOS behavior.

• Option for Immediate Send.  

As mentioned in Registering for Events, when a pSOS task registers with a resource, the resource does not send events to the task immediately, even if it is free at the time of registration. For VxWorks events, the default behavior is the same. However, VxWorks events provide an option that allows a task, at the time of registration, to request that the resource send the events immediately, if the resource is free at the time of registration.

• Option for Automatic Unregister.  

There are situations in which a task may want to receive events from a resource only once, and then unregister. The pSOS implementation requires a task to explicitly unregister after having received events from the resource. The VxWorks implementation provides an option whereby a registering task can tell the resource to only send events once, and automatically unregister the task when this occurs.

• Automatic Unpend upon Resource Deletion.  

When a resource (a semaphore or message queue) is deleted, the semDelete( ) and msgQDelete( ) implementation unpends any task. This prevents the task from pending indefinitely, while waiting for events from the resource being deleted. The pending task then resumes execution, and receives an ERROR return value from the eventReceive( ) call that caused the task to pend. See also, Existing VxWorks API and Existing VxWorks API.

Each task has its own events field or container, referred to as the task events register. The task events register is a per task 32-bit field used to store the events that a task receives from resources, ISRs, and other tasks.

You do not access the task events register directly. Tasks, ISRs, and resources fill the events register of a particular task by sending events to that task. A task can also send itself events, thereby filling its own events register. Events 25 to 32 (VXEV25 or 0x01000000 to VXEV32 or 0x80000000) are reserved for system use only, and are not available to VxWorks users. Table 2-17 describes the routines that affect the contents of the events register.

For details on the API for VxWorks events, see the reference entries for eventLib, semEvLib, and msgQEvLib.

For the purpose of debugging systems that make use of events, the taskShow, semShow, and msgQShow libraries display event information.

The taskShow library displays the following information:

• the contents of the event register

• the desired events

• the options specified when eventReceive( ) was called

The semShow( ) and msgQShow( ) libraries display the following information:

• the task registered to receive events

• the events the resource is meant to send to that task

• the options passed to semEvStart( ) or msgQEvStart( )

The VxWorks events API has made modifications to the pSOS events API for the purpose of better describing the action of the routines. The pSOS API uses a family of notify routines for registering and unregistering from a resource. However, these names do not correctly reflect the action of resources, which is to either send, or not send, events. Thus, the VxWorks API more precisely describes the request for a resource to start sending events and to stop sending events to a task. This implementation uses the semEvStart( ) and msgQEvStart( ) routines to tell resources to start sending events, and the semEvStop( ) and msgQEvStop( ) routines to tell a resource to stop sending events.

Table 2-18 compares the similarities and differences between the VxWorks and pSOS events API:

VxWorks includes a watchdog-timer mechanism that allows any C function to be connected to a specified time delay. Watchdog timers are maintained as part of the system clock ISR. For information about POSIX timers, see 3.2 POSIX Clocks and Timers.

Functions invoked by watchdog timers execute as interrupt service code at the interrupt level of the system clock. However, if the kernel is unable to execute the function immediately for any reason (such as a previous interrupt or kernel state), the function is placed on the tExcTask work queue. Functions on the tExcTask work queue execute at the priority level of the tExcTask (usually 0).

Restrictions on ISRs apply to routines connected to watchdog timers. The functions in Table 2-19 are provided by the wdLib library.

A watchdog timer is first created by calling wdCreate( ). Then the timer can be started by calling wdStart( ), which takes as arguments the number of ticks to delay, the C function to call, and an argument to be passed to that function. After the specified number of ticks have elapsed, the function is called with the specified argument. The watchdog timer can be canceled any time before the delay has elapsed by calling wdCancel( ).

Hardware interrupt handling is of key significance in real-time systems, because it is usually through interrupts that the system is informed of external events. For the fastest possible response to interrupts, VxWorks runs interrupt service routines (ISRs) in a special context outside of any task's context. Thus, interrupt handling involves no task context switch. Table 2-20 lists the interrupt routines provided in intLib and intArchLib.

For boards with an MMU, the optional product VxVMI provides write protection for the interrupt vector table; see 12. Virtual Memory Interface.

You can use system hardware interrupts other than those used by VxWorks. VxWorks provides the routine intConnect( ), which allows C functions to be connected to any interrupt. The arguments to this routine are the byte offset of the interrupt vector to connect to, the address of the C function to be connected, and an argument to pass to the function. When an interrupt occurs with a vector established in this way, the connected C function is called at interrupt level with the specified argument. When the interrupt handling is finished, the connected function returns. A routine connected to an interrupt in this way is called an interrupt service routine (ISR).

Interrupts cannot actually vector directly to C functions. Instead, intConnect( ) builds a small amount of code that saves the necessary registers, sets up a stack entry (either on a special interrupt stack, or on the current task's stack) with the argument to be passed, and calls the connected function. On return from the function it restores the registers and stack, and exits the interrupt; see Figure 2-16.

For target boards with VME backplanes, the BSP provides two standard routines for controlling VME bus interrupts, sysIntEnable( ) and sysIntDisable( ).

All ISRs use the same interrupt stack. This stack is allocated and initialized by the system at start-up according to specified configuration parameters. It must be large enough to handle the worst possible combination of nested interrupts.

Some architectures, however, do not permit using a separate interrupt stack. On such architectures, ISRs use the stack of the interrupted task. If you have such an architecture, you must create tasks with enough stack space to handle the worst possible combination of nested interrupts and the worst possible combination of ordinary nested calls. See the reference entry for your BSP to determine whether your architecture supports a separate interrupt stack.

Use the checkStack( ) facility during development to see how close your tasks and ISRs have come to exhausting the available stack space.

There are some restrictions on the routines you can call from an ISR. For example, you cannot use routines like printf( ), malloc( ), and semTake( ) in your ISR. You can, however, use semGive( ), logMsg( ), msgQSend( ), and bcopy( ). For more information, see 2.6.4 Special Limitations of ISRs.

Many VxWorks facilities are available to ISRs, but there are some important limitations. These limitations stem from the fact that an ISR does not run in a regular task context and has no task control block, so all ISRs share a single stack.

For this reason, the basic restriction on ISRs is that they must not invoke routines that might cause the caller to block. For example, they must not try to take a semaphore, because if the semaphore is unavailable, the kernel tries to switch the caller to the pended state. However, ISRs can give semaphores, releasing any tasks waiting on them.

Because the memory facilities malloc( ) and free( ) take a semaphore, they cannot be called by ISRs, and neither can routines that make calls to malloc( ) and free( ). For example, ISRs cannot call any creation or deletion routines.

ISRs also must not perform I/O through VxWorks drivers. Although there are no inherent restrictions in the I/O system, most device drivers require a task context because they might block the caller to wait for the device. An important exception is the VxWorks pipe driver, which is designed to permit writes by ISRs.

VxWorks supplies a logging facility, in which a logging task prints text messages to the system console. This mechanism was specifically designed for ISR use, and is the most common way to print messages from ISRs. For more information, see the reference entry for logLib.

An ISR also must not call routines that use a floating-point coprocessor. In VxWorks, the interrupt driver code created by intConnect( ) does not save and restore floating-point registers; thus, ISRs must not include floating-point instructions. If an ISR requires floating-point instructions, it must explicitly save and restore the registers of the floating-point coprocessor using routines in fppArchLib.

All VxWorks utility libraries, such as the linked-list and ring-buffer libraries, can be used by ISRs. As discussed earlier (2.2.6 Task Error Status: errno), the global variable errno is saved and restored as a part of the interrupt enter and exit code generated by the intConnect( ) facility. Thus, errno can be referenced and modified by ISRs as in any other code. Table 2-21 lists routines that can be called from ISRs.

When a task causes a hardware exception such as an illegal instruction or bus error, the task is suspended and the rest of the system continues uninterrupted. However, when an ISR causes such an exception, there is no safe recourse for the system to handle the exception. The ISR has no context that can be suspended. Instead, VxWorks stores the description of the exception in a special location in low memory and executes a system restart.

The VxWorks boot programs test for the presence of the exception description in low memory and if it is detected, display it on the system console. The e command in the boot ROMs re-displays the exception description; see Tornado User's Guide: Setup and Startup.

One example of such an exception is the following message:

workQPanic: Kernel work queue overflow.

This exception usually occurs when kernel calls are made from interrupt level at a very high rate. It generally indicates a problem with clearing the interrupt signal or a similar driver problem.

The VxWorks interrupt support described earlier in this section is acceptable for most applications. However, on occasion, low-level control is required for events such as critical motion control or system failure response. In such cases it is desirable to reserve the highest interrupt levels to ensure zero-latency response to these events. To achieve zero-latency response, VxWorks provides the routine intLockLevelSet( ), which sets the system-wide interrupt-lockout level to the specified level. If you do not specify a level, the default is the highest level supported by the processor architecture. For information about architecture-specific implementations of intLockLevelSet( ), see the appropriate VxWorks architecture supplement.

ISRs connected to interrupt levels that are not locked out (either an interrupt level higher than that set by intLockLevelSet( ), or an interrupt level defined in hardware as non-maskable) have special restrictions:

• The ISR can be connected only with intVecSet( ).

• The ISR cannot use any VxWorks operating system facilities that depend on interrupt locks for correct operation. The effective result is that the ISR cannot safely make any call to any VxWorks function, except reboot.

For more information, see the VxWorks architecture supplement document for the architecture in question.

While it is important that VxWorks support direct connection of ISRs that run at interrupt level, interrupt events usually propagate to task-level code. Many VxWorks facilities are not available to interrupt-level code, including I/O to any device other than pipes. The following techniques can be used to communicate from ISRs to task-level code:

• Shared Memory and Ring Buffers.  

ISRs can share variables, buffers, and ring buffers with task-level code.

• Semaphores.  

ISRs can give semaphores (except for mutual-exclusion semaphores and VxMP shared semaphores) that tasks can take and wait for.

• Message Queues.  

ISRs can send messages to message queues for tasks to receive (except for shared message queues using VxMP). If the queue is full, the message is discarded.

• Pipes.  

ISRs can write messages to pipes that tasks can read. Tasks and ISRs can write to the same pipes. However, if the pipe is full, the message written is discarded because the ISR cannot block. ISRs must not invoke any I/O routine on pipes other than write( ).

• Signals.  

ISRs can "signal" tasks, causing asynchronous scheduling of their signal handlers.