Creating Alternate implementation of an existing module

[CrustyAuklet]

I've been in and out over the past few years, doing some of the initial modm-devices work on SAM processors. finally the project I've been circling has actual resources and I am adding the processor for the project so we can use modm! It's the SAML10/SAML11 m23 chip.

All that being said I have UART/GCLK/GPIO/etc all working, but I would like to maybe make an alternative implementation for a few things. I would love to push those new versions upstream, so i want to do it right.

Is there a good example of how to handle this? It seems easiest to keep it separate for now, since in the end it will either stay separate or get merged maybe some help from the community.

Examples

GCLK

The current SAM implementation is great, but makes a lot of assumptions about how each GCLK is used, and what the prescalers are. I would like to make an implementation that models the clock tree config tool in ASF4. The goal would be able to set up the clock in arbitrary ways, but with expressive coding and the compile time checking we expect. This could also make a code generator as mentioning in #715 easier to do.

CMake

The current CMake implementation is designed well for a self contained binary. We kind of want to package the HAL/BSP we generate as a library that we can use from other projects using CMake FetchContent etc. Leave most of the compiler flags that aren't absolutley required, etc to the consuming project. Make the linker script a target to it can be used or not.

M23 differences

not really an existing module, but similar question. A lot of peripheral code is shared with other SAM chips. But some of the GCLK stuff the input file ended up with pretty much

%% if target.family == "l" and target.series == "10"
   // all the L1x code
%% else
   // original code 
%% endif

[salkinium]

You should upstream everything, even if it's not perfect or has a different API from the rest, so that other people can later learn from it and maybe refactor it into a new better API. Most of modm was built that way, since there are way too many devices that you can know in enough detail.

The "official" way to handle this is to make lbuild generate different files for the same module name by switching on the :target repository option. This is basically how everything in :platform works, and we typically just write whatever API is best suited for the device (unless it's a standard thing like UART) and then just limit the availability of the module to only the devices we have looked at. That's why we have our HAL matrix in the README.

GCLK

I don't know the SAM hardware at all, so I just let people design it how they see fit with the idea to later look at the differences and refactor into a shared API. This is how we did it for the STM32 RCC peripheral, which is also very different on each family.
If you want to try another API, you can limit it to only the M23 target, that way you don't have to port it to targets you don't have.
You can also generate other files, like a HTML with Javascript for clock config outside the compile time limits C++.

M23 differences

You can switch on the :target option to select what files are generated, so you don't have to squash everything into the same file.
So I would recommend having a second glck_m23.hpp.in file that is copied to glck.hpp only on M23 targets.

CMake

I'm aware that our compile flags being global and thus also applying to ext/ code and the application code is annoying, but I haven't gotten around to fixing that yet (since it also requires changes to how we generate SCons and Makefile). The main issue is that the compile flags are collected by lbuild and there is no difference between essential and non-essential flags right now.

So feel free to change things, if the changes are incompatible you can switch them via an lbuild option.

[CrustyAuklet]

thanks! The mechanical options of just having a second file and switching on :target was kind of what I was looking for. I also dove into the lbuild docs this morning and I see that I can create sub-modules in the same .lb file by making a module class and adding it in the prepare() function using module.add_submodule().

Looking at the root modm repo.lb file I can also see that it adds modules with the pattern *.lb so I could just make another lbuild file in the same directory with a different name.

I'm aware that our compile flags being global and thus also applying to ext/ code and the application code is annoying, but I haven't gotten around to fixing that yet (since it also requires changes to how we generate SCons and Makefile). The main issue is that the compile flags are collected by lbuild and there is no difference between essential and non-essential flags right now.

I'll see what I can come up with. :)

[chris-durand]

I don't know the SAM hardware at all, so I just let people design it how they see fit with the idea to later look at the differences and refactor into a shared API. This is how we did it for the STM32 RCC peripheral, which is also very different on each family.
If you want to try another API, you can limit it to only the M23 target, that way you don't have to port it to targets you don't have.
You can also generate other files, like a HTML with Javascript for clock config outside the compile time limits C++.

The GCLK hardware is structurally fairly consistent among devices. It is present in about half of all SAM controllers. What is different is which clock sources and peripheral clock sinks are available. This information has to be extracted from device data and CMSIS headers. Also, registers often have inconsistent naming but jinja templates can fix that.

The GCLK peripheral consists of clock generators which receive a clock signal and optionally divide it. For every peripheral there is a mux to select which clock generator it connects to:

I have started with getting SAM E5x devices supported and have been facing exactly the same issues as you with the L2x devices. The current GCLK driver code makes a lot of choices that should be left to the user and hard codes information that is different for each SAM device.

I will most likely continue with the SAME5x support this weekend and implement parsing the GCLK clock sources and peripheral channels from manufacturer provided device data. That way it should be easier to make a portable low-level API for configuring the GCLK.

Furthermore, I am working on a common API for enabling the synchronous APB peripheral clocks for both devices with GCLK/MCLK and those with PMC. This will be very similar to the modm STM32 API that has Rcc::enable<SomePeripheral>(). This is required to make drivers portable between devices which share the same peripheral IP but have different bits to enable the bus clocks. For example, this is just hard coded for SAMD21 in the current SERCOM UART driver.

[CrustyAuklet]

Nice to hear, I've used the SAMD21, and several SAML so I wasn't sure how consistent it was into other chip families. I am imagining some declaritive syntax that would make sense to anyone looking at that image from the datasheet that you posted, but I need to spend some time thinking about it. I'll keep an eye on what you come up with, I was planning on starting out with some hand written version but code generation would be much better.

One additional complication with the L series chips is that they have a Performance Level that affects clock speeds and flash latency. I notice in your changes to setFlashLatency() you added a template parameter for the voltage. The L series have 3 parameters: speed, performance level, and voltage.

Also, do you have any thoughts on the Power Manager Peripheral? I don't see any module for it in modm yet. It's mostly power related things, but it also contains the CPU division factor which you would probably want to configure as part of the clock setup process. The performance level stuff for L series is also in the Power Manager.

I have started with getting SAM E5x devices supported and have been facing exactly the same issues as you with the L2x devices. The current GCLK driver code makes a lot of choices that should be left to the user and hard codes information that is different for each SAM device.

Yea, the current implementation works OK for the prototype I am making with the XPlained board. as of now our custom hardware is looking like it will have some tricky clock stuff though. I did add a connect() function to the GCLK for the GCLK_IO pins so I could do some hardware int he loop testing of the clocks configuration.