Skip to content

Commit 8e55103

Browse files
committed
pico: run the stepper task without FreeRTOS too
Without __FREERTOS the Pico driver drives manageSteppers() from a repeating alarm timer instead of a FreeRTOS task. The core then takes SysTick for its cycle counter, so no PIO state machine is spent on ccount: measured 12 steppers on an RP2350 (first failure at 28), against 11 with the FreeRTOS build (first failure at 27). Add the rpipico2_nofreertos CI variant and document both builds.
1 parent 4cc092a commit 8e55103

14 files changed

Lines changed: 178 additions & 70 deletions

File tree

‎.github/workflows/build_arduino_examples_matrix.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,7 @@ jobs:
8585
- samd51
8686
- rpipico
8787
- rpipico2
88+
- rpipico2_nofreertos
8889

8990
runs-on: ubuntu-latest
9091

‎CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
pre-V2.0.2:
2-
- pico: claim every free state machine of a PIO block and load the relocatable program once, so RP2350 connects 11 steppers instead of 8 (measured) and RP2040 7 instead of 4. A direction change inserts four old-direction pauses so the FIFO pipeline drains before DIR changes
2+
- pico: run without `__FREERTOS` too (a Pico repeating timer drives `manageSteppers()`); a Cortex build then uses SysTick and keeps every PIO state machine, so RP2350 connects 12 steppers instead of 11 and RP2040 8 instead of 7
3+
- pico: claim every free state machine of a PIO block and load the relocatable program once, so a `__FREERTOS` build connects 11 steppers on RP2350 instead of 8 (measured) and 7 on RP2040 instead of 4. A direction change inserts four old-direction pauses so the FIFO pipeline drains before DIR changes
34
- esp32: Fix the `gpio_iomux_in()` deprecation warning on ESP-IDF >= 5.5.0 (IDF 5 branch) with the equivalent inline GPIO LL writes. RISK: the IDF 5.5+ behavior has not been retested on hardware yet (build-only verification so far)
45
- ci: Test Arduino core 3.x via `espressif32 @ 8.0.0` for ESP32/S3/C6 instead of pioarduino 53.03.11; H2 stays on pioarduino 55.03.312 (Arduino 3.3.12) because platform-espressif32 8.0.0 ships no H2 board
56
- pico: fix loop timing in pio code and remove the dropped instruction. Verified on hardware.

‎README.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ For memory footprint information across supported architectures, see the
4141
| ESP32-C3 | 200 [1] | 2 RMT + 32 I2S * | 32 | [esp32.md](extras/doc/platforms/esp32.md) |
4242
| ESP32-C6 | 200 [1] | 2 MCPWM/PCNT + 2 RMT + 32 I2S * | 32 | [esp32.md](extras/doc/platforms/esp32.md) |
4343
| ESP32-P4 | 200 [1] | 4 RMT + 32 I2S * [2] | 32 | [esp32.md](extras/doc/platforms/esp32.md) |
44-
| Raspberry Pi Pico | 200 | 7 [3] | 32 | [pico.md](extras/doc/platforms/pico.md) |
45-
| Raspberry Pi Pico 2 | 200 | 11 | 32 | [pico.md](extras/doc/platforms/pico.md) |
44+
| Raspberry Pi Pico | 200 | 8 [3] | 32 | [pico.md](extras/doc/platforms/pico.md) |
45+
| Raspberry Pi Pico 2 | 200 | 12 [3] | 32 | [pico.md](extras/doc/platforms/pico.md) |
4646
| Atmel SAM Due | 50 | 6 | 32 | [sam.md](extras/doc/platforms/sam.md) |
4747
| Microchip SAMD51 | 100 | 3-5 | 32 | [samd51.md](extras/doc/platforms/samd51.md) |
4848
| Teensy 4.0/4.1 (exp.) | 200 | 16 | 32 | [teensy.md](extras/doc/platforms/teensy.md) |
@@ -54,10 +54,14 @@ Notes:
5454
2. The ESP32-P4 hardware provides 2 MCPWM groups and 4 PCNT units, but
5555
MCPWM/PCNT is not implemented for P4 yet. ESP32-S2 has PCNT but no MCPWM,
5656
ESP32-C3 has neither, so only RMT/I2S are available there.
57-
3. The Pico 2 count is measured: 11 connect and the twelfth is refused. The
58-
Pico count is expected from the same 27-word relocatable program (the
59-
cycle-counter block keeps three free state machines) but has not been
60-
re-measured. Step pins 16..31 reach all three Pico 2 PIO blocks.
57+
3. Measured on a Pico 2: the no-`__FREERTOS` build connects 12 steppers and
58+
the thirteenth is refused. A `-D__FREERTOS=1` build loses one state machine
59+
to the core's 2-word PIO cycle counter: 11 on the Pico 2 and an expected 7
60+
on the Pico.
61+
The Pico's 8 without `__FREERTOS` follows from the same 27-word program but
62+
has not been re-measured. RISC-V always takes the PIO counter, so a RISC-V
63+
Pico 2 connects 11 even without `__FREERTOS`. Step pins 16..31 reach all
64+
three Pico 2 PIO blocks.
6165

6266
\* The 32 I2S steppers require an external demultiplexer (e.g. 74HC154, or a
6367
74HC138 cascade / 74HC595 shift registers) on the I2S data line. Using I2S

‎extras/ci/build_matrix.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -201,6 +201,10 @@ environments:
201201
board: rpipico2
202202
build_flags: ["-D__FREERTOS=1"]
203203

204+
rpipico2_nofreertos:
205+
template: rp2040
206+
board: rpipico2
207+
204208
rpipico2-riscv:
205209
template: rp2040
206210
board: rpipico2
@@ -356,6 +360,7 @@ workflows:
356360
- samd51
357361
- rpipico
358362
- rpipico2
363+
- rpipico2_nofreertos
359364
# Example directories built by build-pio-dirs.sh that this workflow must
360365
# not compile. The Saleae characterization app is written for a few targets
361366
# only and its compilation is not guaranteed for every environment the

‎extras/ci/platformio.ini‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,12 @@ framework = arduino
153153
build_flags = -D__FREERTOS=1
154154
build_src_flags = -Werror -Wall -Wextra
155155

156+
[env:rpipico2_nofreertos]
157+
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
158+
board = rpipico2
159+
framework = arduino
160+
build_src_flags = -Werror -Wall -Wextra
161+
156162
[env:rpipico2-riscv]
157163
platform = https://github.com/maxgerhardt/platform-raspberrypi.git
158164
board = rpipico2

‎extras/doc/implemented/pico_cycle_counter_pio.md‎

Lines changed: 23 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,11 @@ The follow-up is implemented as
99

1010
Arduino-Pico 6.1.0 loads a 2-word `ccount` program on core 0 when
1111
`__riscv`, `__PROFILE`, or `__FREERTOS` is set
12-
(`RP2040::begin()` in `cores/rp2040/RP2040Support.h`). These builds
13-
set `-D__FREERTOS=1`. RISC-V has no SysTick path, so it loads the
14-
program whether or not that flag is set. The stepper program is 32
15-
words at origin 0, so that block cannot hold it.
12+
(`RP2040::begin()` in `cores/rp2040/RP2040Support.h`). The measurements
13+
below set `-D__FREERTOS=1`; the CI now also builds
14+
`rpipico2_nofreertos` without it. RISC-V has no SysTick path, so it loads
15+
the program whether or not that flag is set. The stepper program then was
16+
32 words at origin 0, so that block could not hold it.
1617

1718
Measured 2026-11-08 with `-D__FREERTOS=1`:
1819

@@ -29,3 +30,21 @@ The Pico 2 RISC-V image with `-D__FREERTOS=1` never started USB, so
2930
flag, USB comes up and PIO2 shows the same 2-word block. A length-32
3031
`pio_can_add_program` is not evidence of free space on that compiler:
3132
`1u << 32` becomes a mask of 0.
33+
34+
## Two variants (033)
35+
36+
The driver no longer requires the core's FreeRTOS SMP. With `__FREERTOS`
37+
a FreeRTOS task calls `manageSteppers()`; without it a Pico repeating
38+
timer calls the same function. That makes the Cortex choice in
39+
`begin()` a real build choice:
40+
41+
| `__FREERTOS` | Cortex counter | Pico 2, 27-word program | Pico |
42+
|---|---|---|---|
43+
| undefined | ARM SysTick, no PIO | **12**, measured | 8, expected |
44+
| defined | 2-word PIO `ccount`, one SM | **11**, measured | 7, expected |
45+
46+
Measured 2026-11-08 with `extras/tests/pico_stepper_count` on a Pico 2:
47+
`connected=12 first_failed=28` for the no-`__FREERTOS` build and
48+
`connected=11 first_failed=27` for `rpipico2_freertos`. The RP2040 has not
49+
been re-measured after the 27-word program. RISC-V has no SysTick path, so
50+
it takes the PIO ccount with or without `__FREERTOS` and remains at 11.

‎extras/doc/implemented/pico_pio_block_claim.md‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -5,10 +5,11 @@ Priority: **033**. Follows
55
the Pico SDK is wrong on RISC-V, so a stepper program can be written
66
over the cycle counter.
77

8-
Status: **implemented** (2026-11-08). Measured on an RP2350: 11 steppers
9-
connect. The Saleae catalogue and scale sweep pass, and the loop and
10-
direction timing analyses are recorded below. The platform docs and the
11-
changelog are updated.
8+
Status: **implemented** (2026-11-08). Measured on an RP2350: 12 steppers
9+
connect without `__FREERTOS`, and 11 with it, because the core then spends a
10+
PIO state machine on the cycle counter. The Saleae catalogue and scale sweep
11+
pass, and the loop and direction timing analyses are recorded below. The
12+
platform docs and the changelog are updated.
1213

1314
## Implementation
1415

@@ -33,15 +34,22 @@ full FIFO leaves the pin unchanged.
3334
of that length is one word; the driver still adds the missing words.
3435

3536
The sentence in Alternative that a 27-word program does not fit beside
36-
2 used words is the origin-0 case. This load is relocatable and 29 of 32
37-
words are used, so the counter's block keeps its three free machines.
37+
2 used words is the origin-0 case. This load is relocatable: in a
38+
`__FREERTOS` build 29 of 32 words are used and the counter's block keeps its
39+
three free machines; without `__FREERTOS` the block keeps all four.
3840

3941
## Verification
4042

41-
`extras/tests/pico_stepper_count` connects GPIO 16 through 31 and reports
42-
`connected=11 first_failed=27`: two blocks serve four steppers each and the
43-
cycle counter's block serves three. The pins must be in 16..31, the range
44-
inside all three PIO windows.
43+
`extras/tests/pico_stepper_count` connects GPIO 16 through 31. The
44+
no-`__FREERTOS` build reports `connected=12 first_failed=28`: all three blocks
45+
serve four steppers. The `rpipico2_freertos` build reports `connected=11
46+
first_failed=27`: two blocks serve four each and the cycle-counter block
47+
serves three. The pins must be in 16..31, the range inside all three PIO
48+
windows.
49+
50+
The driver no longer requires the core's FreeRTOS SMP. With `__FREERTOS` a
51+
FreeRTOS task calls `manageSteppers()`; without it a Pico repeating timer
52+
(alarm pool) calls the same function at the same rate.
4553

4654
The `rpipico2` Saleae catalogue passed every implemented scenario, including
4755
the direction-change tests SR_10–SR_12, and `--mode scale --pin-mode nodir`

‎extras/doc/platforms/pico.md‎

Lines changed: 59 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -7,13 +7,19 @@
77
* allows up to 200000 generated steps per second
88
* RP2040 has two PIO blocks and RP2350 has three. Each block has four state
99
machines, and one loaded stepper program serves that block's free machines.
10-
The builds offer 8 queues on the Pico and 12 on the Pico 2.
10+
The builds offer up to 8 queues on the Pico and 12 on the Pico 2; a
11+
`__FREERTOS` build gives 7 and 11 because the core's PIO cycle counter
12+
holds one machine.
1113
* RISC-V is the Pico 2 only. The RP2040 has no RISC-V core.
12-
* Measured on 2026-11-08 with `-D__FREERTOS=1` on a Pico 2: **11 steppers
13-
connect and the twelfth is refused**. One PIO block holds the core's 2-word
14-
cycle counter and still serves three steppers, so the count is 4 + 4 + 3.
15-
The Pico (RP2040) has not been re-measured; the same mechanism should give
16-
7 of its 8 queues.
14+
* Measured on 2026-11-08 on a Pico 2: **12 steppers connect and the
15+
thirteenth is refused** without `__FREERTOS`, because the core takes its
16+
SysTick cycle counter and spends no PIO state machine on it. With
17+
`-D__FREERTOS=1` the core's 2-word PIO `ccount` program holds one machine;
18+
the relocatable stepper program fits beside it, so that block still serves
19+
three and the count is 11. The Pico (RP2040) no-`__FREERTOS` count is
20+
expected to be 8; with `__FREERTOS` it is expected to be 7 (4 was measured
21+
before the 27-word program). RISC-V has no SysTick path, so a RISC-V Pico 2
22+
connects 11 either way.
1723
* On the Pico 2 the step pins must be in 16..31 to reach all three blocks:
1824
PIO0/PIO1 cover 0..31 and PIO2's window starts at 16. Below 16 the first two
1925
blocks take every pin and PIO2 is never reached. The count probe is
@@ -29,10 +35,15 @@ three pios. Each pio contains four state machines and every state machine can
2935
drive one stepper. `claim_pio_resources()` claims every free state machine of a
3036
block and loads the 27-word program once, so all claimed machines share it.
3137

38+
The Pico driver runs with or without the core's FreeRTOS SMP. With
39+
`__FREERTOS` defined, a FreeRTOS task calls `manageSteppers()`; without it, a
40+
Pico repeating timer (alarm pool) calls the same function at the same rate.
41+
The choice also decides the cycle counter, see below.
42+
3243
SoftwareSerial is implemented via pio, too. The program is relocatable, so a
3344
block that already holds another program is still usable when 27 free words
34-
remain. The cycle counter holds 2 words, so its block still serves three
35-
steppers.
45+
remain. In a `__FREERTOS` build the cycle counter holds 2 words, so its block
46+
still serves three steppers; without `__FREERTOS` no block is reserved.
3647

3748
## Cycle-counter state machine
3849

@@ -63,27 +74,28 @@ No flag in `begin()` skips the program when `__riscv` is set.
6374

6475
`PIOProgram::prepare()` (`cores/rp2040/PIOProgram.cpp`) adds those 2 words
6576
with `pio_add_program` at a free origin. The stepper program is 27 words and
66-
relocatable, so it fits beside them (29 of 32 words) and the block keeps its
67-
three free state machines for steppers.
68-
69-
Every Pico environment in `extras/ci/platformio.ini` passes
70-
`build_flags = -D__FREERTOS=1`. On 6.1.0 that macro is the preprocessor
71-
symbol in the `#if` above (the core's own FreeRTOS menu uses `-D__FREERTOS`).
72-
Cortex with the macro defined takes the PIO path. RISC-V takes it because
73-
`__riscv` is set. RISC-V exists on the RP2350 only. The RP2040 image is
74-
Cortex. With the counter loaded it connects 4 steppers, measured on
75-
`/dev/cu.usbmodem4101`.
77+
relocatable, so in the `__FREERTOS` build it fits beside them (29 of 32 words)
78+
and the block keeps its three free state machines for steppers. Without
79+
`__FREERTOS` on Cortex the `#if` takes the SysTick branch, no ccount program
80+
is loaded, and all four machines on every block stay free.
81+
82+
The CI has both variants. `rpipico` and `rpipico2` define
83+
`-D__FREERTOS=1`; `rpipico2_nofreertos` does not. On 6.1.0 the macro in the
84+
`#if` above is exactly `__FREERTOS` (the core's FreeRTOS menu also sets
85+
`-D__FREERTOS`). Cortex with the macro defined takes the PIO path; without it
86+
it takes SysTick. RISC-V takes the PIO path because `__riscv` is set, with or
87+
without `__FREERTOS`. RISC-V exists on the RP2350 only; the RP2040 is Cortex.
7688

7789
The previous wording on this page said the Arduino core allocates one PIO
7890
when the build is not RISC-V, and that a RISC-V build can use every stepper.
7991
That wording does not match `begin()` in 6.1.0.
8092

81-
**Verified on the `rpipico2` compile line (2026-11-08).**
82-
`RP2040Support.cpp` is compiled with `-D__FREERTOS=1`. `build_flags` does
83-
reach the core. The same command has `-DF_CPU=150000000L`. `boards.txt`
84-
in the core package says 125 MHz for `rpipico2`; the PlatformIO board
85-
the saleae env resolves overrides that to 150 MHz. One PIO cycle on this
86-
firmware is 1/150 MHz.
93+
**Verified on the compile lines (2026-11-08).** `rpipico2` compiles
94+
`RP2040Support.cpp` with `-D__FREERTOS=1`; `rpipico2_nofreertos` does not.
95+
`build_flags` reaches the core either way. Both commands have
96+
`-DF_CPU=150000000L`. `boards.txt` in the core package says 125 MHz for
97+
`rpipico2`; the PlatformIO board the saleae env resolves overrides that to
98+
150 MHz. One PIO cycle on that firmware is 1/150 MHz.
8799

88100
**Measured on a Pico 2, Cortex, 2026-11-08, before the 27-word program.**
89101
Env `rpipico2` with `-D__FREERTOS=1`. A throwaway sketch called
@@ -95,12 +107,13 @@ counter's block was lost. The Pico (RP2040) measured 4 of 8 for the same
95107
reason.
96108

97109
**Measured on a Pico 2, Cortex, 2026-11-08, with the 27-word relocatable
98-
program.** `extras/tests/pico_stepper_count` connects GPIO 16 through 31 and
99-
reports **11 connected, first failure at 27**. The counter's block contributes
100-
three state machines and the other two blocks four each. GPIO 16..31 is the
101-
range inside all three PIO windows: PIO0/PIO1 cover 0..31 and PIO2 starts at
102-
16. Below 16 the first two blocks take every pin, PIO2 is never reached, and
103-
the count is 8.
110+
program.** `extras/tests/pico_stepper_count` connects GPIO 16 through 31.
111+
Without `__FREERTOS` it reports **12 connected, first failure at 28**: all
112+
three blocks serve four state machines. With `-D__FREERTOS=1` it reports
113+
**11 connected, first failure at 27**: the ccount block contributes three
114+
machines and the other two blocks four each. GPIO 16..31 is the range inside
115+
all three PIO windows: PIO0/PIO1 cover 0..31 and PIO2 starts at 16. Below 16
116+
the first two blocks take every pin, PIO2 is never reached, and the count is 8.
104117

105118
The Saleae firmware cannot make this count: `SALEAE_STEPPER_BOUND` in
106119
`extras/tests/saleae_based/common/saleae_app.cpp` is 8 and the analyzer has 8
@@ -112,7 +125,10 @@ USB comes up on that image. The image built with `-D__FREERTOS=1` still
112125
does not. Before any stepper program is added, PIO2 has one state
113126
machine claimed. A 30-word program fits there and a 31-word program
114127
does not, so that block holds 2 instruction words. PIO0 and PIO1 are
115-
empty. This measurement predates the 27-word relocatable program.
128+
empty. This measurement predates the 27-word relocatable program. RISC-V
129+
has no SysTick branch, so it takes this PIO path with or without
130+
`__FREERTOS`; with the 27-word program the block keeps three machines and
131+
the count should be 11 (not re-measured on RISC-V).
116132

117133
`pio_can_add_program` builds its occupancy mask with `1u << length`.
118134
A shift of 32 is undefined. This RISC-V compiler emits `bset` of bit
@@ -134,17 +150,18 @@ No Pico environment in this tree uses a `framework` other than `arduino`.
134150
`src/fas_arch/common.h` also has a branch on `PICO_SDK_RP2350`. That macro
135151
is not defined by pico-sdk or by framework-arduinopico 6.1.0 (it occurs only
136152
in this repository). The header it selects, `src/fas_arch/pico_sdk_rp_pico.h`,
137-
calls FreeRTOS `portENTER_CRITICAL` / `portEXIT_CRITICAL`, and
138-
`src/pd_pico/pd_config.h` includes `FreeRTOS.h`. That branch is not a
139-
bare-metal port, and it is not built in CI.
153+
calls FreeRTOS `portENTER_CRITICAL` / `portEXIT_CRITICAL`, and has no
154+
bare-metal task source. That branch still requires FreeRTOS, and it is not
155+
built in CI. (The Arduino branch now builds either way.)
140156

141157
The cycle counter is started by the Arduino class `RP2040::begin()`. A
142158
pico-sdk image does not call it. In the pico-sdk shipped inside
143159
framework-arduinopico 6.1.0, the only `pio_add_program` is the implementation
144160
in `hardware_pio/pio.c`. A non-Arduino image therefore keeps every PIO block,
145161
on Cortex and on RISC-V. FastAccelStepper still has to be ported to build
146-
that way: the hook that exists today requires FreeRTOS, and no such platform
147-
is packaged here.
162+
that way: the `PICO_SDK_RP2350` hook uses FreeRTOS critical sections and
163+
requires FreeRTOS, and no such platform is packaged here. (The Arduino hook
164+
now builds with or without `__FREERTOS`; see the section above.)
148165

149166
`platform = raspberrypi` from the PlatformIO registry is a separate failure
150167
(issue #339). Version 1.20.0 ships only the Arduino **mbed** core
@@ -163,7 +180,9 @@ not run at the same time.
163180
Step edges are produced by the PIO at `clk_sys`. Comparing step periods
164181
between `rpipico2` and `rpipico2-riscv` on a logic analyzer measures the PIO
165182
clock, which is the same clock. It does not measure which CPU is faster.
166-
The comparison that tests this page is how many steppers connect.
183+
The comparison that tests this page is how many steppers connect: 12 for the
184+
no-`__FREERTOS` Cortex build, 11 for the FreeRTOS build and 11 for RISC-V
185+
(which always takes the PIO cycle counter).
167186

168187
Which core finishes a given integer workload first depends on that code.
169188
A secondary CoreMark table (kreier.github.io/benchmark/CoreMark, update
@@ -183,8 +202,9 @@ Integration with applications using pio: `claim_pio_resources()` claims every
183202
free state machine of a block and keeps the ones it does not use, so another
184203
PIO caller cannot be told the block is empty. With every block free the first
185204
block serves four steppers and the second the next four; on the Pico 2 the
186-
third serves the next four. The cycle-counter block keeps three free machines
187-
and serves three. All claimed machines on a block share one 27-word
205+
third serves the next four, for 12 in the no-`__FREERTOS` build. In a
206+
`__FREERTOS` build the cycle-counter block keeps three free machines and
207+
serves three, for 11. All claimed machines on a block share one 27-word
188208
relocatable program, so 5 of the 32 words remain free on that block.
189209

190210
## Loop budget, measured

0 commit comments

Comments
 (0)