From 448e25c86dd8f12f176f06ad9b2b2b38b6ff1160 Mon Sep 17 00:00:00 2001
From: Luca Toniolo <10792599+grandixximo@users.noreply.github.com>
Date: Sun, 17 May 2026 14:21:15 +0800
Subject: [PATCH] docs: document initf command

Add initf documentation alongside loadrt/addf in the HAL basics guide
and the halcmd(1) and haltcl(1) manpages.
---
 docs/src/hal/basic-hal.adoc     | 20 ++++++++++++++++++++
 docs/src/man/man1/halcmd.1.adoc |  7 +++++++
 docs/src/man/man1/haltcl.1.adoc |  2 +-
 3 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/docs/src/hal/basic-hal.adoc b/docs/src/hal/basic-hal.adoc
index f96a7b1c3a0..af2b5c3b9ce 100644
--- a/docs/src/hal/basic-hal.adoc
+++ b/docs/src/hal/basic-hal.adoc
@@ -98,6 +98,26 @@ addf <function> <thread>
 addf mux4.0 servo-thread
 ----
 
+[[sub:hal-initf]]
+=== initf
+
+(((HAL initf,initf)))
+The `initf` command registers a function to run once in realtime context, on a dedicated init cycle of the thread before the cyclic function list runs.
+It is the realtime-thread analogue of `addf`, intended for one-shot setup that must execute in the realtime task (for example EtherCAT master activation via `lcec.0.activate`).
+
+`initf` adds function _functname_ to the init list of thread _threadname_.
+The init list runs once on the first cycle after `start`, then is drained.
+The cyclic list begins on the following period.
+Once the init cycle has run, further `initf` calls on that thread are rejected.
+`position` has the same meaning as in `addf`.
+
+.initf Syntax and Example
+[source,{hal}]
+----
+initf <function> <thread>
+initf lcec.0.activate servo-thread
+----
+
 [[sub:hal-loadusr]]
 === loadusr
 
diff --git a/docs/src/man/man1/halcmd.1.adoc b/docs/src/man/man1/halcmd.1.adoc
index 8ed5c67ad2d..90d21affa46 100644
--- a/docs/src/man/man1/halcmd.1.adoc
+++ b/docs/src/man/man1/halcmd.1.adoc
@@ -192,6 +192,13 @@ _pinname_ *=* _value_::
   _threadname_. _functname_ will run after any functions that were
   previously added to the thread. Fails if either _functname_ or
   _threadname_ does not exist, or if they are incompatible.
+*initf* _functname_ _threadname_::
+  (__init__ __f__unction) Registers _functname_ to run once in realtime
+  context on a dedicated init cycle of _threadname_, before the cyclic
+  function list executes. Intended for one-shot setup that must run in
+  the realtime task (for example EtherCAT slave configuration). Once
+  the init cycle has run, further *initf* calls on that thread are
+  rejected. Fails if either _functname_ or _threadname_ does not exist.
 *delf* _functname_ _threadname_::
   (__del__ete __f__unction) Removes function _functname_ from realtime
   thread _threadname_. Fails if either _functname_ or _threadname_ does
diff --git a/docs/src/man/man1/haltcl.1.adoc b/docs/src/man/man1/haltcl.1.adoc
index ba13939d3a4..770ea10383d 100644
--- a/docs/src/man/man1/haltcl.1.adoc
+++ b/docs/src/man/man1/haltcl.1.adoc
@@ -56,7 +56,7 @@ The augmented commands can be listed with the command:
 
 `haltcl: hal --commands`+
 
-`addf alias delf delsig getp gets ptype stype help linkpp linkps linksp list loadrt loadusr lock net newsig save setexact_for_test_suite_only setp sets show source start status stop unalias unlinkp unload unloadrt unloadusr unlock waitusr`
+`addf alias delf delsig getp gets initf ptype stype help linkpp linkps linksp list loadrt loadusr lock net newsig save setexact_for_test_suite_only setp sets show source start status stop unalias unlinkp unload unloadrt unloadusr unlock waitusr`
 
 Two of the augmented commands, 'list' and 'gets', require special treatment
 to avoid conflict with Tcl built-in commands having the same names.