kinemmatics w halcompile, hal_set_unready()

Prior to this commit, the comp files used to demonstrate
creation of a kinematics module with halcompile instantiated
an auxiliary component instance using hal_init().  This
instance is not loadable with loadrt (its primary purpose is to
provide pins for kinematics functions).

However, without using a loadrt for the auxiliary component
instance, confusing messages were reported at program exit.
typ:

  userkinsdata: not loaded
  <commandline>:0: exit value: 255
  <commandline>:0: rmmod failed, returned -1
  <commandline>:0: unloadrt failed

This commit uses a new function (hal_set_unready()) to
allow the kinematics module to create pins that are added
to the parent component without causing messages on exit.

Update kinematics modules (userkins.comp,millturn.comp) to:
0) eliminate auxiliary component instance by using
   hal_set_unready() followed by reissue hal_ready()
1) incorporate a conventional function 'fdemo' that
   can be added (addf) to a thread for demonstration
2) rename 'dummy' pin to 'fpin' and  test in the 'fdemo'
   function
3) rename var 'is_homed' to 'is_ready' for clarity
   as use depends on kinematics type

Author: dngarrett

src/hal/components/millturn.comp

@@ -28,10 +28,10 @@ switchable kinematics in particular see the switchkins document
 chapter (docs/src/motion/switchkins.txt)
 
 """;
-// The halcompile utility requires a pin definition but
-// the dummy pin is not accessible in kinematics functions.
-// Use the *_setup() function for actual pins and params.
-pin out bit dummy=1;
+// The fpin pin is not accessible in kinematics functions.
+// Use the *_setup() function for pins and params used by kinematics.
+pin out s32 fpin=0"pin to demonstrate use of a conventional (non-kinematics) function fdemo";
+function fdemo;
 license "GPL";
 author "David Mueller";
 ;;
@@ -52,13 +52,24 @@ static struct haldata {
   hal_bit_t   *kinstype_is_1;
 } *haldata;
 
+FUNCTION(fdemo) {
+   // This function can be added to a thread (addf) for
+   // purposes not related to the kinematics functions.
+   if (fpin == 0) {
+       rtapi_print("fdemo function added to thread\n");
+   }
+   fpin++;
+}
+
 static int millturn_setup(void) {
 #define HAL_PREFIX "millturn"
     int res=0;
-    int comp_id;
-    // this name must be different than the component name:
-    comp_id = hal_init("millturndata");
+
+    // inherit comp_id from rtapi_main()
     if (comp_id < 0) goto error;
+    // set unready to allow creation of pins
+    if (hal_set_unready(comp_id)) goto error;
+
     haldata = hal_malloc(sizeof(struct haldata));
     if (!haldata) goto error;
 
@@ -133,7 +144,7 @@ static bool is_setup=0;
            //       joint values in preview prior to homing
 } // kinematicsType()
 
-static bool is_homed=0;
+static bool is_ready=0;
 int kinematicsForward(const double *j,
                       EmcPose * pos,
                       const KINEMATICS_FORWARD_FLAGS * fflags,
@@ -163,9 +174,9 @@ int kinematicsForward(const double *j,
     pos->v = 0;
     pos->w = 0;
 
-    if (*haldata->in && !is_homed && !gave_msg) {
+    if (*haldata->in && !is_ready && !gave_msg) {
        rtapi_print_msg(RTAPI_MSG_ERR,
-                       "%s in pin not echoed until homed\n",
+                       "%s the 'in' pin not echoed until Inverse called\n",
                       __FILE__);
        gave_msg=1;
     }
@@ -177,7 +188,7 @@ int kinematicsInverse(const EmcPose * pos,
                       const KINEMATICS_INVERSE_FLAGS * iflags,
                       KINEMATICS_FORWARD_FLAGS * fflags)
 {
-    is_homed = 1; // Inverse is not called until homed
+    is_ready = 1; // Inverse is not called until homed for KINEMATICS_BOTH
 
     // Update the kinematic joints specified by the
     // [KINS]JOINTS setting (4 required for this template).

src/hal/components/userkins.comp

@@ -50,19 +50,19 @@ kinematics for an xyz machine employing 3 joints
      'userkins' to 'mykins'
 
 \\fBNOTES:\\fR
-  1  A 'dummy' pin is required to satisfy the requirements of
-     the halcompile utility but it is not accessible to
-     kinematics functions.
+  1  The \\fBfpin\\fR pin is included to satisfy the requirements of
+     the halcompile utility but it is not accessible to kinematics
+     functions.
 
   2  Hal pins and parameters needed in kinematics functions
      (kinematicsForward(), kinematicsInverse()) must
-     be setup in a function (userkins_setup()) invoked
+     be setup in a function (\\fBuserkins_setup()\\fR) invoked
      by the initial motion module call to kinematicsType().
 """;
-// The halcompile utility requires a pin definition but
-// the dummy pin is not accessible in kinematics functions.
-// Use the *_setup() function for actual pins and params.
-pin out bit dummy=1;
+// The fpin pin is not accessible in kinematics functions.
+// Use the *_setup() function for pins and params used by kinematics.
+pin out s32 fpin=0"pin to demonstrate use of a conventional (non-kinematics) function fdemo";
+function fdemo;
 license "GPL";
 author "Dewey Garrett";
 ;;
@@ -84,13 +84,24 @@ static struct haldata {
 // hal_s32_t   signed 32bit integer
 // hal_float_t float (double precision)
 
+FUNCTION(fdemo) {
+   // This function can be added to a thread (addf) for
+   // purposes not related to the kinematics functions.
+   if (fpin == 0) {
+       rtapi_print("fdemo function added to thread\n");
+   }
+   fpin++;
+}
+
 static int userkins_setup(void) {
 #define HAL_PREFIX "userkins"
     int res=0;
-    int comp_id;
-    // this name must be different than the component name:
-    comp_id = hal_init("userkinsdata");
+
+    // inherit comp_id from rtapi_main()
     if (comp_id < 0) goto error;
+    // set unready to allow creation of pins
+    if (hal_set_unready(comp_id)) goto error;
+
     haldata = hal_malloc(sizeof(struct haldata));
     if (!haldata) goto error;
 
@@ -129,7 +140,7 @@ static bool is_setup=0;
            //       joint values in preview prior to homing
 } // kinematicsType()
 
-static bool is_homed=0;
+static bool is_ready=0;
 int kinematicsForward(const double *j,
                       EmcPose * pos,
                       const KINEMATICS_FORWARD_FLAGS * fflags,
@@ -148,9 +159,9 @@ int kinematicsForward(const double *j,
     pos->v = 0;
     pos->w = 0;
 
-    if (*haldata->in && !is_homed && !gave_msg) {
+    if (*haldata->in && !is_ready && !gave_msg) {
        rtapi_print_msg(RTAPI_MSG_ERR,
-                       "%s in pin not echoed until homed\n",
+                       "%s The 'in' pin not echoed until Inverse called\n",
                       __FILE__);
        gave_msg=1;
     }
@@ -162,7 +173,7 @@ int kinematicsInverse(const EmcPose * pos,
                       const KINEMATICS_INVERSE_FLAGS * iflags,
                       KINEMATICS_FORWARD_FLAGS * fflags)
 {
-    is_homed = 1; // Inverse is not called until homed
+    is_ready = 1; // Inverse is not called until homed for KINEMATICS_BOTH
 
     // Update the kinematic joints specified by the
     // [KINS]JOINTS setting (3 required for this template).

src/hal/hal.h

@@ -217,6 +217,14 @@ extern void *hal_malloc(long int size);
 */
 extern int hal_ready(int comp_id);
 
+/** hal_set_unready() sets a component state to unready so
+    additional pins can be added.  A subsequent call to
+    hal_ready() must be issued to make the component ready
+    again. Kinematics modules created with halcompile use
+    this function to add pins to a parent component.
+*/
+extern int hal_set_unready(int comp_id);
+
 /** hal_unready() indicates that this component is ready.  This allows
     halcmd 'loadusr -W hal_example' to wait until the userspace
     component 'hal_example' is ready before continuing.

src/hal/hal_lib.c

@@ -429,6 +429,18 @@ int hal_set_constructor(int comp_id, constructor make) {
 }
 #endif
 
+int hal_set_unready(int comp_id) {
+    hal_comp_t *comp;
+    rtapi_mutex_get(&(hal_data->mutex));
+    comp = halpr_find_comp_by_id(comp_id);
+    if (comp) { comp->ready = 0; }
+    rtapi_mutex_give(&(hal_data->mutex));
+    if (comp) {return 0;}
+    rtapi_print_msg(RTAPI_MSG_ERR,
+         "HAL: ERROR: hal_set_unready(): component %d not found\n", comp_id);
+    return -EINVAL;
+}
+
 int hal_ready(int comp_id) {
     int next;
     hal_comp_t *comp;
@@ -4191,6 +4203,7 @@ int hal_stream_num_underruns(hal_stream_t *stream) {
 
 EXPORT_SYMBOL(hal_init);
 EXPORT_SYMBOL(hal_ready);
+EXPORT_SYMBOL(hal_set_unready);
 EXPORT_SYMBOL(hal_exit);
 EXPORT_SYMBOL(hal_malloc);
 EXPORT_SYMBOL(hal_comp_name);