Timers
******

This section is aimed to provide users an overview on available timers, timer usage, 
and availability across various power states.

.. _timer-overview:
.. table:: Timer Overview

    +-----------------------+--------------------------------------------------------+-------------------+
    | **Timer**             | **Availability in Power Mode**                         | **Resolution**    |
    +=======================+========================================================+===================+
    | General Purpose Timer | Available in Active mode and Idle mode.                | (1/48)us          |
    +-----------------------+--------------------------------------------------------+-------------------+
    | Watchdog Timer        | Available in Active mode, Idle mode, and Standby mode. | (1/32)us          |
    +-----------------------+--------------------------------------------------------+-------------------+
    | System Timer          | Available in Active mode and Idle mode.                | 1us or 250ns      |
    +-----------------------+--------------------------------------------------------+-------------------+
    | Real-Time Clock       | Available in Active mode, Idle mode, and Standby mode. | 8us or 524ms      |
    +-----------------------+--------------------------------------------------------+-------------------+
    | Clock DPL             | Available in Active mode, Idle mode, and Standby mode. | 1us               |
    +-----------------------+--------------------------------------------------------+-------------------+
    | FreeRTOS Timer        | Available in Active mode and Idle mode.                | 10ms              |
    +-----------------------+--------------------------------------------------------+-------------------+

Hardware Timers
===============
There are 4 types of HW timer available for the application to use. 

General Purpose Timer (LGPT)
----------------------------
The General Purpose Timer (LGPT) runs off of the High Frequency Clock, which is only available in 
Active or Idle mode. LGPT is often used for high accuracy measurement, timer comparison, 
DMA triggering, PWM, etc. For more information, please refer to the |DEVICE| datasheet.

Watchdog Timer
--------------
The Watchdog Timer is used as a recovery mechanism to regain control.
Upon timer expiration, the |DEVICE| will be reset. Because the |DEVICE| behaves 
differently than previous generations, a workaround is needed to reduce the
power consumption of the Watchdog Timer. The :ref:`watchdog-example-code` 
explains this workaround.

Real-Time Clock (RTC)
---------------------
The RTC is a 2-channel timer (compare channel and capture channel) and runs on
the Low Frequency Clock. The compare channel is used by system software to program
the |DEVICE|'s future wake up time before going into Standby mode.

System Timer (SYSTIM)
---------------------
SYSTIM has 5 channels; 4 channels are reserved by system software and radio
operation. There is only one available for the user. SYSTIM is synchronized to RTC
in hardware.

To get current device timestamp, users should use
ClockP_getSystemTicks() from :ref:`timer-clockp`.

.. attention::
   For more Hardware Timer information, please refer to the |DEVICE| datasheet.
   In general, it is recommended to use :ref:`timer-clockp` if users want to 
   realize the functionality provided by SYSTIM. 

Software Timers
===============

.. _timer-clockp:

ClockP Module
-------------
The ClockP module is developed by Texas Instruments and uses one SYSTIM channel 
with 1 us resolution and is synchronized with the RTC.

ClockP can be used to do the following:

#. Get current timestamp
#. Get CPU clock frequency
#. Periodic timer to trigger periodic task
#. One shot timer to trigger task

.. note::
   To see the available APIs, please navigate to
   ``<SDK_INSTALL_DIR>/source/ti/drivers/dpl/ClockP.h``

FreeRTOS Timer
--------------
FreeRTOS has its own timer module. For more information, please refer to: |FreeRTOS SOFTWARE TIMERS|
