// caveat, not up to date

= Adapting LinuxCNC configure to multiple realtime environments = 

The current configuration options for LinuxCNC regarding 'real time
environments' are:

* --enable-simulator: - userland threads, HAL components are .so  shared objects, 
* --with-realtime=..rtai..: RTAI - kernel threads, HAL components are .ko kernel modules
* --with-realtime=..rtl..: RT linux - kernel threads (posix flavour), HAL components are .ko kernel modules (deprecated)

I believe the underlying assumptions at the time were: 

* a realtime enviroment uses kernel modules
* a system with userland threads and .so shared objects is not suited for real applications, just a 'simulator'
* consequently the simulator has no hardware drivers, since it is, well, a simulator and hence useless for real work.
* a simulator does not do any hardware I/O, so there is no need for setuid root programs (ioperm(2))

Several options for realtime Linux have appeared since, which are:

* Linux with the RT_PREEMPT kernel patch, to improve latency but otherwise remain with the user process programming paradigm - with some 'RT fortification system calls' peppered in

* Xenomai, which is similar to RTAI with it's hypervisor approach to  RT threads, but supports BOTH a kernel and a user process paradigm for 'realtime processes', albeit with a slight performance advantage  for in-kernel processes.

These two platforms provide new options:

* With RT_PREEMPT, the current 'simulator process' (rtapi_app) becomes 'realtime fortified' (locking down memory, scheduling priorities etc) but otherwise remains a user process; see for instance the current hardened rtapi_app for rt_preempt:  http://git.mah.priv.at/gitweb/emc2-dev.git/blob/6640ed5d6ef20c582bf515a7ac7eb527ce486e19:/src/rtapi/linux_rtapi_app.cc

* while the option so far has not explored in the context of LinuxCNC, it seems entirely reasonable to employ normal Linux kernel threads for RTAPI functions; this has been done in the past, for instance with KHTTPD (in-kernel HTTP server to improve performance), and would be an interesting route to explore with RT_PREEMPT.

* with Xenomai, both paradigms are possible: kernel RT threads and kernel modules,  as well as userland RT threads and .so shared object modules

Also, given reasonable latency of one of the user RT process schemes, it becomes entirely feasible to use user-mode device drivers.

It should be obvious that these new options cannot be consistently
adressed with the current configuration assumptions. Realtime does not
imply kernel threads exclusively anymore, and User process mode does
not imply 'useless so no drivers' please.  Also, user RT modules will do I/O, hence rtapi_app needs to be setuid root in this case. 

As work progresses on different branches in parallel, configuration
problems will likely be solved ad-hoc (ad-hack?) and conflicts  will
arise during merge, also with the consequence of an even more incoherent set of options.


== The configuration options have been changed as  == 

(for now, this only applies to http://git.mah.priv.at/gitweb/emc2-dev.git/shortlog/refs/heads/integration-configuration-dev as it is not merged yet):

--with-realtime will be deprecated in its current form, and replaced by:

--with-threads=<arg>, arg being one of:

* posix will be implied by the current '--enable-simulator' option, meaning: simulator rtapi_app, no RT hardening, user mode .so modules

* rt-preempt as above, but hardened rtapi_app.

* rt-preempt-kernel: this would imply: an rt-preempt kernel,  kthreads for RTAPI execution, and .ko modules.

* xenomai: as posix, but using xenomai user RT process hardening (rouhgly as used in the miniemc2 project: http://code.google.com/p/miniemc2/)

* xenomai-kernel: very similar to current RTAI threads.

* rtai: as before

Build system: there are two styles, 'kbuild' (kernel modules) and 'user-dso' (userland shared objects). The thread style implies a build system: posix, xenomai, rt-preempt imply 'user-dso', the others imply 'kbuild'.

Building hardware drivers can be controlled with --enable-drivers. It is default 'yes' except for --with-threads=posix. Some hardware drivers will build as kernel modules only, some as user shared objects, some may build as both; in that case the Submakefile needs to test for BUILD_SYS having the proper value.

The cpp symbols 'SIM', 'SIMULATOR', and 'RTAPI_SIM' have been removed as they do not make sense any more. A simulator configuration is '--with-threads=posix', which is now implied by --enable-simulator.

The shell/Makefile variables are:

THREADS= one of: POSIX, RT_PREEMPT, XENOMAI, XENOMAI_KERNEL, RTAI

BUILD_DRIVERS=yes or no

BUILD_SYSTEM=kbuild or user-dso


THREADS is reflected in config.h as one of the following defined:

RTAPI_POSIX

RTAPI_RT_PREEMPT

RTAPI_XENOMAI

RTAPI_XENOMAI_KERNEL

RTAPI_RTAI



BUILD_DRIVERS is conditionally defined in config.h too.


BUILD_SYSTEM is reflected in config.h as either

BUILD_SYSTEM_KBUILD or

BUILD_SYSTEM_USER_DSO defined.

== hal_parport ==

The experimental usermode parport driver from master: src/hal/simdrivers has been integrated into the main hal_parport.c/.h code using conditionals from above.

== Make setuid: ==

this has been adapted to take care of the case 'threads=posix and drivers enabled', which requires rtapi_app to be setuid root.



Michael Haberler