iLLD_TC27xC  1.0
IfxGtm_Tom_Timer.h
Go to the documentation of this file.
1 /**
2  * \file IfxGtm_Tom_Timer.h
3  * \brief _TOM TIMER details
4  * \ingroup IfxLld_Gtm
5  *
6  * \version iLLD_0_1_0_10
7  * \copyright Copyright (c) 2013 Infineon Technologies AG. All rights reserved.
8  *
9  *
10  * IMPORTANT NOTICE
11  *
12  *
13  * Infineon Technologies AG (Infineon) is supplying this file for use
14  * exclusively with Infineon's microcontroller products. This file can be freely
15  * distributed within development tools that are supporting such microcontroller
16  * products.
17  *
18  * THIS SOFTWARE IS PROVIDED "AS IS". NO WARRANTIES, WHETHER EXPRESS, IMPLIED
19  * OR STATUTORY, INCLUDING, BUT NOT LIMITED TO, IMPLIED WARRANTIES OF
20  * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE APPLY TO THIS SOFTWARE.
21  * INFINEON SHALL NOT, IN ANY CIRCUMSTANCES, BE LIABLE FOR SPECIAL, INCIDENTAL,
22  * OR CONSEQUENTIAL DAMAGES, FOR ANY REASON WHATSOEVER.
23  *
24  * \defgroup IfxLld_Gtm_Tom_Timer_Usage How to use the GTM TOM Timer Driver
25  * \ingroup IfxLld_Gtm_Tom_Timer
26  *
27  * This driver implements the timer functionalities as defined by \ref library_srvsw_stdif_timer.
28  * The user is free to use either the driver specific APIs below or to used the \ref library_srvsw_stdif_timer "standard interface APIs".
29  *
30  * \section specific Specific Implementation
31  * The timer fucntinality is implemented using either a single or 2 TOM channels. The dicision to use 1 or 2 channels is done
32  * depending on the following requirements:
33  * - relative position of the timer channel to the other channels used if any
34  * - need to trigger an other module, for example ADC triggering.
35  *
36  * The figure below show how the TOM is \ref IfxGtm_Tom_Timer_Config "configured" when a single TOM channel is used for the timer and trigger functinalities.
37  * The internal trigger signal (red line) is generated when the counter CN0 reach the CM0 compare register. The value of CM0 act as the period value. This internal
38  * trigger is used to reset the CN0 counter and simultaneously transfer the shadow values for the period value (SR0->CM0)
39  * and trigger edge (SR1->CM1). The internal trigger is used as a trigger input to the next TOM channel.
40  * The trigger signal (output trigger) is generated by the CM0 and CM1 compare values. Depending on the trigger signal active
41  * edge \ref IfxGtm_Tom_Timer_Config "configuiration", the CM0 will reset, and the CM1 will set the trigger signal, or vice versa.
42  *
43  * \image html "IfxGtm_Tom_Timer-0.png" "Timer using one signle TOM channel"
44  *
45  * In case 2 TOM channels are used for the timer and trigger functionalities,
46  * the 1st channel (CHz in the figure below) is used for the generation of the period,
47  * and the 2nd channel (CHz+n the below figure, the figure shows n=1 as example) is used for the trigger generation.
48  *
49  * The CHz TOM channel generates the internal trigger signal (red line) when the counter CN0 reach the CM0 compare register.
50  * The value of CM0 of CHz act as the period value. This internal trigger is used to reset the CN0 counter and simultaneously
51  * transfer the shadow period value (SR0->CM0). The internal trigger is used as an input for the next TOM channel.
52  *
53  * The CHz+n TOM channel, uses the internal trigger signal to simultaneously resets the
54  * counter CN0, and transfer the shadow values used for the generation of the trigger falling and rising edges (SR0->CM0 and SR1->CM1).
55  * The internal trigger is used as a trigger input to the next TOM channel.
56  * Depending on the trigger signal active edge \ref IfxGtm_Tom_Timer_Config "configuiration", the CM0 will reset, and the CM1 will set the trigger signal, or vice versa.
57  * In orter to have a similar behaviour to the single channel implementation,
58  * the CM0 is set to the same value as CHz CM0, and CM1 is used for the trigger edge.
59  *
60  * \image html "IfxGtm_Tom_Timer-1.png" "Timer using two different TOM channels for the timer and the trigger"
61  *
62  *
63  * In order to ensure a coherent update of all registers, the internal trigger must be disable before updating
64  * the timer and trigger shadow values, and enabled once the update is done. The transfer will ocucrs at the next timer reset.
65  *
66  * - Resources used:
67  * - if the trigger channel is identical to the timer channel, only one TOM channels is used
68  * - if the trigger channel is different from the timer channel, 2 TOM channels are used
69  * - All channels used must be own by the same TOM and TOM TGC
70  * - The timer counting direction is limited to \ref IfxStdIf_Timer_CountDir_up
71  * - If the TOM trigger channel is not the same as the TOM timer channels
72  * - The TOM channel used for the trigger must have a lower index than the TOM channels
73  * used for the timer.
74  * - the TOM channels must be contiguous, unless specified by the driver using the timer driver.
75  *
76  * For a detailed configuration of the microcontroller, see \ref IfxGtm_Tom_Timer_init().
77  *
78  * \section example Usage example
79  * Initialisation:
80  * \code
81  * IfxGtm_Tom_Timer_Config driverConfig;
82  * IfxGtm_Tom_Timer driverData;
83  * IfxStdIf_Timer timer;
84  * IfxGtm_Tom_Timer_initConfig(&driverConfig, &MODULE_GTM);
85  * IfxGtm_Tom_Timer_init (&driverData, &driverConfig);
86  * boolean IfxGtm_Tom_Timer_stdIfTimerInit(&timer, &driverData);
87  * \endcode
88  *
89  * During run-time, \ref library_srvsw_stdif_timer "the interface functions" should be used:
90  * \code
91  * IfxStdIf_Timer_run(timer);
92  * IfxStdIf_Timer_disableUpdate(timer);
93  * IfxStdIf_Timer_setPeriod(timer, period);
94  * IfxStdIf_Timer_applyUpdate(timer);
95  * \endcode
96  *
97  *
98  *
99  * \defgroup IfxLld_Gtm_Tom_Timer TOM Timer Interface Driver
100  * \ingroup IfxLld_Gtm_Tom
101  * \defgroup IfxLld_Gtm_Tom_Timer_Data_Structures Data Structures
102  * \ingroup IfxLld_Gtm_Tom_Timer
103  * \defgroup IfxLld_Gtm_Tom_Timer_Timer_Functions Timer Functions
104  * \ingroup IfxLld_Gtm_Tom_Timer
105  * \defgroup IfxLld_Gtm_Tom_Timer_Timer_StdIf_Functions Timer StdIf Functions
106  * \ingroup IfxLld_Gtm_Tom_Timer
107  */
108 
109 #ifndef IFXGTM_TOM_TIMER_H
110 #define IFXGTM_TOM_TIMER_H 1
111 
112 /******************************************************************************/
113 /*----------------------------------Includes----------------------------------*/
114 /******************************************************************************/
115 
116 #include "_PinMap/IfxGtm_PinMap.h"
117 #include "Gtm/Std/IfxGtm_Tom.h"
118 #include "Gtm/Std/IfxGtm_Cmu.h"
119 #include "StdIf/IfxStdIf_Timer.h"
120 
121 /******************************************************************************/
122 /*-----------------------------Data Structures--------------------------------*/
123 /******************************************************************************/
124 
125 /** \addtogroup IfxLld_Gtm_Tom_Timer_Data_Structures
126  * \{ */
127 /** \brief Structure for the timer base
128  */
129 typedef struct
130 {
131  Ifx_TimerValue period; /**< \brief Timer period in ticks (cached value) */
132  boolean triggerEnabled; /**< \brief If TRUE, the trigger functionality is Initialised */
133  float32 clockFreq; /**< \brief Timer input clock frequency (cached value) */
134  IfxStdIf_Timer_CountDir countDir; /**< \brief Timer counting mode */
136 
137 /** \} */
138 
139 /** \addtogroup IfxLld_Gtm_Tom_Timer_Data_Structures
140  * \{ */
141 /** \brief TOM Timer interface Handle
142  */
143 typedef struct
144 {
145  IfxGtm_Tom_Timer_Base base; /**< \brief Timer base structure */
146  Ifx_GTM *gtm; /**< \brief Pointer to GTM module */
147  Ifx_GTM_TOM *tom; /**< \brief Pointer to the TOM object */
148  Ifx_GTM_TOM_TGC *tgc; /**< \brief Pointer to the TGC object */
149  IfxGtm_Tom tomIndex; /**< \brief Enum for TOM objects */
150  IfxGtm_Tom_Ch timerChannel; /**< \brief TOM channel used for the timer */
151  IfxGtm_Tom_Ch triggerChannel; /**< \brief TOM channel used for the trigger, can be identical to the timer channel */
152  uint16 channelsMask; /**< \brief Mask for channels to be modified together */
154 
155 /** \brief Configuration structure for TOM Timer
156  */
157 typedef struct
158 {
159  IfxStdIf_Timer_Config base; /**< \brief Standard interface timer configuration */
160  Ifx_GTM *gtm; /**< \brief Pointer to GTM module */
161  IfxGtm_Tom tom; /**< \brief Pointer to the TOM object */
162  IfxGtm_Tom_Ch timerChannel; /**< \brief TOM channel used for the timer */
163  IfxGtm_Tom_ToutMap *triggerOut; /**< \brief TOM channel used for the trigger output, can be identical to the timer channe */
164  IfxGtm_Tom_Ch_ClkSrc clock; /**< \brief Timer input clock */
166 
167 /** \} */
168 
169 /** \addtogroup IfxLld_Gtm_Tom_Timer_Timer_Functions
170  * \{ */
171 
172 /******************************************************************************/
173 /*-------------------------Global Function Prototypes-------------------------*/
174 /******************************************************************************/
175 
176 /** \brief Returns the pointer to timer channel
177  * \param driver TOM Timer interface Handle
178  * \return Pointer
179  */
181 
182 /** \brief Initialises the timer object
183  * \param driver TOM Timer interface Handle
184  * \param config Configuration structure for TOM Timer
185  * \return TRUE on success else FALSE
186  */
188 
189 /** \brief Initializes the configuration structure to default
190  * \param config Configuration structure for TOM Timer
191  * \param gtm Pointer to GTM module
192  * \return None
193  */
195 
196 /** \} */
197 
198 /** \addtogroup IfxLld_Gtm_Tom_Timer_Timer_StdIf_Functions
199  * \{ */
200 
201 /******************************************************************************/
202 /*-------------------------Global Function Prototypes-------------------------*/
203 /******************************************************************************/
204 
205 /** \brief Returns the timer event
206  * \param driver TOM Timer interface Handle
207  * \return Timer event
208  */
210 
211 /** \brief Returns the trigger event
212  * \param driver TOM Timer interface Handle
213  * \return Trigger event
214  */
216 
217 /** \brief Add a channel to the channel mask
218  * Channels present in the mask are started, stopped, updated at the same time as the timer:
219  * IfxGtm_Tom_Timer_applyUpdate, IfxGtm_Tom_Timer_disableUpdate, IfxGtm_Tom_Timer_stop, IfxGtm_Tom_Timer_run
220  * \param driver TOM Timer interface Handle
221  * \param mask Mask value
222  * \return None
223  */
225 
226 /** \brief Enables the transfer of the shadow registers
227  * \param driver TOM Timer interface Handle
228  * \return None
229  */
231 
232 /** \brief Disables the upadte
233  * \param driver TOM Timer interface Handle
234  * \return None
235  */
237 
238 /** \brief Returns the frequency
239  * \param driver TOM Timer interface Handle
240  * \return Frequency
241  */
243 
244 /** \brief Returns the Input frequncy
245  * \param driver TOM Timer interface Handle
246  * \return Frequency
247  */
249 
250 /** \brief Returns the period of the timer
251  * \param driver TOM Timer interface Handle
252  * \return Period
253  */
255 
256 /** \brief Returns the resolution
257  * \param driver TOM Timer interface Handle
258  * \return Resolution
259  */
261 
262 /** \brief Runs the timer
263  * \param driver TOM Timer interface Handle
264  * \return None
265  */
267 
268 /** \brief Sets the frequency
269  * \param driver TOM Timer interface Handle
270  * \param frequency Frequency
271  * \return TRUE on success else FALSE
272  */
274 
275 /** \brief Sets the period for the timer
276  * \param driver TOM Timer interface Handle
277  * \param period Period value
278  * \return TRUE on success else FALSE
279  */
281 
282 /** \brief Sets the single shot mode of the timer
283  * \param driver TOM Timer interface Handle
284  * \param enabled If TRUE, sets the single shot mode
285  * \return None
286  */
287 IFX_EXTERN void IfxGtm_Tom_Timer_setSingleMode(IfxGtm_Tom_Timer *driver, boolean enabled);
288 
289 /** \brief Sets the trigger
290  * \param driver TOM Timer interface Handle
291  * \param triggerPoint Trigger point value
292  * \return None
293  */
295 
296 /** \brief Initializes the standard interface timer
297  * \param stdif Standard interface timer object
298  * \param driver TOM Timer interface Handle
299  * \return TRUE on success else FALSE
300  */
302 
303 /** \brief Stops the timer
304  * \param driver TOM Timer interface Handle
305  * \return None
306  */
308 
309 /** \brief Updates the input frequency
310  * \param driver TOM Timer interface Handle
311  * \return None
312  */
314 
315 /** \} */
316 
317 #endif /* IFXGTM_TOM_TIMER_H */