PTS.h File Reference

Processor Timer Services. More...

#include <PBS/PTS_comdefs.h>
#include <PBS/impl/PTS.h.xx-xxx-xxx>

Functions
int	PTS_initialize (void)
	Initializes the PTS facility.
unsigned int	PTS_nsecs_to_ptus (unsigned int nanoseconds)
	Convert a number of nanoseconds to PTUs.
unsigned int	PTS_ptus_to_nsecs (unsigned int ptus)
	Convert a number of ptus to nanoseconds.
unsigned long long int	PTS_nsecx_to_ptux (unsigned long long int nanoseconds)
unsigned long long int	PTS_ptux_to_nsecx (unsigned long long int ptus)
unsigned int	PTS_frequency (void)
	Get the frequency of the PTS clock.

---

Detailed Description

Processor Timer Services.

Author:

JJRussell - russell@slac.stanford.edu

     CVS $Id: PTS.h,v 1.6 2011/03/24 23:05:43 apw Exp $

These utilities allow one to deal with the highest resolution clock available on the target platform. The utilities which deal with the clock all take times in the units of the processor clock. These routines allow one to convert these units to and from physical units.

Two parallel sets of routines and macros are provided; one deals with what is called short range processor times and the other with extended range processor times. In general the short range processor times can be represented in 32 bits integer and the extended range processor time can be represented in 64 bits. However, the exact representation is platform dependent. While on many platforms the representation is a 32 or 64 bit unsigned integers, on others it is not. This means the operations on these values most be performed using the routines and macros that PTS provides. As an example, one cannot simple subtract two extended times on LINUX platforms because the representation is not a flat 64 bit integer, it is the wacko seconds and nanoseconds structure.

Because of the this the user of the PTS facility should use PTS_times and PTS_timex to declare variables holding short and extended range processor times.

Nanoseconds has been chosen as the physical unit to deal in. The only limitation that this imposes is on the range, limiting these times, at least in 32 bit representations to the 2-4 second range.

The suite of typedefs and macros is

     - PTS_times
     - PTS_GETS()
     - PTS_PTUS_TO_NSECS(_ptus)
     - PTS_NSECS_TO_PTUS(_nsecs)
     - PTS_DELTAS(_beg, _end)
     - PTS_DELTAS_TO_NSECS(_beg, _end)

     - PTS_timex
     - PTS_GETX()
     - PTS_PTUX_TO_NSECS(_ptus)
     - PTS_NSECX_TO_PTUX(_nsecx)     
     - PTS_DELTAX(_beg, _end)
     - PTS_DELTAX_TO_NSECS(_beg, _end)

---

Function Documentation

unsigned int PTS_frequency

(

void

)

Get the frequency of the PTS clock.

Returns:

The frequency, in Hertz, to the processor clock

References _PTS_parameters::frequency.

Referenced by PBS_initialize2(), and WUT_frequency().

int PTS_initialize

(

void

)

Initializes the PTS facility.

This is a one time only call to initialize internal data structures. This routine should be called as part of the library initialization sequence.

References _PTS_parameters::frequency, _PTS_parameters::nsecs_per_ptu, _PTS_parameters::nsecs_per_ptu_den, _PTS_parameters::nsecs_per_ptu_num, and PTS_INIT_FAILURE.

Referenced by PBS_initialize2().

unsigned int PTS_nsecs_to_ptus

(

unsigned int

nanoseconds

)

Convert a number of nanoseconds to PTUs.

Parameters:

nanoseconds

The number of nanoseconds to convert to PTUs

Returns:

The number of equivalent PTUs

References _PTS_parameters::nsecs_per_ptu, _PTS_parameters::nsecs_per_ptu_den, and _PTS_parameters::nsecs_per_ptu_num.

unsigned int PTS_ptus_to_nsecs

(

unsigned int

ptus

)

Convert a number of ptus to nanoseconds.

Parameters:

ptus

The number of PTUs to convert to nanoseconds

Returns:

The number of equivalent PTUs

References _PTS_parameters::nsecs_per_ptu_den, and _PTS_parameters::nsecs_per_ptu_num.