From 387f2f9f6964640f95aea2d7a9fb6ca144cca58d Mon Sep 17 00:00:00 2001 From: Alrik Vidstrom Date: Mon, 29 Apr 2024 10:38:52 +0200 Subject: [PATCH 1/7] Improve template function Doxygen documentation Adds one declaration for Doxygen and another for the compiler. Plus improves a bit on the documentation. --- src/Arduino_LowPowerPortentaH7.h | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/src/Arduino_LowPowerPortentaH7.h b/src/Arduino_LowPowerPortentaH7.h index 2bdfd7d..edcc214 100644 --- a/src/Arduino_LowPowerPortentaH7.h +++ b/src/Arduino_LowPowerPortentaH7.h @@ -325,18 +325,27 @@ class LowPowerPortentaH7 { */ LowPowerReturnCode standbyM4() const; + // This is the variant that the compiler will see and use + /// @cond DEV + template + typename std::enable_if::value, + LowPowerReturnCode>::type + standbyM7(const T standbyType, const Args... args) const; + /// @endcond + // This is the simplified variant that Doxygen will see and use + // Notice that VISIBLE_ONLY_TO_DOXYGEN isn't defined anywhere - it doesn't + // have to be since Doxygen is configured with ENABLE_PREPROCESSING NO + #ifdef VISIBLE_ONLY_TO_DOXYGEN /** * @brief Make the M7 core enter Standby Mode. * @param standbyType One or a combination of LowPowerStandbyType::untilPinActivity * and LowPowerStandbyType::untilTimeElapsed. The combination is done with the | operator. - * @param args The delay before waking up again + * @param args An optional delay before waking up again, if LowPowerStandbyType::untilTimeElapsed is used. * @return A constant from the LowPowerReturnCode enum. */ - template - typename std::enable_if::value, - LowPowerReturnCode>::type - standbyM7(const T standbyType, const Args... args) const; - + LowPowerReturnCode standbyM7(const T standbyType, const Args... args) const; + #endif + /** * @brief Time since the board was booted. * It reports the time since the last wake-up reset (after being in Standby Mode) @@ -436,6 +445,7 @@ LowPowerStandbyType::UntilEitherClass operator|( ******************************************************************************** */ +/// @cond DEV template typename std::enable_if::value, LowPowerReturnCode>::type @@ -687,5 +697,6 @@ LowPowerPortentaH7::standbyM7(const T standbyType, return LowPowerReturnCode::m7StandbyFailed; } +/// @endcond #endif // End of header guard From 8d0029c5968cde87f3e4147fe009be986ed3eb1d Mon Sep 17 00:00:00 2001 From: Alrik Vidstrom Date: Wed, 8 May 2024 17:00:26 +0200 Subject: [PATCH 2/7] Add option to not turn off Ethernet This option is added for libraries that turn off the rail that powers the Ethernet chip. --- src/Arduino_LowPowerPortentaH7.h | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/Arduino_LowPowerPortentaH7.h b/src/Arduino_LowPowerPortentaH7.h index edcc214..a51c8b5 100644 --- a/src/Arduino_LowPowerPortentaH7.h +++ b/src/Arduino_LowPowerPortentaH7.h @@ -312,7 +312,7 @@ class LowPowerPortentaH7 { */ [[deprecated("This function is experimental and should not be used in production code")]] uint16_t numberOfDeepSleepLocks() const; - + /** * @brief Prepare the option bytes for entry into Standby Mode. * @return A constant from the LowPowerReturnCode enum. @@ -463,11 +463,18 @@ LowPowerPortentaH7::standbyM7(const T standbyType, // otherwise, the Ethernet transmit termination resistors will overheat // from the voltage that gets applied over them. It would be 125 mW in each // of them, while they are rated at 50 mW. If we fail to turn off Ethernet, - // we must not proceed. + // we must not proceed. If this library is used with another library that + // turns off the rail that powers the Ethernet chip before calling this + // function, that library should #define NO_ETHERNET_TURN_OFF, or entering + // Standby Mode will fail. Anyone who defines that constant takes + // responsibility for not overheating the resistors. It is NOT part of the + // API intended for ordinary users. + #ifndef NO_ETHERNET_TURN_OFF if (false == turnOffEthernet()) { return LowPowerReturnCode::turningOffEthernetFailed; } + #endif // Prevent Mbed from changing things core_util_critical_section_enter(); From 9d7f49bc8d497c4597059bda9e4186029004949e Mon Sep 17 00:00:00 2001 From: Alrik Vidstrom Date: Wed, 8 May 2024 17:04:26 +0200 Subject: [PATCH 3/7] Fix two incorrect comments 1. Typo where M7 should be M4. 2. Incorrect comment, because the flags are not just for standby --- src/Arduino_LowPowerPortentaH7.cpp | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/Arduino_LowPowerPortentaH7.cpp b/src/Arduino_LowPowerPortentaH7.cpp index 70e22d5..ada2699 100644 --- a/src/Arduino_LowPowerPortentaH7.cpp +++ b/src/Arduino_LowPowerPortentaH7.cpp @@ -233,7 +233,7 @@ bool LowPowerPortentaH7::wasInCPUMode(CPUMode mode) const void LowPowerPortentaH7::resetPreviousCPUModeFlags() const { - PWR->CPUCR |= PWR_CPUCR_CSSF; // Clear standby flags + PWR->CPUCR |= PWR_CPUCR_CSSF; } uint16_t LowPowerPortentaH7::numberOfDeepSleepLocks() const @@ -312,7 +312,7 @@ LowPowerReturnCode LowPowerPortentaH7::standbyM4() const // <-- // Disable and clear all pending interrupts in the NVIC. There are 8 - // registers in the Cortex-M7. + // registers in the Cortex-M4. for (auto i = 0; i < 8; i++) { NVIC->ICER[i] = 0xffffffff; From 0f9ac3e1fc6d4b25bbc240e1ebef8272bdefc054 Mon Sep 17 00:00:00 2001 From: Alrik Vidstrom Date: Wed, 8 May 2024 17:08:33 +0200 Subject: [PATCH 4/7] Improve Standby Mode example Adds how to go into Standby Mode waiting for only a wakeup pin. --- examples/Standby/Standby.ino | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/examples/Standby/Standby.ino b/examples/Standby/Standby.ino index 5e5af03..b39391f 100644 --- a/examples/Standby/Standby.ino +++ b/examples/Standby/Standby.ino @@ -127,8 +127,13 @@ void setup() { #if defined CORE_CM7 LowPower.standbyM7(LowPowerStandbyType::untilPinActivity | LowPowerStandbyType::untilTimeElapsed, 10_s); - // The following is an alternative way to go into standby for 10 seconds + // + // The following is an alternative way to go into Standby Mode for 10 seconds: // LowPower.standbyM7(LowPowerStandbyType::untilTimeElapsed, RTCWakeupDelay(0, 0, 10)); + // + // The following is how to go to into Standby Mode waiting only for a wakeup pin: + // LowPower.standbyM7(LowPowerStandbyType::untilPinActivity); + // #else LowPower.standbyM4(); #endif From c4cce7aef4a2f91d2df194bdf73c765c56670cae Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Wed, 8 May 2024 15:10:12 +0000 Subject: [PATCH 5/7] Update documentation --- docs/api.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/api.md b/docs/api.md index 3a98072..729bbe6 100644 --- a/docs/api.md +++ b/docs/api.md @@ -28,7 +28,7 @@ This class is specific to the Portenta H7 board. | [`numberOfDeepSleepLocks`](#class_low_power_portenta_h7_1a9d2730d86abf42782261b0f03778c3bb) | Check how many Deep Sleep locks are held at the moment. | | [`prepareOptionBytes`](#class_low_power_portenta_h7_1abdc0ce13b68d3a2188702690997af2ae) | Prepare the option bytes for entry into Standby Mode. | | [`standbyM4`](#class_low_power_portenta_h7_1a9e07fd4f7895a7753e7e28f99aca1ace) | Make the M4 core enter Standby Mode. | -| [`standbyM7`](#class_low_power_portenta_h7_1a1eb5cec6e9604a48074f1c10ef5e7fb0) | Make the M7 core enter Standby Mode. | +| [`standbyM7`](#class_low_power_portenta_h7_1aa9c1cb86c832c35f6653a3d6c9f0d32f) | Make the M7 core enter Standby Mode. | | [`timeSinceBoot`](#class_low_power_portenta_h7_1a4758c25574b6d099545ac8d55eff6f68) | Time since the board was booted. It reports the time since the last wake-up reset (after being in Standby Mode) or power-on depending on what happened last. | | [`timeSpentIdle`](#class_low_power_portenta_h7_1ad42fdfa6885d8e0fdca5aa012fdb4c60) | Time spent in idle. | | [`timeSpentInSleep`](#class_low_power_portenta_h7_1a994eb6fcc0382515a82b81fa37ca9f3c) | Time spent in Sleep Mode. | @@ -130,10 +130,10 @@ Make the M4 core enter Standby Mode. A constant from the LowPowerReturnCode enum.
-### `standbyM7` +### `standbyM7` ```cpp -template<> std::enable_if< ArgumentsAreCorrect< T, Args... >::value, LowPowerReturnCode >::type standbyM7(const T standbyType, const Args... args) const +LowPowerReturnCode standbyM7(const T standbyType, const Args... args) const ``` Make the M7 core enter Standby Mode. @@ -141,7 +141,7 @@ Make the M7 core enter Standby Mode. #### Parameters * `standbyType` One or a combination of [LowPowerStandbyType::untilPinActivity](#class_low_power_standby_type_1a4c5b50ac615cf60ff88dd3b9bb145fa9) and [LowPowerStandbyType::untilTimeElapsed](#class_low_power_standby_type_1aa4882e571c0e9444c5978c8520e8e90e). The combination is done with the | operator. -* `args` The delay before waking up again +* `args` An optional delay before waking up again, if [LowPowerStandbyType::untilTimeElapsed](#class_low_power_standby_type_1aa4882e571c0e9444c5978c8520e8e90e) is used. #### Returns A constant from the LowPowerReturnCode enum. From 47038946b78c1e77c017130fd8c13efbc3933292 Mon Sep 17 00:00:00 2001 From: alrvid <126816223+alrvid@users.noreply.github.com> Date: Wed, 8 May 2024 17:54:59 +0200 Subject: [PATCH 6/7] Change #define name Co-authored-by: Sebastian Romero --- src/Arduino_LowPowerPortentaH7.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Arduino_LowPowerPortentaH7.h b/src/Arduino_LowPowerPortentaH7.h index a51c8b5..1325b65 100644 --- a/src/Arduino_LowPowerPortentaH7.h +++ b/src/Arduino_LowPowerPortentaH7.h @@ -333,7 +333,7 @@ class LowPowerPortentaH7 { standbyM7(const T standbyType, const Args... args) const; /// @endcond // This is the simplified variant that Doxygen will see and use - // Notice that VISIBLE_ONLY_TO_DOXYGEN isn't defined anywhere - it doesn't + // Notice that DOXYGEN_ONLY isn't defined anywhere - it doesn't // have to be since Doxygen is configured with ENABLE_PREPROCESSING NO #ifdef VISIBLE_ONLY_TO_DOXYGEN /** From 7a13c7377fcda0681dc1a2710a60f7814674f0a2 Mon Sep 17 00:00:00 2001 From: alrvid <126816223+alrvid@users.noreply.github.com> Date: Wed, 8 May 2024 17:58:31 +0200 Subject: [PATCH 7/7] Change #define name Co-authored-by: Sebastian Romero --- src/Arduino_LowPowerPortentaH7.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/Arduino_LowPowerPortentaH7.h b/src/Arduino_LowPowerPortentaH7.h index 1325b65..ffb5d28 100644 --- a/src/Arduino_LowPowerPortentaH7.h +++ b/src/Arduino_LowPowerPortentaH7.h @@ -335,7 +335,7 @@ class LowPowerPortentaH7 { // This is the simplified variant that Doxygen will see and use // Notice that DOXYGEN_ONLY isn't defined anywhere - it doesn't // have to be since Doxygen is configured with ENABLE_PREPROCESSING NO - #ifdef VISIBLE_ONLY_TO_DOXYGEN + #ifdef DOXYGEN_ONLY /** * @brief Make the M7 core enter Standby Mode. * @param standbyType One or a combination of LowPowerStandbyType::untilPinActivity