trick/trick_source/sim_services/Clock/main_page.dox_in

/**

@page LEVEL2 Trick Realtime Clock

A realtime clock is an optional feature for %Trick simulations.

The Trick::Clock base class provides %Trick with a consistent interface to different
realtime clocks.  The base class provides a common set of routines called by
Trick::RealtimeSync to get and reset the realtime clock.

%Trick provides built in support for using the system clock (Trick::GetTimeOfDayClock).

%Trick also provides built in support for using Spectracom's TPRO IRIG-B clock board,
also referred as a Central Timing Equipment (CTE) board.  TPRO CTE support is off
by default.  To enable TPRO CTE support %Trick must be built with TPRO driver support.
Go to http://www.spectracomcorp.com for driver support for your particular board.
To enable TPRO CTE support, run ${TRICK_HOME/configure --tprocte=/paht/to/tpropci.
Recompile %Trick after the configure script.

@section LEVEL3 Creating a User Defined Real-Time Clock

Clocks may be created by users.  To create a new clock, the class must inherit from
the Trick::Clock.  Trick::Clock is an abstract class with several methods for the user
to implement.  These methods provide the hardware specific code to initalize, access, and
shutdown clock hardware. See ${TRICK_HOME}/trick_source/sim_services/Clock for examples
to how we implemented the GettimeofDay and the TPRO_CTE clock.  This is the list of
routines that must be implemented by the user:

@par Trick::Clock::clock_init()

Opens the clock hardware, initializes the clock, etc.

@par Trick::Clock::wall_clock_time()

Gets the wall clock time.  Returns the time in integer number of tics of 1us.

@par Trick::Clock::clock_spin(long long req_time)

Waits for real-time to catch up to the requested simulation time.  Polling or waiting
for an interrupt are typical methods for spinning.

@par Trick::Clock::clock_stop()

Shuts down clock hardware, closes devices, etc.

@section LEVEL3 Specifying the Real-Time Clock

%Trick instantiates an instance of  the Trick::GetTimeOfDayClock and Trick::TPROCTEClock
clocks by default.  The Trick::TPROCTEClock will be empty if TPRO CTE support is not
enabled.

%Trick defaults to the Trick::GetTimeOfDay clock. To switch to the TPRO CTE clock
or a user defined clock use the following line in the Python input file.

@code
# Changes to the TPRO CTE clock
trick.real_time_change_clock(real_time.tpro_cte)
# Changes to a user defined clock
trick.real_time_change_clock(<user defined clock>)
@endcode

@section LEVEL3 Accessing the Real-Time Clock

Typically, users will not have to access the real-time clock directly, the
Trick::RealtimeSync uses the real time clock to synchronize to real time.  However
there are several user accessible routines to control the clock and get the status.

#include "trick_source/sim_services/Clock/include/clock_proto.h" for these routines

@section LEVEL4 Clock Time

@code
long long clock_time() ;
@endcode

@code
# Python access
trick.clock_time()
@endcode

Gives you real-time referenced from simulation start.  The returned value is in tics.
A tic is set amount of time, set by the Trick::Executive, usually 1us.

@section LEVEL4 Wall Clock Time

@code
long long wall_clock_time() ;
@endcode

@code
# Python access
trick.wall_clock_time()
@endcode

Gives you the actual time from the clock.  The returned value is in tics
A tic is set amount of time, set by the Trick::Executive, usually 1us.

@section LEVEL4 Clock Spin

@code
int clock_spin(long long ref) ;
@endcode

@code
# Python access
trick.clock_spin(<ref_time>)
@endcode

Calling clock spin will cause the simulation to enter a loop and wait until
realtime catches up to simulation time.  This is not typically called by
users.

@section LEVEL4 Reset Clock Reference

@code
long long clock_reset(long long ref) ;
@endcode

@code
# Python access
trick.clock_reset(<ref_time>)
@endcode

Resetting the clock synchronizes the "reference" time to the real-time clock.
The reference time is typically the current simulation time.

@section LEVEL4 Manually Setting Clock Reference

@code
int clock_set_reference(long long wall_clock_time) ;
@endcode

@code
# Python access
trick.clock_set_reference(<wall_clock_time>)
@endcode

This manually synchronizes the clock's reference to the incoming wall clock time.
This routine is used internally to synchronize the simulation time to a whole
second multiple of the real time clock.

@section LEVEL4 Getting the Clock Ratio

@code
double clock_get_rt_clock_ratio() ;
@endcode

@code
# Python access
trick.clock_get_rt_clock_ratio()
@endcode

The realtime clock has the ability to run at a ratio to realtime.  This routine
gets the current set ratio.

@section LEVEL4 Setting the Clock Ratio

@code
int clock_set_rt_clock_ratio(double in_rt_clock_ratio) ;
@endcode

@code
# Python access
trick.clock_set_rt_clock_ratio()
@endcode

The realtime clock has the ability to run at a ratio to realtime.  This routine
sets the current set ratio.  A simulation may not be able to run fast enough to
honor the set ratio.  In this case the simulation will run as fast as possible.

@section LEVEL3 Realtime Clock Related Pages
Realtime Clock Requirements\n
Realtime Clock Design 

*/