replace hal_priv.h/SHMOFF/self_offset with hal_struct_newf/attach API

Add hal_struct_newf() / hal_struct_attach() / hal_struct_detach() to
hal.h and hal_lib.c as a clean public API for naming opaque blobs in
HAL shmem without exposing hal_priv.h internals.

Migrate all 17 kinematics modules and kinematics_user.c:
- remove #include "hal_priv.h" from every kins module
- replace hal_malloc + hal_param_s32_newf(...uspace-params-offset...) +
  SHMOFF(ptr) with hal_struct_newf(comp_id, sizeof(kinematics_params_t),
  NULL, "<module>.params") + hal_struct_attach()
- remove self_offset field from kinematics_params_t
- simplify nonrt_attach signature from (char *shmem_base, int offset,
  nonrt_ops_t *ops) to (nonrt_ops_t *ops); each module calls
  hal_struct_attach() internally to obtain its uspace_params pointer
- simplify kinematics_user.c: drop hal_pin_reader dependency for the
  offset lookup, call hal_struct_attach() directly in find_shmem_params()
- update kinematics.adoc custom module guide to reflect new API

Author: grandixximo

docs/src/motion/kinematics.adoc

@@ -427,19 +427,18 @@ no per-call overhead.
 The userspace planner resolves a single symbol from the RT `.so`:
 
 ----
-void nonrt_attach(char *shmem_base, int offset, nonrt_ops_t *ops);
+void nonrt_attach(nonrt_ops_t *ops);
 ----
 
-`nonrt_attach` is called once at planner startup.  It receives a
-pointer to the HAL shared memory base and the byte offset of the
-module's `kinematics_params_t` structure.  It stores the pointer
-for later use and registers the forward and inverse functions that
-the planner will call:
+`nonrt_attach` is called once at planner startup.  It calls
+`hal_struct_attach()` to map the module's `kinematics_params_t`
+from HAL shared memory, then registers the forward and inverse
+functions that the planner will call:
 
 ----
-void nonrt_attach(char *shmem_base, int offset, nonrt_ops_t *ops)
+void nonrt_attach(nonrt_ops_t *ops)
 {
-    uspace_params = (kinematics_params_t *)(shmem_base + offset);
+    hal_struct_attach("mykins.params", (void **)&uspace_params);
     ops->forward  = myKinematicsForward;  /* same function as RT */
     ops->inverse  = myKinematicsInverse;
 }
@@ -483,24 +482,29 @@ any `!haldata` guard -- there are no HAL pins to dereference.
 ==== Shared memory setup (required for planner 2)
 
 `rtapi_app_main()` (or `XxxKinematicsSetup()` for switchkins modules)
-allocates the `kinematics_params_t` in HAL shmem and publishes its
-byte offset so the userspace planner can locate it:
+registers the `kinematics_params_t` in HAL shmem using
+`hal_struct_newf()`, then attaches to it with `hal_struct_attach()`:
 
 ----
-uspace_params = (kinematics_params_t *)hal_malloc(sizeof(kinematics_params_t));
-if (hal_param_s32_newf(HAL_RO, &uspace_params->self_offset, comp_id,
-                       "%s.uspace-params-offset", modname) < 0) goto error;
-memset(uspace_params, 0, sizeof(*uspace_params));
+if (hal_struct_newf(comp_id, sizeof(kinematics_params_t), NULL,
+                    "%s.params", modname) < 0) goto error;
+if (hal_struct_attach("mykins.params", (void **)&uspace_params) < 0)
+    goto error;
 uspace_params->num_joints  = num_joints;
 uspace_params->is_identity = 0;  /* 1 for trivial/identity kinematics */
 /* fill initial parameter values */
 uspace_params->valid = 1;
 uspace_params->head  = 1;
 uspace_params->tail  = 1;
-uspace_params->self_offset = (int)SHMOFF(uspace_params);
 ----
 
-If the `uspace-params-offset` param is absent (old external module),
+`hal_struct_newf()` allocates the blob inside HAL's existing shared
+memory segment and registers a `HAL_RO hal_s32` parameter named
+`"<module>.params"` whose value is the shmem byte offset.  The
+userspace planner calls `hal_struct_attach()` with the same name to
+obtain a direct pointer -- no `hal_priv.h`, no raw offsets.
+
+If the `<module>.params` struct is absent (old external module),
 the userspace planner detects this at init time and disables planner 2
 with a logged warning.  Planner 0 and 1 continue to work normally.
 
@@ -561,13 +565,11 @@ the math, the RT interface (with shmem push), and the non-RT interface.
 
 /* ---- RT headers ---- */
 #include "kinematics.h"
-#include "hal.h"
-#include "hal_priv.h"           /* for SHMOFF() */
+#include <hal.h>                /* hal_struct_newf/attach, hal_malloc */
 #include "kinematics_params.h"  /* for kinematics_params_t */
 #include "rtapi.h"
 #include "rtapi_app.h"
 #include "rtapi_math.h"
-#include <string.h>             /* for memset() */
 
 /* ================================================================
  * Layer 1: Pure math (shared by RT and non-RT)
@@ -670,19 +672,17 @@ int rtapi_app_main(void)
         goto error;
     *(haldata->arm_length) = 100.0;  /* default value */
 
-    /* Allocate kinematics_params_t in HAL shmem and publish its offset */
-    uspace_params = (kinematics_params_t *)hal_malloc(sizeof(kinematics_params_t));
-    if (!uspace_params) goto error;
-    if (hal_param_s32_newf(HAL_RO, &uspace_params->self_offset, comp_id,
-                           "mykins.uspace-params-offset") < 0) goto error;
-    memset(uspace_params, 0, sizeof(*uspace_params));
+    /* Register kinematics parameters in HAL shmem via hal_struct_newf() */
+    if (hal_struct_newf(comp_id, sizeof(kinematics_params_t), NULL,
+                        "mykins.params") < 0) goto error;
+    if (hal_struct_attach("mykins.params", (void **)&uspace_params) < 0)
+        goto error;
     uspace_params->num_joints             = 3;
     uspace_params->is_identity            = 0;
     uspace_params->params.mykins.arm_length = 100.0;
     uspace_params->valid = 1;
     uspace_params->head  = 1;
     uspace_params->tail  = 1;
-    uspace_params->self_offset = (int)SHMOFF(uspace_params);
 
     hal_ready(comp_id);
     return 0;
@@ -696,15 +696,16 @@ void rtapi_app_exit(void) { hal_exit(comp_id); }
 /* ================================================================
  * Layer 3: Non-RT entry point (for userspace trajectory planner)
  *
- * nonrt_attach is called once at planner startup.  It maps the
- * shmem params pointer and registers the forward/inverse functions.
+ * nonrt_attach is called once at planner startup.  It attaches to
+ * the kinematics_params_t registered by rtapi_app_main() via
+ * hal_struct_newf() and registers the forward/inverse functions.
  * The same kinematicsForward/Inverse functions are used -- they
  * detect the userspace context via !haldata and read from shmem.
  * ================================================================ */
 
-void nonrt_attach(char *shmem_base, int offset, nonrt_ops_t *ops)
+void nonrt_attach(nonrt_ops_t *ops)
 {
-    uspace_params = (kinematics_params_t *)(shmem_base + offset);
+    hal_struct_attach("mykins.params", (void **)&uspace_params);
     ops->forward  = kinematicsForward;
     ops->inverse  = kinematicsInverse;
 }
@@ -731,7 +732,8 @@ kinematics modules follow:
   is never called.
 
 . **Layer 3 -- Non-RT entry point**: The `nonrt_attach()` function,
-  called once at planner startup.  It stores the shmem pointer and
+  called once at planner startup.  It calls `hal_struct_attach()` to
+  map the module's `kinematics_params_t` from HAL shmem, then
   registers the forward/inverse function pointers.  No separate
   non-RT math functions are needed -- the same RT functions handle
   both contexts via the `!haldata` guard.
@@ -791,8 +793,8 @@ RT `.so` to load and resolves `nonrt_attach` from it at startup.
 - Use `rtapi_snprintf()` instead of `snprintf()` in RT code.
   Standard C library functions are not available in the RT
   environment.
-- Always include `hal_priv.h` (for `SHMOFF()`) and `<string.h>`
-  (for `memset()`) in modules that set up `uspace_params`.
+- Include `<hal.h>` (angle brackets — it is a public header) and
+  `"kinematics_params.h"` in modules that set up `uspace_params`.
 - For modules with no runtime parameters (pure geometric transforms),
   register the RT functions directly in `nonrt_attach` with no
   `!haldata` guard -- there are no HAL pin pointers to dereference.
@@ -805,7 +807,7 @@ RT `.so` to load and resolves `nonrt_attach` from it at startup.
 - The shmem push uses `head`/`tail` guards to protect against torn
   reads: increment `head` before any write, set `tail = head` after
   all writes.  The userspace side retries the read when `head != tail`.
-- Modules without the `uspace-params-offset` param fall back
+- Modules without the `<module>.params` HAL struct fall back
   gracefully: planner 0 and 1 work normally, planner 2 is disabled
   with a logged warning.
 - Look at the existing modules in `src/emc/kinematics/` for

src/emc/kinematics/5axiskins.c

@@ -62,7 +62,6 @@
 #include <kinematics.h>
 
 #include "switchkins.h"
-#include "hal_priv.h"
 #include "kinematics_params.h"
 
 /* ========================================================================
@@ -164,7 +163,8 @@ struct haldata {
 } *haldata;
 static int fiveaxis_max_joints;
 
-/* Userspace-accessible params in HAL shmem */
+/* Pointer into HAL shmem — set by hal_struct_newf/attach in setup,
+ * re-attached by nonrt_attach() in the userspace dlopen path. */
 static kinematics_params_t *uspace_params;
 
 // Joint mapping struct
@@ -309,17 +309,16 @@ int fiveaxis_KinematicsSetup(const  int   comp_id,
 
     *haldata->pivot_length = DEFAULT_PIVOT_LENGTH;
 
-    /* Publish kinematics params to HAL shmem for userspace planner */
-    uspace_params = (kinematics_params_t *)hal_malloc(sizeof(kinematics_params_t));
-    if (!uspace_params) {
-        rtapi_print_msg(RTAPI_MSG_ERR, "5axiskins: hal_malloc for uspace_params failed\n");
-        goto error;
-    }
-    result = hal_param_s32_newf(HAL_RO, &uspace_params->self_offset, comp_id,
-                              "%s.uspace-params-offset", kp->halprefix);
+    /* Register kinematics parameters in HAL shmem via hal_struct_newf() */
+    result = hal_struct_newf(comp_id, sizeof(kinematics_params_t), NULL,
+                             "%s.params", kp->halprefix);
     if (result < 0) goto error;
+    {
+        char _n[HAL_NAME_LEN + 1];
+        rtapi_snprintf(_n, sizeof(_n), "%s.params", kp->halprefix);
+        if (hal_struct_attach(_n, (void **)&uspace_params) < 0) goto error;
+    }
 
-    memset(uspace_params, 0, sizeof(*uspace_params));
     uspace_params->num_joints = fiveaxis_max_joints;
     uspace_params->axis_to_joint[0] = JX; uspace_params->axis_to_joint[1] = JY;
     uspace_params->axis_to_joint[2] = JZ; uspace_params->axis_to_joint[3] = JA;
@@ -329,7 +328,6 @@ int fiveaxis_KinematicsSetup(const  int   comp_id,
     uspace_params->params.fiveaxis.pivot_length = DEFAULT_PIVOT_LENGTH;
     uspace_params->valid       = 1;
     uspace_params->is_identity = 0;
-    uspace_params->self_offset = (int)SHMOFF(uspace_params);
 
     rtapi_print("Kinematics Module %s\n",__FILE__);
     rtapi_print("  module name = %s\n"
@@ -385,16 +383,17 @@ int switchkinsSetup(kparms* kp,
 } // switchkinsSetup()
 
 /* ========================================================================
- * Non-RT interface for userspace trajectory planner
+ * Non-RT interface
  *
- * nonrt_attach() is the only exported symbol. It sets uspace_params so the
- * !haldata branch in fiveaxis_KinematicsForward/Inverse reads live shmem,
- * then registers those functions directly — no separate nonrt functions.
+ * nonrt_attach() is called by kinematics_user.c after dlopen().
+ * It attaches to the kinematics_params_t registered in HAL shmem by the
+ * RT side (hal_struct_newf in fiveaxis_KinematicsSetup) and returns
+ * forward/inverse function pointers.  No hal_priv.h or raw offsets needed.
  * ======================================================================== */
 
-void nonrt_attach(char *shmem_base, int offset, nonrt_ops_t *ops)
+void nonrt_attach(nonrt_ops_t *ops)
 {
-    uspace_params  = (kinematics_params_t *)(shmem_base + offset);
+    hal_struct_attach("5axiskins.params", (void **)&uspace_params);
     ops->forward   = fiveaxis_KinematicsForward;
     ops->inverse   = fiveaxis_KinematicsInverse;
 }

src/emc/kinematics/corexykins.c

@@ -10,7 +10,6 @@
 #include "rtapi_app.h"
 #include "rtapi_string.h"
 #include "kinematics.h"
-#include "hal_priv.h"
 #include "kinematics_params.h"
 
 /*
@@ -103,19 +102,18 @@ int rtapi_app_main(void) {
 
     data = hal_malloc(sizeof(struct data));
 
-    uspace_params = (kinematics_params_t *)hal_malloc(sizeof(kinematics_params_t));
-    if (!uspace_params) { hal_exit(comp_id); return -1; }
-    if (hal_param_s32_newf(HAL_RO, &uspace_params->self_offset, comp_id,
-                         "corexykins.uspace-params-offset") < 0) {
+    if (hal_struct_newf(comp_id, sizeof(kinematics_params_t), NULL,
+                        "corexykins.params") < 0) {
         hal_exit(comp_id); return -1;
     }
-    memset(uspace_params, 0, sizeof(*uspace_params));
-    uspace_params->num_joints = 9;
+    if (hal_struct_attach("corexykins.params", (void **)&uspace_params) < 0) {
+        hal_exit(comp_id); return -1;
+    }
+    uspace_params->num_joints  = 9;
     uspace_params->valid       = 1;
     uspace_params->is_identity = 0;
     uspace_params->head = 1;
     uspace_params->tail = 1;
-    uspace_params->self_offset = (int)SHMOFF(uspace_params);
 
     hal_ready(comp_id);
     return 0;
@@ -124,12 +122,14 @@ int rtapi_app_main(void) {
 void rtapi_app_exit(void) { hal_exit(comp_id); }
 
 /* ========================================================================
- * Non-RT interface for userspace trajectory planner
+ * Non-RT interface
+ *
+ * Called by kinematics_user.c after dlopen().  Returns forward/inverse
+ * function pointers.  (No kinematics-specific parameters to attach.)
  * ======================================================================== */
 
-void nonrt_attach(char *shmem_base, int offset, nonrt_ops_t *ops)
+void nonrt_attach(nonrt_ops_t *ops)
 {
-    (void)shmem_base; (void)offset;
     ops->forward = kinematicsForward;
     ops->inverse = kinematicsInverse;
 }

src/emc/kinematics/genhexkins.c

@@ -116,7 +116,6 @@
 #include "motion.h"
 #include "kinematics.h"             /* these decls, KINEMATICS_FORWARD_FLAGS */
 #include "switchkins.h"
-#include "hal_priv.h"
 #include "kinematics_params.h"
 #include <string.h>
 
@@ -676,13 +675,15 @@ int genhexKinematicsSetup(const  int   comp_id,
 
     if (res) goto error;
 
-    uspace_params = (kinematics_params_t *)hal_malloc(sizeof(kinematics_params_t));
-    if (!uspace_params) goto error;
-    if (hal_param_s32_newf(HAL_RO, &uspace_params->self_offset, comp_id,
-                         "%s.uspace-params-offset", kp->halprefix) < 0) goto error;
+    if (hal_struct_newf(comp_id, sizeof(kinematics_params_t), NULL,
+                        "%s.params", kp->halprefix) < 0) goto error;
+    {
+        char _n[HAL_NAME_LEN + 1];
+        rtapi_snprintf(_n, sizeof(_n), "%s.params", kp->halprefix);
+        if (hal_struct_attach(_n, (void **)&uspace_params) < 0) goto error;
+    }
     {
         int _i;
-        memset(uspace_params, 0, sizeof(*uspace_params));
         uspace_params->num_joints  = kp->max_joints;
         uspace_params->is_identity = 0;
         for (_i = 0; _i < GENHEX_NUM_STRUTS; _i++) {
@@ -708,7 +709,6 @@ int genhexKinematicsSetup(const  int   comp_id,
         uspace_params->valid = 1;
         uspace_params->head  = 1;
         uspace_params->tail  = 1;
-        uspace_params->self_offset = (int)SHMOFF(uspace_params);
     }
     return 0;
 
@@ -748,7 +748,11 @@ int switchkinsSetup(kparms* kp,
 } //switchkinsSetup()
 
 /* ========================================================================
- * Non-RT interface for userspace trajectory planner
+ * Non-RT interface
+ *
+ * Called by kinematics_user.c after dlopen().  Attaches to the
+ * kinematics_params_t registered in HAL shmem by genhexKinematicsSetup()
+ * via hal_struct_newf() and returns forward/inverse function pointers.
  * ======================================================================== */
 
 static void nonrt_build_genhex(const kinematics_params_t *kp, genhex_params_t *p)
@@ -803,9 +807,9 @@ static int nonrt_genhex_inverse(const EmcPose *pos, double *joints,
     return genhex_inv(&p, pos, joints);
 }
 
-void nonrt_attach(char *shmem_base, int offset, nonrt_ops_t *ops)
+void nonrt_attach(nonrt_ops_t *ops)
 {
-    uspace_params  = (kinematics_params_t *)(shmem_base + offset);
+    hal_struct_attach("genhexkins.params", (void **)&uspace_params);
     ops->forward   = nonrt_genhex_forward;
     ops->inverse   = nonrt_genhex_inverse;
 }

src/emc/kinematics/genserfuncs.c

@@ -37,7 +37,6 @@
 #include "kinematics.h"
 #include "hal.h"
 #ifdef RTAPI
-#include "hal_priv.h"
 #include "kinematics_params.h"
 #include <string.h>
 #endif
@@ -688,13 +687,15 @@ int genserKinematicsSetup(const int comp_id,
     D(5) = DEFAULT_D6;
 
 #ifdef RTAPI
-    uspace_params = (kinematics_params_t *)hal_malloc(sizeof(kinematics_params_t));
-    if (!uspace_params) goto error;
-    if (hal_param_s32_newf(HAL_RO, &uspace_params->self_offset, comp_id,
-                         "%s.uspace-params-offset", kp->halprefix) < 0) goto error;
+    if (hal_struct_newf(comp_id, sizeof(kinematics_params_t), NULL,
+                        "%s.params", kp->halprefix) < 0) goto error;
+    {
+        char _n[HAL_NAME_LEN + 1];
+        rtapi_snprintf(_n, sizeof(_n), "%s.params", kp->halprefix);
+        if (hal_struct_attach(_n, (void **)&uspace_params) < 0) goto error;
+    }
     {
         int _i;
-        memset(uspace_params, 0, sizeof(*uspace_params));
         uspace_params->num_joints  = total_joints;
         uspace_params->is_identity = 0;
         for (_i = 0; _i < 6; _i++) {
@@ -708,7 +709,6 @@ int genserKinematicsSetup(const int comp_id,
         uspace_params->valid = 1;
         uspace_params->head  = 1;
         uspace_params->tail  = 1;
-        uspace_params->self_offset = (int)SHMOFF(uspace_params);
     }
 #endif