1  .TH intro "3hal" "2006-10-12" "LinuxCNC Documentation" "HAL"
 2  .SH NAME
 3  
 4  hal \- Introduction to the HAL API
 5  
 6  .SH DESCRIPTION
 7  
 8  HAL stands for Hardware Abstraction Layer, and is used by LinuxCNC to transfer
 9  realtime data to and from I/O devices and other low-level modules.
10  
11  \fBhal.h\fR defines the API and data structures used by the HAL.  This file is
12  included in both realtime and non-realtime HAL components.  HAL uses the RTPAI
13  real time interface, and the #define symbols RTAPI and ULAPI are used to
14  distinguish between realtime and non-realtime code.  The API defined in this
15  file is implemented in hal_lib.c and can be compiled for linking to either
16  realtime or user space HAL components.  
17  
18  The HAL is a very modular approach to the low level parts of a motion control
19  system.  The goal of the HAL is to allow a systems integrator to connect a
20  group of software components together to meet whatever I/O requirements he (or
21  she) needs.  This includes realtime and non-realtime I/O, as well as basic
22  motor control up to and including a PID position loop.  What these functions
23  have in common is that they all process signals.  In general, a signal is a
24  data item that is updated at regular intervals.  For example, a PID loop gets
25  position command and feedback signals, and produces a velocity command signal.  
26  
27  HAL is based on the approach used to design electronic circuits.  In
28  electronics, off-the-shelf components like integrated circuits are placed on a
29  circuit board and their pins are interconnected to build whatever overall
30  function is needed.  The individual components may be as simple as an op-amp,
31  or as complex as a digital signal processor.  Each component can be
32  individually tested, to make sure it works as designed.  After the components
33  are placed in a larger circuit, the signals connecting them can still be
34  monitored for testing and troubleshooting.
35  
36  Like electronic components, HAL components have pins, and the pins can be
37  interconnected by signals.
38  
39  In the HAL, a \fIsignal\fR contains the actual data value that passes from one pin
40  to another.  When a signal is created, space is allocated for the data value.
41  A \fIpin\fR on the other hand, is a pointer, not a data value.  When a pin is
42  connected to a signal, the pin's pointer is set to point at the signal's data
43  value.  This allows the component to access the signal with very little
44  run-time overhead.  (If a pin is not linked to any signal, the pointer points
45  to a dummy location, so the realtime code doesn't have to deal with null
46  pointers or treat unlinked variables as a special case in any way.)
47  
48  There are three approaches to writing a HAL component.  Those that do not
49  require hard realtime performance can be written as a single user mode process.
50  Components that need hard realtime performance but have simple configuration
51  and init requirements can be done as a single kernel module, using either
52  pre-defined init info, or insmod-time parameters.  Finally, complex components
53  may use both a kernel module for the realtime part, and a user space process to
54  handle ini file access, user interface (possibly including GUI features), and
55  other details.
56  
57  HAL uses the RTAPI/ULAPI interface.  If RTAPI is #defined hal_lib.c would
58  generate a kernel module hal_lib.o that is insmoded and provides the functions
59  for all kernel module based components.  The same source file compiled with the
60  ULAPI #define would make a user space hal_lib.o that is staticlly linked to
61  user space code to make user space executables.  The variable lists and link
62  information are stored in a block of shared memory and protected with mutexes,
63  so that kernel modules and any of several user mode programs can access the
64  data.
65  
66  .SH REALTIME CONSIDERATIONS
67  For an explanation of realtime considerations, see \fBintro(3rtapi)\fR.
68  
69  .SH HAL STATUS CODES
70  Except as noted in specific manual pages, HAL returns negative errno values
71  for errors, and nonnegative values for success.
72  
73  .SH SEE ALSO
74  \fBintro(3rtapi)\fR