***** SUPPORT FOR MATHWORKS SIMULINK-REAL_TIME_WORKSHOP IN RTAI USER SPACE *****

This directory contains the support files required to run the Real Time Workshop
API for vxWorks as distributed in Matlab 6.0 Relese 12. It is just a beginning 
and it is promptly distributed to have it tested by other users. 
We have choosen to use this release of Matlab because it implements the upload 
mechanism that allows to print the output on screen while the simulation is 
running.

The few tests we've carried out so far are both for single rate execution 
and for multi tasking in external mode, run both locally and remotely. 
Data logging on file has been also tested.
Comments and suggestions are welcomed.

The base choice made has been to use what found in Matlab as it is. In order
to avoid duplicating Roberto Bucher work on the same stuff for RTAI in kernel 
space (see http://A.die.supsi.ch/~bucher), we have decided to develop a 
user space porting based on hard real time under LXRT.

To this end the easiest choice has been to use the vxWorks support distributed
with Matlab unchanged, with the added benefit of showing how RTAI can easily 
do also what such an OS does.
The only change has been the adaption of the related template makefile to 
RTAI, and you'll find it in this directory. All the rest are support c and h
files required to have RTAI APIs mimicking vxWorks.

Further on it is likely we will make an RTAI proper adaption of all the
support code for the real time workshop. Before doing that we'd like to see
how this simpler compatibility port works and be sure that we can freely
distribute such a port along the line of RTAI OSS policy, i.e. LGPL.
It is possible that we will live with it for ever.
For the moment, if you have Simulink-RealTimeWorkshop, what found here should 
allow you to freely use it without any problem. For an easier use we have 
inserted our template makefile in this directory, along with our Simulink DAQ
drivers and a fixed rt_main for Tornado/vxWorks.

Here you'll find also the drivers for a couple of DAQ boards, i.e. 
Intelligent_Instrumentation_tested and Quanser_not_tested. The style adopted,
i.e. simple inlines and defines to be used directly in the related Matlab 
drivers, suites our needs. You can adapt or change it for your boards at hand. 

It should be noticed that our LXRT implementation enables any user to freely
access hard IO. So you need not to be a super user to develop and use your 
applications, but root permission is still required to install the needed RTAI 
support modules. The script to install the necessary support modules is runrtw. 
Obviously stoprtw makes the opposite job.

To run the application use the following command line:

 ./prog_to_run nohrt p=23 o=5 "optStr", whatever order;

  nohrt to run soft realtime (for dubugging?),
  p=priority(1-99) no spaces,
  o=overuns_check_intervali(seconds) no spaces
  optStr string of matlab commands like "-tf inf -w" that means
         run until a stop signal is sent and wait for a signal to start.
  If not given defaults are: hard real time, p=1, o=5.
 
In the subdirectory /matlab you will find:

      grt_rtai.tlc is Target Language Compiler file to be used
		   for RTAI. 
                   This file must be moved to the directory:

                   $(MATLAB_ROOT)/rtw/c/grt

      grt_rtai.tmf is the template Makefile to be used in Matlab 
                   RealTimeWorkshop.
                   This file must be moved to the directory:

                   $(MATLAB_ROOT)/rtw/c/grt

                   In this file you should check and eventually modify only the 
                   following list of directories, in order to be compatible with
                   your personal PC configuration:
		   
                   LINUX_HOME = /usr/src/linux
                   RTAI_HOME  = /home/rtai4
                   
                   In the make file you will find the following line:
                   
                   DEB_OPT = # -DDBGPRT
                   
                   If you activate the flag  -DDBGPRT you will see a lot of info
                   messages regarding all the creation and deleting of the 
                   different RTAI support tasks.

     rt_main.c    is the patched tornado/vxWorks main that must go in the 
                  directory $(MATLAB_ROOT)/rtw/c/tornado. The correction 
		  relates to an error in the parsing of the option string. 
                  You should also comment the line 128 of rt_main.c:

                  #define STOPONVERRUN

                  In this way the execution won't stop at the starting when 
                  several overrun could happen under very fast timing. 
                  In any case you will get the messages on screen and there is 
                  an overrun counter that shows you what happened (see also 
                  the log file rtw_log).
     
    setup.m       is a matlab script that simply adds the drivers directory to 
                  the matlab path.

In the subdirectory /drivers you will find the drivers  and  the librarys of 
blocks (*.mdl) for Simulink.

In /example there are finally a couple of simple tests:
  
     upldl.mdl   does't need the support of any board. Is composed of two sine 
                 waves that are plotted in output. You can test the 
                 possibility to change the parameters and the uploading 
                 mechanism for plotting the outputs.
    
  simpleio.mdl   is a simple example of I/O with the Intelligent 
                 Instrumentation card. A sine signal is sent to the D/A card 
                 and is acquired back by the A/D converter. 

  multirate.mdl  6 tasks generating sine waves. They can be run either in single
		 tasking or multitasking mode, according to how you compile them
		 in Matlab. 

As said comments/bug reports are welcomed, refer to quaranta@aero.polimi.it.

Giuseppe Quaranta
