docs: correct statements that no longer match the source (Code Notes, G-code, HAL) - #4349
Open
Zia-research wants to merge 3 commits into
Open
docs: correct statements that no longer match the source (Code Notes, G-code, HAL)#4349Zia-research wants to merge 3 commits into
Zia-research wants to merge 3 commits into
Conversation
The linuxcnc-ethercat driver exports its activation funct globally:
rtapi_snprintf(name, HAL_NAME_LEN, %s.activate, LCEC_MODULE_NAME);
(src/lcec_main.c:408 in linuxcnc-ethercat at 87a72a8). Only the cyclic
read/write functs are per-master (lcec.<master>.read / .write). A user
copying the manual's example into a .hal file gets a funct that does
not exist.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Seven corrections, each verified against the current source: - Buffer line types: only SHMEM, LOCMEM and PHANTOM are implemented. FILEMEM and GLOBMEM are recognised nowhere in src/libnml/; RTLMEM is rejected explicitly by cms_config(). (cms_cfg.cc:729,819,844,849) - OVERRIDE_LIMITS: the "currently broken" note described a bug fixed long ago. Limits are automatically re-enabled at the end of the next jog, and only tripped limits are overridden, via a mask built from the joints' hard-limit flags. (command.c:702-730) - The 2020 command-count note: figures updated 73/70 -> 76/73 (the same three commands still lack handlers). - PAUSE: documented the actual semantics - deceleration to a stop within the current segment at that segment's acceleration limit, and the exception that pause is bypassed during position-synchronized (threading / rigid tapping) segments. (tp.c:243-252,2782-2787) The run-down is jerk-limited only where the S-curve planner is selected: [TRAJ]PLANNER_TYPE defaults to 0 = trapezoidal (emccfg.h:57, initraj.cc:157) and is forced back to 0 when jerk is below 1.0 (initraj.cc:159-162), while MAX_JERK itself defaults to 0 (emccfg.h:51,70,87). tp.c enters the S-curve branch only for type 1 (tp.c:3660,3664), so a stock machine never plans one. Thanks to grandixximo for catching the earlier wording, which implied jerk limiting always applies. - ENABLE / STEP Requirements: neither is "always accepted". ENABLE is rejected while the motion.enable HAL pin is low (command.c:1366); STEP is rejected unless the planner is already paused (command.c:1261). - EMCIO chapter: removed the leftover "iocontrol main loop process" wording that contradicted the chapter's own first line; noted the iocontrol.0 / [EMCIO] names are kept for compatibility. - Reckoning of joints and axes: the initraj.cc:loadTraj() example pointed at code that has since been fixed to handle all nine axes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…rpreter
Each change verified against src/emc/rs274ngc at the current source:
- G33 and G33.1: the error lists claimed "The requested linear motion
exceeds machine velocity limits due to the spindle speed". No such
check exists anywhere - the interpreter's only checks are axis word
present, K present, F absent, valid $, and spindle commanded turning
(interp_check.cc:375-378, interp_convert.cc:5496-5529). Replaced the
phantom error with the two real ones that were missing (K word
required, F word forbidden), and stated that "spindle not turning"
tests the commanded state (M3/M4), which is what
settings->spindle_turning holds.
- G33.1: documented that an I word below 1 is treated as 1
(interp_convert.cc:5522-5527).
- G64: documented that changing path control mode is an error while
cutter radius compensation is active ("Cannot change control mode
with cutter radius compensation on", interp_convert.cc:2221).
- G96: removed "A feed move is specified in G96 mode while the spindle
is not turning" from the error list. No such check exists in the
interpreter, task or motion; the spindle-not-turning checks apply
only to G33/G33.1/G76 and the tapping cycles. Documented that
without D the interpreter applies no RPM limit in CSS mode
(SET_SPINDLE_MODE is called with 1e30, interp_convert.cc:5087).
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
grandixximo
reviewed
Aug 8, 2026
| statement in command.c contemplates only 70 commands (as of 6/5/2020). | ||
| ENABLE_WATCHDOG / DISABLE_WATCHDOG commands are in motion-logger.c. Maybe they are obsolete. | ||
| The SET_TELEOP_VECTOR command only appears in motion-logger.c, with no effect other than its own log. | ||
| The cmd_code_t enumeration, in motion.h, contains 76 commands, but the switch |
Contributor
There was a problem hiding this comment.
76/73 and "as of 8/2026" will go stale exactly like 73/70 and 6/5/2020 did; naming the three unhandled commands without the arithmetic stays true indefinitely. Nothing in the tree sends them, see #4359.
grandixximo
reviewed
Aug 8, 2026
| None. The command can be issued at any time, and will always be | ||
| accepted. | ||
| The command is rejected with an error message ("can't enable motion, | ||
| enable input is false") if the motion.enable HAL pin is low. The |
Contributor
There was a problem hiding this comment.
motion.enable is created with default value 1 (motion.c:528), so unconnected reads TRUE and this is never hit on a normal machine; "the hardware enable chain must be satisfied" overstates it.
grandixximo
reviewed
Aug 8, 2026
| The PAUSE command pauses the trajectory planner. It has no effect in | ||
| free or teleop mode. | ||
|
|
||
| The machine neither stops instantly nor completes the current move: the |
Contributor
There was a problem hiding this comment.
This is planner behaviour rather than PAUSE-command behaviour; two sentences plus the synchronized-motion exception would cover what a Code Notes reader needs.
grandixximo
reviewed
Aug 8, 2026
| machine decelerates to a stop within the current segment, at that | ||
| segment's acceleration limit, and halts wherever the deceleration ramp | ||
| ends. The run-down is jerk-limited only on machines configured for the | ||
| S-curve planner ([TRAJ]PLANNER_TYPE = 1 with a non-zero MAX_JERK); both |
Contributor
There was a problem hiding this comment.
Duplicates ini-config.adoc:947, and the threshold is MAX_JERK < 1.0 (inihal.cc:302 and :320), not non-zero.
grandixximo
reviewed
Aug 8, 2026
| bypasses both pause and feed override, because tool position is slaved | ||
| to spindle angle and pausing mid-thread would destroy the work. | ||
| The pause takes effect when the synchronized segment ends. | ||
| Velocity-synchronized segments (G96 style) can be paused normally. |
Contributor
There was a problem hiding this comment.
This is G95, not G96: TC_SYNC_VELOCITY comes from velocity_mode = 1 at emccanon.cc:521 and :530.
grandixximo
reviewed
Aug 8, 2026
| * 'name' - is the identifier of the buffer. | ||
| * 'type' - describes the buffer type - SHMEM, LOCMEM, FILEMEM, PHANTOM, or GLOBMEM. | ||
| * 'type' - describes the buffer type - SHMEM, LOCMEM, or PHANTOM. | ||
| (Older RCS documents also list FILEMEM, GLOBMEM and RTLMEM; none of these is |
Contributor
There was a problem hiding this comment.
Trimming the list is right, but the parenthetical puts the document back to tracking its own history; also "recognise" is the only British spelling in the file.
grandixximo
reviewed
Aug 8, 2026
| For an example of such a bug, see the treatment of axes in src/emc/ini/initraj.cc:loadTraj(). | ||
| There are undoubtedly more, and I need your help to find them and fix them. | ||
| Deviations from this design are considered bugs; if you find one, | ||
| please report it. (An earlier revision of this document pointed at the |
Contributor
There was a problem hiding this comment.
Same as above, the parenthetical keeps the removed bug report alive; the sentence before it is enough on its own.
grandixximo
reviewed
Aug 8, 2026
| * The requested linear motion exceeds machine velocity limits | ||
| due to the spindle speed. | ||
| * No K word is given. | ||
| * An F word is given (the feed follows from K and the spindle speed). |
Contributor
There was a problem hiding this comment.
Additions check out (interp_check.cc:376 and :377). Could the deleted velocity-limit line stay as a NOTE though? It is real behaviour when pitch times RPM exceeds the axis limit, and it was the only mention in the manual.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Disclaimer. This work is AI-generated — directed, reviewed and published by me. Every
claim carries a
file:linecitation, and a script re-reads each cited line against thesource. @grandixximo reviewed these three patches on #3718 and checked the claims at the
cited locations; the one defect he found — the PAUSE paragraph's jerk wording — is fixed
here.
Three documentation corrections, each for a statement that no longer matches the source.
docs/src/hal/basic-hal.adoc— theinitfexample names a funct the lcec driver doesnot export:
lcec.0.activate. The real name islcec.activate, and it is global ratherthan per-master. Fixed in the prose and in the example block.
docs/src/code/code-notes.adoc— seven corrections. Two remove bug reports for bugsfixed years ago (
OVERRIDE_LIMITS, theinitraj.ccexample) — the failure mode where adocument records defects but never their repair. The PAUSE rewrite adds a fact documented
nowhere else: pause is bypassed while a segment is position-synchronized to the spindle,
i.e. during threading and rigid tapping, because
tpGetFeedScale()returns1.0there.docs/src/gcode/g-code.adoc— the G33/G33.1, G64 and G96 error lists aligned with theinterpreter: two phantom errors removed, several real and undocumented ones added.
The commit messages carry the evidence,
file:linefor each change. The full audit,including its own corrections, is at https://github.com/Zia-research/linuxcnc-audit
Base. Rebased on current master. The three files are unchanged upstream since the
audit was made, so these are the diffs that were reviewed.
One caveat. The wording describes
master. If 2.9-applicable text is wanted, thecommand-count note (73/70 → 76/73) is the only figure that differs —
cmd_code_twouldneed checking on the 2.9 branch first.
Independent of #3718, and it does not touch the block diagram.