Merge pull request #5856 from scartmell-arm/feature-hal-ticker-free

Add missing free function to lp and us ticker HAL APIs

Author: cmonr

hal/lp_ticker_api.h

@@ -41,6 +41,7 @@ extern "C" {
  *
  * # Undefined behavior
  * * See the @ref hal_ticker_shared "ticker specification"
+ * * Calling any function other than lp_ticker_init after calling lp_ticker_free
  *
  * @see hal_lp_ticker_tests
  *
@@ -112,6 +113,18 @@ void lp_ticker_irq_handler(void);
  */
 void lp_ticker_init(void);
 
+/** Deinitialize the lower power ticker
+ *
+ * Powerdown the lp ticker in preparation for sleep, powerdown, or reset.
+ *
+ * After calling this function no other ticker functions should be called except
+ * lp_ticker_init(). Calling any function other than init after freeing is
+ * undefined.
+ *
+ * @note This function stops the ticker from counting.
+ */
+void lp_ticker_free(void);
+
 /** Read the current tick
  *
  * If no rollover has occurred, the seconds passed since lp_ticker_init()

hal/us_ticker_api.h

@@ -78,6 +78,7 @@ extern "C" {
  * * Calling any function other than ticker_init before the initialization of the ticker
  * * Whether ticker_irq_handler is called a second time if the time wraps and matches the value set by ticker_set_interrupt again
  * * Calling ticker_set_interrupt with a value that has more than the supported number of bits
+ * * Calling any function other than us_ticker_init after calling us_ticker_free
  *
  * # Potential bugs
  * * Drift due to reschedule - Verified by ::ticker_repeat_reschedule_test
@@ -161,7 +162,18 @@ void us_ticker_irq_handler(void);
  */
 void us_ticker_init(void);
 
-/** Read the current tick
+/** Deinitialize the us ticker
+ *
+ * Powerdown the us ticker in preparation for sleep, powerdown, or reset.
+ *
+ * After this function is called, no other ticker functions should be called
+ * except us_ticker_init(), calling any function other than init is undefined.
+ *
+ * @note This function stops the ticker from counting.
+ */
+void us_ticker_free(void);
+
+/** Read the current counter
  *
  * Read the current counter value without performing frequency conversions.
  * If no rollover has occurred, the seconds passed since us_ticker_init()
@@ -230,7 +242,7 @@ void us_ticker_disable_interrupt(void);
 void us_ticker_clear_interrupt(void);
 
 /** Set pending interrupt that should be fired right away.
- * 
+ *
  * The ticker should be initialized prior calling this function.
  *
  * Pseudo Code:

targets/TARGET_NORDIC/TARGET_NRF5/lp_ticker.c

@@ -24,6 +24,12 @@ void lp_ticker_init(void)
     common_rtc_init();
 }
 
+void lp_ticker_free(void)
+{
+    // A common counter is used for RTC, lp_ticker and us_ticker, so it can't be
+    // disabled here, but this does not cause any extra cost.
+}
+
 uint32_t lp_ticker_read()
 {
     return (uint32_t)common_rtc_64bit_us_get();

targets/TARGET_NORDIC/TARGET_NRF5/us_ticker.c

@@ -259,6 +259,12 @@ void us_ticker_init(void)
     common_rtc_init();
 }
 
+void us_ticker_free(void)
+{
+    // A common counter is used for RTC, lp_ticker and us_ticker, so it can't be
+    // disabled here, but this does not cause any extra cost.
+}
+
 uint32_t us_ticker_read()
 {
     us_ticker_init();