Skip to content

raspberrypi: scale flash timing with system clock; run stage 2 on RP2350 - #11883

Draft
dhalbert wants to merge 5 commits into
adafruit:mainfrom
dhalbert:rp2350-boot-stage2
Draft

dhalbert wants to merge 5 commits into
adafruit:mainfrom
dhalbert:rp2350-boot-stage2

Conversation

@dhalbert

@dhalbert dhalbert commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Exploring that issue brought up a whole host of interesting stuff, including the speedup below.

Code and testing by Claude, with review by @dhalbert.

Draft for now: requires adafruit/nvm.toml#26, which adds flash read timing values to data/nvm.toml. The submodule points at that PR's branch now. I'll update the submodule when that PR is merged.

Speedup: after this PR is merged, common RP2040 and RP2350 boards like the Pi Picos and the Adafruit boards will run Python code faster at the default CPU frequency: about 22% faster on RP2350 and about 28% faster on RP2040.

Issues

  • RP2350 never ran boot stage 2, so flash was read at the slow speed set up by the boot ROM.
  • RP2040 flash clock speed could usually be faster at the default 125 MHz CPU clock speed.
  • Flash timing did not change with microcontroller.cpu.frequency. On RP2040, stage 2 set a fixed divider of 4: a 31.25 MHz flash clock at 125 MHz.

Fix

  • RP2350 stage 2 is now run on startup (PICO_EMBED_XIP_SETUP). The pico-sdk reruns it after each flash erase or program, so it was made safe to rerun:
    • The read that puts the flash into continuous-read mode is now volatile. Without it, the compiler removed the read, and all later flash reads failed.
    • The flash pad setup clears only the Schmitt trigger bits, so SD2 and SD3 keep their pull-ups.
    • Stage 2 uses a slow divider (8) and sample delay (6) that work at any system clock.
  • After stage 2, after each clock change, and after each flash erase or program, CircuitPython sets the flash timing based on the current system clock. The pico-sdk flash erase and program functions rerun stage 2 to resume execute-in-place mode. That puts back stage 2's slow timing, so CircuitPython sets its timing again afterward.
    • RP2350: the divider and sample delay are computed from the flash datasheet timing in data/nvm.toml. It uses the safest values across the board's listed flash chips. It also considers the RP2350 QSPI pad delays (RP2350 datasheet, Table 1291). It does not identify the flash chip at run time. For current boards, that would not change any flash clock.
    • RP2040: the flash clock uses the smallest even divider that keeps the flash clock at or below 62.5 MHz and the flash's rating. The sample delay stays at 1. The RP2040 datasheet gives no QSPI pad delays to compute from.
    • A board can set a lower limit if needed by setting CIRCUITPY_FLASH_MAX_SCK_HZ in mpconfigboard.h.
  • Stage 2 uses the 0xeb quad read on both chips, because the datasheet timing is rated for 0xeb. Seven RP2040 boards used 0xe7 before. 0xe7 has 2 fewer dummy clocks, so it could be a few percent faster at the same flash clock, but datasheets often give no clock rating for it. The seven former 0xe7 boards still get faster overall, because their flash clock doubles.

Results

Python benchmark time at the default system clock:

Board Clock Before After Speedup
Pico 2 (RP2350) 150 MHz 2536 ms 2079 ms 22%
Feather RP2040 125 MHz 5637 ms 4417 ms 28%

Tested on Pico 2, Pico 2 W (with Wi-Fi), Fruit Jam (with PSRAM), Feather RP2350, Feather RP2040 and Pico, from 48 to 300 MHz, including flash writes at high clocks.

On RP2040, 150 MHz is now slower than 125 MHz, because 150 MHz needs divider 4 to stay at or below 62.5 MHz. MicroPython chooses the same divider. The frequency documentation now notes this.

Lowering the clock can crash some RP2350 boards. That's not caused by this PR: it was already happening on main.
See in #11882.

dhalbert and others added 5 commits November 15, 2026 17:20
RP2350 stage 2 is generated from boot_stage2/RP2350.c.jinja, but it
has never run, because RP2350 builds don't set PICO_EMBED_XIP_SETUP.
Fix it before turning it on:

- The read that puts the flash into continuous-read mode wasn't
  volatile, so the compiler dropped it. Every flash read after stage 2
  then failed.
- All the data pads were set from SD0's settings, which dropped the
  SD2/SD3 (WP#/HOLD#) pull-ups. Clear only each pad's Schmitt trigger
  bit instead.
- Use a slow clock divider (8) and a late sample delay (6), so stage
  2's own reads are safe at any system clock. It reruns after every
  flash erase or program.
- Always use the 0xeb quad read. Datasheets rate 0xeb, but often give
  no separate rating for 0xe7.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Without stage 2, RP2350 boards read flash with the boot ROM's
settings: clock divider 3 (50 MHz at 150 MHz) and no continuous-read
mode.

- Set PICO_EMBED_XIP_SETUP, so crt0 runs stage 2 at boot and copies it
  to boot RAM. The SDK then reruns it after each flash erase or
  program.
- Pad RP2350 stage 2 with the SDK's RP2350 pad script, which adds no
  checksum and defines __boot2_entry_point.
- Add a .boot2 section to link-rp2350.ld.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RP2350 flash timing never changed with the system clock. Overclocking
pushed the flash past its rating, and underclocking left it slow.
Each flash erase or program also reset the timing.

- gen_stage2.py writes the worst-case read timing of the board's flash
  devices, from data/nvm.toml, into flash_info.h.
- mcu_processor_update_flash_timing() picks the smallest clock divider
  within the flash's 0xeb rating whose sample point meets the flash's
  setup and hold times, assuming the RP2350's worst-case pad delays.
- common_hal_mcu_processor_set_frequency() uses the timing for the
  faster clock while the clock changes.
- supervisor_flash_post_write() restores the timing after each flash
  erase, program or command.
- A board can set a lower limit with CIRCUITPY_FLASH_MAX_SCK_HZ.

At 150 MHz, boards with Winbond or GigaDevice flash now read it at
75 MHz instead of 50, with continuous-read mode. A Python workload
runs 22% faster on a Pico 2. Boards with Puya flash, which has a 0 ns
output hold time, stay at 50 MHz.

Update data/nvm.toml for the new read timing fields. Requires
adafruit/nvm.toml#26.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
RP2040 stage 2 sets a fixed flash clock divider of 4, so flash reads ran
at 31.25 MHz at the default 125 MHz system clock. Now, as on RP2350,
CircuitPython sets the flash timing after stage 2, after each clock
change, and after each flash erase or program.

RP2040 uses the smallest even divider that keeps the flash clock at or
below the flash's 0xeb rating, 62.5 MHz, and CIRCUITPY_FLASH_MAX_SCK_HZ
if set. The sample delay stays at 1. The RP2040 datasheet gives no QSPI
pad delays, so the RP2350 timing calculation can't be used.

Stage 2 now uses the 0xeb quad read on both chips, because the
datasheet timing is rated for 0xeb.

Python code runs about 22% faster on a Feather RP2040 at 125 MHz.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

RP2350 Never Runs Boot Stage 2

1 participant