---

SPIN.ih File Reference

Utilities to spin the CPU for a well-defined period of time. More...

#include "BBC/inline.h"
#include "BBC/SPIN_time.h"

Defines
#define	SPIN__EXT_PROTO   INLINE_USR_EXT_PROTO
	External Prototype specification.
#define	SPIN__EXT_FNC   INLINE_USR_EXT_FNC
	Internal Prototype specification.
#define	SPIN__LCL_PROTO   INLINE_USR_LCL_PROTO
	External Function declaration.
#define	SPIN__LCL_FNC   INLINE_USR_LCL_FNC
	Internal Function declaration.
Functions
SPIN__EXT_PROTO unsigned int	SPIN__nsecs_to_ptus (unsigned int nanoseconds)
	Converts a number of nanoseconds to PTUs. More...
SPIN__EXT_PROTO unsigned int	SPIN__ptus_to_nsecs (unsigned int ptus)
SPIN__EXT_PROTO SPIN_time	SPIN__curtime (void)
	Returns the current time in units of PTUs. More...
SPIN__EXT_PROTO int	SPIN__wait (SPIN_time begin_ptu, unsigned int ptus)
	Allows one to wait a specified time period after a start time. More...
SPIN__EXT_PROTO int	SPIN__check (SPIN_time begin_ptu, unsigned int ptus)
	Checks whether the requested amount of time has elapsed. More...
SPIN__EXT_PROTO int	SPIN__spin (unsigned int ptus)
	Places the CPU into a spin loop until the specified number of PTUs has elapsed. More...

---

Detailed Description

Utilities to spin the CPU for a well-defined period of time.

Author:

JJRussell - russell@slac.stanford.edu

These are the inline versions of the SPIN routines. The inline and non-inline versions maybe used in any combination. For complete documentation refer to SPIN.h and SPIN.c.

---

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

---