[doc] architecture and platform modules

[dhebbeker]

I find it a bit confusing to have some peripheral interfaces declared in architecture and some only in platform. As a user of the library I prefer not to have to look for documentation in different modules. Especially as header files are generated anyways for each target platform, I do not get it. Also it appears to me, that different concepts are applied for different peripherals, for example:

• I2C Master has a common interface in architecture: modm::I2cMaster
• Timer has it's common interface in platform: modm::platform::BasicTimer

I understand that Timer is not available on all platforms, but I do not see the benefit of having the common declarations of I2cMaster separated to architecture only because it is currently available on all platforms.

I have the impression I am missing something. Please enlighten me.

[salkinium]

Everything that's can be implemented on every platform is declared in architecture.

The current STM32 timer classes aren't much of an interface, they wrap the registers in a nicer way. It should be called modm::platform::Timer6Hal, to be consistent with for example the modm::platform::UsartHalN, which is then used to implement both modm::platform::UartN to satisfy the modm::Uart interface and modm::platform::UartSpiMasterN for modm::SpiMaster.
Note that you can pass the classes implementing modm::Uart, modm::SpiMaster and modm::I2cMaster to any driver in :driver, since they use that common interface regardless of the target.

In that sense, modm::platform::Timer6Hal could be used to implement a fictional modm::Pwm interface, which could then be used by a platform-independent driver.
Alternatively you can make drivers that are only available on the STM32 platform, but they would have to use the modm::platform::Timer6Hal interface.

You can technically generate different interfaces for different targets with lbuild and simply move the platform-specific interfaces from the modm::platform::BasicTimer namespace to modm::BasicTimer. Then just pretend that this is the platform-independent interface. 😇😇😇

So the concepts are applied differently, we simply never created platform-indepentent interfaces for Timers. I assume because it's not as straight forward as Uart, I2c, SPI, Can, which are at least fairly standardized protocols. What protocols can the Timers implement? Pwm, (Quad-)Encoder inputs, Input Capture, etc. Those would be the platform-independent interfaces I'd love to see in :architecture, then some drivers that make use of them!

[dhebbeker]

Thank your for your answer @salkinium! This sentence was the key for my understanding:

Note that you can pass the classes implementing modm::Uart, modm::SpiMaster and modm::I2cMaster to any driver in :driver, since they use that common interface regardless of the target.

I am thinking about, if this insight can be incorperated into the documentation.

[salkinium]

Yes, such general ideas should be described in the :architecture module, which is shamefully empty right now.

[mfp20]

Correct me if I am wrong: I can blindly include the modm:architecture:* modules regardless of the target, and lbuild will do its black magic.

So, in a multi-target project, I can have a common.xml having all the modm:architecture:* and then specialized single-target target.xml extending it with modm:platform:* modules?

[salkinium]

Yes, you can theoretically to modm:** to include all module, but unfortunately the :board:* modules conflict, because they generate the same files (you can't really use two BSPs at the same time). But yeah, :architecture:* is fine. Just be careful about :platform:** because things like :platform:heap or :platform:fault are heavy.

[salkinium]

lbuild will do its black magic.

It's just a dependency graph, you can do lbuild dependencies | dot -Tsvg -Grankdir=BT -o dependencies.svg to graphically explore them (you need graphviz installed).

[salkinium]

You can also rename common.xml to lbuild.xml and because lbuild automatically searches the directory upwards for these files and inherits from them. We use this in the examples to deduplicate some common settings.

[mfp20]

you can theoretically to modm:** to include all module

Does it accept wildcards or you just used the wildcard for talking sake?

You can also rename common.xml to lbuild.xml

Awesome!

[salkinium]

Yes, along full hierarchical name resolution: https://github.com/modm-io/lbuild#name-resolution