PmwOut: Add method to enable/disable PWM

[hugueskamba]

Description

It is now possible to temporarily suspend PWM and safely preserve the duty
cycle set. This functionality is needed to allow a device to enter deep
sleep as a PWM instance prevents deep sleep in order for the timer it
relies on to run so its output can be modified. The duty cycle configuration
can be restored upon resuming from deep sleep.

Pull request type

[X] Fix
[ ] Refactor
[ ] Target update
[ ] Functionality change
[ ] Docs update
[ ] Test update
[ ] Breaking change

Reviewers

@evedon @bulislaw @kjbracey-arm

Release Notes

[bulislaw]

Do we actually need to pwmout_free to free the HW (and then to restore the state)? I'm not sure what will happen with HW state if the high frequency clock would go down and also HW may limit the low power state based on active HW.

[hugueskamba]

#11641 (comment)

[ciarmcom]

@hugueskamba, thank you for your changes.
@bulislaw @kjbracey-arm @evedon @ARMmbed/mbed-os-core @ARMmbed/mbed-os-maintainers please review.

[hugueskamba]

This force-push splits the previously introduced method (PwmOut::enable_pwm) into PwmOut::suspend and PwmOut::resume as they are more user friendly.
The new PwmOut::suspend method powers down the PWM hardware and saves the duty cycle set so the PwmOut::resume is able to restore it.
The deep sleep lock is also now acquired on object instantiation instead of just when PwmOut::write method is called. This has the benefit of ensuring the PWM output is modified if PwmOut::pulsewidth (or its variants) is used instead of PwmOut::write.

[bulislaw]

Looks good. Not related to this PR but this class forces users to use floats 😞

[hugueskamba]

This force-push explicitly mentions that calls prior to resume after suspend are undefined behaviour?

[kjbracey]

Looks good. Not related to this PR but this class forces users to use floats

Not in this case - there are integer versions of both float calls, and they don't go through the float.

[evedon]

We also need to add greentea tests (is there an existing test suite that can be expanded)?

[hugueskamba]

We also need to add greentea tests (is there an existing test suite that can be expanded)?

@evedon

There is no PWM test that I could find test except for https://github.com/ARMmbed/mbed-os/tree/master/TESTS/mbed_hal_fpga_ci_test_shield/pwm

[hugueskamba]

This force-push fixes the Doxygen spelling error.

[0xc0170]

There now PWM test that I could find test except for https://github.com/ARMmbed/mbed-os/tree/master/TESTS/mbed_hal_fpga_ci_test_shield/pwm

Shall we add there new test cases to test resume/suspend?

[hugueskamba]

There now PWM test that I could find test except for https://github.com/ARMmbed/mbed-os/tree/master/TESTS/mbed_hal_fpga_ci_test_shield/pwm

Shall we add there new test cases to test resume/suspend?

That test file is for testing the hal layer. The change is in the driver level.

[0xc0170]

There is no test for the driver layer?

[0xc0170]

I run CI meanwhile

[hugueskamba]

This force-push adds unit test cases for the constructor and the destructor.

[evedon]

Thanks for the changes.
It might have been easier to use the framework to clear the expectations before the test starts but this works as well.

[0xc0170]

CI started

[mbed-ci]

Test run: SUCCESS

Summary: 11 of 11 test jobs passed
Build number : 3
Build artifacts