Code Structure

Marlin Code Overview

Marlin is a very complex Arduino sketch. It is as complicated for developers to navigate as it is for new users who might want to make a small change. This document is meant to be a concise guide to help you find your way around the Marlin codebase and understand how the program works, at least in principle.

This document provides a high level overview of structural details and program flow. By the end you should have an idea where (and how) to find your way around. Other details, such as Marlin coding style, are described in more detail on the Coding Standards page for those who may want to contribute.

Base Folder Structure

The Marlin/src Folder

The Marlin/src folder contains Marlin’s main source file, MarlinCore.cpp and the MarlinCore.h header file. MarlinCore.cpp contains the setup() function that initializes the firmware and the loop() function that continuously runs the program loop.

The rest of the source code is divided up into 10 subfolders, and many of these subfolders are divided up further. Here’s a basic overview of each one:

Configuration and Include Tree

Marlin is highly configurable. You’ll find many places throughout the source code where configuration options are applied to turn code on and off, change behavior, and provide values.

How does a Marlin source file get all the configuration values it needs?

To begin with, when you build a C++ program the first stage is to build all the .c and .cpp files individually. Each of these files must be complete within itself, and each is responsible to include the headers it requires. This can get tedious in a large project, so a lot of compilers allow you make a “precompiled header” (.pch file) that includes all your common headers. Marlin doesn’t use a PCH file, but rather, regular headers that work in a similar way.

The include order of the headers in the inc, core, HAL, and pins folders is important because each one builds on its predecessors. To ensure the correct include order is always followed, any code that needs the Configuration and Conditionals files (up to Conditionals_adv.h) must include inc/MarlinConfigPre.h, while any code that needs the fully realized hardware configuration must include inc/MarlinConfig.h.

Let’s take a closer look at the headers that each of these files includes.

MarlinConfigPre.h

MarlinConfig.h

A Typical Source File

Putting it all together, a typical source file will at least include MarlinConfigPre.h so that it can check some configuration values up front. Additional headers will be included only if they’re needed. It’s not unusual for some source files to include headers for several features.

/**
 * (c) 2021 Marlin Firmware
 * A typical Marlin source.cpp file.
 */
#include "inc/MarlinConfigPre.h"

#if ENABLED(MY_COOL_FEATURE)

#if ENABLED(EXTENSIBLE_UI)
  #include "lcd/extui/ui_api.h"
#endif

#endif // MY_COOL_FEATURE

A Typical Header File

Marlin header files aren’t wrapped with #if…#endif in the same way as source files. Instead, if a header isn’t needed, then it’s simply never included. Marlin also eschews C-style #ifdef wrappers and only uses #pragma once on its own headers.

/**
 * (c) 2021 Marlin Firmware
 * A typical Marlin header.h file.
 */
#pragma once

extern int my_feature_var;
void do_feature_stuff();

Some headers will provide empty functions when the feature is disabled. This makes it easier to turn things off at a single point and can make code neater in other places, but this is used sparingly because it obfuscates what is actually happening.

/**
 * (c) 2021 Marlin Firmware
 * A typical Marlin header.h file.
 */
#pragma once

#include "inc/MarlinConfigPre.h"

#if ENABLED(MY_COOL_FEATURE)
  extern int my_feature_var;
  void do_feature_stuff();
#else
  inline void do_feature_stuff() {}
#endif

Marlin Build Process

A Marlin build can take a while, but it works like any other sketch. All .cpp files in Marlin and its dependencies are compiled, plus anything that they include. A Marlin build with PlatformIO uses the files in the ini folder along with the scripts in buildroot/share/PlatformIO to filter out unused source files based on your configuration, making it much faster.

Program and Command Flow

Marlin program execution begins in MarlinCore.cpp with initialization in the setup() function and the main loop in the loop() function, just like any Arduino sketch. The loop() function is pretty small and is mainly responsible to call idle() and then run the next G-code command at the front of the queue when it arrives.

Most of the tasks in Marlin are executed out of the idle function, which calls manage_inactivity and thermalManager.manage_heater. You’ll see a lot of calls to idle because all wait loops use it to keep the machine running. If Marlin ever goes too long without calling idle the watchdog will get triggered and reset the machine for safety.

This program architecture requires some care, since we don’t want some function that gets called by idle itself calling idle until the stack blows up. There are only a small number of re-entry guards in Marlin, so in practice it works well.

It is pretty straightforward to follow the function calls from idle to see how Marlin keeps all the devices and features running in the program context. Some features carry on activities all the time, but most of what Marlin does is initiated by G-code commands.

Interrupt Service Routines

Marlin defines a few Interrupt Service Routines (ISRs):

• The Stepper ISR runs repeatedly, advancing the planner queue and moving the stepper motors at high speed by sending pulses to their STEP and DIR pins. The frequency of this interrupt is tied to the movement speed.
• The Temperature ISR reads the temperature sensors at a frequency close to 1kHz and signals to the main program when the readings are ready. It also manages Software / Slow PWM configured for heaters and fans that don’t need a very high base frequency.
• The Endstop ISR can be activated if the endstop pins are interrupt-capable. It only fires when an endstop pin’s input state changes.
• The Tone Timer is defined by Arduino for some platforms and defined by Marlin for others. It handles pulsing the Piezo buzzer to create tones, and it runs at double the frequency of the current tone.
• The Servo Timer provides PWM signals for servos.

Platforms will also define interrupts for Serial UART and maybe other devices, so Marlin has to be careful choosing the interrupts and timers that it uses.

Handling a G-code

Next, let’s look at how a G-code is processed and follow the program flow.

0. Emergency Parser

What can you do when the command queue is blocked but the machine needs user input in some form? The emergency parser is a simple state machine that operates at a low level in the serial code watching for certain commands. When it sees M108, M112, etc., it takes action right away to handle the code.

1. Read from Serial and SD

The manage_inactivity function calls queue.get_available_commands() which checks the immediate buffer, polls the serial ports, and reads the active SD print file, copying lines into the command queue with the aim to keep it filled.

2. Pop a G-code

The main loop() calls queue.advance() which gets the command at the front of the queue and runs it right away. Marlin won’t come back to loop() until the command has been completed.

Marlin can command itself to do things within the regular command flow and these commands get run by queue.advance() ahead of the print job queue so they must be used with care.

3. Prescan the G-code

Once queue.advance() has chosen the next command, it calls the parser to pre-process the G-code line. The pre-processor validates the line number and checksum and if all is well it does a quick pre-scan of the parameters before calling the specific G-code handler.

4. Handle the G-code

All G-code handlers are encapsulated in the GcodeSuite class (e.g., GcodeSuite::G28()) although a few are implemented elsewhere. A G-code handler is a simple void method with no return value. Instead of getting parameters from the function call, it queries the GCodeParser class to check for parameters and read their values.

For example, a handler might use parser.seenval('X') to check if the 'X' parameter exists and has a value, then call parser.value_float() to get the value as a float. See gcode/parser.h for all the available methods.

There are hundreds of G-code handlers, so they are split up into individual files by category, with each G-code file only including the headers it needs. All handlers include gcode.h (which includes parser.h) so they can process parameters. Other component headers are included as-needed by each G-code handler file.

5. Command Blocking

Since a G-code command blocks the command queue from advancing until it returns, each command must take care to keep the machine alive during its execution.

A G1 command is considered “completed” as soon as the move is enqueued, so it can potentially return right away. In practice, and especially with bed leveling enabled, every linear move has the potential to fill up the planner queue and block while waiting for planner space to open up.

When a command needs to wait for something like free space in the planner or user feedback, it calls the idle function to keep the machine alive and running. The idle function will even keep reading incoming commands into the queue, but since idle doesn’t dispatch G-codes or advance the queue, the queue can’t get any emptier until the handler finishes and returns.

Movement

Marlin is specialized for movement with stepper motors. These devices allow for precise positioning in a very repeatable and reliable way. You can run print jobs that span several days without losing a single step. The downside to these devices is that the MCU needs to generate precisely-timed signals for every tiny step the motors take. And they require complicated drivers that tend to generate a lot of heat.

In its most basic form, a motion command goes through this flow:

(1) G-code -> (2) Segmented Move -> (3) Planner Queue <-> (4) Stepper ISR

1. A movement command specifies a destination position and a nominal feedrate that it would like to achieve. The actual speed will depend on how fast the machine can accelerate and how far the machine will move before it has to change direction.
2. Marlin only does linear moves at the level of the Planner, so commands like G2/G3/G5 are converted into several small linear segments. The same goes for Delta and SCARA kinematics and leveled moves. So at this stage Marlin may generate several smaller segments and add them to the Planner Queue.
3. The machine can’t instantly go from a full-stop to a fast move rate, nor can it just instantly stop, so all moves need to be accelerated or decelerated to the requested feedrate. As each move goes into the queue we do a “lookahead” over the entire queue to determine each block’s achievable start and end speeds. Acceleration can be linear or slightly curved. One problem you might encounter is “juddering” on curves. This is caused by small segments completing so quickly that the Planner queue gets emptied out. As a result the machine is forced to decelerate to the minimal “jerk” speed. Marlin can throttle the UI and/or slow down moves to try and prevent this, but it’s not always enough. The simple solution is to configure your slicer to produce longer segments on curves, or to use G2/G3 arcs.
4. The Stepper ISR is a high priority interrupt routine that obediently fetches and processes the Planner queue until there are no more segments in the queue. Since it produces the actual STEP signals to the stepper motors it may need to run as often as 40,000 times or more per second. In practice we want to run it as often as possible because this improves timing and reduces “aliasing” (i.e., rounding). The Stepper ISR uses the clever and fast Bresenham line algorithm to coordinate the timing of STEP signals. This algorithm benefits from finer resolution, so we get more accurate timing by running the Stepper ISR “as often as possible.”

Fixed-Time Motion

Marlin 2.1.3 introduces Fixed-Time Motion as an alternative method to get more precise step and direction timing along with its own Linear Advance and Input Shaping handlers. Fixed-Time Motion also uses the Stepper ISR to do regular stepping, but it also has a periodic idle task to handle state changes.

Since Fixed-Time motion requires significantly more resources than the standard motion system to pre-calculate its precise pulse timings, it requires a faster processor and more RAM.

As this system matures it will likely become default for fast 32-bit boards, but the original motion system will be preserved for slower processors and for simpler motion systems that don’t need the most precise timing.

Interesting Numbers

• A 1.8° stepper motor has 200 full steps-per-revolution. A 0.9° stepper motor has 400 steps-per-revolution.
• With the most common 16x micro-stepping that’s 3200 (1.8°) or 6400 (0.9°) micro-steps-per-revolution.
• X and Y are usually driven with a GT2 (2mm pitch) belt and 20 tooth gear, for 40mm per revolution.
• This gives you 80 steps-per-millimeter on the X and Y axis. (The Z axis is commonly 400 steps-per-mm.)
• At 80 steps/mm a modest move speed of 60mm/s on a single axis requires a peak step rate of 4.8kHz.
• A fast move speed of 200mm/s requires a peak step rate of 16kHz.
• A very fast move speed of 500mm/s requires a peak step rate of 40kHz.
• The slowest MCUs are 16MHz AVR. So a 200mm/s move speed needs one step for every 1000 CPU cycles.