NAME

       HAL - Introduction to the HAL API

DESCRIPTION

       HAL  stands  for  Hardware Abstraction Layer, and is used by LinuxCNC to transfer realtime
       data to and from I/O devices and other low-level modules.

       hal.h defines the API and data structures used by the HAL.  This file is included in  both
       realtime and non-realtime HAL components.  HAL uses the RTPAI real-time interface, and the
       #define symbols RTAPI and ULAPI are used to distinguish between realtime and  non-realtime
       code.   The  API  defined in this file is implemented in hal_lib.c and can be compiled for
       linking to either realtime or non-realtime HAL components.

       The HAL is a very modular approach to the low level parts of a motion control system.  The
       goal of the HAL is to allow a systems integrator to connect a group of software components
       together to meet whatever I/O requirements he (or she) needs.  This includes realtime  and
       non-realtime  I/O, as well as basic motor control up to and including a PID position loop.
       What these functions have in common is that they  all  process  signals.   In  general,  a
       signal  is a data item that is updated at regular intervals.  For example, a PID loop gets
       position command and feedback signals, and produces a velocity command signal.

       HAL is based on the approach used to design electronic circuits.  In electronics, off-the-
       shelf components like integrated circuits are placed on a circuit board and their pins are
       interconnected to build whatever overall function is needed.   The  individual  components
       may  be  as  simple  as  an  op-amp,  or  as  complex as a digital signal processor.  Each
       component can be individually tested, to make  sure  it  works  as  designed.   After  the
       components  are  placed  in  a  larger  circuit,  the signals connecting them can still be
       monitored for testing and troubleshooting.

       Like electronic components, HAL components have pins, and the pins can  be  interconnected
       by signals.

       In  the  HAL, a signal contains the actual data value that passes from one pin to another.
       When a signal is created, space is allocated for the data value.  A pin on the other hand,
       is a pointer, not a data value.  When a pin is connected to a signal, the pin's pointer is
       set to point at the signal's data value.  This allows the component to access  the  signal
       with  very  little  run-time overhead.  (If a pin is not linked to any signal, the pointer
       points to a dummy location, so the realtime code doesn't have to deal with  null  pointers
       or treat unlinked variables as a special case in any way.)

       There  are  three  approaches  to writing a HAL component.  Those that do not require hard
       realtime performance can be written as a regular non-realtime  process.   Components  that
       need  hard realtime performance but have simple configuration and init requirements can be
       done as a single realtime component, using either  pre-defined  init  info,  or  load-time
       parameters.   Finally,  complex  components  may  use  both  a  realtime component for the
       realtime part, and a non-realtime process  to  handle  INI  file  access,  user  interface
       (possibly including GUI features), and other details.

       HAL uses the RTAPI/ULAPI interface.  If RTAPI is #defined, hal_lib.c generates a realtime-
       capable library (to be insmoded into the kernel or linked  to  a  realtime  process)  that
       provides  the  functions  for all realtime components.  The same source file compiled with
       the ULAPI #define would make a non-realtime library that would be linked  to  non-realtime
       code to make non-realtime executables.  The variable lists and link information are stored
       in a block of shared memory and protected with mutexes, so that  realtime  components  and
       non-realtime programs can access the data.

REALTIME CONSIDERATIONS

       For an explanation of realtime considerations, see intro(3rtapi).

HAL STATUS CODES

       Except  as  noted  in specific manual pages, HAL returns negative errno values for errors,
       and non-negative values for success.

SEE ALSO

       intro(3rtapi)