svd2rust

svd2rust-regress is a helper program designed to test changes against svd2rust by running it against multiple chips in parallel using rayon.

For each chip/SVD tested, the tool performs the following workflow:

1. Creates a new crate in output/<chip> with architecture-specific dependencies.
2. Downloads the .svd file for the chip.
3. Runs svd2rust to generate output/<chip>/src/lib.rs.
4. Runs cargo check to verify the generated project builds successfully.

You can filter which tests are executed by combining filters. Note that filters can be combined but not repeated.

Common filtering tasks:

• Filter by architecture: Use tests --architecture <arch> (e.g., riscv).
• Filter by chip name: Use -c <chip_name>.
• Filter by manufacturer: Use -m <manufacturer_name>.

Note: Commands must be run from the ci/svd2rust-regress folder.

# Run all RiscV tests
cargo regress tests --architecture riscv

# Run against any chip named MB9AF12xK
cargo regress test -c MB9AF12xK

# Run against specifically the Fujitsu MB9AF12xK
cargo regress test -c MB9AF12xK -m Fujitsu

Before running svd2rust-regress, ensure the following requirements are met:

1. svd2rust binary: By default, the tool assumes you have already built svd2rust in the root of the repository in --release mode. If you have built it elsewhere, you must specify the path to the binary using the appropriate option.
2. rustfmt: If you intend to use the --format flag, you must have rustfmt version > v0.4.0 installed. You can install it via rustup:

   rustup component add rustfmt-preview

If your SVD file includes <enumeratedValues>, the generated API provides enums for bitfield values, making code more readable and safer.

Reading Enums: You can match on the variant or use convenience methods like .is_input().

// Match on variant
match gpioa.dir().read().pin0().variant() {
    gpioa::dir::PIN0_A::Input => { .. },
    gpioa::dir::PIN0_A::Output => { .. },
}

// Use convenience method
if gpioa.dir().read().pin0().is_input() { .. }

Writing Enums: You can use .variant() to pick a value from the enum, or use convenience methods.

// Using variant
gpioa.dir().write(|w| w.pin0().variant(gpio::dir::PIN0_A::Output));

// Using convenience method
gpioa.dir().write(|w| w.pin0().output());

You can control the casing, prefix, and suffix of generated identifiers using IdentFormat. Identifiers can be parsed from a string using the format prefix:case:suffix.

Supported cases:

• constant (or c, upper)
• pascal (or p, type)
• snake (or s, lower)
• unchanged (or svd, `"")

Example string formats:

• MY_PREFIX:pascal:MY_SUFFIX -> Prefix MY_PREFIX, PascalCase, Suffix MY_SUFFIX.
• MY_PREFIX:snake -> Prefix MY_PREFIX, SnakeCase, no suffix.
• constant -> ConstantCase, no prefix, no suffix.

// Parsing an identifier format string
let format = IdentFormat::parse("PRE:pascal:POST").unwrap();

// Programmatic construction
let format = IdentFormat::default()
    .pascal_case()
    .prefix("My")
    .suffix("R");

You can customize how identifiers (registers, fields, etc.) are formatted using the -f or --ident-format flag. This allows you to override default naming conventions for specific types.

Format Syntax: -f <type>:<prefix>:<case>:<suffix>

Parameters:

• type: The identifier type (e.g., names found in the IdentFormats theme).
• prefix: A string to prepend to the identifier.
• case: The casing style. Allowed values are:
  • '' (empty string): unchanged
  • 'p': pascal
  • 'c': constant
  • 's': snake
• suffix: A string to append to the identifier.

You can install the svd2rust command line tool using cargo install.

$ cargo install svd2rust

When targeting cortex-m, svd2rust generates three files:

• build.rs: A build script to locate device.x.
• device.x: A linker script that weakly aliases interrupt handlers to DefaultHandler.
• lib.rs: The generated peripheral API.

All three files must be included in the same device crate. The crate must provide an opt-in rt feature and depend on the following crates:

• critical-section v1.x
• cortex-m >=v0.7.6
• cortex-m-rt >=v0.6.13 (with device feature enabled if rt is enabled)
• vcell >=v0.1.2

Example Cargo.toml for Cortex-M:

[dependencies]
critical-section = { version = "1.0", optional = true }
cortex-m-types = "0.1"
cortex-m-rt = { version = "0.6.13", optional = true }
vcell = "0.1.2"

[features]
rt = ["cortex-m-rt/device"]