1 /******************************************************************************
2 *  Filename:       timer_doc.h
3 *
4 *  Copyright (c) 2015 - 2022, Texas Instruments Incorporated
5 *  All rights reserved.
6 *
7 *  Redistribution and use in source and binary forms, with or without
8 *  modification, are permitted provided that the following conditions are met:
9 *
10 *  1) Redistributions of source code must retain the above copyright notice,
11 *     this list of conditions and the following disclaimer.
12 *
13 *  2) Redistributions in binary form must reproduce the above copyright notice,
14 *     this list of conditions and the following disclaimer in the documentation
15 *     and/or other materials provided with the distribution.
16 *
17 *  3) Neither the name of the ORGANIZATION nor the names of its contributors may
18 *     be used to endorse or promote products derived from this software without
19 *     specific prior written permission.
20 *
21 *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 *  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 *  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 *  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25 *  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 *  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 *  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 *  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 *  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 *  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 *  POSSIBILITY OF SUCH DAMAGE.
32 *
33 ******************************************************************************/
34 //! \addtogroup timer_api
35 //! @{
36 //! \section sec_timer Introduction
37 //!
38 //! The timer API provides a set of functions for using the general-purpose timer module.
39 //!
40 //! The timer module contains four timer blocks with the following functional options:
41 //! - Operating modes:
42 //!   - 16-bit with 8-bit prescaler or 32-bit programmable one-shot timer.
43 //!   - 16-bit with 8-bit prescaler or 32-bit programmable periodic timer.
44 //!   - Two capture compare PWM pins (CCP) for each 32-bit timer.
45 //!   - 24-bit input-edge count or 24-bit time-capture modes.
46 //!   - 24-bit PWM mode with software-programmable output inversion of the PWM signal.
47 //!   - Count up or down.
48 //! - Daisy chaining of timer modules allows a single timer to initiate multiple timing events.
49 //! - Timer synchronization allows selected timers to start counting on the same clock cycle.
50 //! - User-enabled stalling when the System CPU asserts a CPU Halt flag during debug.
51 //! - Ability to determine the elapsed time between the assertion of the timer interrupt and
52 //!   entry into the interrupt service routine.
53 //!
54 //! Each timer block provides two half-width timers/counters that can be configured
55 //! to operate independently as timers or event counters or to operate as a combined
56 //! full-width timer.
57 //! The timers provide 16-bit half-width timers and a 32-bit full-width timer.
58 //! For the purposes of this API, the two
59 //! half-width timers provided by a timer block are referred to as TimerA and
60 //! TimerB, and the full-width timer is referred to as TimerA.
61 //!
62 //! When in half-width mode, the timer can also be configured for event capture or
63 //! as a pulse width modulation (PWM) generator. When configured for event
64 //! capture, the timer acts as a counter. It can be configured to count either the
65 //! time between events or the events themselves. The type of event
66 //! being counted can be configured as a positive edge, a negative edge, or both
67 //! edges. When a timer is configured as a PWM generator, the input signal used to
68 //! capture events becomes an output signal, and the timer drives an
69 //! edge-aligned pulse onto that signal.
70 //!
71 //! Control is also provided over interrupt sources and events. Interrupts can be
72 //! generated to indicate that an event has been captured, or that a certain number
73 //! of events have been captured. Interrupts can also be generated when the timer
74 //! has counted down to 0 or when the timer matches a certain value.
75 //!
76 //! Timer configuration is handled by \ref TimerConfigure(), which performs the high
77 //! level setup of the timer module; that is, it is used to set up full- or
78 //! half-width modes, and to select between PWM, capture, and timer operations.
79 //!
80 //! \section sec_timer_api API
81 //!
82 //! The API functions can be grouped like this:
83 //!
84 //! Functions to perform timer control:
85 //! - \ref TimerConfigure()
86 //! - \ref TimerEnable()
87 //! - \ref TimerDisable()
88 //! - \ref TimerLevelControl()
89 //! - \ref TimerWaitOnTriggerControl()
90 //! - \ref TimerEventControl()
91 //! - \ref TimerStallControl()
92 //! - \ref TimerIntervalLoadMode()
93 //! - \ref TimerMatchUpdateMode()
94 //! - \ref TimerCcpCombineDisable()
95 //! - \ref TimerCcpCombineEnable()
96 //!
97 //! Functions to manage timer content:
98 //! - \ref TimerLoadSet()
99 //! - \ref TimerLoadGet()
100 //! - \ref TimerPrescaleSet()
101 //! - \ref TimerPrescaleGet()
102 //! - \ref TimerMatchSet()
103 //! - \ref TimerMatchGet()
104 //! - \ref TimerPrescaleMatchSet()
105 //! - \ref TimerPrescaleMatchGet()
106 //! - \ref TimerValueGet()
107 //! - \ref TimerSynchronize()
108 //!
109 //! Functions to manage the interrupt handler for the timer interrupt:
110 //! - \ref TimerIntRegister()
111 //! - \ref TimerIntUnregister()
112 //!
113 //! The individual interrupt sources within the timer module are managed with:
114 //! - \ref TimerIntEnable()
115 //! - \ref TimerIntDisable()
116 //! - \ref TimerIntStatus()
117 //! - \ref TimerIntClear()
118 //!
119 //! @}
120