Define a versioning and compatibility strategy for ROM symbols and radio blob updates in `esp-rom-sys`

[JurajSadel]

we never want breaking changes in esp-rom-sys

That was the initial assumption and it will hold true until we need to update the radio blobs.

What makes all of this a bit more complex is, (in my point of view) we have three different "tiers" of items this crate provides:

• the Rust helpers / wrappers (this is the easiest part - we just don't want to see anything breaking here, ever)
• some symbols we rely on (i.e. common ROM functions we use in other crates ... we just don't want to see anything breaking here, ever - but that's only a hand full of symbols)
• a lot of other symbols we don't even can know what their meaning is (the tricky part ... when the blobs in esp-idf are updated it's quite common that ROM functions get commented out and are replaced by code found in the blobs )
• (in theory another category: ROM functions replaced by libesp_rom.a ... but that is not a problem since that happens inside esp-rom-sys ... which makes we wonder if we should/need to take that (symbols from libesp_rom.a) into account here?)

So what to do here and now?

I have ideas how to overcome the above problems but we need to carefully validate these (and hope one of them will work). In any case it's far beyond the scope of this PR.

We can just assume our original assumption about this to never see any breaking changes will hold true and just don't allow anything beyond a patch-version bump here. This PR should help us to uphold this requirement.

And we need to open a new issue to find a solution for the outlined (forseeable) problems. (we will need to solve that before the next blob update)

The outcome of that new issue might even be that we will need breaking changes but hopefully not.

Originally posted by @bjoernQ in #4584 (comment)

[bjoernQ]

Problem Statement

We assume esp-rom-sys is "perma-unstable" - i.e. it will only ever see patch releases.

That is because

• we can only ever have exactly one version of it in the dependency tree
• it's an implementation detail of quite some other crates
• we don't want to break user's project "just for this" (especially since it's something internal the error will be very confusing for users)

The crate provides a few different types of items

1. the Rust helpers / wrappers (we don't want and need breaking changes here)
2. some symbols we rely on (i.e. common ROM functions we use in other crates ... we just don't want to see anything breaking here, ever - but that's only a hand full of symbols, if we want or need to rename a symbol we can just alias it and don't need a breaking change) - this also includes ROM functions replaced by libesp_rom.a
3. a lot of other symbols we don't even can know what their meaning is (the tricky part ... when the blobs in esp-idf are updated it's quite common that ROM functions get commented out and are replaced by code found in the blobs )

As we see 1 and 2 are not a problem at all. However 3 is a huge problem!

Solutions?

• revise our decision on only ever having patch releases
  • this will be very bad for users especially since the error message they will face is not easy to understand
• define every symbol weakly
  • this is a tempting approach
  • if the blobs define their replacements itself as weak the symbol which will finally might vary by differnt linkers (we currently use two) and very hard to influence
  • even if the blobs don't define the replacement as weak it can change in future
• another solution (see below)

Another Solution?

One idea could be to support different versions of the symbols via features. e.g. v0,v1 ... etc.

The (for now) only crates which will ask for a specific version would be esp-phy and esp-radio.

Because Cargo performs feature unification we can end up with multiple "concurrent" versions requested.

If multiple versions are requested we will use the latest but emit a warning - it might work but it indicates something is not quite right.

If no version is requested we can default to latest.

If only one version is requested we use that.

Additional Thoughts

We might want to separate the "definitely stable" parts and the "can change anytime we update the blobs" parts. I'm not sure if this might be helpful in future or just makes everything more complex.

We should also keep in mind that at some point we need to support different ECOs. I don't think this will fundamentally change the decision here however.

Other Solutions?

Maybe there are other / better solutions. Feel free to suggest any alternative ideas.