RFC: Organization of chips / variant hierarchy about tock HOT 10 OPEN

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.?

from tock.

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)

from tock.

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/.

from tock.

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

from tock.

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.

from tock.

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

from tock.

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.

from tock.

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.

from tock.

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?

from tock.

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/

from tock.