Bug of the day: missing entry point
This is a tale of a strange bug I ran into when doing my first ever SAM E70 project. A new MCU. A new type of product. A custom PCB. What could possibly go wrong? 🙂
Spoiler: Not strange. Not a bug.
I started by using Atmel's START tool (pun intended). It is a web-based project generator.
I selected my MCU, picked the clock configuration, added some extra components (like the USB stack) and got a
in the end. This tool hits the sweet spot as it does not require you to download many gigabytes of SDKs and IDEs,
yet gives you a nice minimal project to start with (the headers + startup code + clock configuration + basic Makefile).
START is still available but is deprecated (as of 2023).
The project built nicely with
gcc. I connected a J-Link to my custom board. I opened the
elf in Ozone,
flashed the MCU, let it run and... immediately ended up in the hard fault handler. Not great, not terrible.
The firmware crashed instantly but on the other hand I could connect with a debugger and flash the chip
without any errors.
Ozone by default after flashing halts on
main() so the startup code is executed but not any of the "application" code.
This initially led me to suspect the startup or the clock setup code. In the hard fault handler the CPU behaved normally.
I was able to single step the instructions so the hardware could not be that bad. Unfortunately, all the diagnostic
variables in the hard fault handler had only junk addresses so I could not see an obvious cause for the crash.
I started checking everything I could think of:
- Supply voltages - nominal
- Crystal signal and frequency - nominal
- Solder joints - good
gccbuild flags - all good for Cortex-M7
- Part number on the package vs. the one in START - exact match
- Ozone MCU selection - exact match
- Oscillator config in START - matched the PCB
- Reset handler code - seemed to make sense
- Vector table contents - good (initial stack pointer at top of RAM and good reset handler address)
- Binary inspection in hex editor - nominal
After exhausting all options I added code that changes state of GPIOs at various stages to "debug with a scope" or "debug with an LED" in order to find the last working step. To my surprise the code worked after flashing and a power cycle. The code must have been correct all the time. It must be the debugger that does something wrong.
To confirm it I loaded a raw binary file into Ozone. It does not have any metadata so I had to input the load address manually. I also manually typed the initial stack pointer and program counter into the registers using the debugger. Then, I let the CPU run. And it worked!
This discovery made me certain that is must be either something with Ozone or with the
elf file. On one hand the
elf was perfectly loaded into flash so the linker script could
not be that broken (it was provided by Atmel START anyway).
On the other hand Ozone could not reach
main(). The linker script looked sane at first
glance. It took me quite a while to spot the problem. A missing
It seems that Atmel START must have been using a wrong linker file template.
After adding the missing entry point to the linker script Ozone was able to start the CPU properly and reach main. Yay! 🙂
Why did the broken
elf (partially) worked?
elf does not need an entry point to start with. An example can be a shared library
(though they have standardized "constructors" which are a kind of entry points for the loader
and operating system).
The layout of the sections was specified correctly in the linker script so all the code
ended up in flash at the correct address. The code used RAM at the correct address.
The vector table had references to
Reset_Handler so it was not optimized out during linking.
.bin file was fully usable when it ended up in the flash of the MCU.
That day I learned that the only problem was Ozone not being able to recognize where the firmware should start from.