Deploying to gh-pages from @ Klipper3d/klipper@8db5d254e0 🚀

Code_Overview.html

@@ -1605,19 +1605,36 @@ some functionality in C code.</p>
 <p>Initial execution starts in <strong>klippy/klippy.py</strong>. This reads the
 command-line arguments, opens the printer config file, instantiates
 the main printer objects, and starts the serial connection. The main
-execution of G-code commands is in the process_commands() method in
+execution of G-code commands is in the _process_commands() method in
 <strong>klippy/gcode.py</strong>. This code translates the G-code commands into
 printer object calls, which frequently translate the actions to
 commands to be executed on the micro-controller (as declared via the
 DECL_COMMAND macro in the micro-controller code).</p>
-<p>There are four threads in the Klippy host code. The main thread
-handles incoming gcode commands. A second thread (which resides
-entirely in the <strong>klippy/chelper/serialqueue.c</strong> C code) handles
-low-level IO with the serial port. The third thread is used to process
-response messages from the micro-controller in the Python code (see
-<strong>klippy/serialhdl.py</strong>). The fourth thread writes debug messages to
-the log (see <strong>klippy/queuelogger.py</strong>) so that the other threads
-never block on log writes.</p>
+<p>There are several threads in the Klipper host code:</p>
+<ul>
+<li>There is a Python "main thread" that handles incoming G-Code
+  commands and is the starting point for most actions. This thread
+  runs the <a href="https://en.wikipedia.org/wiki/Reactor_pattern">reactor</a>
+  (<strong>klippy/reactor.py</strong>) and most high-level actions originate from
+  IO and timer event callbacks from that reactor.</li>
+<li>A thread for writing messages to the log so that the other threads
+  do not block on log writes. This thread resides entirely in the
+  <strong>klippy/queuelogger.py</strong> code and its operation is generally not
+  exposed to the main Python thread.</li>
+<li>A thread per micro-controller that performs the low-level reading
+  and writing of messages to that micro-controller. It resides in the
+  <strong>klippy/chelper/serialqueue.c</strong> C code and its operation is
+  generally not exposed to the Python code.</li>
+<li>A thread per micro-controller for processing messages received from
+  that micro-controller in the Python code. This thread is created in
+  <strong>klippy/serialhdl.py</strong>. Care must be taken in Python callbacks
+  invoked from this thread as this thread may directly interact with
+  the main Python thread.</li>
+<li>A thread per stepper motor that calculates the timing of stepper
+  motor step pulses and compresses those times. This thread resides in
+  the <strong>klippy/chelper/stepcompress.c</strong> C code and its operation is
+  generally not exposed to the Python code.</li>
+</ul>
 <h2 id="code-flow-of-a-move-command">Code flow of a move command<a class="headerlink" href="#code-flow-of-a-move-command" title="Permanent link">&para;</a></h2>
 <p>A typical printer movement starts when a "G1" command is sent to the
 Klippy host and it completes when the corresponding step pulses are
@@ -1639,7 +1656,7 @@ provides further information on the mechanics of moves.</p>
   the timing of printing actions. The main codepath for a move is:
   <code>ToolHead.move() -&gt; LookAheadQueue.add_move() -&gt;
   LookAheadQueue.flush() -&gt; Move.set_junction() -&gt;
-  ToolHead._process_moves()</code>.<ul>
+  ToolHead._process_moves() -&gt; trapq_append()</code>.<ul>
 <li>ToolHead.move() creates a Move() object with the parameters of the
 move (in cartesian space and in units of seconds and millimeters).</li>
 <li>The kinematics class is given the opportunity to audit each move
@@ -1664,37 +1681,44 @@ acceleration, its start/cruising/end velocity, and distance traveled
 during acceleration/cruising/deceleration. All the information is
 stored in the Move() class and is in cartesian space in units of
 millimeters and seconds.</li>
+<li>The moves are then placed on a "trapezoid motion queue" via
+trapq_append() (in klippy/chelper/trapq.c). The trapq stores all the
+information in the Move() class in a C struct accessible to the host
+C code.</li>
 </ul>
 </li>
 </ul>
 <ul>
+<li>Note that the extruder is handled in its own kinematic class:
+  <code>ToolHead._process_moves() -&gt; PrinterExtruder.process_move()</code>. Since
+  the Move() class specifies the exact movement time and since step
+  pulses are sent to the micro-controller with specific timing,
+  stepper movements produced by the extruder class will be in sync
+  with head movement even though the code is kept separate.</li>
+</ul>
+<ul>
 <li>Klipper uses an
   <a href="https://en.wikipedia.org/wiki/Root-finding_algorithm">iterative solver</a>
   to generate the step times for each stepper. For efficiency reasons,
-  the stepper pulse times are generated in C code. The moves are first
-  placed on a "trapezoid motion queue": <code>ToolHead._process_moves() -&gt;
-  trapq_append()</code> (in klippy/chelper/trapq.c). The step times are then
-  generated: <code>ToolHead._process_moves() -&gt;
-  ToolHead._advance_move_time() -&gt; ToolHead._advance_flush_time() -&gt;
-  MCU_Stepper.generate_steps() -&gt; itersolve_generate_steps() -&gt;
-  itersolve_gen_steps_range()</code> (in klippy/chelper/itersolve.c). The
-  goal of the iterative solver is to find step times given a function
-  that calculates a stepper position from a time. This is done by
-  repeatedly "guessing" various times until the stepper position
-  formula returns the desired position of the next step on the
-  stepper. The feedback produced from each guess is used to improve
-  future guesses so that the process rapidly converges to the desired
-  time. The kinematic stepper position formulas are located in the
-  klippy/chelper/ directory (eg, kin_cart.c, kin_corexy.c,
-  kin_delta.c, kin_extruder.c).</li>
-</ul>
-<ul>
-<li>Note that the extruder is handled in its own kinematic class:
-  <code>ToolHead._process_moves() -&gt; PrinterExtruder.move()</code>. Since
-  the Move() class specifies the exact movement time and since step
-  pulses are sent to the micro-controller with specific timing,
-  stepper movements produced by the extruder class will be in sync
-  with head movement even though the code is kept separate.</li>
+  the stepper pulse times are generated in C code in a thread per
+  stepper motor. The threads are notified of new activity by the
+  motion_queuing module (klippy/extras/motion_queuing.py):
+  <code>PrinterMotionQueuing._flush_handler() -&gt;
+  PrinterMotionQueuing._advance_move_time() -&gt;
+  steppersync_start_gen_steps() -&gt;
+  stepcompress_start_gen_steps()</code>. The step times are then generated
+  from that thread (klippy/chelper/stepcompress.c):
+  <code>sc_background_thread() -&gt; stepcompress_generate_steps() -&gt;
+  itersolve_generate_steps() -&gt; itersolve_gen_steps_range()</code> (in
+  klippy/chelper/itersolve.c). The goal of the iterative solver is to
+  find step times given a function that calculates a stepper position
+  from a time. This is done by repeatedly "guessing" various times
+  until the stepper position formula returns the desired position of
+  the next step on the stepper. The feedback produced from each guess
+  is used to improve future guesses so that the process rapidly
+  converges to the desired time. The kinematic stepper position
+  formulas are located in the klippy/chelper/ directory (eg,
+  kin_cart.c, kin_corexy.c, kin_delta.c, kin_extruder.c).</li>
 </ul>
 <ul>
 <li>After the iterative solver calculates the step times they are added