Use Cargo's links = "name" feature in singleton crates

[jonas-schievink]

We have several crates that only support linking a single version of them into a crate graph. These crates include:

• All -rt crates, so cortex-m-rt, riscv-rt, msp430-rt, ...
  • These crates need to ensure this since they define the memory layout of the binary, and doing that multiple times would at best result in very confusing errors, and at worst produce a binary that doesn't work right.
• All peripheral access crates like cortex-m and all svd2rust-generated PACs
  • These crates need to ensure this, as otherwise you could depend on 2 PACs and .take() their Peripherals twice.

Currently, these crates define a #[no_mangle] symbol to ensure that only a single version of them is linked to by an application, causing a linker error when more than one version is present.

Another way to do this is to use Cargo's links = "<name>" feature, which was designed to support precisely this use case (only for linking to C libraries that have global state). I think we should switch every crate to use the Cargo feature, since it was designed for this, gives a better error message, and cannot fail when no methods from one of the versions are called (a shortcoming of the current approach).

To do this, we need to migrate slowly, since removing the clashing symbol removes the protection with older versions of the library. That means, we start by adding a links key to all affected crates, and only after a couple of releases we remove the clashing symbol.

[adamgreig]

In general 👍 on this. For the PACs, we don't host them in the wg, and svd2rust doesn't generate Cargo.toml, so I think all we can do is open issues on PACs to encourage them to use links and perhaps update the svd2rust docs.

What value do you think PACs should use for the links key? I wonder if just pac (or peripheral-access-crate) could work, to prevent ever linking two PACs, even alternative PACs such as stm32ral? If you used the crate name, someone might link e.g. stm32f0 from that crate, and another svd2rust-generated crate using stm32f0x1, and even stm32ral all at once.

[jonas-schievink]

Yeah, makes sense to use a shared key. We should probably document this in a central place (maybe this repo?).

And, I suppose, I'd like svd2rust to generate Cargo.toml then.