doc: Rewrite clocks and timing sections

The recent work with k_timeout_t has invalidated much of the existing
timing documentation.  Rewrite the section focusing on the new API,
adding details on the internals and driver-facing API.  Includes a
porting guide for legacy applications and subsystems.

Signed-off-by: Andy Ross <andrew.j.ross@intel.com>