Coldfire port of RTAI
=====================

RTAI has been ported also to Coldfire, a Motorola 68000 core
microcontroller. This README is a verbatim copy of its parent at:

  http://www.rcs.ei.tum.de/~kuhn/uclinux/coldfire/tarifa/20020227,

where you should go for downloading the related material. Thanks to
Bernhard Kuhn (bkhun@lineo.com) for the port.

Paolo Mantegazza.



Introduction
===========

This document describes how to set up the Real Time Application Interface
(RTAI) on the Motorola MCF5272C3 Evaluation Board also known as "Tarifa".

RTAI is an linux kernel extension that allows to preempt the linux kernel
at any time to perform hard real time operations with interrupt latencies
in the microseconds range. Remember: even with special efforts, the
standard linux kernel can have latencies of several milliseconds. So for
creating linux based machine control or data aquisition systems, RTAI is
mandatory.

Unlike the implementations of RTAI for x86, PPC and MIPS, the Coldfire
version is not based in the "deferred interrupt mechanism" but uses the 25
year old capability of the MC68000 architecture to prioritize interrupts in
hardware by the interrupt controller. In the current implementation, Linux
interrupts are assigned up to interrupt priority level 4 while RTAI
interrupts can have interrupt priority levels 5 and 6 (7 is an NMI and
shouldn't be used for normal operation). When Linux is doing cli(), then
all interrupts up the priority level 4 are disabled - means: all standard
linux interrupts are disabled while real time interrupts may preempt the
kernel at any time, even in the early stages of standard linux interrupt
processing (or even during processing hard real time interrupts of lower
priority).

The usual jitter measured on a 66 MHz MCF5272 processor is about 5
Microseconds. The maximum jitter is about 15 microconds. The tarifa can
stand a 20 KHz periodic task and a 5 KHz task in oneshot mode without any
problems.



Installation
============

This document assumes that you already have installed the necessary
m68k-elf-toolchain and that you have uClinux up and running on the
MCF5272C3 using uClinux-dist-20020220 from www.uclinux.org. Ensure that the
kernel is configured for loadable modules and that busybox is configured
with module support (insmod/rmmod/lsmod).

To get RTAI up and running, perform the following commands:


# download rtai and the coldfire specific patches:

MCF_RTAI=http://www.rcs.ei.tum.de/~kuhn/uclinux/coldfire/tarifa/20020227
DL_PATH=/tmp/rtai_downloads
install -d $DL_PATH
cd $DL_PATH
wget -c http://www.aero.polimi.it/RTAI/rtai-24.1.8.tgz
wget -c $MCF_RTAI/rtai-24.1.8_coldfire.patch.bz2
wget -c $MCF_RTAI/rthal_coldfire.patch.bz2

# Define the path to your uClinux-distro:

UC_DIST=$HOME/uClinux-dist 


# Patch the kernel and recompile it:

cd $UC_DIST/linux-2.4.x
bunzip2 -cd $DL_PATH/rthal_coldfire.patch.bz2 | patch -p1
cd ..
make clean && make


# Unpack rtai, apply the patch and perform the configuration:

cd $UC_DIST
tar -xzf $DL_PATH/rtai-24.1.8.tgz
cd rtai-24.1.8
bunzip2 -cd $DL_PATH/rtai-24.1.8_coldfire.patch.bz2 | patch -p1
make ARCH=m68knommu CROSS_COMPILE=m68k-elf- \
  LINUXDIR="$UC_DIST/linux-2.4.x" menuconfig


# Now just press <enter> when being asked for the location of the
# Linux source tree and make the configuration look like this:
#
#    [ ] Enable floating point support
#    < > SMP scheduler
#    <M> UP scheduler
#    < > MUP scheduler
#    <M> POSIX API support
#    --- Select yes to link memory manager into schedulers
#    <*> RT memory manager
#    <M> Fifos
#    < > Real-Time serial driver (rt_com)
#    <M> Compile tests
#    [*] Compile Examples
#    [ ] True Periodic Timer (NEW)


# Save the configuration and exit. Now build the rtai modules
# and examples by simply typing:

make


# Copy the basic RTAI modules to the target filesystem:

install -d $UC_DIST/romfs/lib/modules/rtai
cp modules/*.o $UC_DIST/romfs/lib/modules/rtai
m68k-elf-strip -g $UC_DIST/romfs/lib/modules/rtai/*.o
rm $UC_DIST/romfs/lib/modules/rtai/rtai_sched_up.o # doubled because of
link


# Copy the preemption example to the target filesystem:


cp examples/preempt/ex_preempt.o $UC_DIST/romfs/lib/modules/rtai
m68k-elf-strip -g $UC_DIST/romfs/lib/modules/rtai/*.o
cp examples/preempt/check $UC_DIST/romfs/bin


# Create the real time fifo device nodes:

cd $UC_DIST/romfs/dev
for i in 0 1 2 3 4 5 6 7; do touch "@rtf$i,c,150,$i"; done


# Create the new image:

cd $UC_DIST
make image



Execution of the Demo Application
=================================

Now reset the MCF5272C3, download the new image ("dn" and "go 20000") and
perform the following commands on the target system:

/> insmod rtai
/> insmod rtai_sched
/> insmod rtai_fifos
/> insmod ex_preempt
/> check


You should now get a screen dump like this:

> F r 0 23818
> F s 0 23820
> F r 0 23822
> F s 0 23824
> F r 0 23826
> F s 0 23828
> S s 0 23829
> F r 0 23830
> F s 0 23832
> F r 0 23834
> F s 0 23836
> F r 0 23838
> F s 0 23840
> S r 0 23841
> F r 0 23842
> F s 0 23844
> F r 0 23846
> F s 0 23848
> F r 0 23850
> F s 0 23852
> S s 0 23853

Congratulations, you are done!


Some more outputs from /proc/rtai:


/> cat /proc/rtai/rtai

RTAI Real Time Kernel, Version: 2.3.xx

    RTAI mount count: 1 

RTAI IRQs
72
RTAI sysreqs in use:
1 2 3 4 5


/> cat /proc/rtai/scheduler
                                           
RTAI Uniprocessor Real Time Task Scheduler.

    Calibrated CPU Frequency: 1000000 Hz
    Calibrated 8254 interrupt to scheduler latency: 27000 ns
    Calibrated one shot setup time: 0 ns
                                   
Number of RT CPUs in system: 1

Priority  Period(ns)  FPU  Sig  State  Task  RT_TASK *
------------------------------------------------------
0         4000000     No   No   0x5    1     002dd640
1         24000000    No   No   0x5    2     002dd3a0
TIMED 
> 002dd640 > 002dd3a0
READY


/> cat /proc/rtai/fifos
RTAI Real Time fifos status.

fifo No  Open Cnt  Buff Size  handler  malloc type
-----------------------------------------
0        1         14000      308060     kmalloc



More Demo Applications
======================

There are two MCF5272C3 specific demos (rtaidemos.tgz) where you can check
the jitter with i.e. an osciloscope. Install them with the following
commands:

cd $DL_PATH
wget -c $MCF_RTAI/rtaidemos.tgz

cd $UC_DIST
tar -xzf $DL_PATH/rtaidemos.tgz
cd rtaidemos
make install
cd ..
make image

The 1 KHz (oneshot) an 10 KHz (periodic) signal respectivly can be captured
from J5/B31.


Status
======

This latest version of the RTAI port to Coldfire has not been vastly
tested. However, there is a good chance that this
rtai-24.1.8/uClinux-2.4.17-uc0 based version may be rather stable since it
is derived from the very well tested rtai-24.1.6a/uClinux-2.4.10-uc0
version delivered with Lineo's BSP for its Embedix/SDK.

Tested features:

o Scheduler
o Fifos
o Shared Memory
o preempt example
o stress example

Most examples included in the RTAI distribution are compiling, but only few
of them have been tested.

Missing features:

o LXRT
o RT_COM
o Trapped exceptions



Dragonballs and other Coldfires
===============================

The support for Coldfire 5307 is basically included in the current patch
for rtai, but was not tested at all, but just copyied over from the older
24.1.6a version - YMMV.

There are experimental versions of RTAI for Dragonball (68EZ328 and
68VZ328). These will be published once i find the time to put the files
together in usable packages ...



RTAI Shared Memory Module for uClinux
=====================================

uClinux doesn't support Memory Management Units. So the Shared Memory
Support for RTAI had be rewritten from scratch - but as life is much easier
without MMU on that level, the basic implementation was done in less than
two hours.



Know problems
=============

Probably there are two files in your m68k-elf-toolchain missing or don't
provide the correct content in order to compile rtai/uclinux.  Grap and
install 'em (as root):

cd $DL_PATH
wget -c $MCF_RTAI/specs
wget -c $MCF_RTAI/sched.h
cp specs /opt/uClinux/lib/gcc-lib/m68k-elf/2.95.3
cp sched.h /opt/uClinux/m68k-elf/sys-include



Warranty
========

As allways, there are no guaranties and the author (or Lineo) cannot be
held responsible for any damage that may be caused when using this software
...



Thanks
======

This work was 100% funded by Lineo Inc. Additional thanks are addressed to
Paolo Mantegazza, the initiator of RTAI. Also, i want to thank the most
active uClinux maintainers, David McCullough and Greg Ungerer, for their
work on the base uClinux distribution.


Best regards

Bernhard Kuhn, Software Engineer, Lineo Inc.


-- 
Bernhard Kuhn, Software Engineer, Lineo Inc. (Where Open Meets Smart)
