Add documentation for LP_TICKER defines

They're now potentially useful, so document them as per the US_TICKER
defines.

Author: kjbracey

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

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.
+
  * @{
  */
 

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.
  *