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-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

Unify the suffix zoo to (<type>, <dir>) with dirs from in/out/io/ro/rw: r/w and read/write => rw, in/out and IO => io, input/output => in/out, and the periodm bare r/w abbreviations => real HAL directions verified against the driver sources. Add a leading dot to entries that dropped the HAL name prefix. Add missing type/dir tags in the fanuc section, split the combined 8I20 status/fault entry, fix the jammed SSI encoder parameter block (and its r.w typo), correct inm pin names (input-MM, input-MM-not, raw-input-MM, input-MM-slow) and inm parameter directions (scan_rate, fast_scans, slow_scans, encN_4xmode are RW parameters, scan_width is RO), complete the sserial.port-N prefix on the port pins/parameters, move the xy2mod timer numbers to the pin list and fix its underscore pin names (posx-cmd, velx-cmd, accx-cmd, posx-fb, velx-fb, posx-scale), correct the rcpwmgen rate/width/offset/scale pins to HAL_IN, restore "bit" prose in the SSI bitfield and xy2mod control descriptions, and fix the status.current-lim-not typo. A leading period at the start of a line is an asciidoc block title and breaks the definition list markup, so indent the dotted entries by one space; the dot stays visible in both the HTML and manpage output. Also fix the malformed line continuation in the 8I20 fault/status list that rendered a literal plus sign.

BsAtHome · 2026-09-30T13:23:39Z

hostmot2.9.adoc:

config modparam section in sserial_port list item: the sserial(9) reference is in all CAPS. Should be lower case.
dpll section: prefix specification is off (see also other items noted here). The pins/params should drop the prefix and use the .pinname (type, dir):: format.
Encoder section: There are several pins and a parameters that suddenly use a hm2_XXXX.N prefix where the others all start with a period.
Fanuc encoder section: suddenly the prefix is not using the underscore and becomes hm2XXXX._N. The source should probably read: hm2_XXXX.__N__.fanuc.__MM__.<pinname>. Better would be to describe the prefix at the start of the section and use the .pinname (type, dir):: format throughout in all sections.
3ppwmgen section: The prefix specification suddenly drops the boldface in "hm2_<BoardType>.<BoardNum>.3pwmgen.<Instance>".
FWIW, (all) other places have a spec that includes boldface and italics, but the boldface is dropped in favour of the italics in the rendering. I think the the asciidoc order is __**boldItalic**__, whereas the source uses **__wrongOrder?__**. You may want to test this.
Oneshot section: The table in the .trigger_select1, .trigger_select2 list item needs to be part of the list item. You should drop the empty line.
Stepgen section: one parameter has hm2_XXXX.N prefix.
General purpos I/O section: it states .in & .in_not (bool, out). The usual metgod to write this is .in, .in_not (bool, out) with a comma.
inm and inmux section: The numeric ID/suffix usually is in italic. You may want to specify .input-__MM__ (bool, out):: etc. This also happens in other sections/places.
xy2mod section: No prefix specification is named. Should be added.
SEE ALSO section: should add sserial(9) ad the first in the list.
Smart Serial Interface section: The sserial(9) link does not function because the parentheses are separated by a bold modifier. Just drop the bold.

sserial.9.adoc:

PORTS section: there is no prefix specification. Should add one.
8I20 section: The .status and .fault are not pins by themselves. Maybe they should be specified as .status.* and .fault.*? The list of actual pins is just ugly and barely readable. Either we must spell it out as for other pins or, better, this should be a sub-list using ;; inside the :: list.

BsAtHome · 2026-09-30T13:32:42Z

Have more to write...

fault and status:

 .status.*::
  .brake-old, .brake-old-not;;
    bla bla
  .brake-on, .brake-on-not;;
    bla bla
  .bus-underv, .bus-underv-not;;
  .current-lim, .current-lim-not;;
  .ext-reset, .ext-reset-not;;
  .no-enable, .no-enable-not;;
  .pid-on, .pid-on-not;;
  .sw-reset, .sw-reset-not;;
  .wd-reset, status.wd-reset-not;;

And then actually take the description out of the manual and add it here?

Section 8I20:
The prefix needs to be consistent (boldface markings; see other msg).

Section 7I69, 7I70, 7I71, 7I73:
The MODE<N> list should probably be a table.
Prefix description needs to be added.

…sserial man pages Every section now states its HAL name prefix once in the standard bold/italic form and the pin and parameter entries use the .name (type, dir):: form relative to it. This covers the dpll, encoder (module-global pins and timer-number moved to the pin list), SSI, BiSS and Fanuc sections, the stepgen timer-number (also corrected to sint, in; it is a module-global HAL_IN pin), the 3pwmgen prefix markup (which lost the boldface to a ___triple-underscore___ span), and the xy2mod section which had no prefix specification at all. On the sserial page the PORTS section gains the prefix specification, and the 7I64/7I69/7I70/7I71/7I73 entries drop the hardcoded instance numbers (.7i64.0.0. etc.) in favour of a stated prefix; the 7I73 notes that the analog inputs live on channel 0 and the remaining pins on channel 1. Restructure the 8I20 status/fault entry per review: the two groups are now .status.* and .fault.* labeled-list entries with a nested ;; sublist of the actual pins, with descriptions taken from the 8I20 manual. The bare parameter list drops its hardcoded hm2_5i25.0.8i20.0.1. prefixes. Convert the 7I69/7I70/7I71/7I73 MODE lists to tables, attach the oneshot trigger table to its list item with a + continuation, fix the malformed indented + continuations in the dpll timer-us description that rendered literal plus signs, write .in, .in_not with a comma in the GPIO section, italicize the MM placeholder in the inm/inmux pin names, fix the SSERIAL(9) all-caps reference and the bold-broken sserial(9) link, and add sserial(9) to SEE ALSO.

grandixximo · 2026-09-30T14:10:20Z

Agreed, time to paint the bike shed, it was indeed all rusty ;-)

grandixximo · 2026-09-30T14:25:39Z

All points addressed in e8e7e66, rendering verified in the built HTML.

On the bold-italic question: the 3pwmgen line was the only real case, it used ___<BoardType>___ with unmarked text around it. Every other prefix spec uses adjacent **bold**__italic__ spans and I confirmed in the rendered page that both marks survive, so no wrong-order nesting anywhere.

7I64 got the same prefix treatment as 7I69-7I73. 7I76/7I77 still carry literal instance numbers since the 7I77 analog section really lives on channel 1; happy to do those next if you want them relative too.

The 8I20 descriptions come from the manual (mesanet.com is serving spam these days, so via the Wayback Machine). Also found while verifying: the dpll timer-us text had the same literal + continuation bug as the 8I20 list, fixed.

BsAtHome · 2026-09-30T14:28:46Z

Agreed, time to paint the bike shed, it was indeed all rusty ;-)

Only if I may determine its colour ;-)

BsAtHome · 2026-09-30T14:58:48Z

Since we are painting,...

In hostmot2 section encoder you have: **hm2_**__<BoardType>__**.**__<BoardNum>__**.encoder.**__<Instance>__**.**"
It has a stray trailing double quote. The trailing period after <Instance> is also wrong because that period is part of the list's entries as the first character.

That trailing period is other places as well, but not everywhere.
Another inconsistency is that the prefix is sometimes enclosed in double quotes and other places it did not.

All like some tiles are red and others became green (by some divine intervention?). I suggest we blend some blue in there as well :-)

After this I will shut up, unless the formatting breaks badly. Time to do other work.

…ages All prefix specifications now use the same form: **hm2_**__<BoardType>__**.**__<BoardNum>__**.<comp>.**__<Instance>__** with no enclosing double quotes and no trailing period, since the leading period belongs to the relative pin entries. Fixes the stray trailing quote in the encoder section, the unclosed bold span in the resolver section, and the single-underscore italics in the rcpwmgen, stepgen, inm/inmux, ssr, outm, watchdog and HAL function name specs.

Asciidoctor does not parse ** immediately following an __x__ span, so the trailing ** left on twelve prefix specification lines rendered as literal asterisks in the HTML output. Removed them; the prefix lines now end at the italic placeholder. Verified no literal ** remains in either the HTML or the manpage backend output.