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_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  *
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  */
65 } IfxStdIf_Timer_OutputEvent;
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 */
73 } IfxStdIf_Timer_CountDir;
74 
75 /** \brief Forward declaration */
76 typedef struct IfxStdIf_Timer_ IfxStdIf_Timer;
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  */
82 typedef float32 (*IfxStdIf_Timer_GetFrequency)(IfxStdIf_InterfaceDriver driver);
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  */
88 typedef Ifx_TimerValue (*IfxStdIf_Timer_GetPeriod)(IfxStdIf_InterfaceDriver driver);
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  */
94 typedef float32 (*IfxStdIf_Timer_GetResolution)(IfxStdIf_InterfaceDriver driver);
95 
96 /** \brief Return the timer trigger point
97  * \param driver Pointer to the interface driver object
98  * \return Return the timer timer point
99  */
100 typedef Ifx_TimerValue (*IfxStdIf_Timer_GetTrigger)(IfxStdIf_InterfaceDriver driver);
101 
102 /** \brief Set the timer frequency in Hz
103  * \param driver Pointer to the interface driver object
104  * \param frequency Requested timer frequency in Hz
105  * \retval TRUE The requested frequency could be set
106  * \retval FALSE The requested frequency is out of range
107  */
108 typedef boolean (*IfxStdIf_Timer_SetFrequency)(IfxStdIf_InterfaceDriver driver, float32 frequency);
109 
110 /** \brief Indicates the driver that the imput frequency has changed and that it should be taken in account
111  * \param driver Pointer to the interface driver object
112  * \return None
113  */
114 typedef void (*IfxStdIf_Timer_UpdateInputFrequency)(IfxStdIf_InterfaceDriver driver);
115 
116 /** \brief Apply requested updates.
117  *
118  * Such requested update are calls to:
119  * - IfxStdIf_Timer_setSingleMode()
120  * - IfxStdIf_Timer_setTrigger()
121  * - IfxStdIf_Timer_setPeriod() or IfxStdIf_Timer_setFrequency()
122  * as well as PWM generation related calls such as:
123  * - IfxStdIf_PwmHl_setDeadtime()
124  * - IfxStdIf_PwmHl_setMode()
125  * - IfxStdIf_PwmHl_setOnTime()
126  * - IfxStdIf_PwmHl_setupChannels()
127  *
128  * It is important to note, that only one call to Timer_applyUpdate() is allowed within
129  * one timer period!!!
130  * In order to ensure correct update synchronisation, disableUpdate() should have been called previously.
131  *
132  * \param driver Pointer to the interface driver object
133  * \return None
134  */
135 typedef void (*IfxStdIf_Timer_ApplyUpdate)(IfxStdIf_InterfaceDriver driver);
136 
137 /** \brief Disable updates
138  *
139  * The following API action will not be taken in account before applyUpdate is called:
140  * - IfxStdIf_Timer_setSingleMode()
141  * - IfxStdIf_Timer_setTrigger()
142  * - IfxStdIf_Timer_setPeriod() or IfxStdIf_Timer_setFrequency()
143  * as well as PWM generation related calls such as:
144  * - IfxStdIf_PwmHl_setDeadtime()
145  * - IfxStdIf_PwmHl_setMode()
146  * - IfxStdIf_PwmHl_setOnTime()
147  * - IfxStdIf_PwmHl_setupChannels()
148  *
149  * \param driver Pointer to the interface driver object
150  * \return None
151  */
152 typedef void (*IfxStdIf_Timer_DisableUpdate)(IfxStdIf_InterfaceDriver driver);
153 
154 /** \brief Return the timer input frequency in Hz
155  * \param driver Pointer to the interface driver object
156  * \return Return the timer input frequency in Hz
157  */
158 typedef float32 (*IfxStdIf_Timer_GetInputFrequency)(IfxStdIf_InterfaceDriver driver);
159 
160 /** \brief Immediately start the timer.
161  *
162  * Please note that other mechanism may avoid the timer to tick, such as when the
163  * global (input) clock to the timer block is inactive.
164  * \param driver Pointer to the interface driver object
165  * \return none
166  */
167 typedef void (*IfxStdIf_Timer_Run)(IfxStdIf_InterfaceDriver driver);
168 
169 /** \brief Set the timer period.
170  *
171  * Timer_applyUpdate() shall be invoked in order this to take effect.
172  * \param driver Pointer to the interface driver object
173  * \param period Period value in ticks
174  * \retval TRUE The requested period could be set
175  * \retval FALSE The requested period is out of range
176  */
177 typedef boolean (*IfxStdIf_Timer_SetPeriod)(IfxStdIf_InterfaceDriver driver, Ifx_TimerValue period);
178 
179 /** \brief Stop timer at the end of the period
180  *
181  * Timer_applyUpdate() shall be invoked in order this to take effect.
182  * \param driver Pointer to the interface driver object
183  * \param enabled If TRUE, enable the single mode, else disable the single mode (continuous mode)
184  * \return none
185  */
186 typedef void (*IfxStdIf_Timer_SetSingleMode)(IfxStdIf_InterfaceDriver driver, boolean enabled);
187 
188 /** \brief Set trigger point.
189  *
190  * \see Timer_OutputEvent for the definition of the output level.
191  * Active state is defined by Timer_Config::outputActiveState.
192  *
193  * Timer_applyUpdate() shall be invoked in order this to take effect.
194  * \param driver Pointer to the interface driver object
195  * \param triggerPoint Trigger point in ticks from the period start.
196  * \return none
197  */
198 typedef void (*IfxStdIf_Timer_SetTrigger)(IfxStdIf_InterfaceDriver driver, Ifx_TimerValue triggerPoint);
199 
200 /** \brief Immediately stops the timer
201  * \param driver Pointer to the interface driver object
202  * \return none
203  */
204 typedef void (*IfxStdIf_Timer_Stop)(IfxStdIf_InterfaceDriver driver);
205 
206 /** \brief Return the timer interrupt flag and reset it
207  * \param driver Pointer to the interface driver object
208  * \return Return the timer interrupt flag
209  */
210 typedef boolean (*IfxStdIf_Timer_AckTimerIrq)(IfxStdIf_InterfaceDriver driver);
211 
212 /** \brief Return the trigger interrupt flag and reset it
213  * \param driver Pointer to the interface driver object
214  * \return Return the trigger interrupt flag
215  */
216 typedef boolean (*IfxStdIf_Timer_AckTriggerIrq)(IfxStdIf_InterfaceDriver driver);
217 
218 /** \brief Standard interface object
219  */
220 struct IfxStdIf_Timer_
221 {
222  IfxStdIf_InterfaceDriver driver; /**< \brief Interface driver object */
223  IfxStdIf_Timer_GetFrequency getFrequency; /**< \brief \see IfxStdIf_Timer_GetFrequency */
224  IfxStdIf_Timer_GetPeriod getPeriod; /**< \brief \see IfxStdIf_Timer_GetPeriod */
225  IfxStdIf_Timer_GetResolution getResolution; /**< \brief \see IfxStdIf_Timer_GetResolution */
226  IfxStdIf_Timer_GetTrigger getTrigger; /**< \brief \see IfxStdIf_Timer_GetTrigger */
227  IfxStdIf_Timer_SetFrequency setFrequency; /**< \brief \see IfxStdIf_Timer_SetFrequency */
228  IfxStdIf_Timer_UpdateInputFrequency updateInputFrequency; /**< \brief \see IfxStdIf_Timer_UpdateInputFrequency */
229  IfxStdIf_Timer_ApplyUpdate applyUpdate; /**< \brief \see IfxStdIf_Timer_ApplyUpdate */
230  IfxStdIf_Timer_DisableUpdate disableUpdate; /**< \brief \see IfxStdIf_Timer_DisableUpdate */
231  IfxStdIf_Timer_GetInputFrequency getInputFrequency; /**< \brief \see IfxStdIf_Timer_GetInputFrequency */
232  IfxStdIf_Timer_Run run; /**< \brief \see IfxStdIf_Timer_Run */
233  IfxStdIf_Timer_SetPeriod setPeriod; /**< \brief \see IfxStdIf_Timer_SetPeriod */
234  IfxStdIf_Timer_SetSingleMode setSingleMode; /**< \brief \see IfxStdIf_Timer_SetSingleMode */
235  IfxStdIf_Timer_SetTrigger setTrigger; /**< \brief \see IfxStdIf_Timer_SetTrigger */
236  IfxStdIf_Timer_Stop stop; /**< \brief \see IfxStdIf_Timer_Stop */
237  IfxStdIf_Timer_AckTimerIrq ackTimerIrq; /**< \brief \see IfxStdIf_Timer_AckTimerIrq */
238  IfxStdIf_Timer_AckTriggerIrq ackTriggerIrq; /**< \brief \see IfxStdIf_Timer_AckTriggerIrq */
239 };
240 
241 /** \brief Trigger configuration */
242 typedef struct
243 {
244  boolean enabled; /**< \brief If true, the trigger functionality is Initialised, else ignored */
245  Ifx_TimerValue triggerPoint; /**< \brief Trigger point in timer ticks */
246  Ifx_Priority isrPriority; /**< \brief Interrupt isrPriority of the trigger interrupt, if 0 the interrupt is disable */
247  IfxSrc_Tos isrProvider; /**< \brief Interrupt service provider for the trigger interrupt */
248  IfxPort_OutputMode outputMode; /**< \brief Output mode *//* FIXME use generic type (No specific tricore AURIX type ) */
249  IfxPort_PadDriver outputDriver; /**< \brief Output pad driver *//* FIXME use generic type (No specific tricore AURIX type ) */
250  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 */
251  boolean outputEnabled; /**< \brief If TRUE, the output pin is enabled, else disabled. In case the output is disabled, the output pin is not initialized. */
252 } IfxStdIf_Timer_TrigConfig;
253 
254 /** \brief Timer configuration */
255 typedef struct
256 {
257  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. */
258  Ifx_Priority isrPriority; /**< \brief Interrupt isrPriority of the timer interrupt, if 0 the interrupt is disable */
259  IfxSrc_Tos isrProvider; /**< \brief Interrupt service provider for the timer interrupt */
260  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 */
261  IfxStdIf_Timer_TrigConfig trigger; /**< \brief Trigger configuration */
262  IfxStdIf_Timer_CountDir countDir; /**< \brief Timer counting mode */
263  float32 startOffset; /**< \brief FIXME make startOffset as Ifx_TimerValue. Timer initial offset in % of the period */
264 } IfxStdIf_Timer_Config;
265 
266 /** \addtogroup library_srvsw_stdif_timer
267  * \{
268  */
269 /** \copydoc IfxStdIf_Timer_GetFrequency */
270 IFX_INLINE float32 IfxStdIf_Timer_getFrequency(IfxStdIf_Timer *stdIf)
271 {
272  return stdIf->getFrequency(stdIf->driver);
273 }
274 
275 
276 /** \copydoc IfxStdIf_Timer_GetPeriod */
277 IFX_INLINE Ifx_TimerValue IfxStdIf_Timer_getPeriod(IfxStdIf_Timer *stdIf)
278 {
279  return stdIf->getPeriod(stdIf->driver);
280 }
281 
282 
283 /** \copydoc IfxStdIf_Timer_GetTrigger */
284 IFX_INLINE Ifx_TimerValue IfxStdIf_Timer_getTrigger(IfxStdIf_Timer *stdIf)
285 {
286  return stdIf->getTrigger(stdIf->driver);
287 }
288 
289 
290 /** \copydoc IfxStdIf_Timer_GetResolution */
291 IFX_INLINE float32 IfxStdIf_Timer_getResolution(IfxStdIf_Timer *stdIf)
292 {
293  return stdIf->getResolution(stdIf->driver);
294 }
295 
296 
297 /** \copydoc IfxStdIf_Timer_SetFrequency */
298 IFX_INLINE boolean IfxStdIf_Timer_setFrequency(IfxStdIf_Timer *stdIf, float32 frequency)
299 {
300  return stdIf->setFrequency(stdIf->driver, frequency);
301 }
302 
303 
304 /** \copydoc IfxStdIf_Timer_UpdateInputFrequency */
305 IFX_INLINE void IfxStdIf_Timer_updateInputFrequency(IfxStdIf_Timer *stdIf)
306 {
307  stdIf->updateInputFrequency(stdIf->driver);
308 }
309 
310 
311 /** \copydoc IfxStdIf_Timer_ApplyUpdate */
312 IFX_INLINE void IfxStdIf_Timer_applyUpdate(IfxStdIf_Timer *stdIf)
313 {
314  stdIf->applyUpdate(stdIf->driver);
315 }
316 
317 
318 /** \copydoc IfxStdIf_Timer_DisableUpdate */
319 IFX_INLINE void IfxStdIf_Timer_disableUpdate(IfxStdIf_Timer *stdIf)
320 {
321  stdIf->disableUpdate(stdIf->driver);
322 }
323 
324 
325 /** \copydoc IfxStdIf_Timer_GetInputFrequency */
326 IFX_INLINE float32 IfxStdIf_Timer_getInputFrequency(IfxStdIf_Timer *stdIf)
327 {
328  return stdIf->getInputFrequency(stdIf->driver);
329 }
330 
331 
332 /** \copydoc IfxStdIf_Timer_Run */
333 IFX_INLINE void IfxStdIf_Timer_run(IfxStdIf_Timer *stdIf)
334 {
335  stdIf->run(stdIf->driver);
336 }
337 
338 
339 /** \copydoc IfxStdIf_Timer_SetPeriod */
340 IFX_INLINE boolean IfxStdIf_Timer_setPeriod(IfxStdIf_Timer *stdIf, Ifx_TimerValue period)
341 {
342  return stdIf->setPeriod(stdIf->driver, period);
343 }
344 
345 
346 /** \copydoc IfxStdIf_Timer_SetSingleMode */
347 IFX_INLINE void IfxStdIf_Timer_setSingleMode(IfxStdIf_Timer *stdIf, boolean enabled)
348 {
349  stdIf->setSingleMode(stdIf->driver, enabled);
350 }
351 
352 
353 /** \copydoc IfxStdIf_Timer_SetTrigger */
354 IFX_INLINE void IfxStdIf_Timer_setTrigger(IfxStdIf_Timer *stdIf, Ifx_TimerValue triggerPoint)
355 {
356  stdIf->setTrigger(stdIf->driver, triggerPoint);
357 }
358 
359 
360 /** \copydoc IfxStdIf_Timer_Stop */
361 IFX_INLINE void IfxStdIf_Timer_stop(IfxStdIf_Timer *stdIf)
362 {
363  stdIf->stop(stdIf->driver);
364 }
365 
366 
367 /** \copydoc IfxStdIf_Timer_AckTimerIrq */
368 IFX_INLINE boolean IfxStdIf_Timer_ackTimerIrq(IfxStdIf_Timer *stdIf)
369 {
370  return stdIf->ackTimerIrq(stdIf->driver);
371 }
372 
373 
374 /** \copydoc IfxStdIf_Timer_AckTriggerIrq */
375 IFX_INLINE boolean IfxStdIf_Timer_ackTriggerIrq(IfxStdIf_Timer *stdIf)
376 {
377  return stdIf->ackTriggerIrq(stdIf->driver);
378 }
379 
380 
381 /** \brief Convert timer ticks to seconds
382  * \param clockFreq Timer clock frequency
383  * \param ticks time value in ticks to be converted
384  * \return Return the converted time in s
385  */
386 IFX_INLINE float32 IfxStdIf_Timer_tickToS(float32 clockFreq, Ifx_TimerValue ticks)
387 {
388  return ticks / clockFreq;
389 }
390 
391 
392 /** \brief Convert seconds to timer ticks
393  * \param clockFreq Timer clock frequency
394  * \param seconds time value in seconds to be converted
395  * \return Return the converted time in timer ticks
396  */
397 IFX_INLINE Ifx_TimerValue IfxStdIf_Timer_sToTick(float32 clockFreq, float32 seconds)
398 {
399  return seconds * clockFreq;
400 }
401 
402 
403 /** \brief Return the timer period in second
404  * \param stdIf Pointer to the interface driver object
405  */
406 IFX_INLINE float32 IfxStdIf_Timer_getPeriodSecond(IfxStdIf_Timer *stdIf)
407 {
408  return IfxStdIf_Timer_tickToS(IfxStdIf_Timer_getInputFrequency(stdIf), stdIf->getPeriod(stdIf->driver));
409 }
410 
411 
412 /** \} */
413 
414 /** Initialize the configuration structure to default
415  *
416  * \param config Timer configuration. This parameter is initialised by the function
417  *
418  */
419 void IfxStdIf_Timer_initConfig(IfxStdIf_Timer_Config *config);
420 
421 #endif /* IFXSTDIF_TIMER_H_ */