/ README.INSTALL
README.INSTALL
1 Installing RTAI-3.x 2 =================== 3 4 0. RTAI 3.6 5 ================================ 6 7 RTAI uses only the leanest and fastest RTAI+Linux combination now, i.e. it 8 dispatches real time interrupts immediately. Moreover within such a scheme 9 i386 has the possibility of completely avoiding the dispatching of critical 10 internal timers and interprocessor scheduling interrupts by vectoring them 11 directly to their handlers. Such an option strongly enhances performances 12 on low end machines and comes by default. You can disable it while configuring 13 RTAI though. See the related configuration helper. 14 What above requires you to patch Linux just with patches found wihin this 15 distribution. 16 Notice also that this release is for use with: 17 - i386, 18 - x86_64, 19 - PPC. 20 21 On recent distributions, managing udev/sysfs, devices created by following 22 this installation procedure will disappear at each machine halting. Then they 23 will be available nomore at the next reboot. RTAI should manage udev/sysfs 24 support but in case something weird will impede it you can solve your problem 25 quickly by restoring RTAI devices before running your application. For that 26 the following short script containing: 27 ------------------------------ cut here ------------------------------------- 28 if test \! -c /dev/rtai_shm; then 29 mknod -m 666 /dev/rtai_shm c 10 254 30 fi 31 for n in `seq 0 9`; do 32 f=/dev/rtf$n 33 if test \! -c $f; then 34 mknod -m 666 $f c 150 $n 35 fi 36 done 37 ------------------------------ cut here ------------------------------------- 38 should suffice. 39 40 1. How to build 41 =============== 42 43 1.1 Standard procedure 44 ---------------------- 45 46 The RTAI build system is a merge of Linux's Kconfig with 47 autoconf/automake/libtool. Therefore, you can either build RTAI: 48 49 1.1.1 Interactive configuration 50 ------------------------------- 51 52 1) Into the source tree like with 24.1.x (your_source_dir == 53 your_build_dir). Just run either: 54 55 $ make xconfig # (Qt-based) 56 $ make gconfig # (GTK-based) 57 $ make menuconfig (dialog-based as in 24.1.x) 58 59 Save your configuration, wait for the shell prompt to come back after 60 the configuration script has fully finished, then run "make". 61 62 2) Outside the source tree. From your fresh build directory, 63 either run: 64 65 $ make -f $source_tree/makefile srctree=$source_tree xconfig 66 $ make -f $source_tree/makefile srctree=$source_tree gconfig 67 $ make -f $source_tree/makefile srctree=$source_tree menuconfig 68 69 If you are using a version of make >= 3.80, then you can even get rid 70 of the "srctree=$source_tree" setting. The makefile will infere its 71 value properly. 72 73 1.1.2 Non-interactive configuration 74 ----------------------------------- 75 76 Since RTAI 3.x has autoconf inside, people needing automatic 77 non-interactive configuration can directly use the provided GNU 78 configure script for this purpose. The available configuration 79 switches can be listed by running ./configure --help. The 80 RTAI-specific switches are: 81 82 --enable-trace Enable trace support 83 --enable-math Enable math support 84 --enable-bits Enable bits IPC support 85 --enable-fifos Enable fifo IPC support 86 --enable-netrpc Enable netrpc support 87 --enable-netrpc-rtnet Enable use of RTNet 88 --enable-sem Enable semaphore support 89 --enable-msg Enable messaging support 90 --enable-mbx Enable mailbox support 91 --enable-tbx Enable typed mailbox support 92 --enable-mq Enable POSIX-like message queue support 93 --enable-shm Enable shared memory support 94 --enable-malloc Enable real-time malloc support 95 --enable-tasklets Enable tasklets support 96 --enable-usi Enable user-space interrupt support 97 --enable-watchdog Enable watchdog support 98 --enable-leds Enable leds-based debugging support 99 --enable-sched-lxrt Enable scheduler support without RTAI own ktasks 100 --enable-ktasks-sched-lxrt Enable scheduler support with RTAI own ktasks 101 --enable-sched-lock-isr Enable scheduler lock in ISRs 102 --enable-sched-8254-latency= Set 8254 tuning latency 103 --enable-sched-apic-latency= Set APIC tuning latency 104 --enable-sched-lxrt-numslots= Set number of LXRT slots 105 --enable-cplusplus Build in-kernel C++ support 106 --enable-comedi-lxrt Enable comedi/LXRT support 107 --enable-serial Build real-time serial driver 108 --enable-testsuite Build RTAI testsuite 109 --enable-rtailab Build RTAI-Lab 110 --enable-fpu Enable FPU support 111 --enable-math-c99 Enable math C99 support 112 --enable-malloc-vmalloc Enable vmalloc support in malloc 113 --enable-malloc-heap-size Set size of real-time malloc heap 114 --enable-cpus Enable CPUs 115 --enable-dox-doc Build Doxygen documentation 116 --enable-dbx Build Docbook XML documentation. 117 --enable-dbx-network Try to access Docbook DTD and XSL stylesheets through 118 network. 119 --enable-latex-doc Build LaTeX documentation 120 --enable-verbose-latex Uses LaTeX non-stop mode 121 --enable-compat Enable compatibility mode 122 --enable-module-debug Enable debug information in kernel modules 123 --enable-user-debug Enable debug information in user-space programs 124 125 Some configuration targets in base/ can either produce a module, 126 or be statically linked to the RTAI schedulers. Either pass "m" for 127 the modular build to their respective --enable-xxx switch, or "y" for 128 selecting the built-in mode. 129 130 1.1.3 Recycling a configuration file 131 ------------------------------------ 132 133 You can also recycle an existing .rtai_config file from a previous 134 build by running: 135 136 $ cp -rp $old_builddir/.rtai_config \ 137 $new_builddir/.rtai_config 138 $ cd $new_builddir 139 $ make -f $source_tree/makefile srctree=$source_tree oldconfig 140 141 1.1.4 Selecting alternate compilers 142 ----------------------------------- 143 144 Compiler selection must be done at _configuration_ time. One only 145 needs to pass the right values for the standard environment variables 146 CC and CXX, respectively for compiling C and C++ source files. In any 147 case, using a GCC toolchain is mandatory. When unspecified, these 148 variables's values respectively default to "gcc" and "g++". 149 150 WARNING: this selection is not aimed at toggling the cross-compilation 151 mode on. In order to do so, please refer to 1.2. 152 153 Examples: 154 155 # Start configuring using the Qt-based GUI with alternate compilers 156 $ make xconfig CC=/my/favourite/c/compiler CXX=/my/favourite/c++/compiler 157 158 # Reconfiguring a previous build tree, changing the compilers on-the-fly. 159 $ make reconfig CC=/my/favourite/c/compiler CXX=/my/favourite/c++/compiler 160 161 # Rebuild all [and optionally install] 162 $ make [all [install]] 163 164 CAVEAT: Since the autoconf-based engine needs to analyze the 165 compilers's features and crams the CC and CXX values into the 166 Makefiles it produces, passing CC and CXX variables at build time 167 simply does _not_ work for the purpose of selecting alternate compiler 168 toolchains. Again, you need to let the configuration engine know about 169 these new settings as explained above. 170 171 1.2 Installing the software 172 --------------------------- 173 174 When the standard (or cross-) compilation has finished: 175 176 $ cd $builddir 177 $ make install 178 179 Everything needed to use the RTAI distribution will be copied there 180 out of the build tree. From now on, you should be able to refer to the 181 installation directory as the root of a complete standalone binary 182 RTAI distribution. 183 184 One may also choose to install the RTAI programs under a temporary 185 staging tree by passing the standard DESTDIR variable to "make" while 186 installing. e.g. 187 188 $ make install DESTDIR=/mnt/target 189 190 will create a standard RTAI hierarchy under /mnt/target, keeping the 191 original prefix information unmodified. If the installation directory 192 selected at configuration time was "/usr/realtime", then the command 193 above will put the RTAI binary distribution under 194 /mnt/target/usr/realtime. 195 196 WARNING: running "make install" is required to run several standard 197 RTAI programs correctly. RTAI 3.x enforces the actual split between 198 the source distribution tree, the build tree where RTAI is going to be 199 compiled, and the final installation directory where RTAI programs can 200 be run eventually. In any case, you should only rely on the 201 installation directory contents to run RTAI programs. 202 203 NOTE: Do not pay attention to the "*** Warning" messages appearing on 204 module compilation output. They are harmless and will be fixed later. 205 206 1.3 Compiling parts of the tree 207 ------------------------------- 208 209 RTAI developers may want to recompile parts of the tree from times to 210 times. This automake-based build system allows it: just go to the 211 proper directory level, then issue "make", as usual. This process will 212 recurse as needed. 213 214 The "makefile" (small caps) found in the root source directory is used 215 to bootstrap the build system when it is about to be configured for 216 the first time. After the first configuration has been successful, one 217 just need to run "make xconfig|gconfig|menuconfig|..." as usual. 218 219 1.4 Changing the configuration 220 ------------------------------ 221 222 Each time you want to change your configuration, just run "make 223 xconfig|gconfig|menuconfig" in your build dir, then "make" (or "make 224 all"). 225 226 If you only want to rerun the "configure" script using the current 227 RTAI configuration, just run "make reconfig", there is no need to 228 restart any GUI for that. 229 230 When invoked for the first time in an empty build directory, the 231 default "make" goal is "menuconfig" in a regular terminal, or 232 "xconfig" in an emacs-term. 233 234 1.5 Modifying the autotool template files 235 ----------------------------------------- 236 237 If you have to change some template files used by any of the autotools 238 (i.e. Makefile.am, configure.in, acinclude.m4), then you will need the 239 following pack to rebuild the derived files: 240 241 o autoconf 2.59 242 o automake 1.9.2 243 o aclocal 1.9.2 244 o libtool 1.5.8 245 246 1.6 Using the integrated calibration tool 247 ----------------------------------------- 248 249 RTAI 3.x comes with a brand new calibration tool which should help you 250 determining if your hardware platform is up to the hard real-time 251 duties. You can find this tool under $installdir/calibration. Here is 252 the output of this tool's help message for x86-based platforms: 253 254 $ ./calibration --help 255 256 OPTIONS: 257 -h, --help 258 print usage 259 -r, --r8254 260 calibrate 8254 oneshot programming type 261 -k, --kernel 262 oneshot latency calibrated for scheduling kernel space tasks 263 -u, --user 264 oneshot latency calibrated for scheduling user space tasks 265 -p <period (us)>, --period <period (us)> 266 the period of the underlying hard real time task/intr, default 100 (us) 267 -t <duration (s)>, --time <duration (s)> 268 set the duration of the requested calibration, default 5 (s) 269 -c, --cpufreq 270 calibrate cpu frequency 271 -a, --apic 272 calibrate apic frequency 273 -b, --both 274 calibrate both apic and cpu frequency 275 -i, --interrupt 276 check worst case interrupt locking/contention on your PC 277 -s<y/n>, --scope<y/n> 278 toggle parport bit to monitor scheduling on a scope, default y(es) 279 280 2. Bootstrapping with vulcano in 7 steps 281 ======================================== 282 283 >1. patch and build a vanilla Linux kernel tree with the RTAI support as 284 usual. Patches for x86 are available from 285 vulcano/base/arch/i386/patches/. Apply only one of them 286 that matches the Linux kernel version, like this: 287 $ cd $linux-src-dir 288 $ patch -p1 < base/arch/$arch/patches/patchfile 289 290 >2. $ mkdir $builddir && cd $builddir 291 292 >3. $ make -f ../vulcano/makefile srctree=../vulcano 293 294 >4. a GUI should pop up, allowing you to configure RTAI: 295 o default settings should be ok for most platforms 296 o in the "General" section, set your site values for the RTAI 297 installation directory (defaults to /usr/realtime) and 298 Linux kernel tree (defaults to /usr/src/linux). 299 o save and exit. 300 301 -- 302 303 At this point, you should see the typical output of a GNU configure 304 script. Your RTAI settings are being used to setup the 305 autoconf/automake-based build system. 306 307 -- 308 309 >5. $ make install 310 311 RTAI will be compiled then installed under the directory you specified 312 at configuration time (ensure that your shell can write to the 313 destination directory). 314 315 Remember to add $installdir/bin to your shell PATH variable, where 316 $installdir is your site value for the RTAI installation directory. 317 318 -- 319 320 >6. $ cd $installdir/testsuite/kern/latency 321 322 >7. $ ./run 323 324 If "sudo" is installed on your box, the application loader script 325 (rtai-load) will attempt to use it for running privileged commands 326 (e.g. insmod, rmmod et al.) If sudo is not available, just "su" 327 manually before running the run script. You should then see the 328 typical output of the latency calibration program running in kernel 329 space. Hit ^C to stop it. 330 331 -- 332 <rpm@xenomai.org> 333 12/5/2004