Adding a new chip

So, you have a shiny new samd21 or samd51, but the specific chip isn't supported by us yet. What do you do? Never fear, this guide is here to help!

Generating the PAC

A peripheral access crate, or PAC, is the low(ish)-level interface for changing values in peripheral registers. It's for twiddling bits, essentially. The hardware abstraction layer (HAL), builds up a more user-friendly interface on top, and everything in the HAL is built on top of the PAC. So you need a PAC. You might think it would be a lot of work to build up a whole crate for accessing every register in a chip, but in the Embedded Rust world, we're quite lucky to have a tool known as svd2rust, which generates the PAC for us from an SVD file. We already have all the svds for samd51 and samd21 chips in the svd folder, so you don't even have to go hunting for that file from the manufacturer. What you do have to do though, is create a directory for the new pac with the chip name, give it a Cargo.toml similar to the ones in the other PACs, but with the name replaced, add the chip name to the update.sh bash script, where it says for chip in, and run the script.

Adding the PAC to the HAL

Open up hal/Cargo.toml in your favourite editor, and add a new dependency section and feature like the ones below, with your chip name instead of atsamd51j19a:

[dependencies.atsamd51j19a]
path = "../pac/atsamd51j19a"
version = "~0.4"
optional = true

[features]
samd51j19a = ["atsamd51j19a"]
samd51j19a-rt = ["atsamd51j19a", "atsamd51j19a/rt"]

Note that you don't want to add a new [features] section, but add to the existing one.

Also, add a section similar to the following to hal/src/lib.rs, again, with your chip name:

#[cfg(feature = "samd51j19a")]
pub extern crate atsamd51j19a;
#[cfg(feature = "samd51j19a")]
pub use atsamd51j19a as target_device;

Configuring chip-specific functionality

Let's say your chip-variant has a difference from the ones we've already implemented the HAL for, like 8 SERCOMs instead of 4 or 6. What would you do then? Well, you would add a new #[cfg(feature = "CHIP_NAME")] statement, using the features we created in the last section. Going along with the 8 SERCOM example, you would edit hal/src/sercom51/pads.rs and add

#[cfg(feature = "samd51p20a")] 
pad!(
    pub enum Sercom6Pad0 {
    [... the rest omitted for brevity]

You can have a look at where the existing #[cfg] statements are (and what you may need to edit) if you have ripgrep installed. If you don't, install it from your operating system's package manager, or cargo install ripgrep. Once you have ripgrep installed, run the command, rg 'feature = "s' to find all the #[cfg] statements.

Congratulations

Once you've done these 3 things, you should have a fully functioning chip. Woohoo! Don't forget to send us a PR so everyone can benefit. And next you may want to Add a new board