Instructions for RTLinux

What is RTLinux?

RTLinux is a real-time extension to the Linux operating system created by FSMLabs, Inc. It provides hard real-time performance by implementing a micro-kernel which runs all of Linux as a subordinate thread. Users develop software which can run in that microkernel and thus run at a higher priority than Linux itself. DSCUD for RTLinux provides the full DSCUD API for software running inside that RTLinux microkernel.

The DSCUD API is only available in RTLinux kernel space, so if you must access the DAQ from user space you will have to implement your own methods for communication between RTLinux kernel space and Linux user space such as a real-time FIFO or shared memory. See the examples provided with the RTLinux kit or the RTLinux user manul for more information on this.

Supported RTLinux Versions

RTLinuxPro version 2.1 and 2.2 is supported. Support for other versions of RTLinuxPro 2.x may be available on request. Contact support@diamondsystems.com in inquire. Only the commercial version of RTLinux is supported. RTLinux/GPL and RTLinuxFree are not supported at this time.

Installing the Driver on your Development System

The driver is available as a simple tar gzip'd archive. To install the driver in this format you just extract the archive and move the new driver folder to the correct location on your system. Here is an example.

  $ tar zfx dscud-5.9.tar.gz
  $ mv dscud5 /usr/local/

The driver consists of a header file dscud.h which you include in your C program, and an RTLinux module dscud5.rtl which you run on your RTLinux system to provide the DSCUD API within RTLinux. Also included are example programs and a Linux kernel config file useful for recompiling the FSMLabs provided kernel for running on Diamond Systems CPU boards.

Compiling With the Driver

You compile RTLinux software for DSCUD using the build system provided by FSMLabs. They provide many example Makefiles which show how to compile software for their system. However, you must update the CFLAGS Makefile variable to point to the correct path to the dscud.h header file.

For RTLinuxPro 2.x you add the following near the top of your Makefile. This must come after your Makefile includes the rtl.mk build rules file provided with RTLinux. In this example you must change the MODULE variable to the name of your RTLinux module.

  MODULE=myprogram
  CFLAGS_$(MODULE).o := -I/usr/local/dscud5
  CFLAGS_$(MODULE).rtl := -I/usr/local/dscud5

Example Programs and DSCUD Demos

Due to the nature of RTLinux and its dependence on the pthreads API, the standard DSCUD demo programs provided on the Diamond Systems website will not compile on RTLinux as is. Instead you should use the example programs provided with the driver itself. These examples include Makefiles and can be used to start your own programs based on DSCUD.

However, the DSCUD Demos on our website are still very useful as example code for how to use the DSCUD API and can be converted to run on RTLinux by removing the user keyboard interaction and running the code in a RTLinux thread.

Installing the Driver on your Embedded System

To install DSCUD for RTLinux on your target system you should copy the dscud5.rtl module to your embedded system. This module should be run after the RTLinux environment is initialized or you will see "unresolved symbol" errors as DSCUD is unable to access the RTLinux API. The dscud5.rtl module must remain running to provide the DSCUD API within RTLinux.

Important Notes on DSCUD for RTLinux

These notes apply only to the RTLinux version of DSCUD.

1. The Diamond Systems Zircon-MM DAQ board interrupt driven features are not supported by DSCUD for RTLinux.
2. You must always call dscFreeBoard() before exiting your program. Failure to do this will "leak" driver resources and ultimately disable the driver. Any DSCB board handle allocated by dscInitBoard() must always be freed by calling dscFreeBoard(). Just calling dscFree() will not work.
3. The board specific driver functions are not thread safe. If you have multiple threads or programs interacting with the same board at the same time using DSCUD you must implement your own synchronization methods.
4. There is only a single instance of DSCUD running at a time. All user programs calling the functions provided by DSCUD are sharing the same memory space inside the driver. The driver uses a mutex to make dscInit(), dscFree(), dscInitBoard() and dscFreeBoard() safe across threads and programs. None of the other DSCUD functions are protected this way. However, it is safe to call DSCUD functions at the same time from multiple threads or programs as long as they are not communicating with the same board.
5. User interrupt functions are called directly from the interrupt service routine and run in a hard real-time interrupt context. This is a restrictive environment. See the RTLinux documentation for more information on features which are not available in an interrupt context.
6. Interrupt sharing support is not implemented in DSCUD for RTLinux. Each DAQ board must be assigned a unique IRQ for interrupt driven DAQ operations. Support for this feature may appear in future versions of the software.