iLLD_TC27xC  1.0
IfxGtm_Tom_Timer.h
Go to the documentation of this file.
1 /**
2  * \file IfxGtm_Tom_Timer.h
3  * \brief GTM TIMER details
4  * \ingroup IfxLld_Gtm
5  *
6  * \version iLLD_1_0_0_11_0
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  * Note: the timer and trigger must bepart of the same TGC, but PWM channels can be of different TGC of the same TOM as the timer
77  *
78  * For a detailed configuration of the microcontroller, see \ref IfxGtm_Tom_Timer_init().
79  *
80  * \section example Usage example
81  * Initialisation:
82  * \code
83  * IfxGtm_Tom_Timer_Config driverConfig;
84  * IfxGtm_Tom_Timer driverData;
85  * IfxStdIf_Timer timer;
86  * IfxGtm_Tom_Timer_initConfig(&driverConfig, &MODULE_GTM);
87  * IfxGtm_Tom_Timer_init (&driverData, &driverConfig);
88  * boolean IfxGtm_Tom_Timer_stdIfTimerInit(&timer, &driverData);
89  * \endcode
90  *
91  * During run-time, \ref library_srvsw_stdif_timer "the interface functions" should be used:
92  * \code
93  * IfxStdIf_Timer_run(timer);
94  * IfxStdIf_Timer_disableUpdate(timer);
95  * IfxStdIf_Timer_setPeriod(timer, period);
96  * IfxStdIf_Timer_applyUpdate(timer);
97  * \endcode
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 */
135 } IfxGtm_Tom_Timer_Base;
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[2]; /**< \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[2]; /**< \brief Mask for channels to be modified together, The 1st value corresponds to the Timer's TGC, the 2nd value corresponds to the timer's next TGC if any */
153  Ifx_TimerValue offset; /**< \brief Timer initial offset in ticks */
154  uint32 tgcGlobalControlDisableUpdate[2]; /**< \brief Cached value for TGC GLOB_CTR */
155  uint32 tgcGlobalControlApplyUpdate[2]; /**< \brief Cached value for TGC GLOB_CTR */
156 } IfxGtm_Tom_Timer;
157 
158 /** \brief Configuration structure for TOM Timer
159  */
160 typedef struct
161 {
162  IfxStdIf_Timer_Config base; /**< \brief Standard interface timer configuration */
163  Ifx_GTM *gtm; /**< \brief Pointer to GTM module */
164  IfxGtm_Tom tom; /**< \brief Index of the TOM object used */
165  IfxGtm_Tom_Ch timerChannel; /**< \brief TOM channel used for the timer */
166  IfxGtm_Tom_ToutMap *triggerOut; /**< \brief TOM channel used for the trigger output, can be identical to the timer channel */
167  IfxGtm_Tom_Ch_ClkSrc clock; /**< \brief Timer input clock */
168  IfxGtm_IrqMode irqModeTimer; /**< \brief Interrupt mode for the timer */
169  IfxGtm_IrqMode irqModeTrigger; /**< \brief Interrupt mode for the trigger */
170 } IfxGtm_Tom_Timer_Config;
171 
172 /** \} */
173 
174 /** \addtogroup IfxLld_Gtm_Tom_Timer_Timer_Functions
175  * \{ */
176 
177 /******************************************************************************/
178 /*-------------------------Global Function Prototypes-------------------------*/
179 /******************************************************************************/
180 
181 /** \brief Returns the initial timer offset in ticks
182  * \param driver TOM Timer interface Handle
183  * \return Returns the initial timer offset in ticks
184  */
185 IFX_EXTERN Ifx_TimerValue IfxGtm_Tom_Timer_getOffset(IfxGtm_Tom_Timer *driver);
186 
187 /** \brief Returns the pointer to timer channel
188  * \param driver TOM Timer interface Handle
189  * \return Pointer
190  */
191 IFX_EXTERN volatile uint32 *IfxGtm_Tom_Timer_getPointer(IfxGtm_Tom_Timer *driver);
192 
193 /** \brief Returns the pointer to trigger channel
194  * \param driver TOM Timer interface Handle
195  * \return Pointer
196  */
197 IFX_EXTERN volatile uint32 *IfxGtm_Tom_Timer_getTriggerPointer(IfxGtm_Tom_Timer *driver);
198 
199 /** \brief Initialises the timer object
200  * \param driver TOM Timer interface Handle
201  * \param config Configuration structure for TOM Timer
202  * \return TRUE on success else FALSE
203  */
204 IFX_EXTERN boolean IfxGtm_Tom_Timer_init(IfxGtm_Tom_Timer *driver, const IfxGtm_Tom_Timer_Config *config);
205 
206 /** \brief Initializes the configuration structure to default
207  * \param config This parameter is Initialised by the function
208  * \param gtm Pointer to GTM module
209  * \return None
210  */
211 IFX_EXTERN void IfxGtm_Tom_Timer_initConfig(IfxGtm_Tom_Timer_Config *config, Ifx_GTM *gtm);
212 
213 /** \} */
214 
215 /** \addtogroup IfxLld_Gtm_Tom_Timer_Timer_StdIf_Functions
216  * \{ */
217 
218 /******************************************************************************/
219 /*-------------------------Global Function Prototypes-------------------------*/
220 /******************************************************************************/
221 
222 /** \brief Returns the timer event
223  * \see IfxStdIf_Timer_AckTimerIrq
224  * \param driver TOM Timer interface Handle
225  * \return Timer event
226  */
227 IFX_EXTERN boolean IfxGtm_Tom_Timer_acknowledgeTimerIrq(IfxGtm_Tom_Timer *driver);
228 
229 /** \brief Returns the trigger event
230  * \see IfxStdIf_Timer_AckTriggerIrq
231  * \param driver TOM Timer interface Handle
232  * \return Trigger event
233  */
234 IFX_EXTERN boolean IfxGtm_Tom_Timer_acknowledgeTriggerIrq(IfxGtm_Tom_Timer *driver);
235 
236 /** \brief Add a channel to the channel mask
237  * Channels present in the mask are started, stopped, updated at the same time as the timer:
238  * IfxGtm_Tom_Timer_applyUpdate, IfxGtm_Tom_Timer_disableUpdate, IfxGtm_Tom_Timer_stop, IfxGtm_Tom_Timer_run
239  * \param driver TOM Timer interface Handle
240  * \param channel Channel to ba added to the mask
241  * \return None
242  */
243 IFX_EXTERN void IfxGtm_Tom_Timer_addToChannelMask(IfxGtm_Tom_Timer *driver, IfxGtm_Tom_Ch channel);
244 
245 /** \brief Enables the transfer of the shadow registers
246  * \see IfxStdIf_Timer_ApplyUpdate
247  * Specific implementation: Enable the transfer of the shadow registers
248  * \param driver TOM Timer interface Handle
249  * \return None
250  */
251 IFX_EXTERN void IfxGtm_Tom_Timer_applyUpdate(IfxGtm_Tom_Timer *driver);
252 
253 /** \brief Disables the upadte
254  * \see IfxStdIf_Timer_DisableUpdate
255  * Specific implementation: Disable the transfer of the shadow registers
256  * \param driver TOM Timer interface Handle
257  * \return None
258  */
259 IFX_EXTERN void IfxGtm_Tom_Timer_disableUpdate(IfxGtm_Tom_Timer *driver);
260 
261 /** \brief Returns the frequency
262  * \see IfxStdIf_Timer_GetFrequency
263  * \param driver TOM Timer interface Handle
264  * \return Frequency
265  */
266 IFX_EXTERN float32 IfxGtm_Tom_Timer_getFrequency(IfxGtm_Tom_Timer *driver);
267 
268 /** \brief Returns the Input frequncy
269  * \param driver TOM Timer interface Handle
270  * \return Frequency
271  */
272 IFX_EXTERN float32 IfxGtm_Tom_Timer_getInputFrequency(IfxGtm_Tom_Timer *driver);
273 
274 /** \brief Returns the period of the timer
275  * \see IfxStdIf_Timer_GetPeriod
276  * \param driver TOM Timer interface Handle
277  * \return Period
278  */
279 IFX_EXTERN Ifx_TimerValue IfxGtm_Tom_Timer_getPeriod(IfxGtm_Tom_Timer *driver);
280 
281 /** \brief Returns the resolution
282  * \see IfxStdIf_Timer_GetResolution
283  * \param driver TOM Timer interface Handle
284  * \return Resolution
285  */
286 IFX_EXTERN float32 IfxGtm_Tom_Timer_getResolution(IfxGtm_Tom_Timer *driver);
287 
288 /** \brief Returns the trigger point
289  * \param driver TOM Timer interface Handle
290  * \return Trigger point
291  */
292 IFX_EXTERN Ifx_TimerValue IfxGtm_Tom_Timer_getTrigger(IfxGtm_Tom_Timer *driver);
293 
294 /** \brief Runs the timer
295  * \see IfxStdIf_Timer_Run
296  * \param driver TOM Timer interface Handle
297  * \return None
298  */
299 IFX_EXTERN void IfxGtm_Tom_Timer_run(IfxGtm_Tom_Timer *driver);
300 
301 /** \brief Sets the frequency
302  * \see IfxStdIf_Timer_SetFrequency
303  * \param driver TOM Timer interface Handle
304  * \param frequency Frequency
305  * \return TRUE on success else FALSE
306  */
307 IFX_EXTERN boolean IfxGtm_Tom_Timer_setFrequency(IfxGtm_Tom_Timer *driver, float32 frequency);
308 
309 /** \brief Sets the period for the timer
310  * \see IfxStdIf_Timer_SetPeriod
311  * \param driver TOM Timer interface Handle
312  * \param period Period value
313  * \return TRUE on success else FALSE
314  */
315 IFX_EXTERN boolean IfxGtm_Tom_Timer_setPeriod(IfxGtm_Tom_Timer *driver, Ifx_TimerValue period);
316 
317 /** \brief Sets the single shot mode of the timer
318  * \see IfxStdIf_Timer_SetSingleMode
319  * \param driver TOM Timer interface Handle
320  * \param enabled If TRUE, sets the single shot mode
321  * \return None
322  */
323 IFX_EXTERN void IfxGtm_Tom_Timer_setSingleMode(IfxGtm_Tom_Timer *driver, boolean enabled);
324 
325 /** \brief Sets the trigger
326  * \see IfxStdIf_Timer_SetTrigger
327  * \param driver TOM Timer interface Handle
328  * \param triggerPoint Trigger point value
329  * \return TRUE on success else FALSE
330  */
331 IFX_EXTERN boolean IfxGtm_Tom_Timer_setTrigger(IfxGtm_Tom_Timer *driver, Ifx_TimerValue triggerPoint);
332 
333 /** \brief Initializes the standard interface timer
334  * \param stdif Standard interface timer object, will be initialized by the function
335  * \param driver Interface driver to be used by the standard interface. must be initialised separately
336  * \return TRUE on success else FALSE
337  */
338 IFX_EXTERN boolean IfxGtm_Tom_Timer_stdIfTimerInit(IfxStdIf_Timer *stdif, IfxGtm_Tom_Timer *driver);
339 
340 /** \brief Stops the timer
341  * \see IfxStdIf_Timer_Stop
342  * \param driver TOM Timer interface Handle
343  * \return None
344  */
345 IFX_EXTERN void IfxGtm_Tom_Timer_stop(IfxGtm_Tom_Timer *driver);
346 
347 /** \brief Updates the input frequency
348  * \see IfxStdIf_Timer_UpdateInputFrequency
349  * \param driver TOM Timer interface Handle
350  * \return None
351  */
352 IFX_EXTERN void IfxGtm_Tom_Timer_updateInputFrequency(IfxGtm_Tom_Timer *driver);
353 
354 /** \} */
355 
356 #endif /* IFXGTM_TOM_TIMER_H */