Merge pull request #772 from kjbracey-arm/timer64

Update Timer and related for precision + power

Author: Amanda Butler

docs/api/drivers/TimeOut.md

@@ -8,12 +8,12 @@ You can create any number of Timeout objects, allowing multiple outstanding inte
 
 ### Warnings and notes
 
-* Timers are based on 32-bit int microsecond counters, so they can only time up to a maximum of 2^31-1 microseconds (30 minutes). They are designed for times between microseconds and seconds. For longer times, you should consider the time() real time clock.
-
 * No blocking code in ISR: avoid any call to wait, infinite while loop or blocking calls in general.
 
 * No printf, malloc or new in ISR: Avoid any call to bulky library functions. In particular, certain library functions (such as printf, malloc and new) are not re-entrant, and their behavior could be corrupted when called from an ISR.
 
+* While a Timeout is running, deep sleep is blocked to maintain accurate timing. If you don't need microsecond precision, consider using the LowPowerTimeout class instead because this does not block deep sleep mode.
+
 ### Timeout class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](http://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_timeout.html)

docs/api/drivers/Timer.md

@@ -1,10 +1,15 @@
 ## Timer
 
-Use the Timer interface to create, start, stop and read a timer for measuring small times (between microseconds and seconds).
+<span class="images">![](https://os-doc-builder.test.mbed.com/docs/development/mbed-os-api-doxy/classmbed_1_1_timer.png)<span>Timer class hierarchy</span></span>
+
+Use the Timer interface to create, start, stop and read a timer for measuring precise times (better than millisecond precision).
 
 You can independently create, start and stop any number of Timer objects.
 
-<span class="notes">**Note:** Timers are based on 32-bit int microsecond counters, so they can only time up to a maximum of 2^31-1 microseconds (30 minutes). They are designed for times between microseconds and seconds. For longer times, use the `time()` real time clock.</span>
+### Warnings and notes
+
+- Timers are based on 64-bit unsigned microsecond counters, but for backward compatibility, the `read_ms()` and `read_us()` methods only return 32-bit signed integers. This limits their range before wrapping to 49 days and 35 minutes respectively. Use `read_high_resolution_us()` to access the full range of over 500,000 years.
+- While a Timer is running, deep sleep is blocked to maintain accurate timing. If you don't need microsecond precision, consider using the LowPowerTimer class instead because this does not block deep sleep mode.
 
 ### Timer class reference