Skip to content

docs: document EXRAIL compiler and resource usage #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
BanjoR wants to merge 2 commits into from
Closed

docs: document EXRAIL compiler and resource usage #1

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0db0a49
docs: document EXRAIL resource usage
BanjoR Aug 16, 2026
4f65dfa
docs: link EXRAIL resource usage guide
BanjoR Aug 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/exrail/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,7 @@ Click 'Next' to explore the possibilities of |EX-R|.
getting-started
examples
tips
resource-usage
cookbooks/index
exrail-command-reference
about
21 changes: 21 additions & 0 deletions docs/exrail/resource-usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
EXRAIL compiler and resource usage
=================================

EXRAIL expands ``myAutomation.h`` into a byte-coded route table and lookup tables during firmware compilation. The route table is stored in flash. At startup, routes and event handlers are indexed in RAM, and each active sequence has an ``RMFT2`` task object.

Task lifetime and recycling
---------------------------

Running sequences are linked in a task ring. When a task reaches ``DONE`` or is killed, its destructor releases the task object so a later sequence can reuse that heap allocation. Concurrent sequences increase peak RAM use; completed tasks can be recycled. Each task stores program-counter, delay, locomotive, event, pause, and call-stack state. The current upstream implementation sets the call-stack depth to 4.

Runtime resource use
--------------------

Startup allocates RAM-backed lookup arrays for routes and event handlers including ``ONTHROW``, ``ONCLOSE``, ``ONACTIVATE``, ``ONCHANGE``, ``ONTIME``, and overload/block handlers when used. Signals and route-state features add further tables. The exact cost depends on the target board, definitions, optional features, and simultaneous tasks. There is no portable maximum-lines limit: available flash and free heap are the practical limits.

Compile-time checks
-------------------

The assertion pass over ``myAutomation.h`` checks sequence references and duplicate route/automation/sequence IDs; flag IDs 0--255; speed values 0--127; ``SPEED_REL`` 1--500 percent; valid signal addresses; and reserved motor-shield/critical pins used by ``SET``, ``RESET``, ``BLINK``, and signal macros. These checks do not measure runtime capacity: compile success and sufficient free RAM are separate checks.

When a script grows, inspect compiler flash/RAM output and test the largest expected number of simultaneous automations and event handlers. Let finished sequences reach ``DONE``, avoid unnecessary concurrent tasks, remove unused event handlers/features, and keep ``CALL`` nesting within 4. These details are based on upstream ``EXRAIL2.h``, ``EXRAIL2.cpp``, and ``EXRAILAsserts.h`` and may change with firmware revisions.