***** Various precise tunings of RTAI timing facilities *****
=============================================================

Please type "./calproc -h" to understand how to use it. A more detailed
explanation of the various available options follows below.


8254 Calibration
================

Evaluates the time it takes to write two bytes to the 8254 timer. Such a time 
is required for programming the oneshot timer and sets the macro 
SETUP_TIME_8254 in rtai.h. 
It just calls an undocumented entry in rtai.c.

APIC Frequency Calibration
==========================

Calibrates the APIC timer against the 8259 timer.

In about twenty seconds the frequency value displayed on the console should
converge to the last significant digit. If you keep it running longer you can 
verify full convergence.

We always use the most precise calibration obtainable by running it for an 
appropriate amount of time. The highest precision is needed for periodic
timers, if you want to minimize the drift from real time.


CPU Frequency Calibration
=========================

Calibrates the cpu clock against the 8259 timer.

In about twenty seconds the frequency value displayed on the console should
converge to at least one part in ten million.  If you keep it running
longer you can verify that more and more digits remain stable. In about a
quarter of an hour you should get a precision to the least significant
digit. For a very precise and safe calibration let it run for an hour or so.

Such a high precision is not strictly required for RTAI to work
appropriately, in fact RTAI is enough with Linux calibration values it
uses as defaults. However we (DIAPM) always use the most precise calibration 
obtainable by running it for an appropriate amount of time. The highest 
precision is needed for periodic timers, if you want to minimize the drift from real time.


Latency Calibration
===================

Calibrates the scheduling latency of RTAI schedulers with oneshot timers, to
allow a more precise of timed tasks. Chose the one (kernel/user space) more
appropriate to the scheduler you want to use.


Interrupt Delays Caused by Bus Hardware Arbitrations and Locks
==============================================================

More and more motherboards are being sold with chipsets that have hardware
optimizations allowing locking the bus, maybe up to few millisecs. 
Without judging if such a way of working is acceptable, maybe it makes it 
appear to improve overall average performances in general applications, it 
surely dooms real time usage.
Often what RTAI users see are large scheduling jitters and they start hinting 
at bugs that likely do not exist.
This check is aimed at helping in tracking such a problem. It measures interruptlatency by using the TSC on the timer interrupt, machines without TSCs are old
enough to have no optimising chipsets. Thus they do not have such a problem.
The only module implied is rtai.c, there is thus no scheduling but just
interrupt dispatching, that should have latencies in the range of 20/30 us
worst case. So if you'll see something too much higher play with its
configuration parameters, with those of Linux as well, to end in buying
another board eventually.
The worst interrupt latency is displayed at the end of the run, which comes
when you type "Ctrl-C".
Note that it is possible to check it also on a scope by defining using "-sy" 
and connecting the scope to the first output bit of the parallel port.
See also README.SMI in this directory for some clues that might help with
some INTEL chipsets.
