Author: Alejandro Lucero (alucero@os3sl.com)
	Date: May, 9 2007
	Version: 0.2


RTLINUX and Microblaze HOWTO

1. Introduction
2. Aplying the kernel patch
3. Compiling RTLinux modules
4. Target Installation
5. Running examples
6. Programming references


1. Introduction

This document tries to explain how to work with RTLinux on a Microblaze/uClinux
 system. The RTLinux porting to Microblaze was done by OS3 (www.os3sl.com)
engineer Alejandro Lucero under a spanish PROFIT project in 2005. 
The main page of the project is at:

	http://www.os3sl.com/microblaze_rtlinux.html 

Microblaze is a soft processor designed to be used inside FPGAs and it lacks some 
features present in generic powerful processors as  memory management unit 
(MMU) for virtual memory functionality. 

uClinux is a modification of the Linux kernel which enables this operating 
system to be used in noMMU processors as Microblaze. The uClinux porting to Microblaze was 
done by John Williams from the Queensland University

	http://www.itee.uq.edu.au/~jwilliams/mblaze-uclinux/

RTLinux is a microkernel which enables "hard" real time tasks to be executed in the same
system with Linux. Interrupts virtualization done by RTLinux avoids Linux impact
in real time code since the full Linux OS is another real time task for the 
RTLinux microkernel, but just with the lowest priority of execution.

Some modifications are necessary inside Linux kernel to allow this virtualization
 and RTLinux takes the control of the system when RTLinux modules are inserted 
in Linux through usual modules insertion mechanism. Then, you need two things 
for working with RTLinux:

	1) uClinux kernel patch
	2) RTLinux modules



	MICROBLAZE CONFIGURATION
	========================

	Microblaze is a soft processor which allows to be configured just as we need. If you
	are going to use RTLinux on it, you must configure the hardware divider.
	Other point where you must be careful is the OPB timer configuration. This IP BLOCK
	comes with an option to use one or two timers per IP BLOCK. RTLinux needs OPB timer
	to be configured with the two timers option enabled.



2. Aplying the kernel patch

Surely, if you are reading this doc you have a uCLinux for microblaze enviroment, 
and you have been involved in the uClinux kernel and apps compilation process.
The first step you need to do is to aply the RTLinux kernel patch for uCLinux.
You can find the patch file inside the RTLinux directory structure. Download 
the rtlinux package from 

http://www.os3sl.com/rtlinux_and_microblaze/download.html

Follow this steps to aply the patch:

	1) cd $(UCLINUX_DIST_DIRECTORY)/linux-2.4.x
	2) patch -p1 < rtlinux_patch

The patch modifies some kernel files and adds some new ones. The related files 
are not usually changed from new minor kernel versions, for example from 2.4.20 
to the 2.4.21. The current RTLinux patch has been tested with uCLinux 2.4.32. 
If some error arises when the patch is aplied, report it to alucero@os3sl.com

You must recompile the uCLinux kernel with the patch aplied and install it as 
you usually do. The mb-gcc version used should be 3.4.1.

	NOTE: This beta version works with Microblaze option USE_MSR_INSTR 
	      disabled






3. Compiling RTLinux modules

Once you have downloaded the rtlinux for microblaze package and aplied the kernel
patch, the RTLinux modules must be compiled. First of all, you must change 
RTLINUX variable in the Makefile:

	- Edit the file and set the RTLINUX variable pointing to the uCLinux 
	  kernel directory in your host machine. 

Other thing to do is to change the MUL_PERIOD variable located at 
schedulers/microblaze/rtl_time.c line 32. You must fix it based on your
microblaze configuration.


I assume you have the microblaze TOOLCHAIN installed and $PATH variable pointing to it.

	- type
		# make config 
		# make dep
		# make


After that you should have the next modules compiled:

	- rtl.o
	- rtl_time.o
	- rtl_sched.o
	- rtl_posixio.o
	- rtl_fifo.o



4. Target installation

You need to insert the RTLinux modules once uCLinux is running in the system. 
As a good Microblaze/uCLinux developer you know how to add aditional files to 
the default file system built during uCLinux compilation. The modules must be
in the file system or perhaps you just need to copy the modules to a directory in 
your host machine which is exported by NFS and mounted by uCLinux machine during 
boot. I recommend this last option during the development cycle since it is more
flexible and fast way to work with.

The rtl_fifo.o module enables to work with rtlinux fifos used for communication
between RT threads or between RT threads and Linux processes. There's a fifo
driver for Linux allowing Linux processes to use them just following the
standard API: open, read, write, close, ioctl. But, you need to create the 
special files for fifos devices in /dev directory:

	- Modify the uCLinux-dist/vendors/Xilinx/uclinux-auto/Makefile
	- Add the next lines after the original DEVICES variable definition:

		DEVICES +=  \
			rtf0,c,150,0	rtf1,c,150,1	rtf2,c,150,2	\
			rtf3,c,150,3	rtf4,c,150,4	rtf5,c,150,5	 

	
	If you need more fifos add more entries here.
		
	Built the uClinux romfs image after the modifications.





5. Running examples

Using RTLinux consists in inserting the RTLInux modules and the specific RT thread 
module/s. As a first point you can use the code in examples directory where we 
can install a RT thread "Hello world!" and another simple RT task using fifos.

Insert the RT basic modules:

	# insmod rtl.o
	# insmod rtl_time.o
	# insmod rtl_sched.o

And if you need fifos:

	# insmod rtl_posixio.o
	# insmod rtl_fifo.o


Hello world example: (from examples/hello directory)

	# insmod hello.o

	This is a periodic RT thread just printing a message each period.
	

Fifos example: (from examples/frank directory)

	# insmod frank_module.o
	# ./frank_app

	This is a usual RTlinux design with a RT thread and a Linux
	process changing data through fifos.




6. Programming references

	http://www.fsmlabs.com/a-linux-based-real-time-operating-system.html
	
	http://rtlinux.lzu.edu.cn/documents.html

	http://www.tldp.org/HOWTO/RTLinux-HOWTO.html

	http://www.linuxjournal.com/article/4444