E

Creating a VxWorks Timestamp Driver

E.1 Introduction

Detailed monitoring of real-time application performance requires timing information based on high-resolution timers. You can extend the range of information available from VxWorks kernel instrumentation by supplying a timestamp driver. For example, if a timestamp driver is available, a precise chronology can be displayed by WindView, a graphical analysis tool for real-time and embedded systems based on VxWorks.

The timer is a hardware facility; a timestamp driver is a software interface to that facility. This appendix describes the standard interfaces for a VxWorks timestamp driver, and discusses the requirements for a hardware timer for use with VxWorks kernel instrumentation. It is not a step-by-step tutorial on the process of writing a timestamp driver.

This appendix is meant for the following readers:

VxWorks users who need to add a timestamp driver to an existing BSP.

VxWorks users who wish to use an existing VxWorks timestamp driver in their own applications.

This chapter assumes that the reader has a working knowledge of the target board hardware. No knowledge of the VxWorks kernel or of WindView is assumed, although experience writing device drivers is helpful.

E.2 Hardware Overview

This section discusses typical hardware timer modes of operation and characteristics. This section also defines the VxWorks requirements for timestamp drivers.

Modes of Operation

Most target boards have multiple hardware timers available for operating system and application use. The characteristics of timers vary widely due to evolving hardware technology. Generally, timers on older target boards are not as easy to work with as timers on newer, more refined hardware. However, many different types of timers are suitable for use with VxWorks.

In its most basic form (shown in Figure E-1), a timer is simply a timing source (that is, a clock) used as input to a counter. The counter counts up or down as the associated clock transitions.

Figure E-1: Basic Form of Timer

There are three common modes in which timers operate: periodic, one-shot, and timestamp. Many newer timers are versatile, and can be used in any one of these modes, depending on how they are configured. The characteristics of each mode are as follows:

Periodic Interrupt Timer

The timer counts up or down to a programmed value (called the terminal count), at which point it generates a hardware interrupt. The counter is reset (either by hardware or software), and begins to count up or down again towards the terminal count. The interrupt is the sole output of a periodic interrupt timer. After acknowledging the interrupt, an interrupt service routine (ISR) usually calls an operating system facility to log the interrupt as a clock tick. In some cases, the ISR calls an application-specific routine instead.

The terminal count may be adjusted so that an interrupt is generated at a specified time interval. For instance, if the terminal count is set such that an interrupt occurs every 10 msec, 100 ticks per second are generated (100Hz). The VxWorks system and auxiliary clocks use the underlying hardware timers in periodic interrupt mode.

One-Shot Timer

The timer counts up or down to a programmed terminal count, at which point it generates a hardware interrupt. The counter is then disabled (either by hardware or software). An ISR acknowledges the interrupt, and then calls a user-specified routine.

Currently, VxWorks does not provide a one-shot timer facility, although this type of timer may be simulated by having a periodic interrupt timer disable the counter in the ISR.

Timestamp Timer

The timer counts up or down to its maximum count (0 or 0xfff) at which point it generates a hardware interrupt. The counter rolls over and begins to count again towards the maximum value. After acknowledging the interrupt, an ISR calls an operating system facility or application-specific routine to log the counter rollover. At any time, the operating system or application may read the counter value to obtain high-resolution timing information in timestamp tick units.

This mode of operation differs from a periodic interrupt timer in that the counter is usually allowed to count to its maximum value (that is, the terminal count is set to 0 or 0xfff). Additionally, the counter value is the primary output of the timestamp timer, and the interrupt is only used to announce a counter rollover. Timestamp timer components are typically similar to Figure E-2.

Figure E-2: Components of a Timestamp Timer

The remainder of this document deals only with timers operating in timestamp mode.

Characteristics of Hardware Timers

Several factors determine how suitable a particular hardware timer may be for a timestamp driver. This information may help to choose an appropriate timer, if several are available.

Read While Enabled

The most important characteristic of a good timestamp timer is the ability to read the counter's value without having to stop the timer from counting. If the timer must be disabled to read the timestamp value accurately, the time spent without the timer running is not recorded, although the system is actually doing work and other timers are continuing to run (the system clock, for instance). This situation is commonly called time skew. As time skew accumulates, the timestamp values become more and more removed from the absolute time of the system, as kept by the system clock. Additionally, interrupts must be locked out while the timer is stopped. Both of these effects are detrimental to real-time systems.

Prescaler Counter

The input clock is often passed through a prescaler counter to divide the input clock frequency, thereby producing a lower frequency input for the timestamp counter. Although a prescaler is not always present (and need not be used) it can be a useful way of tuning timer devices that have an unusually high input clock frequency.

Counter Width

The timer's counter should be at least 16 bits wide, although a 24- or 32-bit counter is preferable. The wider a counter, the less often it must roll over, and therefore the less system overhead its ISR incurs. The input frequency can also be higher with a wide counter, which yields more accurate timing information.

Preload After Disable

Some timers require that the counter be preloaded with a value before counting resumes. This is an issue only for timers that cannot be read while enabled. This characteristic adds to the time spent with the timer disabled, thereby increasing time-skew problems. The preload mechanism itself provides a way to correct skew, but determining the amount of the correction is difficult; see the discussion of counter preloading in Working Around Deficiencies in Hardware Timers.

Cache Coherency

As with all hardware devices, the locations of timer device registers must be cache coherent. This ensures that reads and writes to timer registers are actually accessing the register locations themselves, and not CPU data cache locations. If data cache memory exists, and there is no hardware mechanism (such as an MMU) to guarantee data cache coherency for register locations, the timestamp timer driver must make explicit calls to flush and invalidate the CPU's data cache. This adds to the overhead of reading the timestamp tick value. For more information, see the VxWorks BSP Porting Kit: Cache and Virtual Memory Library Support.

VxWorks Requirements for Timestamp Timers

The VxWorks kernel instrumentation uses a timestamp timer, when available, to log timing information for selected operating system events--for example, semaphore gives and takes, task spawns and deletions, system clock ticks, and interrupts.

VxWorks requires that timestamp timers provide these features:

Rollover Interrupt

The timestamp timer must be able to generate a hardware interrupt once the maximum (or terminal) count is reached. An interrupt is needed to avoid aliasing, by announcing the rollover event. Without the interrupt, timestamps are ambiguous, since there is no way to distinguish two timestamps separated by the timer's period.

Fine Resolution

The timestamp tick resolution is calculated as follows:

To be effective, the resolution should be 10 usec or less (that is, a timestamp tick frequency of at least 100KHz). Although this is not a strict requirement, it is consistent with timing limitations within the VxWorks kernel. If the timestamp timer output is slower than 100KHz, some instrumented kernel events may not have distinguishable timing information.

Sizable Period

The time between timestamp rollovers is the timestamp timer's period. The period is defined as the product of the timer resolution and the timer's maximum count:

To be effective, the period should be at least 10 msec. If rollovers are more frequent, the overhead of servicing the rollover interrupt may be too intrusive. The greater the period, the better.

E.3 Timestamp Driver Interface

The timestamp timer interface is a non-standard device driver interface; it does not go through the VxWorks I/O system. Although the interface was developed for use with VxWorks kernel instrumentation, it is also useful as a general BSP facility. The timestamp driver's external interface is expected to change in the future, when a more generic, abstracted timer facility is adopted.

The following sections describe each procedure and its external interface. The descriptions are for a standard timestamp driver. Although the external functionality must remain as described here, procedure content may differ for a particular driver implementation.

NOTE: Remember that each routine must return the appropriate value, as described in the following sections. For example, sysTimestampEnable( ) must return OK if successful, or ERROR if not successful. OK and ERROR are defined in the VxWorks header file installDir/target/h/vxWorks.h.

sysTimestampConnect( )

This routine specifies the timestamp callback routine, a routine to be run each time the timestamp counter rolls over. If this facility is available, sysTimeStampConnect( ) must store the function pointer in the global variable sysTimestampRoutine and return OK, to indicate success.

If the callback cannot be provided, sysTimeStampConnect( ) returns ERROR to indicate that no callback routine is connected. In this situation, the VxWorks kernel instrumentation does not use the interrupt handler sysTimestampInt( ) as part of its timestamp timer implementation, but relies instead on the system clock tick to signal a timestamp reset event (see Using the VxWorks System Clock Timer). To use the timestamp driver in other applications, you must make similar provisions for an ERROR result.

NOTE: sysTimestampConnect( ) must not enable or disable the timestamp timer itself. Initialization must be done in the sysTimestampEnable( ) routine.

STATUS sysTimestampConnect 
    ( 
    FUNCPTR routine, 
    int arg 
    )

The arguments for this routine are:

routine

pointer to the function called at each timer rollover interrupt.

arg

argument for routine.

The result must be OK or ERROR.

sysTimestampEnable( )

If the timer is not already enabled, this routine performs all the necessary initialization for the timer (for example, connecting the interrupt vector, resetting registers, configuring for timestamp mode, and so on), and then enables the timestamp timer. If the timer is already enabled, this routine simply resets the timer counter value.

STATUS sysTimestampEnable (void)