RFC: Organization of chips / variant hierarchy

[ppannuto]

We're starting to get a growing collection of variants for chips. Organizing this has been a standing design challenge. Navigating the nrf52 family in #3615 and the cfg issues in #3528 has renewed me thinking about what a next iteration might look like.

Currently, chips/ is a flat namespace with shared variants and actual chips all in the root. I propose that chips/ be re-organized into a strict hierarchy such that variants always live 'inside' their containing folder, and any 'leaf' directories and only 'leaf' directories represent real, specific, physical chips to avoid maintaining a growing list of exceptions like this. I believe this will also make it easier to reason about where components come from on the more fractured families.

As an example, the nrf family of chips would be revised to look something like this:

chips/
└── nrf5X
    ├── nrf51X
    │   └── nrf51822 [hypothetical chip]
    └── nrf52X
        ├── nrf52 [hypothetical chip]
        ├── nrf52832
        └── nrf528XX
            ├── nrf52833
            └── nrf52840

Design Questions

Will this play nice with cargo / workspaces / etc?

From some early reading, I think so. I haven't actually tried implementing it yet and could be proven sad.

'X' as a sentinel?

I put an X in to explicitly mark something as a variant holder. I am honestly unsure at this point whether there exists a plain nrf52 chip from Nordic you can buy, or they only named the dev board that and the chip is always a 52832, but I wouldn't put it past them, or some other manufacturer to distinguish a chip at some point with only additional letters, so I think we need something to explicitly assert this as a variant.

Of course, there are also chips that happen to use the letter x in their names. I toyed around with the idea of a unicode _ or some other game, but decided that would be more annoying than anything else in practice. Rust convention is that crate names are all lowercase. Rust is also case-sensitive. I propose that we use only lowercase letters for actual chips (regardless of manufacturer casing) and allow the capital X to be a clear sentinel.

'X' always at the end?

I don't think that's strictly necessary, one might imagine a stmf32XX20 or something it if made sense.

Exact number of 'X's?

I think when there is clear placeholders, naming with X's in each place makes sense. For the nrf family, there's a varying number of letters later sometimes, so can say that a trailing X indicates zero-or-more additional characters for actual chips.

What about diamond patterns?

I don't know of a chip family that names things this way — cross that bridge when we come to it.

[bradjc]

Where does shared code, like the nrf52 crate, go?

[ppannuto]

In the nrf52X folder.

Should have been clearer, sorry. Variant folders would hold all the rust code common to that variant, and subfolders for all the chips that share that variant.

[bradjc]

So crates would have other crates inside them? I'm confused how that would work.

[ppannuto]

That was my thinking yes, the nrf528XX/ folder would have a Cargo.toml in it an a src with all its contents, as well as sub-directories of nrf52833 and nrf52840 (which each have Cargo.toml and src/ inside).

Maybe it's clearer if nrf528XX/ has a src/ and its own chips/ folder... I'll try messing around a bit with nrf to see if I can get a MWE going; it's a bunch of mechanical changes eventually to get it all put together so I was trying to see if the concept made sense first.

[bradjc]

I feel strongly we shouldn't have crates inside of crates. Too confusing as I would never think to look for a crate within another crate.

I don't see the need for all of this complexity and the redundant folder searching it would require. If some organization is needed (I'm not really sure it is as we only have ~32 chip crates), why not just put families in a single folder? So all nrf5* crates go in chips/nrf5/, stm in /chips/stm32, etc.?

[ppannuto]

My main motivation here stems from trying to teach people (and frankly sometimes to figure out myself) where code comes from for the nrf family of chips. I think that platform happens to be a particularly unfortunate example with the legacy of the nrf51822 leaving a today-confusing nrf5x vs nrf52 split.

Nordic is further pathological in that the nrf52840{dk,dongle} boards use the nrf52840 chip, but the nrf52{dk} board does not use the nrf52 chip — because there is no nrf52 chip, even though there is a chips/nrf52 folder/capsule.

The hierarchy was motivated by trying to make it harder for people to make the mistake of including hardware that doesn't exist (i.e. including the 15.4 radio on the nrf52832), but agree it probably become more crate and module boilerplate than it would be worth; at least at our current scale.

I do still think we should move to something that makes is clearer to the inexperienced user what in chips/ folder is actually a chip. Perhaps then something like this:

nrf52/
├── nrf52-common <-- consolidate nrf5x and nrf52 stuff into one crate
├── nrf52832
├── nrf52833
└── nrf52840

I could also be pretty easily convinced to just have nrf5-common and nrf52-common (or nrf5x-common and nrf52x-common) folders to avoid the relatively useless labor of merging the crates. (critically not the mixed "5x" and "52" we have today though; we should be consistent in how we label partial identifiers)

[lschuermann]

I'd be onboard with @ppannuto's revised proposal in #3627 (comment).

One thing which may be interesting are chip-independent chip crates (e.g., virtio, or a potential crate which would share the #3523 driver, as that's shared between multiple chips of different vendors). They are "chip" crates as they interact with MMIO HW directly, but are not necessarily bound to a single chip and/or vendor.

We can cross that bridge when we get there, and put these crates into a subfolder where they seem "the most appropriate" in the meantime. However it might make sense to think about how they could influence such a hierarchy in the long term.

[alexandruradovici]

I agree with @lschuermann here, for the ST family, we have a lot of chips that share peripherals, but not in a hierarchical way. We have the STM32F4 family chips sharing peripherals with the ST32F3, but not with F7.

The CAN is another example, many different vendors use the same hardware.

What about having a folder for crates that implement just peripherals?

[ppannuto]

I think ideally we can separate vendor-specific shared peripherals (e.g. stuff under the STM umbrella) from shared IP blocks (e.g. multiple vendors using the same CAM block). The latter would make sense to be in a separate crate probably.

I understand the nordic ecosystem reasonably well, but don't really have my head wrapped around the STM side quite as well. Would it be possible to write up a rough summary or make a table of the peripheral sharing / specialization for a some representative examples across a few boards? Really what I'm trying to understand is

stm32f/
├── stm32f-common <-- inside this, use cfg / features to gate accessibility of things?
├── stm32f303xc/
├── stm32f401cc/
├── stm32f412g/
├── stm32f429zi/
└── stm32f446re/

would something like this make the 32f-common crate unruly? How should we draw the line for having 32f-common 32f3-common and 34f4-common crates, etc?

Versus an alternative of "another family root", e.g. this:

stm32f3/
├── stm32f3-common <-- inside this, use cfg / features to gate accessibility of things?
├── stm32f303xc/
stm32f4/
├── stm32f4-common <-- inside this, use cfg / features to gate accessibility of things?
├── stm32f401cc/
├── stm32f412g/
├── stm32f429zi/
└── stm32f446re/

[bradjc]

A lot of this seems like it depends on how the IP is named. If there is a single namespace for the blocks across an entire family, then that family can use one common crate, but if there is something like a different uart for f7 vs f4 then those would need their own common crates. I still think they can be in the stm32/.