"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
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.
The following drivers are built and tested:
- hm2_7i43 (tested with 7i43-4)
- hm2_pci (tested with 5i20, 5i25, 5i22)
- hm2_eth (tested with 7i80hd)
- hal_ppmc (tested by dgarr)
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
Then in another terminal, interact with halcmd
$ 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.
- Building "realtime" code? defined(RTAPI)
- APIs specified as "realtime only" (e.g., rtapi_parport_get) are available
- Building "userspace" code? defined(ULAPI)
- Not all RTAPI APIs available
- Building on a Linux operating system? defined(__linux__)
- Building this code in kernel space? defined(__KERNEL__)
- Realtime resides in kernelspace? rtapi_is_kernelspace()
- Underlying OS provides realtime guarantees? rtapi_is_realtime()
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.