Creating a VxWorks Timestamp Driver

G.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.

Path Name Conventions

Tornado uses the same tree organization on Windows hosts and UNIX hosts. However, because UNIX and Windows use a different convention to separate directory segments in path names, any concrete examples of path names in this appendix cannot apply to both kinds of host. Because the UNIX convention matches the VxWorks convention, this appendix shows path names using UNIX separators. Whenever you see a path name of the following form in this manual, you can use the path directly on UNIX, but not on Windows:

dir/subdir/file

To obtain the corresponding path name on Windows, use \ (backslash) rather than / (slash) as the separator between segments. The following Windows path name corresponds to the example above:

dir\subdir\file

***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)