intro(3hal)

💖 intro(3hal) — HAL 💖

okay bestie, welcome to the HAL era, the intro page for the whole HAL API. this is intro(3hal) from the HAL manual, and honestly? it's giving origin story. 🦋

---

✨ NAME ✨

HAL — Introduction to the HAL API 💅

---

🌸 DESCRIPTION 🌸

okay so, HAL stands for Hardware Abstraction Layer, and LinuxCNC uses it to move realtime data to and from I/O devices and other low-level modules. no cap, that's the whole job. 🫶

hal.h is the file that defines the API and the data structures the HAL uses. it gets included in both realtime and non-realtime HAL components. HAL rides on the RTPAI real-time interface, and the #define symbols RTAPI and ULAPI are how you tell realtime code and non-realtime code apart. the API defined in this file is implemented in hal_lib.c, and you can compile it to link against either realtime or non-realtime HAL components. slay. ✨

the HAL is a very modular approach to the low-level parts of a motion control system. the goal? let a systems integrator connect a group of software components together to meet whatever I/O requirements he (or she) needs. we love a flexible queen. 👑

and that includes realtime and non-realtime I/O, plus basic motor control all the way up to and including a PID position loop. what do all these functions have in common? they all process signals. 💜

in general, a signal is a data item that gets updated at regular intervals. for example — a PID loop gets position command and feedback signals, and produces a velocity command signal. iconic behavior, honestly. 🎀

---

🧚 HAL is literally a circuit board, iykyk 🧚

HAL is based on the approach used to design electronic circuits. and the way that works in electronics? off-the-shelf components like integrated circuits get placed on a circuit board, and their pins get 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. and 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. periodt.

---

🫶 signals vs. pins (the lore) 🫶

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 lets the component access the signal with very little run-time overhead. and bestie — 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. so thoughtful of it. 🌸

---

👑 the three approaches to writing a HAL component 👑

1. components that don't require hard realtime performance can be written as a regular non-realtime process. 💅
2. 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. 🔥
3. 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. ✨

---

🌈 the RTAPI/ULAPI situation 🌈

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, which would get linked to non-realtime code to make non-realtime executables. and where does all the bookkeeping live? 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 both access the data. mutual access, mutual respect. 💖

---

⚡ REALTIME CONSIDERATIONS ⚡

for an explanation of realtime considerations, see intro(3rtapi). go read it bestie, it's important. 🫶

---

🍓 HAL STATUS CODES 🍓

except as noted in specific manual pages, HAL returns negative errno values for errors, and non-negative values for success. that's it, that's the vibe check. 💅

---

🔥 SEE ALSO 🔥

• intro(3rtapi)

---

and that's the whole page, bestie!! this one came from the LinuxCNC Documentation crew, dated 2006-10-12 — so yes, she's an elder icon and she still ate. 💖✨🎀🦋👑