hal: restore working homecomp example

docs/src/code/code-notes.adoc

@@ -151,6 +151,8 @@ or command line options.  Custom modules must implement all
 functions used by the default modules.  The halcompile utility
 can be used to create a custom module.
 
+The interface a homing module must implement is declared and documented function by function in `src/emc/motion/homing.h`. It comprises one-time initialization (`homing_init`), per-servo-period control (`read_homing_in_pins`, `do_homing`, `write_homing_out_pins`), command entry points (`do_home_joint`, `do_cancel_homing`, `set_unhomed`, and the homing parameter setters), status queries (`get_allhomed`, `get_homed`, `get_homing`, and friends), and a callback registration for the rotary unlock functions (`homeMotFunctions`). The `homecomp` component (`src/hal/components/homecomp.comp`) is a buildable template implementing the full interface; see the homecomp(9) man page.
+
 image::LinuxCNC-motion-controller-small.png[align="center",pdfwidth=100%]
 
 == Block diagrams and Data Flow

docs/src/config/ini-config.adoc

@@ -686,6 +686,7 @@ For more information on the motion controller see the <<sec:motion,Motion>> sect
 * `COMM_TIMEOUT = 1.0` - Number of seconds to wait for Motion (the realtime part of the motion controller) to acknowledge receipt of messages from Task (the non-realtime part of the motion controller).
 * `HOMEMOD =` _alternate_homing_module_ [home_parms=value]
   The HOMEMOD variable is optional.  If specified, use a specified (user-built) module instead of the default (homemod).
+  The homecomp(9) component provides a buildable template for custom homing modules.
   Module parameters (home_parms) may be included if supported by the named module.
   The setting may be overridden from the command line using the -m option ($ linuxcnc -h).
 

src/emc/motion/homing.h

@@ -15,8 +15,17 @@
 
 //---------------------------------------------------------------------
 // INTERFACE routines
+//
+// A homing module (default: homemod) provides all functions declared
+// below.  motmod resolves the symbols at load time, so a custom module
+// named by [EMCMOT]HOMEMOD must export every one of them.  The
+// homecomp component (src/hal/components/homecomp.comp) is a buildable
+// template implementing this interface.
 
 // per-joint interface parameters (one-time setup)
+// Called once per joint with the homing values from the INI file
+// [JOINT_N] section (HOME, HOME_OFFSET, velocities, HOME_FLAGS,
+// HOME_SEQUENCE, VOLATILE_HOME).
 void set_joint_homing_params(int    jno,
                              double offset,
                              double home,
@@ -29,6 +38,8 @@ void set_joint_homing_params(int    jno,
                              );
 
 // updateable interface params (for inihal pin changes typically):
+// Runtime update of the subset of homing parameters that may change
+// after setup (offset, home position, sequence).
 void update_joint_homing_params (int    jno,
                                  double home_offset,
                                  double home_home,
@@ -39,6 +50,10 @@ void update_joint_homing_params (int    jno,
 // CONTROL routines
 
 // one-time initialization (return 0 if ok):
+// Called from motmod's rtapi_app_main().  'id' is motmod's HAL
+// component id, so pins created here are owned by motmod.  'pjoints'
+// points at motmod's joint array.  The module creates its HAL pins
+// (joint.N.home-sw-in, joint.N.homed, ...) here.
 int  homing_init(int id,
                  double servo_period,
                  int n_joints,            // total no of joints
@@ -47,36 +62,66 @@ int  homing_init(int id,
                  );
 
 // once-per-servo-period functions:
+// read_homing_in_pins(): called at the start of every servo period;
+// latch HAL input pins (home switches, index-enable, custom inputs).
 void read_homing_in_pins(int njoints);
+// do_homing(): called every servo period while motion is in FREE
+// mode; advances the homing sequence and the per-joint state
+// machines.  Returns 1 on the transition to all-homed so motmod can
+// switch from FREE to teleop mode.
 bool do_homing(void);  //return 1 if allhomed
+// write_homing_out_pins(): called at the end of every servo period;
+// push internal state to HAL output pins (homed, homing, home-state).
 void write_homing_out_pins(int njoints);
 
 // responses to EMCMOT_JOINT_HOME message:
+// jno == -1 requests home-all (start the homing sequence).
 void do_home_joint(int jno);
 // per-joint controls
+// Abort an in-progress homing of joint jno.
 void do_cancel_homing(int jno);
+// Mark joint(s) unhomed.  jno == -1 unhomes all joints, jno == -2
+// unhomes joints with VOLATILE_HOME set.  motstate guards against
+// unhoming an extrajoint while motion is enabled.
 void set_unhomed(int jno,motion_state_t motstate);
 
 //---------------------------------------------------------------------
 // QUERIES
 
 // overall status:
+// get_allhomed(): true if every active joint is homed.
 bool get_allhomed(void);
+// get_homing_is_active(): true while any homing sequence or per-joint
+// homing state machine is in progress.
 bool get_homing_is_active(void);
 
 // per-joint information:
 int  get_home_sequence(int jno); //return s
+// get_homing(): joint jno is currently running its homing state machine.
 bool get_homing(int jno);
+// get_homed(): joint jno has completed homing.
 bool get_homed(int jno);
+// get_index_enable(): state of the index-enable handshake for joint
+// jno (set by the homing module, cleared by the encoder driver).
 bool get_index_enable(int jno);
+// get_home_needs_unlock_first(): joint jno has HOME_UNLOCK_FIRST set
+// (rotary axis must be unlocked before homing).
 bool get_home_needs_unlock_first(int jno);
+// get_home_is_idle(): joint jno's homing state machine is HOME_IDLE.
 bool get_home_is_idle(int jno);
+// get_home_is_synchronized(): joint jno homes synchronized with other
+// joints (shares a negative home_sequence).
 bool get_home_is_synchronized(int jno);
+// get_homing_at_index_search_wait(): joint jno's state machine waits
+// at HOME_INDEX_SEARCH_WAIT (used for index handling).
 bool get_homing_at_index_search_wait(int jno);
 
 //---------------------------------------------------------------------
 // Module interface
 // motmod provided ptrs for functions called by homing:
+// Called once by motmod before homing_init() to hand the homing
+// module the rotary unlock/lock callbacks, so the module can unlock
+// rotaries without including motion internals.
 void homeMotFunctions(void(*pSetRotaryUnlock)(int,int)
                      ,int( *pGetRotaryUnlock)(int)
                      );

src/hal/components/Submakefile

@@ -1,5 +1,5 @@
 ifneq ($(KERNELRELEASE),)
-COMPS := $(filter-out %/tpcomp.comp %/homecomp.comp, $(patsubst $(BASEPWD)/%,%,$(wildcard $(BASEPWD)/hal/components/*.comp $(BASEPWD)/hal/drivers/*.comp)))
+COMPS := $(filter-out %/tpcomp.comp, $(patsubst $(BASEPWD)/%,%,$(wildcard $(BASEPWD)/hal/components/*.comp $(BASEPWD)/hal/drivers/*.comp)))
 include $(patsubst %.comp, $(BASEPWD)/objects/%.mak, $(COMPS))
 else
 CONVERTERS :=  \
@@ -32,8 +32,8 @@ CONVERTERS :=  \
     conv_u64_s32.comp \
     conv_u64_u32.comp \
     conv_u64_s64.comp
-COMPS := $(filter-out hal/components/tpcomp.comp hal/components/homecomp.comp, $(sort $(wildcard hal/components/*.comp) $(addprefix hal/components/, $(CONVERTERS))))
-COMP_MANPAGES := $(patsubst hal/components/%.comp, ../docs/build/man/man9/%.9, $(COMPS)) ../docs/build/man/man9/tpcomp.9 ../docs/build/man/man9/homecomp.9
+COMPS := $(filter-out hal/components/tpcomp.comp, $(sort $(wildcard hal/components/*.comp) $(addprefix hal/components/, $(CONVERTERS))))
+COMP_MANPAGES := $(patsubst hal/components/%.comp, ../docs/build/man/man9/%.9, $(COMPS)) ../docs/build/man/man9/tpcomp.9
 ifeq ($(BUILD_SYS),uspace)
 COMP_DRIVERS += hal/drivers/serport.comp
 COMP_DRIVERS += hal/drivers/mesa_7i65.comp
@@ -56,7 +56,7 @@ endif
 # wildcard that mixes hal/components and hal/drivers, so deriving the adoc
 # targets from it there yields hal/drivers/*.comp entries that fail the
 # hal/components/%.comp static pattern rule.
-COMP_MANPAGE_ADOCS := $(patsubst hal/components/%.comp, objects/man/man9/%.9.adoc, $(COMPS)) objects/man/man9/tpcomp.9.adoc objects/man/man9/homecomp.9.adoc
+COMP_MANPAGE_ADOCS := $(patsubst hal/components/%.comp, objects/man/man9/%.9.adoc, $(COMPS)) objects/man/man9/tpcomp.9.adoc
 COMP_DRIVER_MANPAGE_ADOCS := $(patsubst hal/drivers/%.comp, objects/man/man9/%.9.adoc, $(COMP_DRIVERS))
 
 # Extract adoc from .comp via halcompile --adoc.  Only needs Python +