This is a comprehensive real time application interface (RTAI), developped at the Dipartimento di Ingegneria Aerospaziale del Politecnico di Milano (DIAPM), (www.polimi.it.aero). It allows you to use Linux kernel 2.2.xx for many hard real time applications. Note that it cannot be used for 2.0.xxx. Please note also that the all stuff is based on the assumption that the Linux kernel tree starts at "/usr/src/linux" and that "rtai.tgz" is untarred and expanded in the "/home" directory so that it generates, or ovewrites, the directory "/home/rtai". If you do not adhere to those assumptions you must change the various "Makefile"s accordingly. This version can be used for uniprocessor (UP) PCs and for symmetric multi processors (SMP) as well. In the latter case task are defaulted to work on any cpu but you can assign them to any subset, or to a single cpu, by using the function "rt_set_runnable_on_cpus". The schedulers allow to chose between a periodic and a oneshot timer, not to be used together. The periodic ticking is less flexible but, with the usual PC hardware much more efficient. So it is up to you which one to choose in relation to the applications at hand. It should be noted that in the oneshot mode the time is measured on the base of the CPU time stamp clock (TSC) and not on the 8254 chip, which is used only to generate oneshot interrupts. The periodic mode is instead timed by the 8254 chip only. In this way slow I/Os to the ISA bus are limited as much as possible with a sizable gain in efficiency. The oneshot mode has just about 15-20% more overhead than the periodic one. It is likely that local APIC timers could lead to a further improvement, but we've to learn more about their use in the Linux kernel before adopting them. Right now I know that they are not available on UPs and that, if a single APIC timer is used for SMP, the performance improvement it is likely to produce for the oneshot case will be sizable but not so large to with respect to the present solution. In fact by using the TSC just two outb are required to reprogram the 8254, i.e 2.5 us approximatly, against almost nothing for the APIC timer. However you have to broadcast a message to all the cpus in any case, and that is about 2 us, the APIC bus is an open drain 2 wires one and is not lightning like. So the performance loss is just a factor of two, and not infinite, and furthermore is just a fraction of the overall task switching procedure. It will be significant in any case so it must be taken into account, expecially if UPs with enabled APIC will ever appear on the PC market. On the other hand the use of multiple coordinated APIC timers in an SMP scheduler requires some more thought and time. Since the TSC is not available on 3/486 machines for them we use a form of emulation of the "read time stamp clock" (rdtsc) assembler instruction based on counter2 of the 8254. So you can use RTAI also on such machines. Be warned that the oneshot timer on 3/486 is a performance overkill because of the need of reading the tsc, i.e. 8254 counter2 in this case, twice. That can take 6-8 us, i.e. more than it takes for a full switch among many tasks while using a periodic timer. Thus only a few Khz period is viable at most for real time tasks if you want to keep Linux alive. No similar problems exist for the periodic timer that needs not to use any TSC at all. So, compared to the 20% cited above, the real time performance ratio of the oneshot/periodic timer efficiency ratio can be very low on 3/486 machines. Moreover it will produce far worse jitters than those caused on Pentiums and upward machines. If you really need a oneshot timer buy at least a Pentium. Instead, for a periodic timing 3/486s can be still more than adequate for many applications. An important remark. We have tested this option only on Pentiums, since we have no more 3/486s available. A feature of this RTAI implementation is that interrupt handlers preambles take care natively of the task switched (TS) flag. Thus you can freely use floating point operation in your interrupt handlers, without causing a trap fault whatever thing Linux is doing. RTAI is thus very suitable to trap interrupts without minding of Linux so that you can effectively interact with the bare PC hardware much in the same way I, and maybe many of you, liked the old good time of DOS. With RTAI you have the added advantage that Linux maintains all of its feature untouched so that you can pass to it whatever you get from your handler for logging, displaying and postprocessing, by using fifos and/or shared memory. Imagine a remote controller at 10 Khz, +-5 us interrupt uncertainty, connected through the internet, with the all the bells and wistles of X and its applications. It is an application we simulated easily. See the "examples/timer" directory in examples for some clues, without remote control however. RTAI needs to calibrate the cpu clock frequency, and scheduling latency as well if the oneshot scheduler for Pentiums and upward machines. On the contrary, as it will be clarified shortly afterward, 3/486s need not such a calibration. For the cpu frequency you have two choices: - the first, and less precise, is to get the cpu frequency by just typing "cat /proc/cpuinfo" and taking the value shown on the screen. - the second, and reccomanded mode, requires running the module rt_cal from the directory "cpu_freq_calibration" included in this distribution. Yuo'll get something better than in cpuinfo in about twenty seconds. If you want to get full precision let it run till the least significant digit is stabilized. See README in "cpu_freq_calibrate" for a more precise description. Note that this must be done just once for all. No calibration is needed for 3/486s, just set CPU_FREQ equal to 8254_FREQ (1193180 hz) in "rtai.h" in the directory "include". That's the way the various modules understand that 3/486s are being used. A further calibration is required, only if you intend to use the oneshot mode, for the LATENCY macro to be set in "rtai.h" file in directory "include". For that see the README file in directory "latency". Note that this version of RTAI has also some very useful system services, including: timings, semaphores, messages and remote procedure calls (RPC). That makes it easier to develop complex real time applications. RPCs are a limited form of QNX messages as they pass either just an usigned integer or a pointer to an unsigned integer for reason of efficiency. They can be easily changed to be fully compatible with QNX if you'd like. What to do: 1 - Get a clean distribution of linux-2.2.xx kernel and follow the instructions in file INSTALL of this distribution to patch it. So far what suggested there has remained valid from 2.2.pre1 up to 2.2.5. We expect that it will be so for a long time ahead. However the RTHAL/RTAI concept is so flexible that it would be easy to upgrade, should anything change in the basic kernel interfaces toward the PC hardware. However if you are lazy or do not want to learn the "where and why"s go to directory "linux" and type "copythere". See the "readme" file there for an explanation. 2 - "make config" (menuconfig or xconfig) to configure the kernel. Right now you must set the SMP option also for UP machines. This entails a slight loss of performance but has eased development. Code cleanup and ifdeffing to allow avoiding SMP in UPs is underway. However be warned that it will come after a full real time SMP scheduler, i.e one using any combination of cpus, is in place and reliably working. 3 - Carry out the compilation of the kernel by "make bzImage"; 4 - Get the cpu frequency as described above and set the macro CPU_FREQ in rtai.h in directory include, then "make" in directory rtai to have the "rtai" module prepared. Remember that for 3/486s no calibration is required but CPU_FREQ must be set to 8254_FREQ (1193180 hz), already defined in "rtai.h". 5 - Do "make install" in the distribution subdirectories "ipc" and: "scheduler" for UP, "smpscheduler" for SMP, to prepare the fifo and scheduler modules. The file "ldmod" and "remod" can be used to insmod and rmmod all at once rtai, fifo and scheduler modules with the default parameters. For the scheduler these are: the cpu frequency, as set in the corresponding macro CPU_FREQ in rtai.h, a periodic scheduler and Linux assumed not to use the fpu. You can change any of the above either by setting the corresponding macros in "rtai.h" or at module installation: just type the extended command: "insmod /usr/src/linux/modules/rtl_sched CpuFreq= LinuxFpu= OneShot=", where x is the cpu frequency in hz, y==0 Linux does not use the fpu y!=0 does, z==0 periodic timer z!=0 oneshot timer. Clearly you can set any combination of the above parameters. While the cpu frequency can be changed just by compiling the scheduler modules or at its installation, the functions: "rt_linux_use_fpu(int yes_no)", "rt_set_periodic_mode()", "rt_set_oneshot_mode()", can be used to set/reset the scheduler dynamically. Note that any setting of the timer mode stops any already running timer. Now you are done and can try the test cases. Be carefull in setting the macro TICK_PERIOD (nanosecs) in the various examples to a value appropriate to your machine. Those used now works for a 200Mhz PPro and can be too demanding for lower class Pentiums and 3/486s. In all the tests the choice of which timer, periodic or oneshot, use is done by commeting/uncommentig the macro ONE_SHOT. It is important to remark that since in all tests a oneshot timer is set specifically at module load time, any choice made at the scheduler installation is overridden. It should be also remarked that if the timer mode is chosen at module installation that must be done by adding a call to "rt_set_[oneshot/periodic]_mode()" before any time conversion or service is requested to the scheduler. Thus in the case of a multi modules application set the mode in the very first module to be loaded or in a common header file, as it is done in the digital wrist clock examples (se file "clock.h" in directories "sem_clock" and "msg_clock"). There are some html files with some documentation of the various function calls, see directory "doc_rtai". The introduction is outdated and will be changed but the rest is still valid. Have a look also at the header files in directory "include" for some further more up to date explanations, especially if you want to use fifos with large statically assigned user buffers and want to experiment with different bottom_halves and immediate_wake_up (see also the very first comment in the file "rtl_fifo.c" in directory "ipc"). I'm looking forward for people joining in the development, both for a better understanding of the kernel internals, so to set a portable general RTHAL specification, and in adding features to rtai and related modules. Note that if you want to interface to the rtai substrate you need not to know the kernel deeply, so that adding new modules should be easier and safer, no kernel compilation but just your troubled code. In this spirit, since this is the first distribution of the all stuff, I'll also hope that you will not throw it in the rubbish if something goes wrong or is unclear. It has been thorougly tested on different machines, the SMP scheduler only on standard INTEL dual cpus, without any problem beside those cited in bugs_and_todo, and there are examples, see directories "sem_clock", "msg_clock" and "msgsw", that are basically fairly complex. However there are unknown bugs for sure. You will not see many copyrights in this software and you can use it as you like and want, but I would like "to be remembered" if you'll find it usefull. As usuall it is "as it is" and I assume no responsability if anything goes wrong. However, I'll repeat, comments, any feedback, and help for any further development, if you like the idea, are warmly welcomed. Email to: "mantegazza@aero.polimi.it". Many warm thanks are due to Emanuele Bianchi, Davide Martini, Lorenzo Dozio and Daniele Danlugli for their cooperation, suggestions and precious help in various job using Linux for hard real time control systems. Emanuele, Davide and Lorenzo did a nice work to verify and test our RTLinux variant of NMT-RTLinux in production work for their thesis and following research works at DIAPM. The helpful html documentation is almost entireky due to Emanuele and Davide. Lorenzo played also a very important role in retrofitting our efficient oneshot timers to the then purely periodic timing control, because of the need to use them to easily pulse width modulate air jets emulating on-off control rockets. Daniele has also been very very fundamental in the past scheduler development, especially in relation to fpu support. He was the first one to point out unbearable jitters when the fpu was used in RTLinux and in its DIAPM variant. Without it convincing cryes many people, including myself would never have known that they were using the fpu just to generate troubles in their applications. It is because of that that the fpu support is included natively also for RTAI interrupt handlers.