Clarification of subroutine return data

In the current version of LinuxCNC documents for subroutines (linuxcnc.org/docs/html/gcode/o-code.html), section 3 states that subroutines do not have return values.

"Subroutines do not have return values, but they may change the value of parameters above #30 and those changes will be visible to the calling code. Subroutines may also change the value of global named parameters."

Yet, in Section 9 of the same page...

"Subroutines may optionally return a value by an optional expression at an endsub or return statement.
......
A subroutine return value is stored in the <_value> predefined named parameter , and the <_value_returned> predefined parameter is set to 1, to indicate a value was returned."

It is a bit confusing, but I think the Section 3 comment should be either deleted, corrected or somehow modified.

woudent it be a nice thing to
get Examples for etch subroutine direct into the NC_folder examples im missing this also for education use as Students like to look into examples
and IUm shure not the only one

BigJohnT wrote:

The documents have been corrected.

What is the process lately for contributing and participating in making such corrections?

During my recent LinuxCNC installation project, I collected several pages of notes (including this confusion of subroutine return behavior) of things in the documentation that need clarification, expansion or correction. This list spans minor typos to serious lapses of clarity.

For example, the M Codes documentation on M66 says, "In LinuxCNC these inputs are not monitored in real time and thus should not be used for timing-critical applications." To my understanding, this should say the readings are monitored but not synchronously with the G-code interpreter execution (the "queue busting" problem), and G-code must otherwise synchronize to external information. (In which case what good are they?) Why say "not monitored" when they are, or if not monitored, they are meaningless? Unless they're only good for reading some state prior to run-time that doesn't change during the entirety of run-time? I've implemented an adaptive-positioning feedback algorithm in G-code that uses M66 to bust the queue and synchronize the G-code run-time with HAL states, and it works perfectly, so I know that the documentation is too dismissive. This complexity might have been clear in the minds of the developers, but the documentation doesn't represent that clarity. The issue amounts to the control-theory principle that you can implement feedback algorithms in G-code, but they must self-enforce a lower bandwidth feedback loop (by waiting on external real-time process synchronization via M66 queue-busting) than the real-time core apparatus. The G-code also has to be wise to the dry-run of the interpreter's read-ahead occasion and accommodate that.

Here's the method in pseudo-G-code that works despite the documentation saying it can't:


This method is independent of the axis absolute position. The subroutine doesn't know and doesn't care where the axis is (i.e., G53,G54,...,G59.3 values, and all the offsetting apparatus)! All axis motion is relative. I conclude this control agnosticism the only way it could possibly succeed, and that compensation tables cannot succeed.

andypugh wrote:

What it actually means is that they [m66 commands?] are not monitored in the realtime thread, so there is no guarantee that the result of a change in state will be actioned in a bounded time. Code execution might pause for many tens of milliseconds. This is in contrast to the results of changes to HAL pins that are typically actioned in < 1mS.

Thank you for explaining that.

The documentation on m66 seems overbroad in saying "real time", not "realtime thread", which unclearly implies that m66 can't be relied on for any real action, or for any definite effect. If I understand your explanation correctly, m66 is definite in "ordinal" real time, just not "cardinal" real time. In plainer terms, the action of an m66 command will be definitely in effect before the next G-code line starts, but there is no definition of how much clock time will elapse between the m66 starting and the next line starting. But this is true of any G-code command: the programmer has no control or run-time awareness of how long anything takes (cardinal real time, the clock), but does control the order in which actions progress (ordinal real time, the sequence). The significance is that you can program real-time feedback loops in G-code, as long as the controlled variable is a logical or physical ordinate, and insensitive to elapsed time. My adaptive positioning example is a demonstration. It achieves a definite physical goal (positioning to an independent scale reading) through a feedback loop, with a known result, and without having control (other than timeout) over the loop bandwidth or clock time required.

Kind of like air travel these days. You define and control the destination in ordinal time, not the delays in cardinal time. Schedules are imaginary. Sometimes you time out and they send you back home.