README.INSTALL

Basic introduction to RTAI
================================

RTAI uses the world's fastest Real-time + Linux combination, featuring
real-time interrupts that are dispatched immediately.
An exclusive feature to the x86 32-bit architecture is that it has the
potential of completely avoiding the dispatching of critical
internal timers and interprocessor scheduling interrupts by vectoring them
directly to their handlers. This option heavily increases
real-time performances on a variety of machines and comes by default,
however it can easily be disabled using the ncurses menuconfig interface.

In order to use the above features, you must be already running an
RTAI (Real-time Application Interface) patched Linux kernel with
IPIPE (Interrupt Pileline) enabled.

Please note that only x86-based (32-bit and x86_64) architectures
have been tested with this branch.

This README.INSTALL file was written for x86-based architectures only.
If you are using ARM or any other architecture, YMMV (Your mileage may vary.)



How to build RTAI (Written by Alec Ari / NTULINUX)
================================

To build, compile, and install RTAI, follow the steps below carefully.

Please note: If you are not using the 3.4.55 kernel, replace ALL references to that version,
to the version of the kernel source you downloaded.

If you are a highly experienced Linux poweruser, you can ignore 99% of this, but do not
file a bug report if you have not built the kernel and RTAI userspace in correlation to this
very README.INSTALL file.

   Tip:
   $ signs are commands that are meant to be run as your regular user,
   i.e. without elevated root privileges.

   # signs are meant to be run as root or with root privileges,
   using sudo, or su -c 'command here>


1.) Download the RTAI source code using git:

   $ cd ~/ && mkdir -p devel && cd devel
   $ git clone https://github.com/ShabbyX/RTAI.git


2.) Download, patch, and install your RTAI-enabled kernel.

Please note: For quite awhile, all the commands are run as root until you reach near the bottom
so feel free to just run "su - root" (without quotes) now.

In this example, we use the 3.4.55 kernel:

   # cd /usr/src
   # wget https://www.kernel.org/pub/linux/kernel/v3.x/linux-3.4.55.tar.xz
   # tar xf linux-3.4.55.tar.xz
   # ln -sfv linux-3.4.55 linux
   # cd linux
   # make mrproper

Please note: Replace <your user> with your actual NON-ROOT user account name. If unsure,
running the following command may help, especially if you are on a single user machine:

$ ls /home

   # cp -prvL /home/<your user>/devel/RTAI/base/arch/x86/patches/hal-linux-3.4.55-x86-1.patch /usr/src/
   # patch -p1 < ../hal-linux-3.4.55-x86-1.patch

Please note: It is necessary to know your CPU architecture before proceeding.
Run the following command to determine if you are on a 64-bit or 32-bit Linux distribution:

   $ uname -m

Copy the kernel config corresponding to your architecture (32-bit or 64-bit)
to the root of your kernel source directory:

Please note: Replace <your user> with your NON-ROOT user account name.
	 (2) Replace <insert_arch> with either "32" or "64" (without quotes)

   # cp -prvL /home/<your user>/devel/RTAI/base/arch/x86/configs/rtai_<insert_arch>_defconfig /usr/src/linux/

   # make menuconfig

Load the RTAI-optimized kernel config by selecting
"Load an Alternate Configuration File" and type in either
"rtai_32_defconfig" or "rtai_64_defconfig" (without quotes)
depending on which config file you copied over that corresponded to your architecture.

3.) Configure the kernel for RTAI.

Configuring the kernel here is mandatory, but should not take long at all, especially
if you are familar with configuring custom kernels. If not, do not worry. The kernel
you have previously copied is a great baseline for RTAI, but a few options need to be
manually configured in order for it to boot.

*IMPORTANT: IT IS GUARANTEED THAT THE RTAI KERNEL CONFIG AS-IS WILL NOT WORK ON ANY SYSTEM!*

*IMPORTANT: DO NOT MODIFY ANY OTHER SETTINGS MENTIONED HERE
UNLESS YOU ARE SURE YOU KNOW EXACTLY WHAT YOU ARE DOING!*

*IMPORTANT: DO NOT COMPILE ANY NEW OPTIONS AS MODULES (M) AS IT CAN
BE VERY DANGEROUS, ESPECIALLY WHEN DEALING WITH SCSI CONTROLLER SUPPORT!
IT IS HIGHLY RECOMMENDED, SUGGESTED, AND ENCOURAGED TO COMPILE ALL NEW OPTIONS
INTO (Y) THE KERNEL! A "*" SIGN IS GOOD, AN "M" SIGN IS BAD!*

To determining your basic hardware, open up a new tab in the terminal or a new
terminal window and run the following command. Note that some systems require
root access to execute "lspci" so to be safe, we suggest it here:

   # lspci -k | grep "driver in use"

Enabling netork support for your ethernet controller:

Device drivers ->
   Network device support ->
   Ethernet driver support

For example, for the Realtek 8169 controller (r8169) commonly found on many modern
AMD motherboards such as the 785/880/970-990, scroll down to "Realtek devices" using the
arrow keys on your keyboard, and enabling "Realtek 8169 gigabit ethernet support" by
pressing "Y" on the highlighted option to compile the driver into the kernel.

Enabling I2C device support for your hardware:

Device drivers ->
   I2C support ->
   I2C Hardware Bus support

Enabling SATA / PATA / SCSI / Hard drive support for your hardware:

Please note: If your hard drive controller module is not in the
"Serial ATA and Parallel ATA drivers" section at all, look in
"ATA/ATAPI/MFM/RLL support (DEPRECATED)"

Device drivers ->
   Serial ATA and Parallel ATA drivers

Please note: If you specifically use AHCI for your Solid State Drive (SSD)
or Hard Disk Drive (HDD) then you do not need to enable ATA SFF support.
ATA SFF support simply shows more possible drivers. It is recommended to
turn on support for any and ALL drive controllers mentioned in the lspci -k command.

After you are done, press tab or use the right arrow key and toggle back to the
main kernel configuration screen. At the bottom you should see an option that says
"Save an Alternate Configuration File." Highlight the option and press enter,
and make sure the contents in the field box says ".config" (without quotes.)
Press enter again, and proceed with compiling the kernel.

4.) Compiling and installing the kernel:

   Tip: The following "make" command automatically detects the number of CPU cores
   and compiles the kernel with however many jobs that number might be. This speeds up
   compiling times on SMP systems.

   # make -j$(cat /proc/cpuinfo | grep processor | wc -l)
   # make modules_install install

5.) Update your boot loader. If you are an experienced GRUB user, it is recommended to
modify the grub.cfg or menu.lst file by hand, to remove unncessary bloat from the file,
as grub2-mkconfig -o /boot/grub2/grub.cfg (or whatever you use to automatically generate it)
can cause serious pollution and in rare cases, impact RTAI performance.

Depending on your Linux distribution, one of these commands would do it for you:

   # grub2-mkconfig -o /boot/grub2/grub.cfg
   # grub2-mkconfig -o /boot/grub/grub.cfg
   # update-grub

6.) Reboot into your new kernel and be sure you select it at boot time!

7.) Compile RTAI userland / userspace:

   $ cd ~/devel/RTAI
   $ autoreconf -i
   $ make menuconfig

*IMPORTANT: IF YOU ARE USING A MULTI-CORE SMP SYSTEM, IT IS REQUIRED
TO ENTER IN THE EXACT NUMBER OF CPU CORES YOUR SYSTEM HAS! To do this,
go to "Machine (x86 / x86_64)" and select "Number of CPUs (SMP-only)"
then enter the number of CPU cores you have into the field box.*

   $ make

8.) Install RTAI (default is /usr/realtime)

   # make install


RTAI is now fully installed! If you have any questions, comments, complaints, or issues,
feel free to contact the author of this file directly at <neotheuser@ymail.com>
or leave a comment somewhere on the github repository and I will assist you the best I can.