From 0d51a329434583f9cbd6c72db5d8f4e069c848c1 Mon Sep 17 00:00:00 2001 From: Zia-research <309084419+Zia-research@users.noreply.github.com> Date: Thu, 13 Aug 2026 14:02:51 +0200 Subject: [PATCH 1/2] docs: replace the Code Notes architecture diagram with a corrected SVG code-notes.adoc renders LinuxCNC-block-diagram-small.png, unchanged in the repository since 2012-11-19 (b60c20198e). This adds a hand-written SVG with the same topology and ten corrections, each established by reading master at caa13ca6, and points the image directive at it. Nothing is removed: both PNGs stay in place, including the Spanish variant that the translation catalogue maps to. The corrections are listed with their source locations at https://zia-research.github.io/linuxcnc-audit/sheets/linuxcnc-code-notes-errata.html Co-Authored-By: Claude Opus 5 --- .../src/code/LinuxCNC-block-diagram-small.svg | 146 ++++++++++++++++++ docs/src/code/code-notes.adoc | 2 +- 2 files changed, 147 insertions(+), 1 deletion(-) create mode 100644 docs/src/code/LinuxCNC-block-diagram-small.svg diff --git a/docs/src/code/LinuxCNC-block-diagram-small.svg b/docs/src/code/LinuxCNC-block-diagram-small.svg new file mode 100644 index 00000000000..ce093358da1 --- /dev/null +++ b/docs/src/code/LinuxCNC-block-diagram-small.svg @@ -0,0 +1,146 @@ + + + + + + + + GUI · halui · linuxcncrsh + axis · gmoccapy · qtvcp · touchy · gscreen + + + + emcCommand + 8192 B · queue + emcStatus + 20480 B + emcError + 8192 B · queue + NML + the only triplet · owned by linuxcncsvr + + + + milltask + + RS-274 + interpreter · rs274ngc + + interp_list + std::deque + throttled at 1000 + + sequencing + emctaskmain.cc + + iocontrol.0.* + 14 HAL pins + former io process + tool, coolant, estop — no NML channel left for I/O + + + + RTAPI shmem · key 100 · emcmot segment + + emcmot_command_t + SINGLE SLOT + mutex + commandNum + + emcmot_status_t + seqlock head / tail + + config, internal + + emcmot_error_t + MPSC RING 32 × 1024 + the only real queue here + not NML, + not a FIFO: + one exchange at a time + + + ordinary scheduling + SCHED_FIFO — rtapi_app, user space + a scheduling boundary, no longer a kernel boundary — except under RTAI + + + motmod + loaded modules + + tpmod + trajectory planner + cruckig · finite jerk + + homemod + homing + + *kins + forward and inverse + kinematics · 19 modules + + TC_QUEUE + ring · 2000 segments + ≈ 1 MB + + spindle × 8 + spindle.N.on · speed-out + at-speed · index-enable + + limit and home + status + + JOINT 1 … 16 — a motor, not an axis · 9 separate Cartesian axes + + cubic interpolator + + backlash + screw comp + output: motor_pos_cmd on a HAL pin — the controller stops there + + WHAT THE DIAGRAM GOT RIGHT + cubic interpolator · forward and inverse kinematics · limit/home status + RS-274 interpreter · sequencing logic · NML triplet to the GUI + encoder and motor closing the loop · the principle of a real-time boundary + + + HAL + 2 MiB shared block · key 0x48414C32 · components ▸ pins ▸ signals ▸ functions ▸ threads + absent from the original — yet it now carries every bit of hardware coupling + + + HAL COMPONENTS — wired by the integrator, moved out of the controller + pid + stepgen + pwmgen + encoder + estop_latch + limit3 + 124 .comp + 25 .c source files + + + DRIVERS AND HARDWARE + hostmot2 · Mesa + hal_parport + gpio · rpi, beaglebone + + motor · encoder · limit switches · spindle — 23 driver files + hostmot2 (42 modules, one driver) + + \ No newline at end of file diff --git a/docs/src/code/code-notes.adoc b/docs/src/code/code-notes.adoc index c0f777a390f..98a8e87e22f 100644 --- a/docs/src/code/code-notes.adoc +++ b/docs/src/code/code-notes.adoc @@ -100,7 +100,7 @@ document, both from the design point of view and from the developers point of view (where to find needed data, how to easily extend/modify things, etc.). -image::LinuxCNC-block-diagram-small.png[align="center",pdfwidth=100%] +image::LinuxCNC-block-diagram-small.svg[align="center",pdfwidth=100%] === LinuxCNC software architecture From 8a166016c122a18d9c4bab7e65c28f8878d725e3 Mon Sep 17 00:00:00 2001 From: Zia-research <309084419+Zia-research@users.noreply.github.com> Date: Wed, 19 Aug 2026 14:13:20 +0200 Subject: [PATCH 2/2] docs: simplify the Code Notes diagram after review Drops what belonged to the errata sheet this figure was extracted from and carried no meaning here: the numbered errata markers, the "what the diagram got right" panel, the "absent from the original" caption, and the colour key, which marked what the audit had corrected rather than anything about LinuxCNC. Shape still carries meaning - a dashed outline is a queue; colour carries none. Also fixes the one label that overflowed its box (it was the only one), and trims the file header to what a future editor needs. This addresses three of the six points in the review. The other three - drivers and components side by side, motmod drawn as a container, the missing motion controller - are about what the figure is trying to show, and are answered separately. Co-Authored-By: Claude Opus 5 --- .../src/code/LinuxCNC-block-diagram-small.svg | 64 +++++++++---------- 1 file changed, 30 insertions(+), 34 deletions(-) diff --git a/docs/src/code/LinuxCNC-block-diagram-small.svg b/docs/src/code/LinuxCNC-block-diagram-small.svg index ce093358da1..4cbc334e6b6 100644 --- a/docs/src/code/LinuxCNC-block-diagram-small.svg +++ b/docs/src/code/LinuxCNC-block-diagram-small.svg @@ -1,29 +1,31 @@ - + GUI · halui · linuxcncrsh @@ -47,21 +49,21 @@ RS-274 interpreter · rs274ngc - interp_list + interp_list std::deque throttled at 1000 sequencing emctaskmain.cc - iocontrol.0.* + iocontrol.0.* 14 HAL pins former io process tool, coolant, estop — no NML channel left for I/O - RTAPI shmem · key 100 · emcmot segment + RTAPI shmem · key 100 · emcmot segment emcmot_command_t SINGLE SLOT @@ -71,7 +73,7 @@ seqlock head / tail + config, internal - emcmot_error_t + emcmot_error_t MPSC RING 32 × 1024 the only real queue here not NML, @@ -80,11 +82,11 @@ ordinary scheduling - SCHED_FIFO — rtapi_app, user space + SCHED_FIFO — rtapi_app, user space a scheduling boundary, no longer a kernel boundary — except under RTAI - motmod + loaded modules + motmod + loaded modules tpmod trajectory planner @@ -97,7 +99,7 @@ forward and inverse kinematics · 19 modules - TC_QUEUE + TC_QUEUE ring · 2000 segments ≈ 1 MB @@ -108,25 +110,19 @@ limit and home status - JOINT 1 … 16 — a motor, not an axis · 9 separate Cartesian axes + JOINT 1 … 16 — a motor, not an axis · 9 separate Cartesian axes cubic interpolator backlash + screw comp output: motor_pos_cmd on a HAL pin — the controller stops there - - WHAT THE DIAGRAM GOT RIGHT - cubic interpolator · forward and inverse kinematics · limit/home status - RS-274 interpreter · sequencing logic · NML triplet to the GUI - encoder and motor closing the loop · the principle of a real-time boundary - HAL + HAL 2 MiB shared block · key 0x48414C32 · components ▸ pins ▸ signals ▸ functions ▸ threads - absent from the original — yet it now carries every bit of hardware coupling - HAL COMPONENTS — wired by the integrator, moved out of the controller + HAL COMPONENTS — wired by the integrator, moved out of the controller pid stepgen pwmgen @@ -141,6 +137,6 @@ hal_parport gpio · rpi, beaglebone - motor · encoder · limit switches · spindle — 23 driver files + hostmot2 (42 modules, one driver) + motor · encoder · limit switches · spindle — 23 driver files + hostmot2 \ No newline at end of file