Consider incorporating fixes and extensions to vendor SVD files maintained by the svd2rust related projects

[tim-seoss]

The Rust embedded community maintains a considerable set of patches against vendor-supplied SVD files which add both corrections for vendor SVD errata, and also enhancements.

E.g. this repository is for stm32 "peripheral access crates" (which I believe is the most mature):

https://github.com/stm32-rs/stm32-rs

The patches are maintained at yaml files for readability.

e.g. https://github.com/stm32-rs/stm32-rs/tree/master/devices/common_patches

... and are applied against the vendor-supplied SVD files here:

https://github.com/stm32-rs/stm32-rs/tree/master/svd

... by https://github.com/rust-embedded/svd2rust

This project may want to work with the svd2rust and/or stm32-rs maintainers (there is overlap between the two) to maintain these fixes and/or get them applied to the vendor files?

[Fabien-Chouteau]

Hi @tim-seoss,

I think the best would be to produce and publish standard SVD files from those patches. It would benefit every SVD code generator / reader.

[tim-seoss]

That sounds reasonable, but I'm not sufficiently familiar with SVD files to know the practicalities of this.

It might be best if someone familiar with this project and involved in this project looks into how that might work, and/or opens discussions with some of the embedded rust developers. A good place to enquire might be e.g. https://matrix.to/#/#stm32-rs:matrix.org , or https://matrix.to/#/#rust-embedded:matrix.org

[Fabien-Chouteau]

We don't have spare cycles to take on this task at the moment.

I will keep this ticket as an enhancement request.

[kevlar700]

I am not sure that the way that the Rust community is doing this is as helpful to other communities, as it could be. A repo of patched SVD files or SVD patches without Rusts language specific enumeration generation lines, might be useful for collaboration.

In fact a community SVD repo that e.g. STM32 Cube or all debugger users can fix, rather than waiting for vendors, might be a much more powerful idea.

Having seen atleast one Rust SVD error introduction. The problem I see is, who is going to verify PRs for many SVDs when being sure laboriously involves referencing ref manuals and potentially C code. I have found that either one can be incorrect. Perhaps a maintainer system for particular chips could be adopted (supported SVDS)?

[Joebeazelman]

I just checked out the repos. They're very interesting. I gather the Yaml files are changesets which are applied to the SVD using some tool? It's good to keep a history of changes, but I wonder why they went through the effort of storing it as a Yaml file. Doesn't git do a good enough job at tracking such changes? It also has facilities to consolidate changesets and even spit it out as a file that can be applied independently to a file.

Regardless, normalized and corrected SVD files are very useful.

[simonjwright]

I just checked out the repos. They're very interesting. I gather the Yaml files are changesets which are applied to the SVD using some tool?

Looks to me like the equivalent of svd2ada, in other words they make up the tool used to convert SVDs to rust, and contain specific fixes for specific SVDs

[tim-seoss]

@simonjwright There are two distinct steps in the process that the rust embedded team use.

First a patched SVD is output (using either a python script, or a compatible rust binary - both are available and supported and are maintained in this repo: https://github.com/stm32-rs/svdtools - along with some documentation).

After that, svd2rust uses these fixed SVDs as input to create rust "peripheral access crates".

Obviously this svd2ada would only potentially find the first step useful!

IIRC, additional metadata can be added too during the patching step, which I suppose could also be useful (or could be ignored it not useful).

The most complete set of SVD patches would be the stm32 family I think, e.g. see here (and also the sub-directories) - https://github.com/stm32-rs/stm32-rs/tree/master/devices and also here - https://github.com/stm32-rs/stm32-rs/tree/master/peripherals

I assume the choice of yaml was taken as part of the requirement to apply the same set of patches to a large set of SVDs (commonly errors are duplicated across mcu family members), whilst also desiring to have something more readable than xml as an input.

There are also associated tools which are used during CI, and e.g. show the differences in the resultant MCU memory map before and after a change is made to the patch files.

[Joebeazelman]

OK. Makes a lot of sense. So I guess there's quite a bit of overlap among the same MCU family that the same yaml patch file can be used. This means there's enough overlap present to create a higher level Ada abstraction across a range of MCUs. Cool!

[tim-seoss]

Doesn't git do a good enough job at tracking such changes?

I seem to remember that part of the reason for this workflow being adopted was that:

In the case of some manufacturers' SVD file licences, publishing modified SVDs appeared to be prohibited, whereas generating fixed SVDs as temporary+intermediate artefacts during an automated process was thought to be acceptable.

[kevlar700]

A list of manufacturers with this term would be useful. I believe they should change their license. After all, their own debug experience would benefit.

[tim-seoss]

@kevlar700 I don't know if such a list exists, however all ST Micro SVD files released before 2020 are released without any license. In this situation, the legality of use varies in different jurisdictions, but in the majority of countries it would be illegal to distribute modified versions (e.g. see https://choosealicense.com/no-permission/ ). I believe ST changed their policy in around 2019 (newer SVDs are Apache 2.0), but there are still no SVDs for many ST families which allow modified versions to be distributed (e.g. F3, F4, L0 families).

Currently the embedded Rust community is pretty much the sole user of these files (and this may explain certain rust-centric design decisions or annotations) but it's likely that they would be interested in sharing the work of correcting and annotating SVDs to make them more useful for automatic code generation across languages - as long as corrected files are available in some form it seems unlikely to matter whether they are made available as originals with patches, or ready-patched version...