hal: C++ API (hal.hh) and pybind11 bindings on the new HAL API

debian/control.top.in

@@ -40,6 +40,7 @@ Build-Depends:
     psmisc,
     python3,
     python3-dev,
+    python3-pybind11,
     python3-tk,
     python3-xlib,
     tcl,

lib/python/hal.py

@@ -29,9 +29,16 @@
 
 import _hal
 from _hal import *
+from _hal import query
+import sys
 import warnings
 import lcnc_realtime
 
+# _hal.query is a submodule, not a plain attribute. Registering it in
+# sys.modules under its dotted name makes 'import hal.query' and
+# 'from hal import query' work as they would for a real package.
+sys.modules['hal.query'] = query
+
 def __getattr__(name):
     if name == 'is_rt':
         warnings.warn(f"{name} is deprecated, use lcnc_realtime.verify() instead", FutureWarning, stacklevel=2)

lib/python/haltype.py

@@ -0,0 +1,60 @@
+#!/usr/bin/env python3
+# vim: sts=4 sw=4 et
+
+"""
+
+Symbolic names for the HAL type and direction constants.
+
+The values mirror the hal_type_t and hal_pdir_t enums in hal.h. This
+module deliberately depends on nothing but the standard library, so it
+can be imported by tools that must not pull in the HAL extension module
+(documentation generators, config checkers, editors).
+
+Both enums derive from IntEnum, so a member is accepted anywhere the
+plain integer constant from hal or _hal is:
+
+import haltype
+h.newpin("out", haltype.HALType.HAL_REAL, haltype.HALDir.HAL_OUT)
+
+hal.h spells the enumerators HAL_BIT, HAL_FLOAT, HAL_S32, HAL_U32,
+HAL_PORT, HAL_S64 and HAL_U64, with HAL_BOOL, HAL_REAL, HAL_SINT and
+HAL_UINT as macros over them. Here the macro names are the canonical
+members and the enumerator names the IntEnum aliases. Both spellings
+exist on either side, compare equal and iterate the same, so the
+distinction is only visible in member.name.
+"""
+
+from enum import IntEnum
+
+
+class HALType(IntEnum):
+    """Type of a HAL pin, parameter or signal (hal_type_t)."""
+
+    HAL_BOOL = 1
+    HAL_REAL = 2
+    HAL_S32 = 3
+    HAL_U32 = 4
+    HAL_PORT = 5
+    HAL_SINT = 6
+    HAL_UINT = 7
+
+    # Aliases, as in hal.h
+    HAL_BIT = HAL_BOOL
+    HAL_FLOAT = HAL_REAL
+    HAL_S64 = HAL_SINT
+    HAL_U64 = HAL_UINT
+
+
+class HALDir(IntEnum):
+    """Direction of a HAL pin or parameter (hal_pdir_t).
+
+    HAL_IN, HAL_OUT and HAL_IO apply to pins; HAL_RO and HAL_RW apply to
+    parameters. The bit patterns are disjoint between the two groups so
+    that a direction also identifies which of the two it belongs to.
+    """
+
+    HAL_IN = 1 << 4
+    HAL_OUT = 1 << 5
+    HAL_IO = HAL_IN | HAL_OUT
+    HAL_RO = 1 << 6
+    HAL_RW = HAL_RO | (1 << 7)

src/Makefile

@@ -394,6 +394,7 @@ build-software: headers $(INFILES)
 #
 SRCHEADERS := \
     hal/hal.h \
+    hal/hal.hh \
     hal/drivers/mesa-hostmot2/hostmot2-serial.h \
     emc/linuxcnc.h \
     emc/kinematics/kinematics.h \

src/hal/Submakefile

@@ -3,6 +3,10 @@
 ../include/hal.h: ./hal/hal.h
 	cp $^ $@
 
+# hal.hh is the C++ interface on top of the public C API
+../include/hal.hh: ./hal/hal.hh
+	cp $^ $@
+
 HALLIBSRCS := hal/hal_lib.c hal/hal_lib_query.c hal/hal_lib_extra.c $(ULAPISRCS)
 $(call TOOBJSDEPS, $(HALLIBSRCS)): EXTRAFLAGS += -fPIC $(ULAPI_CFLAGS)
 USERSRCS += $(HALLIBSRCS)
@@ -28,5 +32,27 @@ $(HALMODULE): $(call TOOBJS, $(HALMODULESRCS)) $(HALLIB)
 	$(ECHO) Linking python module $(notdir $@)
 	$(Q)$(CXX) $(LDFLAGS) -shared -o $@ $^
 
+# pybind11 C++ bindings (hal.hh based)
+# setps_util.c only exists in the tree with the HAL query API
+# pybind11 headers: python3-pybind11 (system include) or pip user site.
+# Without them the bindings are skipped, not failed: they are optional
+# until the build dependency is made mandatory.
+PYBIND11INCLUDES := $(shell $(PYTHON) -m pybind11 --includes 2>/dev/null)
+ifneq ($(PYBIND11INCLUDES),)
+HALPPSRCS := hal/halpybind.cc $(wildcard hal/utils/setps_util.c)
+PYSRCS += $(HALPPSRCS)
+
+$(call TOOBJS, $(HALPPSRCS)): EXTRAFLAGS += $(PYBIND11INCLUDES)
+
+HALPP := ../lib/python/halpp.so
+$(HALPP): $(call TOOBJS, $(HALPPSRCS)) $(HALLIB)
+	$(ECHO) Linking python module $(notdir $@)
+	$(Q)$(CXX) $(LDFLAGS) -shared -o $@ $^
+
+PYTARGETS += $(HALPP)
+else
+$(info NOTE: pybind11 headers not found, skipping the halpp bindings (install python3-pybind11))
+endif
+
 TARGETS += $(HALLIB) ../lib/liblinuxcnchal.so.0
 PYTARGETS += $(HALMODULE)