docs: fix pin/param documentation errors found by a docs-vs-code sweep by grandixximo · Pull Request #4606 · LinuxCNC/linuxcnc

grandixximo · 2026-09-29T11:40:11Z

A docs-vs-code sweep following the HAL API docs update (#4596 - #4599). While the type renames are now consistent, the sweep found a set of long-standing factual errors in pin and parameter documentation: wrong names, wrong types, wrong directions, parameters that are actually pins, pins that do not exist, and defaults the code does not have. Each fix was verified against the component or driver source.

The final commit covers the bulk old-type-name rename for hostmot2(9), sserial(9) and hm2_eth(9) (the three pages the rename PRs did not cover), folded in as requested in review. It only touches type words in pin/param tags and leaves prose (bit fields, 16/18-bit counts, bit streams) alone.

HAL manual (rtcomps.adoc)

stepgen: no default step_type (loadrt fails without it), MAX_CHAN is 16, step types run 0-15 with type 15 user-defined via user_step_type
pwmgen: scale/offset/pwm-freq/dither-pwm/min-dc/max-dc/curr-dc are pins (HAL_IO/HAL_OUT), not parameters; document the offset pin
encoder: latch-input defaults FALSE, latch-rising TRUE; drop the per-function timing table (those objects are generic to every HAL function, not encoder-specific); document velocity-rpm
pid: saturated-s/saturated-count/do-pid-calcs use dashes; document command-deriv, feedback-deriv, FF3, maxcmdDDD, index-enable, error-previous-target, the tune-* pins and the remaining debug pins
sim_encoder: ppr and scale are HAL_IO pins; document rawcounts
debounce: no default cfg, macro is MAX_GROUP, group size limited to 50
siggen: document clock and reset pins

Man pages

hostmot2(9): dpll.prescale direction, no_clear_on_index spelling, count-latched, data-invalid, ssi.MM.timer-number, fanuc batt_fail/pos_invalid, position-latch, and several direction/type corrections
sserial(9): port_state/fault-count names, 7i76/7i77/7i71 output vs input-not directions, 7i73 encN pin expansion, swrevision copy-paste prefixes
hm2_eth(9): packet-error-decrement is RO
halui(1): tool.length_offset.* uses underscores (9 pins), garbled jog prose
vfs11_vfd(1): drop nonexistent output-voltage pin; frequency-limit/error-count/max-rpm are output pins
xhc-hb04(1): enable pins have the jog. prefix; xhc-whb04b-6(1): remove nonexistent home-all pin, fix three directions
moveoff_gui(1): mv.move-enable; io(1): tool-from-pocket; sendkeys(1): trigger-MM; gs2_vfd(1): enable and initialized pins
hy_vfd(1): "(bin, in)" was never a type; demux_generic(9): bit-to-bit leftover

Driver docs

vfs11: frequency-limit is a pin, drop nonexistent output-voltage
pmx485: prose pin names use underscores like the component
mitsub-vfd: stat-bit-N
gm: index-enable spelling, counts-per-rev uint, invert-serial bool, axis vs joint switch pins, estop pins-not-params, relay direction, rs485 %02d numbering, example fixes
pico-ppmc: -ns param suffixes, freq name, DAC8 dot, DAC direction
mb2hal: stale type words, zero-based bit numbering in the example

Rendering

halmodule.adoc: 8-column table spec on 6-cell rows made asciidoctor drop cells (introduced in docs: Update to reflect the HAL API changes #4596)

…eric.9 hy_vfd.1 documented spindle-reverse/spindle-on as '(bin, in)', a type name that never existed; both are bool IN pins (hy_vfd.c). demux_generic.9 kept 'bit-to-bit' where mux_generic.9 was updated to 'bool-to-bool'.

stepgen: no default step_type (load fails without it), MAX_CHAN is 16, step types run 0-15 with type 15 user-defined via user_step_type. pwmgen: scale/offset/pwm-freq/dither-pwm/min-dc/max-dc/curr-dc are pins (HAL_IO/HAL_OUT), not parameters; document the offset pin. encoder: latch-input defaults FALSE, latch-rising defaults TRUE; .time values are output pins, .tmax/.tmax-increased are per-function params without a channel prefix; fix update-counter.tmax typo; document velocity-rpm. pid: saturated-s/saturated-count/do-pid-calcs use dashes; document command-deriv, feedback-deriv, FF3, maxcmdDDD, index-enable, error-previous-target, the tune-* pins and the remaining debug pins. sim_encoder: ppr and scale are HAL_IO pins, not parameters; document rawcounts. debounce: no default cfg (load fails without it), macro is MAX_GROUP, group size limited to MAX_GROUP_SIZE 50. siggen: document clock and reset pins.

vfs11.adoc: drop nonexistent output-voltage pin; frequency-limit is a pin (real out), not an RO parameter. pmx485.adoc: prose used dashed pin names; the Python component registers mode_set/current_set/pressure_set with underscores. mitsub-vfd.adoc: status-bit-N is stat-bit-N. gm.adoc: index-enable (not index-enabled); counts-per-rev is uint R/W; invert-serial is bool; can-gm position-fb is an output and the example pin is position-fb; watchdog-timeout-ns is uint; switch pins live under gm.N.axis.N (not joint); estop in/in-not are pins, not parameters; relay pins are inputs; rs485 module numbering is %02d; fix stepspace example typo. pico-ppmc.adoc: setup-time/pulse-width/pulse-space-min gain the -ns suffix; stepgen frequency is freq; DAC8 value pin uses a dot; DAC value is an input. mb2hal.adoc: stale bit/float/s32 type words renamed; first bit example is .00 (numbering is zero-based).

halui.1: tool.length_offset.* uses underscores (9 pins); drop garbled 'bit in in' leftovers in jog prose. vfs11_vfd.1: drop nonexistent output-voltage pin; frequency-limit and error-count are output pins, max-rpm is an output pin. xhc-hb04.1: enable pins have the jog. prefix (jog.enable-x etc). xhc-whb04b-6.1: remove nonexistent whb.halui.home-all pin; feed-override.scale and spindle-override.scale are outputs, max-velocity.value is an input. moveoff_gui.1: pin is mv.move-enable. io.1: document iocontrol.0.tool-from-pocket. sendkeys.1: document sendkeys.N.trigger-MM pins. gs2_vfd.1: document the enable and initialized pins.

The hal64 docs update left an 8-column spec on a table whose rows now have 6 cells, making asciidoctor drop cells with 'dropping cells from incomplete row'.

Factual fixes verified against the driver sources (the bulk old-type rename for these pages is a separate change): hostmot2.9: dpll.prescale is an output; no_clear_on_index uses underscores; encoder probe-enable/probe-invert are inputs; count_latch is count-latched; muxed-skew is u32; encoder timer-number is an input pin; ssi/biss data-incomplete is data-invalid (out); ssi timer-number-num is ssi.MM.timer-number; fanuc batt/valid are batt_fail/pos_invalid; resolver joint-pos-fb is float; 3pwmgen sample-time is float; periodm averages is u32 and invert is io; stepgen position-latched is position-latch; stepgen index-invert/probe-invert are input pins; swap_step_dir is an r/w param; gpio example uses in_not. sserial.9: run_state is port_state; error-count is fault-count; 7i76/7i77/7i71 output pins are 'in' and input-NN-not pins are 'out'; 7i70/7i71 swrevision copy-paste prefixes; 7i73 encN expanded to count/rawcounts/position/index-enable/reset; 7i73 output-00-invert is bit rw. hm2_eth.9: packet-error-decrement is ro.

Bulk rename of type-position bit/float/s32/u32 to bool/real/sint/uint, which the HAL API docs update (LinuxCNC#4596-LinuxCNC#4599) did not cover. Prose uses (bit stream, firmware bit files, 16/18-bit galvanometer protocol widths) are left alone.

BsAtHome · 2026-09-29T12:37:30Z

+f: (bitField):: (bool, out) hm2_XXXX.N.ssi.MM.<name>-NN. +
+ The value of each individual bool in the data field.
 NN starts at 00 up to the number of bits in the field. +
- (bit, out) hm2_XXXX.N.ssi.MM.<name>-NN-not. +
+ (bool, out) hm2_XXXX.N.ssi.MM.<name>-NN-not. +
 An inverted version of the individual bit values.


The change in the text is inconsistent. "The value of each individual bit in the data field." refers to the bit in a word and not the pin type.

BsAtHome · 2026-09-29T12:39:00Z

+ (real, r/w) hm2_XXXX.N.ssi.MM._<name>_.scale: (real, r.w) The encoder
+ scale in counts per machine unit. (uint, r/w)
+ hm2_XXXX.N.ssi.MM._<name>_.counts-per-rev (uint, r/w) Used to emulate the


Are there some newlines missing here?

BsAtHome · 2026-09-29T12:40:02Z

+hm2___XXXX__._N_.fanuc._MM_.batt_fail:: indicates battery state
+hm2___XXXX__._N_.fanuc._MM_.batt_fail-not:: inverted version of above
 hm2___XXXX__._N_.fanuc._MM_.comm:: The 0-1023 absolute output for motor commutation
 hm2___XXXX__._N_.fanuc._MM_.crc:: The CRC checksum. Currently HAL has no way to use this
 hm2___XXXX__._N_.fanuc._MM_.encoder.count:: Encoder counts
 hm2___XXXX__._N_.fanuc._MM_.encoder.index-enable:: Simulated index. Set by counts-per-rev parameter
 hm2___XXXX__._N_.fanuc._MM_.encoder.position:: Counts scaled by the ...scale parameter
 hm2___XXXX__._N_.fanuc._MM_.encoder.rawcounts:: Raw counts, unaffected by reset or index
 hm2___XXXX__._N_.fanuc._MM_.encoder.reset:: If high/True then counts and position = 0
-hm2___XXXX__._N_.fanuc._MM_.valid:: Indicates that the absolute position is valid
-hm2___XXXX__._N_.fanuc._MM_.valid-not:: Inverted version
+hm2___XXXX__._N_.fanuc._MM_.pos_invalid:: Indicates that the absolute position is not valid
+hm2___XXXX__._N_.fanuc._MM_.pos_invalid-not:: Inverted version


These are not including type and direction. Add them for consistency?

BsAtHome · 2026-09-29T12:42:07Z

+offset-mode (bool r/w)::
 When True, offset-mode modifies the PWM behavior so that a PWM value


Sometimes it is called "r/w" and other places it is "rw". We should pick one: rw (in, out, io, ro).
(many places)

BsAtHome · 2026-09-29T12:43:37Z

+enable (bool input)::
 When high the PWM is enabled as long as the fault bit is not set by


direction in

BsAtHome · 2026-09-29T12:54:26Z

+has_bit (bool in/out)::
 True if the watchdog has bit, False if the watchdog has not bit.


Direction naming

BsAtHome · 2026-09-29T12:54:39Z

+timeout_ns (uint read/write)::
 Watchdog timeout, in nanoseconds.


Direction naming

BsAtHome · 2026-09-29T12:58:23Z

+angle (real in)::
  The rotor angle of the motor in fractions of a full *phase* revolution.


This is again inconsistent naming when the prefix(es) are not added.

IMO, the least it needs is the leading . to make it clear that the name is not an independent name. (.angle (real, in)::)

BsAtHome · 2026-09-29T13:03:43Z

+count (sint out)::
 Number of encoder counts since the previous reset. 32-bit truncation of the 64-bit internal counter; position is computed from the full-width internal value so it does not wrap.


There is an inconsistency in the type/dir suffix. Some have a comma and some don't. I think they all should be done consistently as (<type>, <dir>) with a comma and one space after the comma and no leading/trailing space within the parentheses. This should be done throughout.

BTW, I knew there as a reason these were not yet done... All the different spellings and inconsistencies are the reason ;-)

BsAtHome · 2026-09-29T13:08:42Z

+status and fault. (bool, ro):: The following fault/status bits are exported.
  For further details see the 8I20 manual: +


having two parameters on one line is not consistent. Maybe better to do:

<prefix>.status (bool, ro):: <prefix>.fault (bool, ro):: The 'fault' and 'status' bits are exported. For further detail see the 8I20 manual: + ...

BsAtHome · 2026-09-29T13:10:49Z

Just as I noted in one of the review comments... There are many inconsistencies in the hostmot2 docs. Also remember why I had not yet done them... too much thinking needed ;-)

grandixximo · 2026-09-29T13:20:37Z

I'll do the thinking tomorrow, brain is off