---

GLAST/LAT > DAQ and FSW > FSW > Doxygen Index > PBS / V2-10-5

Constituent: pbs     Tag: linux-gcc

---

         

---

SPIN.h File Reference

Spin the CPU for a well-defined period of time, callable version. More...

#include "PBS/SPIN_time.h"

Include dependency graph for SPIN.h:

This graph shows which files directly or indirectly include this file:

Functions
unsigned int	SPIN_nsecs_to_ptus (unsigned int nsecs)
	Converts a number of nanoseconds to PTUs.
unsigned int	SPIN_ptus_to_nsecs (unsigned int ptus)
SPIN_time	SPIN_curtime (void)
	Returns the current time in units of PTUs.
int	SPIN_check (SPIN_time begin_ptu, unsigned int ptusToWait)
	Checks whether the requested amount of time has elapsed. is that this routine is used in a polling mode.
int	SPIN_wait (SPIN_time begin_ptu, unsigned int ptusToWait)
	Allows one to wait a specified time period after a start time.
int	SPIN_spin (unsigned int ptuToSpin)
	Places the CPU into a spin loop until the specified number of PTUs has elapsed.

---

Detailed Description

Spin the CPU for a well-defined period of time, callable version.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: SPIN.h,v 1.2 2003/08/20 17:37:02 russell Exp $

SYNOPSIS

Provides the generic interface definitions of the SPIN utility. This utility implements timed spin loops with a specified resolution of nanoseconds. Note that this is the resolution but NOT the accuracy. The accuracy and precision will vary depending on the platform. The implementation method of choice is to use a local high resolution timer when available.

These routines are useful when one needs to wait a very short amount of time for some operation to complete. Here short means short compared to the overhead of using an TIMER interrupt routine to do the same job.

The units of time are always in the processors native time units (PTUs). This varies platform to platform. For example, PPC implementations have resolutions in the range 50-100nsecs, Sun's are around 60nsecs and Linux around 10msecs.

This implementation is the standard function call interface. See SPIN.ih for an inline version of these same routines. Given that one is generally spinning for a very short period of time, the increased efficiency and, perhaps, more importantly, the better the minimum time that one can wait, the inlines may be more appropriate.

USAGE

General usage would be to use SPIN_nsecs_to_ptus() to convert the number of nanoseconds to the number of processor timer unit (that's what the ptu stands for, Processor Timer Units) counts. This number would then be used as the argument to SPIN_spin() which would spin wait for the specified time. Because tasks may be preemptied by higher priority goings-on, one can only guarantee that the elapsed time is greater than or equal to the requested time. T herefore, SPIN_spin() returns the overrun, ie how long past the requested expiration time the SPIN lasted.

EXAMPLE

    / * Convert 2 usec to local units * /
    ptus = SPIN_nsecs_to_ptus (2000);

    / * Load a register every 2 usecs * /
    while (--nbytes >= 0)
    {
        load_register (REG, value);
        SPIN_spin (ptus);
    }

LIMITATIONS

Due to arthimetic reasons, the amount of time one can spin is limited to about 2**31 nanoseconds or about 2 seconds. In practice this should not be a problem. The WakeUp Timer facility, WUT, is a much better choice if one wishes to mark off times greater than around ~25 microseconds.

---

Function Documentation

int SPIN_check (  SPIN_time  begin_ptu, unsigned int  ptus )

Checks whether the requested amount of time has elapsed. is that this routine is used in a polling mode. Parameters: begin_ptu  The start time ptus  The number of PTUs to wait Returns: See SPIN_spin(). The difference here is that this routine can return a negative number, indicating the number of PTUs until expiration time. This is a polling version of SPIN_wait(). Whereas in SPIN_wait(), control does not return from until the requested amount of time has elapsed, this routine returns immediately with the amount of time till expiration. Using this routine, the caller can check, without blocking, if the specified amount of time has passed. Note that in order to keep the interpretation of the return value uniform over the SPIN routines, the amount of time till expiration is returned as a negative number. A positive number indicates the amount of time past the expiration time.

SPIN_time SPIN_curtime (  void   )

Returns the current time in units of PTUs. Return values: The  current time in units of PTUs. This gets the current time. For performance reasons, the units are in PTUs and the range is generally limited to 32 bits, although this is a platform dependent statement. The customary use of this routine is to strobe the starting time, then use the return value along with SPIN_check() or SPIN_wait() to allow a specified amount of time to elapsed from the starting time.

int SPIN_nsecs_to_ptus (  unsigned int  nsecs  )

Converts a number of nanoseconds to PTUs. Parameters: nsecs  The number of nanoseconds to convert to a PTUs Returns: The equivalent time in PTUs. This routine converts nanoseconds into Processor Timer Units. This is usually a one time call which must be made to convert the natural time units of nanoseconds to the units the SPIN routines work in.

unsigned int SPIN_ptus_to_nsecs (  unsigned int  ptus  )

Parameters: ptus  The number of PTUs to convert to nanoseconds Returns: The equivalent time in units of nanoseconds. This routine is the complement of the SPIN_nsecs_to_ptus(). It is useful only when converting the return value of the SPIN_spin routines back to physically meaningful units, ie nanaseconds. It certainly will not be as heavily used as SPIN_nsecs_to_ptus().

int SPIN_spin (  unsigned int  ptusToSpin  )

Places the CPU into a spin loop until the specified number of PTUs has elapsed. Parameters: ptusToSpin  The number of PTUs to spin. Returns: The number of PTUs past the expiration time. The CPU is placed into a tight loop, sampling an internal clock until the specified time has elapsed. Because of task switching or interrupt activity, the SPIN routines can only guarantee that at least the specified time has elapsed. Generally spin loops are rather loose in nature, so that the actual elapsed time is not critical. Nevertheless, the return value of this routine indicates how far past the expiration time the SPIN routine ran.

int SPIN_wait (  SPIN_time  begin_ptu, unsigned int  ptusToWait )

Allows one to wait a specified time period after a start time. Parameters: begin_ptu  The start time ptusToWait  The number of PTUs to wait Returns: See SPIN_spin(). This routine allows the user to spin for a specified amount of time after an arbitrary start time. It is similar to SPIN_spin(), but whereas SPIN_spin starts from the current time, SPIN_wait starts from an arbitrary time. Warning: Due to the split nature of the calls involved in SPIN_wait's usage, ie one call to get the start time and another call to do the wait, it is somewhat easier to exceed the range limitation. Due to arthimetic reasons, the range is limited to less than 2**31, or about 2 seconds. Do not split the call to get the start time, SPIN_curtime() and the SPIN_wait() with any code that code take significant amounts of time.

---