PWM: Single-phase initialization creates flicker

[chrysn]

Description

The current initialization sequence for PWM is:

• pwm_init(), which sets all values to 0
• pwm_set()

In active-low situations, this creates flickering between the init and the set.

Steps to reproduce the issue

Check out https://github.com/RIOT-OS/RIOT/pull/15115 and run the saul example on an nrf52840 (whose LEDs are wired active-low). In a brief instant, all LEDs are on before going to their natural (per saul_pwm autoinitialization that sets LEDs dark) state.

Roadmap

The API addition I propose to solve this is simple: Introduce pwm_init_poweroff() (pwm_init2? pwm_init_off?) that does the same as init but leaves the device in its poweroff mode. Then, the application can set its initial state, and finally pwm_poweron() to make it actually run.

I hope to do this without introducing a feature that's actually a bug-workaround and will never ever go away again. Thus my initial PR will, unless someone comes up with a better option,

• Add the pwm_init_poweroff function with a documentation comment flagging it as experimental.
• Implement it for platforms I can test it on.
• Replace those platforms' pwm_init() with pwm_init_poweroff(); pwm_poweron() to reduce code duplication.

I'd then issue a call for platform maintainers to follow the changes.

If the new function is not implemented everywhere after a release cycle, we can still put it behind a feature and remove the experimental label; otherwise, the experimental can go when the last platform is merged.

[chrysn]

A follow-up discussion of this could become a more principal one; current driver guides state that

Device drivers should be as easy to use as possible. This implies an 'initialize->ready' paradigm, meaning, that device drivers should be ready to use and in operation right after they have been initialized.

which is not what'd be happening there. On the long run, should we reconsider that paradigm?

[chrysn]

For DAC we probably have the same issue (there, the typical situation is not "it's active low", but "its idle value is 32768" because the output is driving a speaker and supposed to be DC-free on an unbalanced line).