|
1 /* |
|
2 pm_thermalsensing_chipset_api.h |
|
3 |
|
4 Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). |
|
5 All rights reserved. |
|
6 |
|
7 This program and the accompanying materials are made available |
|
8 under the terms of the Eclipse Public License v1.0 which accompanies |
|
9 this distribution, and is available at |
|
10 http://www.eclipse.org/legal/epl-v10.html |
|
11 |
|
12 Initial Contributors: |
|
13 Nokia Corporation - initial contribution. |
|
14 |
|
15 Contributors: |
|
16 */ |
|
17 |
|
18 /** @file |
|
19 @brief Thermal sensing chipset API |
|
20 |
|
21 @publishedDeviceAbstraction |
|
22 */ |
|
23 |
|
24 #ifndef __PM_THERMALSENSING_CHIPSET_API_H__ |
|
25 #define __PM_THERMALSENSING_CHIPSET_API_H__ |
|
26 |
|
27 |
|
28 // Include files |
|
29 |
|
30 #include <kern_priv.h> |
|
31 |
|
32 |
|
33 /** |
|
34 Description of the function pointer |
|
35 |
|
36 @note Description Callback Function which is being executed from DFC |
|
37 |
|
38 @param TAny* Any type of parameter passed to the callback function |
|
39 */ |
|
40 typedef void (*TthermalSensorCbFn(TAny* aParam)); |
|
41 |
|
42 // Forward declarations |
|
43 |
|
44 class TthermalSensorCb; |
|
45 class ChipsetThermalSensorHWPool; |
|
46 class DThermalSensorHW; |
|
47 |
|
48 |
|
49 // Class declaration |
|
50 /** |
|
51 * |
|
52 * Thermal Sensor Callback function |
|
53 * |
|
54 */ |
|
55 class TthermalSensorCb : public TDfc |
|
56 { |
|
57 |
|
58 public : |
|
59 /** |
|
60 Description of TthermalSensorCb |
|
61 This is the Thermal Sensor Callback Function |
|
62 @param aFn Callback Function Pointer |
|
63 @param aParam Any type of parameter passed to the callback function |
|
64 @param aPriority Priority Assigned |
|
65 @return KErrNone or a system wide error code to specify the effect of the method call. |
|
66 @pre This can be called only after the ChipsetThermalSensorHWPool has been initialized |
|
67 in the system. Preferable way to call this function is from a thread context with |
|
68 interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
69 */ |
|
70 IMPORT_C TthermalSensorCb(TthermalSensorCbFn aFn, TAny *aParam, TInt aPriority); |
|
71 /** |
|
72 Description of TthermalSensorCb |
|
73 This is the Thermal Sensor Callback Function |
|
74 @param aFn Callback Function Pointer |
|
75 @param aParam Any type of parameter passed to the callback function |
|
76 @param aPriority Priority Assigned |
|
77 @param aQue Interrupt Handling DFC queue. The same queue is used by the HW specific interface |
|
78 @return KErrNone or a system wide error code to specify the effect of the method call. |
|
79 @pre This can be called only after the ChipsetThermalSensorHWPool has been initialized |
|
80 in the system. Preferable way to call this function is from a thread context with |
|
81 interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
82 */ |
|
83 IMPORT_C TthermalSensorCb(TthermalSensorCbFn aFn, TAny *aParam, TInt aPriority, TDfcQue* aQue); |
|
84 |
|
85 private : |
|
86 |
|
87 static void CallbackFunc( TAny *); |
|
88 |
|
89 private : |
|
90 /*** Any type of parameter passed to the callback function */ |
|
91 TAny* iParam; |
|
92 |
|
93 /*** Callback Function Pointer */ |
|
94 TthermalSensorCbFn iCallback; |
|
95 |
|
96 }; |
|
97 |
|
98 /** |
|
99 @brief Class acting as a container class for several sensor objects |
|
100 |
|
101 This class acts as a repository using which the references to the specific thermal sensor |
|
102 interface can be accessed. The recommendation is to implement this as a Singleton class. |
|
103 */ |
|
104 class ChipsetThermalSensorHWPool |
|
105 { |
|
106 // Methods |
|
107 public : |
|
108 enum TthermalSensorID |
|
109 { |
|
110 /// Invalid Sensor ID to be used if system design does not have any thermal sensor. |
|
111 EInvalidThermalSensor = 0x0, |
|
112 /// Battery Specific Sensing |
|
113 EBatteryThermalSensor, |
|
114 /// DRAM Specific Sensing |
|
115 EDRAMThermalSensor, |
|
116 /// RF ASIC Specific Sensors |
|
117 ERFThermalSensor, |
|
118 /// Memory Card Specific Sensors |
|
119 EMemoryCardThermalSensor, |
|
120 /// SOC Specific Sensors |
|
121 EAPEThermalSensor, |
|
122 /// Camera Module Specific Sensors |
|
123 ECameraThermalSensor, |
|
124 /// GPS Module Specific Sensors |
|
125 EGPSThermalSensor, |
|
126 /// Display Module Specific Sensors |
|
127 EDisplayThermalSensor, |
|
128 /// Chipset Specific Sensors |
|
129 EChipsetCustom1ThermalSensor, |
|
130 EChipsetCustom2ThermalSensor, |
|
131 EChipsetCustom3hermalSensor, |
|
132 EChipsetCustom4ThermalSensor, |
|
133 EChipsetCustom5ThermalSensor, |
|
134 EChipsetCustom6ThermalSensor |
|
135 }; |
|
136 |
|
137 /** |
|
138 Description of GetThermalSensorHW |
|
139 This is the method to get the pointer of the DThermalSensorHW object from the |
|
140 ChipsetThermalSensorHWPool. |
|
141 @param aId input parameter specifying the ID of the thermal sensor whose pointer we are |
|
142 trying to reference. |
|
143 @param aSensor output parameter giving the pointer of the thermal sensor object representing |
|
144 the ID requested or NULL if the thermal sensor do not exist in the system. |
|
145 @return KErrNone or a system wide error code to specify the effect of the method call. |
|
146 @pre This can be called only after the ChipsetThermalSensorHWPool has been initialized |
|
147 in the system. Preferable way to call this function is from a thread context with |
|
148 interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
149 */ |
|
150 |
|
151 IMPORT_C static TInt GetThermalSensorHW(TthermalSensorID aId, DThermalSensorHW** aSensor); |
|
152 |
|
153 /** |
|
154 Description of GetNumberOfSensors |
|
155 This is the method to get the number of sensors supported by the chipset adaptation software. |
|
156 In addition it should give the highest and lowest identifier for the sensors to optimize the search |
|
157 possibilities for the client software. |
|
158 @param aHighestID output parameter that gives the ID of the thermal sensor with the most positive value |
|
159 or 0 if no sensor is present. |
|
160 @param aLowestID output parameter that gives the ID of the thermal sensor with the least positive value |
|
161 or 0 if no sensor is present. |
|
162 @return number of sensors in the system (+ve value or 0) or |
|
163 a system wide error code to specify the effect of the method call. |
|
164 @pre This can be called only after the ChipsetThermalSensorHWPool has been initialized |
|
165 in the system. |
|
166 */ |
|
167 IMPORT_C static TInt GetNumberOfSensors(TthermalSensorID& aHighestID, TthermalSensorID& aLowestID); |
|
168 |
|
169 }; |
|
170 |
|
171 |
|
172 /** |
|
173 * |
|
174 * This class represents a generic thermal sensor that would be found in the HW. |
|
175 * The pointer of the thermal sensor object would be passed to the client who can then call the virtual methods that are exposed by this interface. |
|
176 * |
|
177 */ |
|
178 NONSHARABLE_CLASS( DThermalSensorHW ) : public DBase |
|
179 { |
|
180 public : |
|
181 /** |
|
182 Constructor |
|
183 Defined as a private to prevent clients to create own instances |
|
184 from this class |
|
185 @since ver 1 |
|
186 @param none |
|
187 @return none |
|
188 @panic none |
|
189 */ |
|
190 DThermalSensorHW(); |
|
191 |
|
192 /** |
|
193 Virtual Destructor |
|
194 @since ver 1 |
|
195 @param none |
|
196 @return none |
|
197 @panic none |
|
198 */ |
|
199 virtual ~DThermalSensorHW(); |
|
200 |
|
201 /** |
|
202 Description of InitHw |
|
203 This is the method by which the HW is initialized in the system. |
|
204 The implementation has to take care that the HW is initialized only once even though this method can be called multiple times. |
|
205 The main motivation for this method is that the client becomes sure about the functional state of the HW after it calls this method. |
|
206 There are several scenarios possible when the interface is called. For example, |
|
207 • If the HW cannot be initialized then the implementation should return KErrNotReady or KErrNotSupported depending on the scenario. |
|
208 • If the HW can be initialized then the call would do the necessary initializations and reply with KErrNone. |
|
209 • If the HW is already initialized, then the call should return immediately without changing the HW state and return value should also be KErrNone. |
|
210 @since ver 1 |
|
211 @param none |
|
212 @return KErrNone if success |
|
213 otherwise system wide error code to let the client know about the status of the HW |
|
214 @panic none |
|
215 @ pre This can be called at any time after the kernel extensions have been loaded. |
|
216 The preferable way to call this function is from a thread context with interrupts enabled. |
|
217 */ |
|
218 virtual TInt InitHw() = 0; |
|
219 |
|
220 /** |
|
221 Description of SetupAlert |
|
222 This is the method to set up a callback mechanism when temperature moves outside the range |
|
223 [alerts should occur when temperature is higher than high temperature limit (aTmpHigh) and lower than the low temperature limit (aTmpHigh – aTmpDiff)] |
|
224 presented in the arguments of this method. Only one client is permitted to call this API because this controls the functional behavior of the thermal sensor. |
|
225 If the boundary condition is already set and another client calls this method the call would not have any functional effect and the callback would not be registered. |
|
226 @since ver 1 |
|
227 @param aTmpHigh The higher boundary of the temperature range in Kelvin. |
|
228 The callback specified would be triggered if the temperature of the sensor becomes greater than this level |
|
229 @param aTmpDiff difference between THIGH and TLOW |
|
230 @param aCb this is the DFC that should be queued when the temperature of the sensor moves outside the range specified by the boundaries |
|
231 @return KErrNone if success |
|
232 KErrAlreadyExists if the boundary values are already specified |
|
233 otherwise system wide error code |
|
234 @panic none |
|
235 @pre the preferable way to call this function is from a thread context with interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
236 */ |
|
237 virtual TInt SetupAlert(TInt16 aTmpHigh, TInt16 aTmpDiff,TthermalSensorCb *aCb) = 0; |
|
238 |
|
239 /** |
|
240 Description of SetupCallBack |
|
241 This is the method to register callbacks for the current prevailing boundary conditions for a particular sensor. |
|
242 This function is needed because only the controlling client is allowed to call the SetupAlert API, hence this API needs to be used by all other observer clients |
|
243 @since ver 1 |
|
244 @param aCb This is the DFC that should be queued when the temperature of the sensor moves outside the range specified by the boundaries set before in the SetAlert method. |
|
245 @return KErrNone if success |
|
246 otherwise system wide error code |
|
247 @panic none |
|
248 @pre The preferable way to call this function is from a thread context with interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
249 */ |
|
250 virtual TInt SetupCallBack(TthermalSensorCb *aCb) = 0; |
|
251 |
|
252 /** |
|
253 Description of StopAlert |
|
254 This is the method to cancel callbacks or the entire alert mechanism for a particular sensor. |
|
255 @since ver 1 |
|
256 @param stopAll If this true then the Alert mechanism is stopped altogether and the sensing HW is disabled until the next InitHW is called. |
|
257 It is recommended that only the client who has called SetupAlert successfully before calls this method. |
|
258 In other cases only the callback function is removed. If the callback function was the one used in the SetupAlert call before |
|
259 then the Alert mechanism is disabled also before the next SetupAlert is called. |
|
260 @param aCb This is the DFC that should be removed from the list of callbacks. |
|
261 @return KErrNone if success |
|
262 otherwise system wide error code |
|
263 @panic none |
|
264 @pre This can only be called after SetupAlert API or SetupCallback API |
|
265 The preferable way to call this function is from a thread context with interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
266 */ |
|
267 virtual TInt StopAlert(TBool stopAll, TthermalSensorCb *aCb) = 0; |
|
268 |
|
269 |
|
270 /** |
|
271 Description of ReadTempData |
|
272 This is the method to read temperature data from a particular sensor |
|
273 @since ver 2 |
|
274 @param tmpData stores the current temperature reading |
|
275 @param aNewRead checks whether a new read is required for temperature |
|
276 @return KErrNone if success |
|
277 otherwise system wide error code |
|
278 @panic none |
|
279 @pre The preferable way to call this function is from a thread context with interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
280 */ |
|
281 virtual TInt ReadTempData(TInt16& tmpData, TBool aNewRead) = 0; |
|
282 |
|
283 /** |
|
284 Description of PeformHWSelfTest |
|
285 This is the method to performing self test on the underlying thermal sensor HW. This method should be self contained meaning it should be able to save the context , |
|
286 perform the self test and then restore the context back exactly to the state before the self test. |
|
287 @since ver 2 |
|
288 @param none |
|
289 @return KErrNone if success |
|
290 otherwise system wide error code |
|
291 @panic none |
|
292 @pre The preferable way to call this function is from a thread context with interrupts enabled after all the kernel extensions have been initialized in the boot up. |
|
293 */ |
|
294 virtual TInt PerformHWSelfTest(void) = 0; |
|
295 }; |
|
296 |
|
297 #endif // __PM_THERMALSENSING_CHIPSET_API_H__ |