A few days ago, some­one asked on the Ada Dri­vers Library repos­i­to­ry how to add sup­port for the SAMD21 micro-controller.

Nowa­days, I would rather rec­om­mend peo­ple to con­tribute this kind of micro-con­troller sup­port project to the Alire ecosys­tem. Like I did with the samd51_hal crate and lat­er Jere­my Gross­er with the rp2040_hal crate.

I start­ed to write a few instruc­tions on how to get start­ed, but it quick­ly became a blog-wor­thy piece of text. So here it is:

Hard­ware require­ments #

I strong­ly rec­om­mend get­ting a good debug­ger set up. Writ­ing low lev­el periph­er­al dri­vers can be hard, and with­out a prop­er debug­ger it will be most­ly impos­si­ble to know what is going wrong.

So pick a devel­op­ment board that has a debug port avail­able. For the SAMD21, the AdaFruit METRO M0 Express is a bet­ter option than the AdaFruit Feath­er M0.

For the debug­ger itself, you can either get a SEG­GER J‑Link EDU Mini that has sup­port for most Cortex‑M devices, or Black Mag­ic Probe that is open source and open hard­ware but with less devices supported.

An Alire crate for our Hard­ware Abstrac­tion Lay­er (HAL) #

Let’s start our project. To begin with, down­load and install Alire.

Then cre­ate the HAL crate for the SAMD21:

Add the fol­low­ing lines to the samd21_hal.gpr project file:

The run-time used is light-cortex-m0p because the SAMD21 is an ​“ARM Cor­tex-M0 plus” device. You might have to use a dif­fer­ent run-time for your device.

I also rec­om­mend renam­ing the root pack­age to fol­low what is done in the samd51_hal and rp2040_hal:

And then build:

This is the start­ing point for our Hard­ware Abstrac­tion Lay­er library.

Use svd2ada to gen­er­ate the low lev­el hard­ware bind­ings #

Most, if not all, ARM Cortex‑M micro-con­trollers are pro­vid­ed with an SVD file that describes the mem­o­ry mapped periph­er­al reg­is­ters. Some of the RISC‑V ones do too. Using the svd2ada tool, we can auto­mat­i­cal­ly gen­er­ate the Ada bind­ings for all the reg­is­ters, which tremen­dous­ly reduces the effort of sup­port­ing a new micro-controller.

Get the SVD file #

First we have to find the SVD file for our micro-con­troller. For the Microchip (for­mer­ly ATMEL) prod­ucts, the SVD files are found at this address: http://​packs​.down​load​.atmel​.com/

Down­load the .atpack archive cor­re­spond­ing to our micro-con­troller fam­i­ly and unzip it:

Now one of the issues here is that there is one SVD file for each micro-con­troller of the samd21 fam­i­ly, 34 SVD files. That’s because each micro-con­troller can have a dif­fer­ent set of periph­er­als and dif­fer­ent mem­o­ry banks sizes.

Mak­ing a crate for each of the micro-con­trollers in the fam­i­ly would not scale very well (some fam­i­lies have hun­dreds of variants).

There are solu­tions to deal with that issue, but for this post I want to keep it sim­ple. So we pick the SVD file that cor­re­sponds to the spe­cif­ic micro-con­troller that we are using, and this will be a good start­ing point.

In our case, it will be the samd21_atpack/samd21a/svd/ATSAMD21G18A.svd file.

Build svd2ada #

Unfor­tu­nate­ly svd2ada is not avail­able in Alire yet, but we can down­load and com­pile the sources from the GitHub repos­i­to­ry: https://​github​.com/​A​d​a​C​o​r​e​/​s​v​d2ada

Gen­er­ate the bind­ings #

Using svd2ada we are now going to gen­er­ate the low lev­el hard­ware bindings:

We also have to add a depen­den­cy on the hal crate that is used by the bindings:

And then build again:

Make an exam­ple crate #

Now that we pre­pared all this code for our HAL, it is time to final­ly start pro­gram­ming the micro-con­troller for real.

To do that we are going to make anoth­er crate. For every micro-con­troller HAL crate, I rec­om­mend mak­ing an exam­ple crate for a devel­op­ment board that any­body can try. We will call the crate metro_m0_example here because it will be an exam­ple for the AdaFruit Metro M0 board:

Some expla­na­tion is required for the last com­mand here. For this new metro_m0_example crate we declare a depen­den­cy to the samd21_hal crate using the alr with samd21_hal com­mand. Since the samd21_hal crate is not pub­lished yet (we are just start­ing to work­ing on it) the option --use=../samd21_hal tells Alire to get the sources for this crate in a local fold­er rather than try­ing to fetch it from a remote crate index.

We also have to spec­i­fy tar­get and run-time in the metro_m0_example.gpr project file:

We can now build, but there will be an issue:

We see this warn­ing because two things are miss­ing in our code:

• Link­er script
• Start­up code

There is a tool that will gen­er­ate those two for us: startup-gen

Using start­up-gen #

We already have a blog post about startup-gen here. I rec­om­mend look­ing at the blog post for more info on what we are going to do.

First we add the board spec­i­fi­ca­tions to the metro_m0_example.gpr project file. For the SAMD21G18 they are:

I extract­ed the data from the samd21_atpack/Atmel.SAMD21_DFP.pdsc file.

We then build startup-gen with Alire and use it to gen­er­ate the files:

We now have our link­er script and start­up code, there are two more things that we have to do before com­pil­ing the example.

We have to add the fol­low­ing line in the project file (metro_m0_example.gpr) to spec­i­fy that we also want to com­pile assem­bly code:

And we have to add the fol­low­ing lines in the project file (metro_m0_example.gpr) to spec­i­fy the link­er script to use:

We can now final­ly build our first appli­ca­tion for the SAMD21:

The default Alire init project is just a null state­ment, so don’t for­get to add an end-less loop in src/metro_m0_example.adb procedure.

Run­ning on the board #

Now that we have a suc­cess­ful build, we can run our infi­nite loop on the board.

This part is not going to be very detailed because the process can be dif­fer­ent depend­ing on the micro-con­troller/board­/de­bug­ger.

The basic steps with JLink are:

• Cre­ate a GDB serv­er for the debug­ger. For instance $ JLinkGDBServerCLExe -device ATSAMD21G18 -if swd -vd -nogui
• Start GDB with the appli­ca­tion bina­ry: arm-eabi-gdb bin/metro_m0_example
• From GDB:
  • Con­nect to the debug­ger: (gdb) target remote :2331
  • Reset the micro-con­troller: (gdb) monitor reset
  • Load the appli­ca­tion: (gdb) load
  • Put a break point on the main pro­ce­dure: (gdb) b <_ada_metro_m0_example>
  • Start the exe­cu­tion: (gdb) continue

The debug­ger should stop after reach­ing the break­point. That’s it, we made our first pro­gram for the SAMD21.

Build high­er lev­el abstrac­tions #

From here we can start devel­op­ing our example/​application with just the SVD gen­er­at­ed bind­ings, but it is best to build a high­er abstrac­tion above to help the users of our HAL crate.

This will also allow us to have com­mon inter­faces to use exist­ing dri­vers for I2C or SPI for instance. It’s also good to pro­vide use­ful pack­ages to con­fig­ure and set­up the micro-con­troller, like the clock gen­er­a­tors for instance.

This is where the hard part begins and where we are get­ting out­side the scope of this blog post ^^

The use­ful resources will be:

• micro-con­troller documentation
• Ven­dor pro­vid­ed dri­vers (in C)
• Ada dri­vers for oth­er micro-controllers

Make a BSP crate #

There is one last thing I want to men­tion here. So far we made two crates: the samd21_hal and metro_m0_example. But there is anoth­er lev­el of abstrac­tion that we can add.

Most of the time the peo­ple will start pro­gram­ming a micro-con­troller using a devel­op­ment board, either from the ven­dor or from a third par­ty like AdaFruit, Spark­Fun or pimoroni. This is what we did in this blog post.

These devel­op­ment boards come with some fea­tures that are spe­cif­ic to them. For instance, LEDs, but­tons, sen­sors, etc.

It is bet­ter to make a Board Sup­port Pack­age (BSP) crate for those fea­tures, so that our­selves and oth­ers can re-use that code in the future.

So let’s make a new crate:

And in the exam­ple crate, depend on this BSP:

Con­clu­sion #

I realise that this pro­ce­dure is a bit long, but on the oth­er hand it is made short­er and eas­i­er by the use of tools such as Alire, svd2ada and startup-gen. There are short­cuts that you can take if you want, but this will set you in the right direc­tion for the long term main­te­nance of your HAL and BSP code.