***** 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.
Notice also that in oneshot mode using the APIC timer a precise scheduling 
time depends also on the ratio cpu_freq/apic_freq.



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

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


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, even 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 the
timer interrupt latency by using the Time Stamp Clock (TSC). Mchines 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
an immediate dispatching of the timer interrupt, that should have latencies 
in the range of 20/30 us worst case. So if you'll see something too much 
higher play with your system configuration parameters and 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". Worsening latencies are displayed as they happen.
Notice that 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.
