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,20 @@ 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 16 bits or less.
+ *
+ * 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.
+
  * @{
  */