-- Introduction --
This file describes how to use the timelib wrapper for tcl/expect.

The idea behind this virtual time adaptation is to intervene system calls to
time related functions. Instead they are implemented in such a way that the
virtual time of CPPemu is used.  This means that the timeout of existing
tcl/expect scripts are run as if real hardware is used.

Using the virtual time adaption requires two steps, one related to CPPemu and
the other related to the test environment. The test environment will require a
wrapper script to initialize some environment variables.


-- The CPPemu part --
On the emualtor a device called 'time-server' need to be initialized. It
handles the CPPemu side of the virtual time distribution. 

This is done with the command 
cppemu-create-time-server [port] (the default port is 8123)


-- The Tcl/Expect part --
Before starting the tcl script, i.e. the test case, one need to 
initialize some environment varaibles.

If a tcl script invokes another script, that can be done as:
  set env(TIME_SERVER) localhost
  set env(TIME_PORT)   8123
  set env(LD_PRELOAD)  "<CPPEMU_INSTALL_DIR>/core/util/timelib-<SUFFIX>.so"

In a tcsh script this is done like this:
  setenv TIME_SERVER localhost
  setenv TIME_PORT 8123
  setenv LD_PRELOAD <CPPEMU_INSTALL_DIR>/core/util/timelib-<SUFFIX>.so

And in a bash script it looks like:
  TIME_SERVER=localhost
  TIME_PORT=8123
  LD_PRELOAD=<CPPEMU_INSTALL_DIR>/core/util/timelib-<SUFFIX>.so
  export TIME_SERVER
  export TIME_PORT
  export LD_PRELOAD

TIME_SERVER is the host where CPPemu executes, and ports is the port number
given when creating the time server. Default value for the port is 8123, and
locahost for host.  LD_PRELOAD Points the wrapper library, this variable is
mandatory.

When the LD_PRELOAD library is set all applications started from same script or
shell will use virtual time, if CPPemu is running.  When no CPPemu instance is
found timelib will use the real system calls instead.

Virtual time can be temporarily disabled by setting the environment variable
TIME_DISABLE, e.g.:

tcl:
  set env(TIME_DISABLE) 1
  unset env(TIME_DISABLE)

tcsh:
  setenv TIME_DISABLE 1
  unsetenv TIME_DISABLE

bash:
  export TIME_DISABLE=1
  unset TIME_DISABLE


-- More examples --
An example wrapper-script which sets up the timelib is provided along with
this file, it is called 'timelib-wrapper.sh'
There is also an example timeclient implementation written in python that can
be used to test the time-server in CPPemu as well as an inspiration/guid to
write own applications using the virtual time from CPPemu.
The python file is called 'timeclient.py'. It can be tested by executing it,
through 'cppemu-time' to print the current virtual time or through
'cppemu-sleep NUMBER' to sleep for NUMBER virtual seconds.
An example implementation in C is available upon request from the CPPemu
support

-- Troubleshooting --
The log-level can be raised by setting the environment variable TIME_LOG to a
value from 0 (no logging) to 5 (full logging).  Log printouts are made to
STDERR

-- Known issues --
* Due to tcl/expect doing a busy-idle loop the total performance
drops severely when waiting on expected strings. A work-around is implemented.

* All client started from a script will inherit the virtual 
time awareness. This means that spawning a telnet or similar might require one
to unset the LD_PRELOAD variable before the spawn call and reinitialze it
after. It might also be possible to use the TIME_DISABLE feature (see above)

