SPIN.ih.lx-xxx-xxx File Reference

Implements the inline LINUX version of the SPIN routines. More...

#include <stdlib.h>
#include <time.h>
#include <PBS/impl/SPIN_time.h.lx-xxx-xxx>

Defines
#define	SPIN_PTUS_TO_NSECS(_ptus)   _ptus * SPIN_K_NSECS_PER_PTU;
	Converts a short range processor spin time to nanoseconds.
#define	SPIN_NSECS_TO_PTUS(_nsecs)   (_nsecs + SPIN_K_NSECS_PER_PTU - 1)/SPIN_K_NSECS_PER_PTU;
	Converts a short range nanoseconds to a processor spin time.
Functions
SPIN__EXP_FNC unsigned int	SPIN__nsecs_to_ptus (unsigned int nsecs)
	Converts a number of nanoseconds to PTUs.
SPIN__EXP_FNC unsigned int	SPIN__ptus_to_nsecs (unsigned int ptus)
SPIN__EXP_FNC SPIN_time	SPIN__curtime (void)
	Returns the current time in units of PTUs.
SPIN__EXP_FNC int	SPIN__wait (SPIN_time begin_ptu, unsigned int ptus)
	Allows one to wait a specified time period after a start time.

---

Detailed Description

Implements the inline LINUX version of the SPIN routines.

Author:

JJRussell - russell@slac.stanford.edu

    CVS $Id: SPIN.ih.lx-xxx-xxx,v 1.6 2011/03/24 23:05:45 apw Exp $

---

Define Documentation

#define SPIN_NSECS_TO_PTUS

(

_nsecs

)

(_nsecs + SPIN_K_NSECS_PER_PTU - 1)/SPIN_K_NSECS_PER_PTU;

Converts a short range nanoseconds to a processor spin time.

Parameters:

_nsecs

The short range time, in nanoseconds, to convert to a processor time.

Returns:

The processor time in ticks (32-bit result)

Note:

On some platforms, this macro merely calls SPIN__ptus_to_nsecs() will on other platforms this macro is called by SPIN__ptus_to_nsecs(). There is an advantage of always using the macro, however. On those platforms where the conversion factors are known at compile time, the conversion of a constant number of nsecs by this macro will be done at compile time.

Referenced by SPIN__nsecs_to_ptus().

#define SPIN_PTUS_TO_NSECS

(

_ptus

)

_ptus * SPIN_K_NSECS_PER_PTU;

Converts a short range processor spin time to nanoseconds.

Parameters:

_ptus

The short range processor spin time to convert.

Returns:

The processor spin time in nanoseconds (32-bit result)

This is macro most likely use is in converting the result a spin overrun back into nanoseconds.

Note:

On some platforms, this macro merely calls SPIN__ptus_to_nsecs() will on other platforms this macro is called by SPIN__ptus_to_nsecs(). There is an advantage of always using the macro, however. On those platforms where the conversion factors are known at compile time, the conversion of a constant number of ptus by this macro will be done at compile time.

Referenced by SPIN__ptus_to_nsecs().

---

Function Documentation

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

Referenced by SPIN__wait().

SPIN__EXP_FNC unsigned 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.

References SPIN_NSECS_TO_PTUS.

SPIN__EXP_FNC 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().

References SPIN_PTUS_TO_NSECS.

SPIN__EXP_FNC int SPIN__wait	(	SPIN_time	begin_ptu,
		unsigned int	ptus
	)

Allows one to wait a specified time period after a start time.

Parameters:

	begin_ptu	The start time
	ptus	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.

References SPIN__curtime().