NAME

       rtapi - Introduction to the RTAPI API

DESCRIPTION

       RTAPI  is a library providing a uniform API for several real time operating systems.  As of LinuxCNC 2.7,
       POSIX threads and RTAI are supported.

HEADER FILES

   rtapi.h
       The file rtapi.h defines the RTAPI for both realtime and non-realtime code.  This is a change from Rev 2,
       where the non-realtime API was defined in ulapi.h and used different function names.  The  symbols  RTAPI
       and  ULAPI  are  used  to  determine  which mode is being compiled, RTAPI for realtime and ULAPI for non-
       realtime.

   rtapi_math.h
       The file rtapi_math.h defines floating-point functions and constants.   It  should  be  used  instead  of
       <math.h> in rtapi real-time components.

   rtapi_string.h
       The  file  rtapi_string.h  defines  string-related functions.  It should be used instead of <string.h> in
       rtapi real-time components.

   rtapi_byteorder.h
       This   file   defines   the    preprocessor    macros    RTAPI_BIG_ENDIAN,    RTAPI_LITTLE_ENDIAN,    and
       RTAPI_FLOAT_BIG_ENDIAN as true or false depending on the characteristics of the target system.  It should
       be used instead of <endian.h> (userspace) or <linux/byteorder.h> (kernel space).

   rtapi_limits.h
       This  file  defines the minimum and maximum value of some fundamental integral types, such as INT_MIN and
       INT_MAX.  This should be used instead of <limits.h> because that header file is not available  to  kernel
       modules.

REALTIME CONSIDERATIONS

   Non-realtime code
       Certain  functions  are  not available in non-realtime code.  This includes functions that perform direct
       device access such as rtapi_inb(3).

   Init/cleanup code
       Certain functions may only be called from realtime  init/cleanup  code.   This  includes  functions  that
       perform memory allocation, such as rtapi_shmem_new(3).

   Realtime code
       Only  a  few  functions  may  be  called from realtime code.  This includes functions that perform direct
       device access such as rtapi_inb(3).  It excludes most Linux kernel APIs such  as  do_gettimeofday(3)  and
       many rtapi APIs such as rtapi_shmem_new(3).

   Simulator
       For  an  RTAPI  module  to  be  buildable  in the "sim" environment (fake realtime system without special
       privileges), it must not use any linux kernel APIs, and must not use the RTAPI  APIs  for  direct  device
       access  such  as rtapi_inb(3).  This automatically includes any hardware device drivers, and also devices
       which use Linux kernel APIs to do things like create special devices or entries in the /proc filesystem.

RTAPI STATUS CODES

       Except as noted in specific manual pages, RTAPI returns negative errno values for errors, and nonnegative
       values for success.

LinuxCNC Documentation                             2006-10-02                                      intro(3rtapi)