iLLD_TC27xC  1.0
IfxGtm_Tom_PwmHl.h
Go to the documentation of this file.
1 /**
2  * \file IfxGtm_Tom_PwmHl.h
3  * \brief _TOM PWMHL 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_PwmHl_Usage How to use the GTM TOM PWM Driver
25  * \ingroup IfxLld_Gtm_Tom_PwmHl
26  *
27  * This driver implements the PWM functionalities as defined by \ref library_srvsw_stdif_pwmhl.
28  * The user is free to use either the driver specific APIs below or to used the \ref library_srvsw_stdif_pwmhl "standard interface APIs".
29  *
30  * \section specific Specific implementation
31  * The PWM driver is a concatenation of a \ref IfxLld_Gtm_Tom_Timer "timer" with additional PWM generation cells.
32  *
33  * The timer is implemented as described in \ref IfxLld_Gtm_Tom_Timer, it generate an internal trigger
34  * that is used to synchronize all the TOM channel used (shown in red in the pictures below).
35  *
36  * The picture below presents two configuration examples:
37  * - On the left, the timer and trigger are generated using the same TOM channel CH0. The 3 dual-complementary
38  * PWMs, CCx and COUTx, are generated using 6 additional TOM channels (CH1 to Ch6).
39  * - On the right, the timer and the trigger uses separate TOM channels to allow the triggering of the ADC
40  * conversions. The order of the CCx and COUTx has been allocated freely between CH9 up to CH14.
41  *
42  * \image html "IfxGtm_Tom_PwmHl-0.png" "PWM implementations on GTM TOM"
43  *
44  *
45  * Each of the TOM channel used for the generation of the CCx and COUTx signals are configured as in the figure below:
46  *
47  * \image html "IfxGtm_Tom_PwmHl-1.png" "TOM channel configuration".
48  *
49  * The internal trigger (red line) is generated by the \ref IfxLld_Gtm_Tom_Timer "timer" on timer rest and used by the
50  * TOM PWM channels to reset the counters CN0 and transfer the shadow values saved in SR0 and SR1 to the
51  * CM0 and CM1 registers. When the counter CN0 reach the values of the CM0 or CM1 compare registers,
52  * a rising or falling edge is generated on the output PWM signal. The signal active state configuration
53  * define which of the CM0 or CM1 is generating the falling or rising edge.
54  *
55  * This trigger mechanism ensure that all the PWM channels, period and trigger are updated at the
56  * exact same time, avoiding any possibility for glitch or incoherent signals.
57  *
58  * The clock use is the same as the timer clock.
59  *
60  * In order to ensure a coherent update of all registers, the internal trigger must be disable before updating
61  * the timer, trigger and PWM duty cycles shadow values, and enabled once the update is done. The transfer will ocucrs at the next timer reset.
62  *
63  * \subsection features Features
64  * - This implementation allows from 1 up to 3 dual-complementary PWM channels.
65  * - Resources used:
66  * - Additionally to the linked timer resources used, the following resources are used:
67  * - 2 TOM channels per PWM channels
68  * - All TOM channels used must be own by the same TOM and TGC as for the linked timer
69  * - The TOM channel used for the timer must always have a lower index than the TOM channels
70  * used for the pwm.
71  * - All TOM channels used (including the timer and the trigger) must be contiguous but the order of the TOM channels is free.
72  *
73  *
74  * For a detailed configuration of the microcontroller, see \ref IfxGtm_Tom_PwmHl_init().
75  *
76  * \section example Usage Example
77  * Initialisation is done by, e.g:
78  * \code
79  * IfxGtm_Tom_PwmHl_Config driverConfig;
80  * IfxGtm_Tom_PwmHl driverData;
81  * IfxStdIf_PwmHl pwmhl;
82  * IfxGtm_Tom_PwmHl_initConfig(&driverConfig, &MODULE_GTM);
83  * IfxGtm_Tom_PwmHl_init(&driverData, &driverConfig);
84  * IfxGtm_Tom_PwmHl_stdIfPwmHlInit(pwmhl, &driverData);
85  * \endcode
86  *
87  * During run-time, \ref library_srvsw_stdif_pwmhl "the interface functions" shall be used, e.g.:
88  * \code
89  * IfxStdIf_Timer* timer = IfxStdIf_PwmHl_getTimer(pwmhl);
90  * Ifx_TimerValue onTime[3]; // assume configured for three HL channels
91  *
92  * onTime[0] = 10;
93  * onTime[1] = 20;
94  * onTime[2] = 30;
95  *
96  * IfxStdIf_Timer_disableUpdate(timer);
97  * IfxStdIf_Timer_setPeriod(timer, period);
98  * IfxStdIf_PwmHl_setOnTime(pwmhl, onTime);
99  * IfxStdIf_Timer_applyUpdate(timer);
100  * \endcode
101  *
102  *
103  *
104  * \defgroup IfxLld_Gtm_Tom_PwmHl TOM PWM Interface Driver
105  * \ingroup IfxLld_Gtm_Tom
106  * \defgroup IfxLld_Gtm_Tom_PwmHl_Data_Structures Data Structures
107  * \ingroup IfxLld_Gtm_Tom_PwmHl
108  * \defgroup IfxLld_Gtm_Tom_PwmHl_PwmHl_Functions PwmHl Functions
109  * \ingroup IfxLld_Gtm_Tom_PwmHl
110  * \defgroup IfxLld_Gtm_Tom_PwmHl_PwmHl_StdIf_Functions PwmHl StdIf Functions
111  * \ingroup IfxLld_Gtm_Tom_PwmHl
112  */
113 
114 #ifndef IFXGTM_TOM_PWMHL_H
115 #define IFXGTM_TOM_PWMHL_H 1
116 
117 /******************************************************************************/
118 /*----------------------------------Includes----------------------------------*/
119 /******************************************************************************/
120 
121 #include "StdIf/IfxStdIf_PwmHl.h"
123 
124 /******************************************************************************/
125 /*-----------------------------------Macros-----------------------------------*/
126 /******************************************************************************/
127 
128 /** \brief Maximal number of channels handled by the driver. One channel has a top and bottom pwm output
129  * Limited to 3 because the PWM channels used must be owned by the same TGC
130  */
131 #define IFXGTM_TOM_PWMHL_CH_MAX_CHANNELS (3)
132 
133 /******************************************************************************/
134 /*------------------------------Type Definitions------------------------------*/
135 /******************************************************************************/
136 
138 
140 
141 /******************************************************************************/
142 /*-----------------------------Data Structures--------------------------------*/
143 /******************************************************************************/
144 
145 /** \addtogroup IfxLld_Gtm_Tom_PwmHl_Data_Structures
146  * \{ */
147 /** \brief Multi-channels PWM object definition (channels only)
148  */
149 typedef struct
150 {
151  Ifx_TimerValue deadtime; /**< \brief Dead time between the top and bottom channel in ticks */
152  Ifx_TimerValue minPulse; /**< \brief minimum pulse that is output, shorter pulse time will be output as 0% duty cycle */
153  Ifx_TimerValue maxPulse; /**< \brief internal parameter */
154  Ifx_Pwm_Mode mode; /**< \brief actual PWM mode */
155  sint8 setMode; /**< \brief A non zero flag indicates that the PWM mode is being modified */
156  Ifx_ActiveState ccxActiveState; /**< \brief Top PWM active state */
157  Ifx_ActiveState coutxActiveState; /**< \brief Bottom PWM active state */
158  boolean inverted; /**< \brief Flag indicating the center aligned inverted mode (TRUE) */
159  uint8 channelCount; /**< \brief Number of PWM channels, one channel is made of a top and bottom channel */
161 
162 /** \} */
163 
164 /** \addtogroup IfxLld_Gtm_Tom_PwmHl_Data_Structures
165  * \{ */
166 /** \brief GTM TOM: PWM HL configuration
167  */
168 typedef struct
169 {
170  IfxStdIf_PwmHl_Config base; /**< \brief PWM HL standard interface configuration */
171  IfxGtm_Tom_Timer *timer; /**< \brief Pointer to the linked timer object */
172  IfxGtm_Tom tom; /**< \brief TOM unit used */
173  const IfxGtm_Tom_ToutMapP *ccx; /**< \brief Pointer to an array of size base.channelCount/2 containing the channels used. All channels used for ccx and coutx must be adjacent to the channel used for the timer, order is not important. */
174  const IfxGtm_Tom_ToutMapP *coutx; /**< \brief Pointer to an array of size base.channelCount/2 containing the channels used. All channels used for ccx and coutx must be adjacent to the channel used for the timer, order is not important */
176 
177 /** \brief Structure for PWM configuration
178  */
179 typedef struct
180 {
181  boolean inverted; /**< \brief Inverted configuration for the selected mode */
182  IfxGtm_Tom_PwmHl_Update update; /**< \brief update call back function for the selected mode */
184 
185 /** \brief GTM TOM PWM driver
186  */
188 {
189  IfxGtm_Tom_PwmHl_Base base; /**< \brief Multi-channels PWM object definition (channels only) */
190  IfxGtm_Tom_Timer *timer; /**< \brief Pointer to the linked timer object */
191  IfxGtm_Tom_PwmHl_Update update; /**< \brief Update function for actual selected mode */
192  Ifx_GTM_TOM *tom; /**< \brief TOM unit used */
193  Ifx_GTM_TOM_TGC *tgc; /**< \brief TGC unit used */
194  IfxGtm_Tom_Ch ccx[IFXGTM_TOM_PWMHL_CH_MAX_CHANNELS]; /**< \brief TOM channels used for the CCCX outputs */
195  IfxGtm_Tom_Ch coutx[IFXGTM_TOM_PWMHL_CH_MAX_CHANNELS]; /**< \brief TOM channels used for the OUTX outputs */
196  IfxGtm_Tom_Ch *ccxTemp; /**< \brief cached value */
197  IfxGtm_Tom_Ch *coutxTemp; /**< \brief cached value */
198 };
199 
200 /** \} */
201 
202 /** \addtogroup IfxLld_Gtm_Tom_PwmHl_PwmHl_Functions
203  * \{ */
204 
205 /******************************************************************************/
206 /*-------------------------Global Function Prototypes-------------------------*/
207 /******************************************************************************/
208 
209 /** \brief Initializes the timer object
210  * note To ensure that the channels counter are reset by the timer and do not overflow, leading to random signal on the output, the timer must be started before the call to this function.
211  * Note: all PWM channels must use the same TGC
212  * Note: the current implementation must use the same TGC for the timer and PWM channels
213  * \param driver GTM TOM PWM driver
214  * \param config GTM TOM: PWM HL configuration
215  * \return TRUE on success else FALSE
216  */
218 
219 /** \brief Initialize the configuration structure to default
220  * \param config Channel configuration. This parameter is Initialised by the function
221  * \return None
222  */
224 
225 /** \} */
226 
227 /** \addtogroup IfxLld_Gtm_Tom_PwmHl_PwmHl_StdIf_Functions
228  * \{ */
229 
230 /******************************************************************************/
231 /*-------------------------Global Function Prototypes-------------------------*/
232 /******************************************************************************/
233 
234 /** \brief Returns the dead time
235  * \param driver GTM TOM PWM driver
236  * \return Dead Time
237  */
239 
240 /** \brief Returns the minimum pulse
241  * \param driver GTM TOM PWM driver
242  * \return Min Pulse
243  */
245 
246 /** \brief Returns Pwm mode
247  * \param driver GTM TOM PWM driver
248  * \return Pwm mode
249  */
251 
252 /** \brief Sets the dead time
253  * \param driver GTM TOM PWM driver
254  * \param deadtime Dead time value
255  * \return TRUE on success else FALSE
256  */
258 
259 /** \brief Sets the minimum pulse
260  * \param driver GTM TOM PWM driver
261  * \param minPulse Minimum pulse
262  * \return TRUE on success else FALSE
263  */
265 
266 /** \brief Sets the PWM mode, the mode is only applied after setOnTime() + applyUpdate()
267  * \param driver GTM TOM PWM driver
268  * \param mode Pwm mode
269  * \return TRUE on success else FALSE
270  */
272 
273 /** \brief Sets the ON time
274  * \param driver GTM TOM PWM driver
275  * \param tOn ON time
276  * \return None
277  */
279 
280 /** \brief Set up channels
281  * \param driver GTM TOM PWM driver
282  * \param activeCh Active channel
283  * \param stuckSt Stuck state
284  * \return None
285  */
286 IFX_EXTERN void IfxGtm_Tom_PwmHl_setupChannels(IfxGtm_Tom_PwmHl *driver, boolean *activeCh, boolean *stuckSt);
287 
288 /** \brief Initialises the statndard interface Pwm
289  * \param stdif standard interface object, will be initialized by the function
290  * \param driver device driver object used by the standard interface. must be initialised separately
291  * \return TRUE on success else FALSE
292  */
294 
295 /** \} */
296 
297 #endif /* IFXGTM_TOM_PWMHL_H */