avr-device

Auto-generated wrappers around registers for AVR microcontrollers.

Usage

Add the following to Cargo.toml:

[dependencies.avr-device]
version = "0.7.0"
features = ["atmega32u4"]

Via the feature you can select which chip you want the register specifications for. The following list is what is currently supported:

ATmega	ATmega USB	ATmega 0,1 Series	AT90	ATtiny
atmega8	atmega8u2	atmega3208	at90usb1286	attiny13a
atmega48p	atmega16u2	atmega3209		attiny167
atmega64	atmega32u2	atmega4808		attiny202
atmega644	atmega32u4	atmega4809		attiny212
atmega88p	avr64du32			attiny214
atmega16	avr64du28			attiny402
atmega168				attiny404
atmega324pa				attiny412
atmega328p				attiny414
atmega328pb				attiny416
atmega32a				attiny44a
atmega1280				attiny84
atmega1284p				attiny85
atmega128a				attiny88
atmega128rfa1				attiny816
atmega2560				attiny828
atmega164pa				attiny841
				attiny84a
				attiny861
				attiny1614
				attiny2313
				attiny2313a

Build Instructions

The PACs (Peripheral Access Crates, or really modules, in our case) are not checked into git. Rather, we generate them at build time, via an automated process implemented in build.rs. It takes the ATDF files Microchip (former Atmel) provides plus some patches of our own making as inputs, and outputs a module generated from those device descriptions. These inputs are checked-in. The process is similar to what the *bindgen crates provide, just has more steps. So, in short, building should be a matter of selecting the features and running cargo.

Adding a new Chip

To add a new chip:

1. Download the ATDF from http://packs.download.atmel.com/ and place it in vendor/. Be sure to name it like the Rust module that should be generated.
2. Add a feature of the same name to Cargo.toml (it should enable device-selected);
3. Add any needed patches to a yaml file with the same name under the patch directory, ideally by including some of the snippets present in patch/common and patch/timer; The format is decribed here, but it should not include the top-level _svd key, as that's handled by the build system; If patching is unneeded (it's almost always needed!), the file can be omitted.
4. Include the module into the tree, in devices.rs, following the format used by other modules in that file;
5. Finally, try building the crate for your MCU with cargo build --features <mcu>,rt.
6. Also check the built documentation for inconsistencies, via cargo doc --features <mcu>,rt --open (it will pop up in your browser).

Internals

Since the vendor does not provide SVDs we can pass to svd2rust, we generate one via atdf2svd. The sequence is as follows:

1. Check which MCUs are known to the crate (build.rs:get_available_mcus);

2. Select which to build for by checking enabled features (build.rs:select_mcu);

3. Generate the Rust module (build.rs:build_mcu_module);

   Substeps are:

   1. Register inputs with cargo;
   2. Get a temporary directory;
   3. Apply atdf2svd;
   4. If a yaml patch exists, use it via svdtools and read the new content / else, read the content of the unpatched file to continue;
   5. Get the output directory;
   6. Apply svd2rust;
   7. Run prettyplease on the module to make it readable in docs.rs;

4. It will be included from $OUT_DIR/pac/<mcu>.rs into the path avr_device::devices::<mcu> (private), and re-exported as avr_device::<mcu> (public).

License

avr-device is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

The vendored atdf files are licensed under the Apache License, Version 2.0 (LICENSE-VENDOR).