Step 13 of 13

Troubleshooting, and where to go next

The failure modes worth recognising on sight, a one-screen cheat sheet, and the parts of the project to read once the board is blinking.

Troubleshooting

Symptom	Cause and fix
`gprbuild` or the cross-GNAT not found	A toolchain is missing, or `PATH` lost Alire. Recheck step 2 and `alr toolchain`.
`XTENSA_GNU_CONFIG unset`, or a missing `bb-runtimes`	Submodules were never fetched: `git submodule update --init --recursive`.
`Permission denied` on `/dev/ttyACM0`	Add yourself to `dialout`, then log out and back in.
No `/dev/ttyACM0` appears at all	Wrong socket (use the native USB port, not UART), or a charge-only cable. Check `dmesg \| tail`.
The flasher never connects	Force download mode: hold BOOT, tap RESET, release BOOT. Also check no OpenOCD still holds the port — `./x kill-openocd`.
The board resets or panics in a loop	The bare boot runs with memory protection (W^X) off, which the Ada task-body trampolines require. Every example ships `CONFIG_ESP_SYSTEM_MEMPROT_FEATURE=n`; rebuild clean.
The first build takes forever	Expected. It generates the Ada runtime and builds the host tools. Later builds are incremental.
Console shows nothing, or garbage	115200 8N1 on the native USB port; confirm which `/dev/ttyACM*` is the board.
A build error you cannot parse	Bare-metal GNAT complains about constructs the runtime omits; the book's Debugging chapter has a section decoding those messages.

One-screen cheat sheet

# --- one-time setup (no ESP-IDF, no esptool, no Python) ---
wget .../alr-2.1.0-bin-x86_64-linux.zip && unzip -d ~/alire alr-*.zip
export PATH="$HOME/alire/bin:$PATH"
alr toolchain --select gnat_native gprbuild
alr toolchain --select gnat_xtensa_esp32_elf
git clone --recurse-submodules https://github.com/rowsail/ada-bare-metal-esp32s3.git
cd ada-bare-metal-esp32s3
sudo usermod -aG dialout $USER          # then log out/in

# --- build, flash, watch an example ---
./x list
./x run gpio0_blink -p /dev/ttyACM0

# --- or start your own app in any folder ---
. ~/ada-bare-metal-esp32s3/export.sh    # ESP32S3_ADA_SDK + esp32-ada on PATH
mkdir ~/myblink && cd ~/myblink && esp32-ada init
esp32-ada run -p /dev/ttyACM0           # build + flash + monitor

Where to go next

Read an example. They are written to be read, not just run. esp32s3_gpio0_blink and esp32s3_gdma_copy are the house-style models; examples/STYLE.md records the bar.
Run the self-test for a peripheral you care about before writing code against it. Most need no wiring.
The book (book/main.pdf, LaTeX sources alongside it) is the long-form design write-up: the kernel and context switch, the interrupt model, the HAL's design rules, the filesystems, the ACATS conformance work, and the full-profile limitations.
TOOLING.md for editor integration in depth, including the JSON discovery interface if you want to write a plugin.

You now have a bare-metal Ada program running on both cores of an ESP32-S3, built and flashed by a toolchain you could describe in one sentence. That was the point.