From 6423633122aa0df94fde41fcfd8bf609be354e98 Mon Sep 17 00:00:00 2001
From: Kevin Bracey <kevin.bracey@arm.com>
Date: Thu, 30 Apr 2020 10:51:27 +0300
Subject: [PATCH] Add documentation for LP_TICKER defines

They're now potentially useful, so document them as per the US_TICKER
defines.
---
 hal/include/hal/lp_ticker_api.h             | 16 ++++++++++++++++
 hal/include/hal/us_ticker_api.h             |  2 +-
 hal/tests/TESTS/mbed_hal/lp_ticker/main.cpp |  6 ++++++
 3 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/hal/include/hal/lp_ticker_api.h b/hal/include/hal/lp_ticker_api.h
index aecaf8ac4a..82a67b7dd1 100644
--- a/hal/include/hal/lp_ticker_api.h
+++ b/hal/include/hal/lp_ticker_api.h
@@ -49,6 +49,22 @@ extern "C" {
  *
  * @see hal_lp_ticker_tests
  *
+ * # Compile-time optimization macros
+ *
+ * To permit compile-time optimization, the following macros can be defined by a target's device.h:
+ *
+ * LP_TICKER_PERIOD_NUM, LP_TICKER_PERIOD_DEN: These denote the ratio (numerator, denominator)
+ * of the ticker period to a microsecond. For example, a 64kHz ticker would have NUM = 125, DEN = 8;
+ * a 4kHz ticker would have NUM = 250, DEN = 1; a 32.768kHz ticker would have NUM = 15625, DEN = 512.
+ * Both numerator and denominator must be 32 bits or less. They do not need to be fully simplified,
+ * so 32.768kHz could also be NUM = 1000000, DEN = 32768, but more simplification may be a minor
+ * speed optimisation, as can matching numerator or denominator with US_TICKER.
+ *
+ * LP_TICKER_MASK: The value mask for the ticker - eg 0x07FFFFFF for a 27-bit ticker.
+ *
+ * If any are defined, all 3 must be defined, and the macros are checked for consistency with
+ * lp_ticker_get_info by test ::lp_ticker_info_test.
+
  * @{
  */
 
diff --git a/hal/include/hal/us_ticker_api.h b/hal/include/hal/us_ticker_api.h
index ecfa712bb9..f793e87858 100644
--- a/hal/include/hal/us_ticker_api.h
+++ b/hal/include/hal/us_ticker_api.h
@@ -50,7 +50,7 @@ extern "C" {
  * US_TICKER_PERIOD_NUM, US_TICKER_PERIOD_DEN: These denote the ratio (numerator, denominator)
  * of the ticker period to a microsecond. For example, an 8MHz ticker would have NUM = 1, DEN = 8;
  * a 1MHz ticker would have NUM = 1, DEN = 1; a 250kHz ticker would have NUM = 4, DEN = 1.
- * Both numerator and denominator must be 16 bits or less.
+ * Both numerator and denominator must be 16 bits or less, but need not be fully simplified.
  *
  * US_TICKER_MASK: The value mask for the ticker - eg 0x07FFFFFF for a 27-bit ticker.
  *
diff --git a/hal/tests/TESTS/mbed_hal/lp_ticker/main.cpp b/hal/tests/TESTS/mbed_hal/lp_ticker/main.cpp
index 7331edf9e9..43f8e39cdd 100644
--- a/hal/tests/TESTS/mbed_hal/lp_ticker/main.cpp
+++ b/hal/tests/TESTS/mbed_hal/lp_ticker/main.cpp
@@ -110,6 +110,12 @@ void lp_ticker_info_test()
     TEST_ASSERT(p_ticker_info->frequency >= 4000);
     TEST_ASSERT(p_ticker_info->frequency <= 64000);
     TEST_ASSERT(p_ticker_info->bits >= 12);
+
+#ifdef LP_TICKER_PERIOD_NUM
+    TEST_ASSERT_UINT32_WITHIN(1, 1000000 * LP_TICKER_PERIOD_DEN / LP_TICKER_PERIOD_NUM, p_ticker_info->frequency);
+    TEST_ASSERT_EQUAL_UINT32(LP_TICKER_MASK, ((uint64_t)1 << p_ticker_info->bits) - 1);
+#endif
+
 }
 
 #if DEVICE_SLEEP