Step 09 of 13

Board configuration: board.ads

Flash size and PSRAM size are the two things the build has to be told about your board. They live in an Ada spec at the root of each project — there is no global config, and no sdkconfig.

The file

Every example owns one. Here is examples/esp32s3_gpio0_blink/board.ads:

package Board is
   Flash_Size : constant := 2 * 1024 * 1024;   --  total SPI flash
   PSRAM_Size : constant := 2 * 1024 * 1024;   --  external PSRAM @0x3D000000
end Board;

It is ordinary Ada, not a config-file dialect, so it participates in the build like any other spec. Edit it and rebuild — build.sh regenerates the board config and the 2nd-stage bootloader automatically. There is no separate step to remember.

Or let the tooling edit it

./x config gpio0_blink show
./x config gpio0_blink flash-size 4MB
./x config gpio0_blink psram-size 8MB

Sizes accept several spellings: 4MB, 512KB, 0x800000, 8388608. For a project outside the repo, the same verb exists on the launcher: esp32-ada config psram-size 8MB.

Why PSRAM size changes the bootloader

The 2nd-stage bootloader brings up the external octal PSRAM and maps it, so the size is baked into it. A project whose PSRAM_Size differs from the default gets its own bootloader built for it; projects that match the default reuse the prebuilt one. That is why changing PSRAM size costs a bootloader rebuild and changing flash size does not.

If you are curious what that bring-up involves: it is entirely from-source here, including a genuine 80 MHz din-sampling timing sweep rather than a vendor default. The write-up is in examples/common/bare/bootloader/PSRAM_BRINGUP_RESEARCH.md.

Machine-readable

For editor plugins and scripts, both discovery commands emit JSON:

./x list   --json
./x config --json
# {"flash_size":2097152,"flash_size_str":"2MB","psram_size":2097152,"psram_pages":32}