Repository files navigation

This repository provides Rust device support crates for all STM32microcontrollers, providing a safe API to that device's peripherals usingsvd2rust and a community-built collection of patches to the basic SVD files.There is one crate per device family, and each supported device is afeature-gated module in that crate. These crates are commonly known asperipheral access crates or "PACs".

To view the generated code that makes up each crate, visit thestm32-rs-nightliesrepository, which is automatically rebuilt on every commit to stm32-rs master.The stm32-rs repository contains the patches to the underlying SVD files andthe tooling to generate the crates.

While these crates are widely used, not every register of every device willhave been tested on hardware, and so errors or omissions may remain. We can'tmake any guarantee of correctness. Please report any bugs you find!

You can see current coverage status for each chiphere. Coverage means that individual fields aredocumented with possible values, but even devices with low coverage shouldhave every register and field available in the API. That page also allows youto drill down into each field on each register on each peripheral.

In your own project'sCargo.toml:

[dependencies.stm32f4]version ="0.16.0"features = ["stm32f405","rt"]

Thert feature is optional but helpful. Seesvd2rust fordetails.

Then, in your code:

use stm32f4::stm32f405;letmut peripherals = stm32f405::Peripherals::take().unwrap();

Refer tosvd2rustdocumentation for further usage.

Replacestm32f4 andstm32f405 with your own device; see the individualcrate READMEs for the complete list of supported devices. All current STM32devices should be supported to some level.

Whenever the master branch of this repository is updated, all device crates arebuilt and deployed to thestm32-rs-nightliesrepository. You can use this in yourCargo.toml:

[dependencies.stm32f4]git ="https://github.com/stm32-rs/stm32-rs-nightlies"features = ["stm32f405","rt"]

The nightlies should always build and be as stable as the latest release, butcontain the latest patches and updates.

• Installsvd2rust,svdtools, andform:
  • On x86-64 Linux, runmake install to download pre-built binaries at thecurrent version used by stm32-rs
  • Otherwise, build usingcargo (double check versions againstscripts/tool_install.sh):
    • cargo install form --version 0.13.0
    • cargo install svdtools --version 0.5.0
    • cargo install svd2rust --version 0.36.1
• Install rustfmt:rustup component add rustfmt
• Generate patched SVD files:make patch (you probably want-j for allmake invocations)
  • Alternatively you could installcargo-make runner and then use it instead ofmake. Works on MS Windows natively:
    • cargo install cargo-make
    • cargo make patch
• Generate svd2rust device crates:make svd2rust
• Optional: Format device crates:make form

Basically, the full process is:

+--------------------------+  +------------------------+  +--------------------------+  +--------------------------+| ST-supplied SVD archives |  | SVD peripheral patches |  | Peripheral fields detail |  | Perip. fields collecting ||     in 'svd/vendor/'     |  |  in 'devices/patches/' |  |    in 'devices/fields'   |  |   in 'devices/collect'   |+--------------------------+  +------------------------+  +--------------------------+  +--------------------------+             |                            |                            |                             |             |                            |                        (optional)                    (optional)       `make extract`                     |                            |                             |             |                            +----------------------------+-----------------------------+             |                                                         |             v                                                         v+----------------------------+                            +--------------------------+|   ST-supplied SVD files    |                            |    SVD device changes    ||         in 'svd/'          |                            |      in 'devices/'       |+----------------------------+                            +--------------------------+              |                                                        |              +---------------------------+----------------------------+                                          |                                    `make patch`                                  (using svdtools)                                          |                                          v                              +------------------------+                              |   Patched SVD files    |                              |       in 'svd/'        |                              +------------------------+                                          |                                   `make svd2rust`                                          |                                          v                              +------------------------+                              | Generated STM32 crates |                              |      in 'stm32*/'      |                              +------------------------+                                          |                                 `make form` (optional)                                          |                                          v                              +------------------------+                              | Formatted STM32 crates |                              |      in 'stm32*/'      |                              +------------------------+

This project serves two purposes:

• Create a source of high-quality STM32 SVD files, with manufacturer errorsand inconsistencies fixed. These files could be used with svd2rust or othertools, or in other projects. They should hopefully be useful in their ownright.
• Create and publish svd2rust-generated crates covering all STM32s, usingthe SVD files.

When this project began, many individual crates existed for specific STM32devices, typically maintained separately with hand-edited updates to the SVDfiles. This project hopes to reduce that duplication of effort and centralisethe community's STM32 device support in one place.

This project is still young and there's a lot to do!

• More peripheral patches need to be written, most of all. See what we've gotindevices/ and grab a reference manual!
  • Eachstm32*.yaml file is a patch for a specific device SVD.
  • To avoid repetition, common patches are written per peripheral indevices/patches. Search there if a patch you want to add doesn't alreadyexist!
  • Register fields description indevices/fields are not a part of theCMSIS-SVD specification but enable type-safe friendly-name interface(enumerated values) for highly detailed crates.
  • devices/collect is here for collecting inarrays,clusters andderivesto minimize duplication.
• Also everything needs testing, and you can't so easily automate finding bugsin the SVD files...

• Update SVD zips insvd/vendor to include new SVDs.
• Runmake extract to extract the new zip files.
• Add new YAML file indevices/ with the new SVD path and include anyrequired SVD patches for this device, such as renaming or merging fields.
• Add the new devices tostm32_part_table.yaml.
• Add the new devices toscripts/makecrates.py.
• You can runscripts/matchperipherals.py script to find out what existingperipherals could be cleanly applied to this new SVD. If they look sensible,you can include them in your device YAML. This requires a Python environment with thepyyamlandsvdtools dependencies.Example command:python scripts/matchperipherals.py devices/fields/rcc devices/stm32h562.yaml
• Re-runscripts/makecrates.py devices/ to update the crates with the new devices.
• Runmake to rebuild, which will make a patched SVD and then runsvd2ruston it to generate the final library.

If adding a new STM32 family (not just a new device to an existing family), completethese steps as well:

• Add the new devices to theCRATES field inMakefile.
• Update this Readme to include the new devices.
• Add the devices toworkflows/ci.yaml andworkflows/nightlies.yaml.

• Using Linux, runmake extract at least once to pull the SVDs out.
• Edit the device or peripheral YAML (see below for format).
• Using Linux, runmake to rebuild all the crates usingsvd patch andsvd2rust.
• Test your new stuff compiles:cd stm32f4; cargo build --features stm32f405

If you've added a new peripheral, consider using thematchperipherals.pyscript to see which devices it would cleanly apply to.

To generate a new peripheral file from scratch, consider usingperiphtemplate.py, which creates an empty peripheral file based on a singleSVD file, with registers and fields ready to be populated. For single bit widefields with names ending in 'E' or 'D' it additionally generates sample"Enabled"/"Disabled" entries to save time.

Please see thesvdtools documentationfor full details of the patch file format.

• Enumerated values should be named in the past tense ("enabled", "masked",etc).
• Descriptions should start with capital letters but do not end with a period

Notes for maintainers:

1. Create PR preparing for new release:
   • UpdateCHANGELOG.md with changes since last release and new contributors
   • UpdateREADME.md to bump version number in example snippet
   • Updatescripts/makecrates.py to update version number for generated PACs
2. Merge PR once CI passes, pull master locally.
3. make clean
4. make -j16 form
5. for f in stm32c0 stm32f0 stm32f1 stm32f2 stm32f3 stm32f4 stm32f7 stm32h5 stm32h7 stm32l0 stm32l1 stm32l4 stm32l5 stm32g0 stm32g4 stm32mp1 stm32n6 stm32u0 stm32u5 stm32wl stm32wb; cd $f; pwd; cargo publish --allow-dirty --no-default-features; cd ..; end
6. git tag -a vX.X.X -m vX.X.X
7. git push vX.X.X

Licensed under either of

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

at your option.

Unless you explicitly state otherwise, any contribution intentionally submittedfor inclusion in the work by you, as defined in the Apache-2.0 license, shall bedual licensed as above, without any additional terms or conditions.