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