Handling of device / peripheral access crates


#1

Currently devices / peripheral access crates are developed at various places in the wild:

I’d like to discuss if we can come up with some kind of best practices for these topics:

  • What is the recommended way of handling device crates? One crate per SVD file? One per device? One per device family?
  • Should we group this repositories in GitHub organiations (Like stm32-rs, lpc-rs, nrf-rs, …)
  • Should we group device crates in GitHub repositories?
  • Do we have naming conventions for device crates? (Name of the svd file, -pac postfix, …)

I discussed the issue briefly with @dbrgn and @hannobraun on IRC and we decided to post the questions here.


The embedded-hal reference implementation
#2

I’m personally very fond of one crate per SVD file, since this kind of matches the abstraction made by the manufacturer of the devices.
I think it is then valuable to group this crates in a device family repository or GitHub organization. Maybe even a GitHub organization for svd2rust based device crates which contains one repository per device family.


#3

I’d say that depends on the device. One crate per SVD file is a good rule of thumb in my opinion, but I’ve seen SVD files that were basically identical (e.g. LPC822 and LPC824, which I manually merged to LPC82x).

We’re talking about peripheral access crates here, but I think it’s worth mentioning that HAL crates can cover a wider range of devices. See nrf52-hal, for example (and in that specific case, it could cover even more devices, I believe).

I think that always depends on the people involved. If there’s willingness to cooperate, then it makes total sense. (And as I mentioned on GitHub, I’m all for an lpc-rs organization; details to be determined, of course.)

I’m undecided, but I think it makes sense to group the peripheral access crates of one family into a single repository. At this point, svd2rust isn’t a really comprehensive tool, so additional tooling is required to patch the SVD file, integrate form, and do whatever else is required. I usually write a Bash script for that, and it makes sense to share that among crates.

Over at nrf-rs, we’ve started establishing devicename-pac (PAC for Peripheral Access Crate) as the convention for those crates. I’d love to see this gain traction in the wider community. In my mind, it has the following advantages:

  • It’s a more descriptive name.
  • The HAL is what users should generally use, but mydevice is a more attractive name than mydevice-hal, which might cause users to not accidentally miss the HAL and use the PAC instead.

There’s one open question though: If there’s mydevice-pac and mydevice-hal on crates.io, what happens with the mydevice name? It’s what will show up first when searching for mydevice. Some ideas:

  • Reserve the crate, but make compilation fail with a descriptive message ("this is the situation, you’re probably looking for mydevice-hal").
  • Make mydevice some kind of alias for mydevice-hal.

#4

I think I’d employ a strategy like the one described by @hannobraun: Create a crate per SVD file unless multiple of them are very similar and can be merged.

I think that’s a good idea. I created the lpc-rs organization and invited you and @hannobraun as owners.

I’d suggest to create a lpc-pac repository in there to hold the different PAC crates. @rnestler @hannobraun would you agree with that naming, and is one of you interested in moving one of the existing PAC crates there as a base for future work? Probably it makes sense to use the most mature one.

I think this is a good approach (see stm32-rs) since the tooling (build scripts, contributors documentation, etc) can often be shared among multiple crates.

I think I’d favor this over a single svd2rust organization, since it also allows putting hal crates and other related repos in the same organization.

I like the -pac suffix, for the same reasons as stated by @hannobraun.

I think that’s a good approach, and would probably be “fair use” on crates.io.

Regarding naming in general, especially stm32f1 vs stm32f103xx, I’m not sure… The former looks much nicer, but the latter is more specific, and maybe a bit more flexible. Currently I’d tend towards basing the naming on the SVD file names.


#5

Thank you!

Sounds good. I’ll move my lpc82x-pac (currently still named lpc82x) and lpc82x-hal repositories to the organization shortly. Then we can create a new lpc-pac repository (or repurpose an existing one) when someone has the time and inclination to do it.


#6

I created the https://github.com/lpc-rs/lpc-pac-rs repository and put the lpc11uxx and lpc176x5x inside it, while preserving the history of them. The repository ends up with multiple root commit that way, but I coudln’t think of a cleaner way to do it.