periph/pwm: support for PWM extension API

[gschorcht]

Contribution description

This is an implementation of the extension API as proposed in #9582 for PWM extensions. It corresponds to the implementation of the GPIO extension API in #9860 and #9958. The PR contains the following contributions:

• Low level function prototypes pwm_*_ll in drivers/include/periph.h.
• Changes of pwm_* functions to redirect a function call either to the low level functions pwm_*_ll or to the pwm_ext_* function provided by an PWM extension device driver.
• Changes of low level function pwm_*_ll for all CPUs that support PWM devices.

The PWM extension API does not require feature periph_pwm which makes it possible to extend boards that do not provide PWM capabilities by the MCU by external PWM modules.

Testing procedure

A test case is provided that implements a soft-driver for the PWM extension interface. The test case uses this driver to confirm that interception and redirection of the API call are working properly. This has been tested and is working properly on esp8266-esp-12x, esp32-wroom-32 and arduino-mega2560.

To test only the PWM extension API use

make  flash test -C tests/extend_pwm BOARD=...

To test the PWM extension API together with internal PWM channels use

USEMODULE=periph_pwm make  flash test -C tests/extend_pwm BOARD=...

In that case feature periph_pwm is required of course.

Issues/PRs references

Implements #9582
Corresponds to #9860 and #9958

The changes in the makefiles/pseudomodules.mk and in drivers/Makefile.include made to get it working are the same as in #9958. These changes might be removed once #9958 is merged.

PR #10556 provides a working PWM extension driver that use the PWM extension API and serves as a proof of concept.

[leandrolanzieri]

Nice implementation. Just those comments. I ran the provided test in nucleo-f091rc and works as intended.

[leandrolanzieri]

On error 0 should be returned.

Suggested change

	return -1;
	return 0;

[gschorcht]

Yes, of course. Thanks.

[leandrolanzieri]

Should we only keep the definition of PWM_EXT_NUMOF if MODULE_EXTEND_PWM is not defined, instead of having it both here and in drivers/include/extend/pwm.h? Like:

#ifndef PWM_EXT_NUMOF
#if !(MODULE_EXTEND_PWM)
#define PWM_EXT_NUMOF       (0U)
#endif
#endif

[gschorcht]

Ok, I just placed it also in drivers/include/periph/pwm.h to avoid wrong definitions if someone includes drivers/include/periph/pwm.h before drivers/include/extend/pwm.h.

[ZetaR60]

This should be placed only in periph/pwm.h because it is included by extend/pwm.h, which means that periph/pwm.h is always loaded first.

Also, needs to be something like:

#ifndef PWM_EXT_NUMOF
#if MODULE_EXTEND_PWM
#define PWM_EXT_NUMOF    (sizeof(pwm_ext_list) / sizeof(pwm_ext_list[0]))
#else
#define PWM_EXT_NUMOF    (0U)
#endif /* MODULE_EXTEND_PWM */
#endif /* PWM_EXT_NUMOF */

[gschorcht]

@leandrolanzieri Thank you for reviewing and testing.

[ZetaR60]

Looks good. atmega_common is missing the _ll functions though.

[ZetaR60]

Please mark your #endifs with a comment after when you have nested #ifs: #endif /* MODULE_PERIPH_PWM */. This will make it much easier to read.

[gschorcht]

yes, of course.

[ZetaR60]

Explicitly referencing the test is no longer necessary. If ./tests/01-run.py exists, then it will be used.

[ZetaR60]

Clarification on waiting for PR: This is waiting on approval of the methods outlined in #9582 via the approval by a senior maintainer of this or any of the other extension API PRs: #9860 + #9958, or #10512, #10527, #10533. They are all identical in method, and have only minor differences in implementation. As a split PR #9860 and #9958 are intended to make this easier.

[gschorcht]

@ZetaR60

atmega_common is missing the _ll functions though.

I don't know why atmega_common does not implement PWM peripherals. Each Arduino board has PWM channels.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.