iLLD_TC27xC  1.0
IfxDts_Dts.h
Go to the documentation of this file.
1 /**
2  * \file IfxDts_Dts.h
3  * \brief DTS DTS details
4  * \ingroup IfxLld_Dts
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_Dts_Dts_Usage How to use the DTS Interface driver?
25  * \ingroup IfxLld_Dts
26  *
27  * DTS gives the die-temperature result which will decoded to standard temperature value. Minimum first two temperature results are to be ignored to get reliable temperature.
28  *
29  * In the following sections it will be described, how to integrate the driver into the application framework.
30  *
31  * \section IfxLld_Dts_Dts_Preparation Preparation
32  * \subsection IfxLld_Dts_Dts_Include Include Files
33  *
34  * Include following header file into your C code:
35  *
36  * \code
37  * #include <Dts/Dts/IfxDts_Dts.h>
38  * \endcode
39  *
40  * \subsection IfxLld_Dts_Dts_Interrupt Interrupt Handler Installation
41  *
42  * See also \ref IfxLld_Cpu_Irq_Usage
43  *
44  * Define priorities for the Interrrupt handler. This is normally done in the Ifx_IntPrioDef.h file:
45  * \code
46  * // priorities are normally defined in Ifx_IntPrioDef.h
47  * #define IFX_INTPRIO_DTS 1
48  * \endcode
49  *
50  * Add the interrupt service routine to your C code which should do the error flag handling:
51  * \code
52  * IFX_INTERRUPT(dtsISR, 0, IFX_INTPRIO_DTS)
53  * {
54  * // DTS finished temperature measurement
55  *
56  * uint16 temperatureValue = IfxDts_Dts_getTemperatureValue();
57  * // here we could do something with the value...
58  *
59  * // and the DTS can be restarted
60  * IfxDts_Dts_startSensor();
61  * }
62  * \endcode
63  *
64  * Finally install the interrupt handler in your initialisation function:
65  * \code
66  * // install interrupt handler
67  * IfxCpu_Irq_installInterruptHandler(&dtsISR, IFX_INTPRIO_DTS);
68  * IfxCpu_enableInterrupts();
69  * \endcode
70  *
71  * \subsection IfxLld_Dts_Dts_Module DTS Module Initialisation
72  *
73  * The module initialisation can be done in the same function:
74  * \code
75  * // Get the default configuration
76  * IfxDts_Dts_Config dtsConfig;
77  * IfxDts_Dts_initModuleConfig(&dtsConfig);
78  *
79  * // Adapt the default configuration if required
80  * dtsConfig.isrPriority = IFX_INTPRIO_DTS;
81  * dtsConfig.isrTypeOfService = (IfxSrc_Tos)IfxCpu_getCoreId();
82  * dtsConfig.lowerTemperatureLimit = -35; // SMU alarm if temperature value is below this Celsius value
83  * dtsConfig.upperTemperatureLimit = 150; // SMU alarm if temperature value is above this Celsius value
84  *
85  * // Module initialisation
86  * IfxDts_Dts_initModule(&dtsConfig);
87  * \endcode
88  *
89  * Now, DTS is initialised for starting temperature measurements:
90  * \code
91  * IfxDts_Dts_startSensor();
92  * \endcode
93  *
94  *
95  * \subsection IfxLld_Dts_Dts_IrqBased IRQ based measurements
96  *
97  * Whenever the interrupt handler is called, a new measurment result is available and could be processed further (e.g. for statistical analysis).
98  *
99  * \code
100  * IFX_INTERRUPT(dtsISR, 0, IFX_INTPRIO_DTS)
101  * {
102  * // DTS finished temperature measurement
103  *
104  * uint16 temperatureValue = IfxDts_Dts_getTemperatureValue();
105  * // here we could do something with the value...
106  *
107  * // and the DTS can be restarted
108  * IfxDts_Dts_startSensor();
109  * }
110  * \endcode
111  *
112  *
113  * \subsection IfxLld_Dts_Dts_NonIrqBased Measurements without IRQs
114  *
115  * If no interrupt routine should be used, a new measurement result can be requested the following way:
116  *
117  * \code
118  * // start Sensor
119  * IfxDts_Dts_startSensor();
120  *
121  * // wait until a new result is available
122  * while( IfxDts_Dts_isBusy() );
123  *
124  * uint16 temperatureValue = IfxDts_Dts_getTemperatureValue();
125  * \endcode
126  *
127  *
128  * Alternatively (and this is the normal usage), the DTS could be periodically started from a timer routine, e.g. each mS. The conversion itself takes 100 uS maximum.
129  *
130  *
131  * \subsection IfxLld_Dts_Dts_Converted Temperature conversion
132  *
133  * Following function returns the actual temperature in Celsius:
134  *
135  * \code
136  * float32 temperature = IfxDts_Dts_getTemperatureCelsius();
137  * \endcode
138  *
139  * \defgroup IfxLld_Dts_Dts Dts
140  * \ingroup IfxLld_Dts
141  * \defgroup IfxLld_Dts_Dts_Structures Data Structures
142  * \ingroup IfxLld_Dts_Dts
143  * \defgroup IfxLld_Dts_Dts_Module Module Initialisation functions
144  * \ingroup IfxLld_Dts_Dts
145  * \defgroup IfxLld_Dts_Dts_Sensor Sensor Functions
146  * \ingroup IfxLld_Dts_Dts
147  * \defgroup IfxLld_Dts_Dts_Conversion Conversion Functions
148  * \ingroup IfxLld_Dts_Dts
149  */
150 
151 #ifndef IFXDTS_DTS_H
152 #define IFXDTS_DTS_H 1
153 
154 /******************************************************************************/
155 /*----------------------------------Includes----------------------------------*/
156 /******************************************************************************/
157 
158 #include "Dts/Std/IfxDts.h"
159 
160 /******************************************************************************/
161 /*-----------------------------Data Structures--------------------------------*/
162 /******************************************************************************/
163 
164 /** \addtogroup IfxLld_Dts_Dts_Structures
165  * \{ */
166 /** \brief DTS module configuration structure
167  */
168 typedef struct
169 {
170  boolean sensorControlDisabled; /**< \brief MODULE_SCU.DTSCON.SCLK, specifies the control register lock except MODULE_SCU.DTSCON.START. */
171  float32 lowerTemperatureLimit; /**< \brief Specifies the lower temperature limit compared against die temperature in Celsius
172  *
173  * A SMU will be triggered if the measurement result is below this limit */
174  float32 upperTemperatureLimit; /**< \brief Specifies the upper temperature limit compared against die temperature in Celsius.
175  *
176  * A SMU will be triggered if the measurement result is above this limit */
177  uint16 isrPriority; /**< \brief interrupt priority */
178  IfxSrc_Tos isrTypeOfService; /**< \brief type of interrupt service */
179  boolean enableSecureLock; /**< \brief MODULE_SCU.DTSCON.SLCK,MODULE_SCU.DTSLIM.SLCK, Specifies the Security Lock for Configuration and Limitation register. */
181 
182 /** \} */
183 
184 /** \addtogroup IfxLld_Dts_Dts_Module
185  * \{ */
186 
187 /******************************************************************************/
188 /*-------------------------Global Function Prototypes-------------------------*/
189 /******************************************************************************/
190 
191 /** \brief Initialise the DTS with supplied configuration.
192  * \param config pointer to module configuration structure
193  * \return None
194  *
195  * Usage Example : \ref IfxLld_Dts_Dts_Usage
196  *
197  */
199 
200 /** \brief Intialises the module configuration buffer with default configuration.
201  * \param config pointer to module configuration structure
202  * \return None
203  *
204  * Usage Example : \ref IfxLld_Dts_Dts_Usage
205  *
206  */
208 
209 /** \} */
210 
211 /** \addtogroup IfxLld_Dts_Dts_Sensor
212  * \{ */
213 
214 /******************************************************************************/
215 /*-------------------------Inline Function Prototypes-------------------------*/
216 /******************************************************************************/
217 
218 /** \brief Returns the converted temperature in Celsius
219  * \return The temperature based on the DTS temperature value
220  *
221  * Usage Example : \ref IfxLld_Dts_Dts_Usage
222  *
223  */
225 
226 /** \brief Returns the unconverted temperature measurement result
227  * \return current sensor measured result.
228  *
229  * Usage Example : \ref IfxLld_Dts_Dts_Usage
230  *
231  */
233 
234 /** \brief Returns the current BUSY status of the Sensor
235  * \return TRUE if Sensor is busy in measuring temperature otherwise FALSE
236  *
237  * Usage Example : \ref IfxLld_Dts_Dts_Usage
238  *
239  */
240 IFX_INLINE boolean IfxDts_Dts_isBusy(void);
241 
242 /** \brief Starts the next temperature measurement.
243  * \return None
244  *
245  * Usage Example : \ref IfxLld_Dts_Dts_Usage
246  *
247  */
249 
250 /** \} */
251 
252 /** \addtogroup IfxLld_Dts_Dts_Conversion
253  * \{ */
254 
255 /******************************************************************************/
256 /*-------------------------Global Function Prototypes-------------------------*/
257 /******************************************************************************/
258 
259 /** \brief Converts a temperature value in Celsius to DTS value
260  * \param temperatureValue the temperature in Celsius
261  * \return the appr. DTS value
262  */
264 
265 /** \brief Converts the measurement value returned from DTS to Celsius
266  * \param dtsValue measurement value returned from DTS
267  * \return temperature in Celsius
268  */
270 
271 /** \} */
272 
273 /******************************************************************************/
274 /*---------------------Inline Function Implementations------------------------*/
275 /******************************************************************************/
276 
278 {
280 }
281 
282 
284 {
286 }
287 
288 
290 {
291  return IfxDts_isBusy();
292 }
293 
294 
296 {
297  /* start sensor */
299 
300  /* one dummy read to a SCU register which ensures that the BUSY flag is synchronized
301  * into the status register before IfxDts_Dts_isBusy() is called */
302  if (IfxDts_isBusy())
303  {}
304 }
305 
306 
307 #endif /* IFXDTS_DTS_H */