STATUS: WORK IN PROGRESS. NOTHING TO SEE HERE.

A minimalist guide and skeleton for building, running, and debugging firmware for ARM-based microcontrollers.

You will use only the following software tools:

• Make, for orchestrating build tasks

• GNU GCC and LD, for compiling ARM binaries

• OpenOCD, for flashing firmware and interactive debugging.

• GDB, for interactive debugging via OpenOCD.

• Your favorite text editor, for editing source files.

• Your favorite terminal emulator, for doing CLI tasks.

After following this guide, you will be able to:

• Demonstrate a minimal Makefile-based solution for a very simple LED-blinking firmware.

• Understand the basic concepts of MCU development.

• Perform build/test/debug cylces entirely from the CLI on Linux (and eventually Mac)

• Adapt the Makefile to a continuous integration system such as Jenkins. In other words, it should be straightforward to automate building and publishing firmware binary release-candidates automatically following code review

• Avoid copying vendor code with non-free licenses. Some vendors provide code examples or supporting source files with non-free licenses. Instead of copying example code from these vendors, we will reference datasheets and manuals.

• The classic vendor-supported methods of developing firmware for MCUs is using a full-blown GUI-based IDE like Keil, IAR, or MCU Eclipse.

• These tools are GUI-based and can be proprietary and/or expensive. They also have their own learning curves as they are advanced tools for "serious professionals".

• GUI-based tools can obscure the underlying concepts which aren’t really that complicated!

• Using vendor-provided SDKs and their accompanying non-free licenses could inadvertently lock you into a particular MCU vendor. There are many different ARM MCU vendors you can choose from, and you should be able to switch when you want.

The following source files are used to build the binary you will load:

• The device startup ARM assembly source (startup_ARMCMX.s)

• The device memory parameters (heap and stack size) (mem_ARMCM0.h)

• The device application C source (main.c)

We’ll start by copying the the ARM assembly startup file we need from the official ARM software github.

What is going on in this file? First go read the first five paragraphs from the fine manual for binutils as (the GNU binutils assembler). The manual explains what a binary section is and will help you understand how the linker works, so don’t skip it!

The first two lines of startup_ARMCM0.S set the ASM syntax and architecture (the Cortex-M0 is an armv6-m).

The main purpose of the linker script is to describe how the sections in the input files should be mapped into the output file, and to control the memory layout of the output file.

The linker script instructs GNU ld to create a binary that includes the vector table section, compiled assembly instructions section, and compiled C program sections. All these sections need to go into the exact right locations in the binary. This way the CPU can find the vector table where it expects it to be, the vector table’s second entry points at the compiled ResetHandler code, and so on.

We will just the copy linker script from the ARM CMSIS v5 distribution since it has an open license:

The linker script references a file called mem_ARMCM0.h which defines the stack size as 12 KB and a heap size of 1024 KB (1 MB).

Next, edit the linker script to make the size value parameters match your MCU from the information you collected above. Make sure to convert decimal sizes to hex!

For example, for the NUC029SEE has 128KB ROM and 16KB RAM, so you would set the values as follows.

• Set __ROM__SIZE to "0x000020000" (128Kb*1024 is 131072 bytes in decimal, 0x20000 in hex)

• Set __RAM__SIZE to "0x000004000" (16Kb*1024 is 16384 bytes in decimal, 0x4000 in hex)

• The __ROM_BASE and __RAM_BASE do not need to be changed since they are standard values.

The linker script defines the memory layout using the MEMORY command. This command allows later parts of the linker script to reference specific regions of memory. Our memory consists of two regions: FLASH and RAM, which are defined according to the size/base parameters you setup.

Next, the linker script declares that that ResetHandler function (defined in the startup assembly file) should be the main entry point for our final binary.

The script then uses the SECTIONS keyword to define the binary sections:

• The main .text section is defined in the FLASH memory region. It includes the following susubsections:

  • The .vectors section, which references the vector table defined in the startup assembly file.

  • All input program binary .text sections follow next. In our case the C code will be compiled into a binary object with a single text section.

  • The code for any initializers, finalizers, constructors, and destructors (i.e. for C libraries or C++ applications)

  • Read-only data (rodata)

  • A special section called the eh-frame is used by GCC to handle C++ exceptions and unwind the stack when debugging.

• The .ARM.extab and .ARM.exidx sections are also used for exceptions and stack unwinding, but are specifically part of the ARM standard.

• The .copy.table section is a special section that is used by the ARM startup assembly code. This section will contain the memory addresses of the program data section (i.e. the part that would contain global variables or structures).

• The .zero.table section is similar to the .copy.table sections. The memory regions referenced by the symbols in this section will be zeroed out in the ARM startup assembly.

• The .data section is the first binary section in the MEMORY region. It includes the following subsections:

  • the data_start symbol marks the start of this section; it is referenced earlier in the linker script and in startup assembly fiile.

  • the vtable (a virtual method table) used by C++ programs. **

  • Next, the linker includes the main data section and all other data sections from any input binary files.

  • Data values for preinit, init, finit come next. These are also used for C++ programs.

• TODO: Walkthrough install of ARM GCC toolchain

• TODO: Walkthrough build/install OpenOCD

• Cortex-M0 Boot nice article describing how the Cortex-M0 boots

• Bare Metal ARM Programming a great guide with all the basics you need to know.

• Blink, the HelloWorld of Hardware another fantastic but more in-depth guide.

• Cross compiling from Linux for the Cortex-M basics of using GCC (targeting the STM32F407)

• Building OpenOCD on a Fresh Ubuntu

• Setting up STM32F4 Clocks detailed explanation of setting up accurate clocks (i.e. for USB)

• Retargeting the C Library

• Embed With Elliot: ARM Makefile Madness, targeting the STM32F407 MCU, specifically the STM32F407G-DISC1 development board, and using CMSIS standard ARM libraries.

• GNU ARM Embedded Toolchain for Centos 7.3 Using the ARM GCC toolchain on CentOS 7.x

• GNU Arm Embedded Toolchain Downloads

• OpenOCD CLI tool used for firmware loading and to enable interactive debugging using GDB.

• OpenOCD for Nuvoton MCUs Customized (forked) OpenOCD for Nuvoton devices

• HIDAPI Library Cross-platform library for programming USB devices (used by OpenOCD)

• Vendor MDK5 Software Packs Vendor software packs for Keil MDK. These .pack files are just zip files with interesting stuff inside, even if you aren’t using Keil MDK. In particular we are interested in the SVD XML files which describe the hardware in a standardized machine-readable format.

• MCU Clocks and Introduction to Interrupts article about the basics of clocks on MCUs.

• A Deep Dive into ARM Cortex-M Debug Interfaces in-depth guide to how Cortex-M debugging works

• Nuvoton Board Support Packages Links to various downloads (including github links) for many different Nuvoton MCUs, including the NUC029.

• GNU LD Command language Understanding GNU LD linker scripts.

• From Zero to main(): Demystifying Firmware Linker Scripts How linker scripts work, illustrated by a simple blinky hello world.