iLLD_TC27xC  1.0
IfxStdIf_Timer.h
Go to the documentation of this file.
1 /**
2  * \file IfxStdIf_Timer.h
3  * \brief Standard interface: Timer
4  * \ingroup IfxStdIf
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  *
25  * \defgroup library_srvsw_stdif_timer Standard interface: Timer
26  * \ingroup library_srvsw_stdif
27  *
28  * The standard interface timer (Timer) abstract the hardware used for timer feature. It provide, after proper initialization an hardware
29  * independant way to interact with the timer functionallity like setting period, trigger points, ...
30  *
31  * The figure below shows the standard timer interface.
32  *
33  * \image html "Timer.png" "Standard timer interface"
34  *
35  * This interface defines the following features:
36  * - Timer with configurable frequency
37  * - Configurable counting direction
38  * - Optional interrupt on timer event with configurable service request provider and priority
39  * - Optional trigger signal with:
40  * - Optional interrupt on trigger event with configurable service request provider and priority
41  * - Configurable trigger point
42  * - Configurable trigger edge
43  * - trigger signal can be internal only or forwarded to a port pin
44  */
45 
46 #ifndef IFXSTDIF_TIMER_H_
47 #define IFXSTDIF_TIMER_H_ 1
48 
49 #include "Cpu/Std/Ifx_Types.h"
50 #include "Src/Std/IfxSrc.h" /* FIXME interface should not have dependencies to the HAL, an If type needs to be defined */
51 #include "Port/Std/IfxPort.h" /* FIXME interface should not have dependencies to the HAL, an If type needs to be defined */ /*FIXME introduce generic IF for ports. ex: IfxPort_OutputMode */
52 #include "IfxStdIf.h"
53 /** \brief Output event enable / disable */
54 typedef enum
55 {
56  IfxStdIf_Timer_Output_disabled, /**< \brief Timer output is set to the inactive, no change in the output */
57  IfxStdIf_Timer_Output_enabled /**< \brief In case the trigger is enabled,
58  * the output is set to active between time 0 to the trigger point,
59  * and is set to inactive between the trigger point and the period.
60  * In case the trigger is disabled and counting direction if IfxStdIf_Timer_CountDir_up, the output is toggled when the timer is reset
61  * In case the trigger is disabled and counting direction if IfxStdIf_Timer_CountDir_down, the output is toggled when the timer is reloaded
62  * In case the trigger is disabled and counting direction if IfxStdIf_Timer_CountDir_upAndDown, the output is toggled when the timer reach 0
63  * In case the trigger is enabled the trigger is active before the trigger point and inactive after the trigger point.
64  */
66 
67 /** \brief Timer increment direction */
68 typedef enum
69 {
70  IfxStdIf_Timer_CountDir_up, /**< \brief Timer is counting up */
71  IfxStdIf_Timer_CountDir_upAndDown, /**< \brief Timer is counting up and down */
72  IfxStdIf_Timer_CountDir_down /**< \brief Timer is counting down */
74 
75 /** \brief Forward declaration */
77 
78 /** \brief Return the timer frequency in Hz
79  * \param driver Pointer to the interface driver object
80  * \return Return the timer frequency in Hz
81  */
83 
84 /** \brief Return the timer period in ticks
85  * \param driver Pointer to the interface driver object
86  * \return Return the timer period in ticks
87  */
89 
90 /** \brief Return the timer resolution in seconds
91  * \param driver Pointer to the interface driver object
92  * \return Return the timer resolution in seconds
93  */
95 
96 /** \brief Set the timer frequency in Hz
97  * \param driver Pointer to the interface driver object
98  * \param frequency Requested timer frequency in Hz
99  * \retval TRUE The requested frequency could be set
100  * \retval FALSE The requested frequency is out of range
101  */
103 
104 /** \brief Indicates the driver that the imput frequency has changed and that it should be taken in account
105  * \param driver Pointer to the interface driver object
106  * \return None
107  */
109 
110 /** \brief Apply requested updates.
111  *
112  * Such requested update are calls to:
113  * - IfxStdIf_Timer_setSingleMode()
114  * - IfxStdIf_Timer_setTrigger()
115  * - IfxStdIf_Timer_setPeriod() or IfxStdIf_Timer_setFrequency()
116  * as well as PWM generation related calls such as:
117  * - IfxStdIf_PwmHl_setDeadtime()
118  * - IfxStdIf_PwmHl_setMode()
119  * - IfxStdIf_PwmHl_setOnTime()
120  * - IfxStdIf_PwmHl_setupChannels()
121  *
122  * It is important to note, that only one call to Timer_applyUpdate() is allowed within
123  * one timer period!!!
124  * In order to ensure correct update synchronisation, disableUpdate() should have been called previously.
125  *
126  * \param driver Pointer to the interface driver object
127  * \return None
128  */
130 
131 /** \brief Disable updates
132  *
133  * The following API action will not be taken in account before applyUpdate is called:
134  * - IfxStdIf_Timer_setSingleMode()
135  * - IfxStdIf_Timer_setTrigger()
136  * - IfxStdIf_Timer_setPeriod() or IfxStdIf_Timer_setFrequency()
137  * as well as PWM generation related calls such as:
138  * - IfxStdIf_PwmHl_setDeadtime()
139  * - IfxStdIf_PwmHl_setMode()
140  * - IfxStdIf_PwmHl_setOnTime()
141  * - IfxStdIf_PwmHl_setupChannels()
142  *
143  * \param driver Pointer to the interface driver object
144  * \return None
145  */
147 
148 /** \brief Return the timer input frequency in Hz
149  * \param driver Pointer to the interface driver object
150  * \return Return the timer input frequency in Hz
151  */
153 
154 /** \brief Immediately start the timer.
155  *
156  * Please note that other mechanism may avoid the timer to tick, such as when the
157  * global (input) clock to the timer block is inactive.
158  * \param driver Pointer to the interface driver object
159  * \return none
160  */
162 
163 /** \brief Set the timer period.
164  *
165  * Timer_applyUpdate() shall be invoked in order this to take effect.
166  * \param driver Pointer to the interface driver object
167  * \param period Period value in ticks
168  * \retval TRUE The requested period could be set
169  * \retval FALSE The requested period is out of range
170  */
172 
173 /** \brief Stop timer at the end of the period
174  *
175  * Timer_applyUpdate() shall be invoked in order this to take effect.
176  * \param driver Pointer to the interface driver object
177  * \param enabled If TRUE, enable the single mode, else disable the single mode (continuous mode)
178  * \return none
179  */
181 
182 /** \brief Set trigger point.
183  *
184  * \see Timer_OutputEvent for the definition of the output level.
185  * Active state is defined by Timer_Config::outputActiveState.
186  *
187  * Timer_applyUpdate() shall be invoked in order this to take effect.
188  * \param driver Pointer to the interface driver object
189  * \param triggerPoint Trigger point in ticks from the period start.
190  * \return none
191  */
193 
194 /** \brief Immediately stops the timer
195  * \param driver Pointer to the interface driver object
196  * \return none
197  */
199 
200 /** \brief Return the timer interrupt flag and reset it
201  * \param driver Pointer to the interface driver object
202  * \return Return the timer interrupt flag
203  */
205 
206 /** \brief Return the trigger interrupt flag and reset it
207  * \param driver Pointer to the interface driver object
208  * \return Return the trigger interrupt flag
209  */
211 
212 /** \brief Standard interface object
213  */
215 {
216  IfxStdIf_InterfaceDriver driver; /**< \brief Interface driver object */
217  IfxStdIf_Timer_GetFrequency getFrequency; /**< \brief \see IfxStdIf_Timer_GetFrequency */
218  IfxStdIf_Timer_GetPeriod getPeriod; /**< \brief \see IfxStdIf_Timer_GetPeriod */
219  IfxStdIf_Timer_GetResolution getResolution; /**< \brief \see IfxStdIf_Timer_GetResolution */
220  IfxStdIf_Timer_SetFrequency setFrequency; /**< \brief \see IfxStdIf_Timer_SetFrequency */
221  IfxStdIf_Timer_UpdateInputFrequency updateInputFrequency; /**< \brief \see IfxStdIf_Timer_UpdateInputFrequency */
222  IfxStdIf_Timer_ApplyUpdate applyUpdate; /**< \brief \see IfxStdIf_Timer_ApplyUpdate */
223  IfxStdIf_Timer_DisableUpdate disableUpdate; /**< \brief \see IfxStdIf_Timer_DisableUpdate */
224  IfxStdIf_Timer_GetInputFrequency getInputFrequency; /**< \brief \see IfxStdIf_Timer_GetInputFrequency */
225  IfxStdIf_Timer_Run run; /**< \brief \see IfxStdIf_Timer_Run */
226  IfxStdIf_Timer_SetPeriod setPeriod; /**< \brief \see IfxStdIf_Timer_SetPeriod */
227  IfxStdIf_Timer_SetSingleMode setSingleMode; /**< \brief \see IfxStdIf_Timer_SetSingleMode */
228  IfxStdIf_Timer_SetTrigger setTrigger; /**< \brief \see IfxStdIf_Timer_SetTrigger */
229  IfxStdIf_Timer_Stop stop; /**< \brief \see IfxStdIf_Timer_Stop */
230  IfxStdIf_Timer_AckTimerIrq ackTimerIrq; /**< \brief \see IfxStdIf_Timer_AckTimerIrq */
231  IfxStdIf_Timer_AckTriggerIrq ackTriggerIrq; /**< \brief \see IfxStdIf_Timer_AckTriggerIrq */
232 };
233 
234 /** \brief Trigger configuration */
235 typedef struct
236 {
237  boolean enabled; /**< \brief If true, the trigger functionality is Initialised, else ignored */
238  Ifx_TimerValue triggerPoint; /**< \brief Trigger point in timer ticks */
239  Ifx_Priority isrPriority; /**< \brief Interrupt isrPriority of the trigger interrupt, if 0 the interrupt is disable */
240  IfxSrc_Tos isrProvider; /**< \brief Interrupt service provider for the trigger interrupt */
241  IfxPort_OutputMode outputMode; /**< \brief Output mode *//* FIXME use generic type (No specific tricore AURIX type ) */
242  IfxPort_PadDriver outputDriver; /**< \brief Output pad driver *//* FIXME use generic type (No specific tricore AURIX type ) */
243  boolean risingEdgeAtPeriod; /**< \brief Set the clock signal polarity, if TRUE, the rising edge is at the period, else at the trigger offset. When the timer is stopped, the output is set to high */
244  boolean outputEnabled; /**< \brief If TRUE, the output pin is enabled, else disabled. In case the output is disabled, the output pin is not initialized. */
246 
247 /** \brief Timer configuration */
248 typedef struct
249 {
250  float32 frequency; /**< \brief PWM frequency in Hz. This parameter is only used to initialise the timer structure. An additional cell is required to build the timer. */
251  Ifx_Priority isrPriority; /**< \brief Interrupt isrPriority of the timer interrupt, if 0 the interrupt is disable */
252  IfxSrc_Tos isrProvider; /**< \brief Interrupt service provider for the timer interrupt */
253  float32 minResolution; /**< \brief Minimum resolution of the timer in seconds. if 0, this parameter is ignored. If the configuration does not enable this setting a warning is given */
254  IfxStdIf_Timer_TrigConfig trigger; /**< \brief Trigger configuration */
255  IfxStdIf_Timer_CountDir countDir; /**< \brief Timer counting mode */
257 
258 /** \addtogroup library_srvsw_stdif_timer
259  * \{
260  */
261 /** \copydoc IfxStdIf_Timer_GetFrequency */
263 {
264  return stdIf->getFrequency(stdIf->driver);
265 }
266 
267 
268 /** \copydoc IfxStdIf_Timer_GetPeriod */
270 {
271  return stdIf->getPeriod(stdIf->driver);
272 }
273 
274 
275 /** \copydoc IfxStdIf_Timer_GetResolution */
277 {
278  return stdIf->getResolution(stdIf->driver);
279 }
280 
281 
282 /** \copydoc IfxStdIf_Timer_SetFrequency */
284 {
285  return stdIf->setFrequency(stdIf->driver, frequency);
286 }
287 
288 
289 /** \copydoc IfxStdIf_Timer_UpdateInputFrequency */
291 {
292  stdIf->updateInputFrequency(stdIf->driver);
293 }
294 
295 
296 /** \copydoc IfxStdIf_Timer_ApplyUpdate */
298 {
299  stdIf->applyUpdate(stdIf->driver);
300 }
301 
302 
303 /** \copydoc IfxStdIf_Timer_DisableUpdate */
305 {
306  stdIf->disableUpdate(stdIf->driver);
307 }
308 
309 
310 /** \copydoc IfxStdIf_Timer_GetInputFrequency */
312 {
313  return stdIf->getInputFrequency(stdIf->driver);
314 }
315 
316 
317 /** \copydoc IfxStdIf_Timer_Run */
319 {
320  stdIf->run(stdIf->driver);
321 }
322 
323 
324 /** \copydoc IfxStdIf_Timer_SetPeriod */
326 {
327  return stdIf->setPeriod(stdIf->driver, period);
328 }
329 
330 
331 /** \copydoc IfxStdIf_Timer_SetSingleMode */
333 {
334  stdIf->setSingleMode(stdIf->driver, enabled);
335 }
336 
337 
338 /** \copydoc IfxStdIf_Timer_SetTrigger */
340 {
341  stdIf->setTrigger(stdIf->driver, triggerPoint);
342 }
343 
344 
345 /** \copydoc IfxStdIf_Timer_Stop */
347 {
348  stdIf->stop(stdIf->driver);
349 }
350 
351 
352 /** \copydoc IfxStdIf_Timer_AckTimerIrq */
354 {
355  return stdIf->ackTimerIrq(stdIf->driver);
356 }
357 
358 
359 /** \copydoc IfxStdIf_Timer_AckTriggerIrq */
361 {
362  return stdIf->ackTriggerIrq(stdIf->driver);
363 }
364 
365 
366 /** \brief Convert timer ticks to seconds
367  * \param clockFreq Timer clock frequency
368  * \param ticks time value in ticks to be converted
369  * \return Return the converted time in s
370  */
372 {
373  return ticks / clockFreq;
374 }
375 
376 
377 /** \brief Convert seconds to timer ticks
378  * \param clockFreq Timer clock frequency
379  * \param seconds time value in seconds to be converted
380  * \return Return the converted time in timer ticks
381  */
383 {
384  return seconds * clockFreq;
385 }
386 
387 
388 /** \} */
389 
390 /** Initialize the configuration structure to default
391  *
392  * \param config Timer configuration. This parameter is initialised by the function
393  *
394  */
396 
397 #endif /* IFXSTDIF_TIMER_H_ */