LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org


"uspace" is a new implementation of RTAPI which uses userspace POSIX APIs for scheduling. It can be run in a mode which provides access to hardware and realtime scheduling guarantees, or it can be run in a "sim-like" mode. When used with the RT-PREEMPT kernel, max latency on most hardware is enough for "servo-cycle-only" systems, and in some systems may be good enough for software step generating systems. (latency reports on a small range of systems seem to range from 12us to 90us)

"uspace" is desirable because it allows LinuxCNC to work with a kernel shipped by Debian, and enables new hardware interfaces such as ethernet (mesa 7i80).

The work was mostly done by JeffEpler, with help from a variety of the usual suspects. Some code is adapted from "unified-build-candidate-3", an ancestor branch of the machinekit project.

Because of the way the machinekit project's git history was structured, it is not possible to merge just their userspace rtapi implementation. That is why JeffEpler chose to make a fresh implementation instead.

Comparison of RTAPI implementations

  Hardware access
Name in version.. Kernelspace Realtime guarantee PCI ISA Ethernet
rtai all linuxcnc Y Y Y Y N
sim 2.6 and earlier N N N N Y
uspace master branch N Y Y no memory-mapped Y
unified machinekit N Y Y no memory-mapped Y


Everything has been merged with the linuxcnc master branch. The last version based on the 2.6 branch is preserved at jepler/rtos-uspace-for-2.6 (without ethernet) and jepler/hm2-eth-for-2.6 (with ethernet, but non-ethernet hm2 card support broken).


In addition to the regular requirements of linuxcnc in sim mode, libudev-dev is required to build, and a -rt kernel is required for realtime scheduling guarantees. libpth-dev is no long required.

All testing to date has been done on Debian 7 "Wheezy" with the 3.2.0-rt-amd64 and 3.2.0-rt-686-pae kernels. Ubuntu used to offer -rt kernels, but no longer appears to do so.

Getting the code

The code is on git.linuxcnc.org in the master branch.

Configuring and building

 ./configure --with-realtime=uspace
 sudo make setuid
If you do not "sudo make setuid", then linuxcnc runs without realtime guarantees and without access to hardware. If you run "sudo make setuid", then linuxcnc runs with access to hardware. If you run "sudo make setuid", and run with a RT-PREEMPT kernel, then linuxcnc runs with access to hardware and with realtime guarantees.

Hardware support

The following drivers are built and tested:

The other PCI drivers will need adaptation to the hostmot2-style PCI driver registration before they work.

Other EPP drivers should only require a small amount of work to adapt. (except that's only pluto, which is likely to be removed during the 2.7 development cycle)

ISA drivers are probably not worth tinkering with. Any which use memory-mapped I/Os? would require additional API work.

Using a debugger

Since f396a90, rtapi_app will refuse to run under "sudo" unless a non-root "fallback UID" is specified in the environment variable RTAPI_UID. In order to debug rtapi_app (e.g., with gdb), start rtapi_app in one terminal:
$ sudo env RTAPI_UID=`id -n` gdb rtapi_app
... # set breakpoints or whatever
(gdb) run
Then in another terminal, interact with halcmd (not halrun):
$ halcmd -f testfile.hal
$ halcmd stop
$ halcmd unload all
There's probably a slightly more irritating sequence that can be used to debug rtapi_app when running linuxcnc instead of halcmd, but in the case that you need to debug motion remember that you can also just skip "sudo make setuid" and use a sim-only configuration.

What kind of system is this?

While the <rtapi_xxx.h> headers provide the portability APIs required by most realtime components, sometimes it's necessary to make decisions based on the details of the system. Here are some checks that you may find it useful to perform.

Preprocessor checks

Runtime checks

Further testing and feedback

If you try uspace and have feedback of any kind, or if you find any evidence it affects rtai realtime, please post to the developers' mailing list.

LinuxCNCKnowledgeBase | RecentChanges | PageIndex | Preferences | LinuxCNC.org
This page is read-only. Follow the BasicSteps to edit pages. | View other revisions
Last edited August 17, 2014 4:50 pm by JeffEpler (diff)
Published under a Creative Commons License