1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/kernel/kpower.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,364 @@
1.4 +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// e32\include\kernel\kpower.h
1.18 +// Public header for power management
1.19 +//
1.20 +// WARNING: This file contains some APIs which are internal and are subject
1.21 +// to change without notice. Such APIs should therefore not be used
1.22 +// outside the Kernel and Hardware Services package.
1.23 +//
1.24 +
1.25 +
1.26 +#ifndef __K32POWER_H__
1.27 +#define __K32POWER_H__
1.28 +
1.29 +#include <e32power.h>
1.30 +#include <kernel/kernel.h>
1.31 +
1.32 +/**
1.33 +@internalTechnology
1.34 +*/
1.35 +#define __PM_ASSERT(aCond) \
1.36 + __ASSERT_DEBUG( (aCond), \
1.37 + ( \
1.38 + Kern::Printf("Assertion '" #aCond "' failed;\nFile: '" __FILE__ "' Line: %d\n", __LINE__), \
1.39 + Kern::Fault("Power Management", 0) \
1.40 + ) )
1.41 +
1.42 +/**
1.43 +@internalTechnology
1.44 +*/
1.45 +#define __PM_PANIC(aMsg) \
1.46 + (\
1.47 + Kern::Printf("PANIC:'" aMsg "';\nFile: '" __FILE__ "' Line: %d\n", __LINE__), \
1.48 + Kern::Fault("Power Management", 0) \
1.49 + )
1.50 +
1.51 +
1.52 +
1.53 +
1.54 +/**
1.55 +@publishedPartner
1.56 +@released
1.57 +
1.58 +Interface and support functions for a power controller implementation.
1.59 +
1.60 +A power controller implementation depends on the specific power management
1.61 +hardware and is typically variant-dependent.
1.62 +
1.63 +The class defines the interface that any power controller implementation
1.64 +must provide to the generic kernel-side power manager.
1.65 +It also provides the power controller with an API to the power manager.
1.66 +*/
1.67 +class DPowerController : public DBase
1.68 + {
1.69 +public:
1.70 + IMPORT_C DPowerController();
1.71 + IMPORT_C void Register();
1.72 + IMPORT_C void WakeupEvent();
1.73 +#ifndef __X86__
1.74 + IMPORT_C TInt RegisterResourceController(DBase* aController, TInt aClientId);
1.75 +protected:
1.76 + struct SResourceControllerData
1.77 + {
1.78 + DBase* iResourceController;
1.79 + TInt iClientId;
1.80 + }iResourceControllerData;
1.81 +#endif
1.82 +public:
1.83 +
1.84 +
1.85 + /**
1.86 + The target power state of the last, possibly still not completed,
1.87 + kernel transition.
1.88 + */
1.89 + volatile TPowerState iTargetState;
1.90 +public:
1.91 +
1.92 +
1.93 + /**
1.94 + Puts the CPU into the Idle mode.
1.95 + */
1.96 + virtual void CpuIdle() = 0;
1.97 +
1.98 +
1.99 + /**
1.100 + Enables wakeup events.
1.101 +
1.102 + When called, iTargetState is guaranteed NOT to be equal to EPwActive.
1.103 +
1.104 + After this call, and until a DisableWakeupEvents() or PowerDown() call,
1.105 + the power controller must track and signal wakeup events corresponding
1.106 + to iTargetState.
1.107 +
1.108 + @see DPowerController::iTargetState
1.109 + @see TPowerState
1.110 + */
1.111 + virtual void EnableWakeupEvents() = 0;
1.112 +
1.113 +
1.114 + /**
1.115 + Disables wakeup events.
1.116 +
1.117 + When called, iTargetState is guaranteed to be equal to EPwActive.
1.118 +
1.119 + After this call, the power controller must stop signalling wakeup events.
1.120 +
1.121 + @see DPowerController::iTargetState
1.122 + @see TPowerState
1.123 + */
1.124 + virtual void DisableWakeupEvents() = 0;
1.125 +
1.126 +
1.127 + /**
1.128 + Notifies an absolute timer expiration.
1.129 +
1.130 + The power controller implementation must call WakeupEvent() if absolute
1.131 + timer expiration is currently tracking wakeup events.
1.132 + */
1.133 + virtual void AbsoluteTimerExpired() = 0;
1.134 +
1.135 +
1.136 + /**
1.137 + Puts the CPU into the low power state.
1.138 +
1.139 + When called, iTargetState is guaranteed NOT to be equal to EPwActive.
1.140 +
1.141 + If iTargetState is EPwStandby, the power controller will put
1.142 + the hardware into standby.
1.143 +
1.144 + If at least one wakeup event has been detected since the last
1.145 + call to EnableWakeupEvents(), then PowerDown() returns immediately;
1.146 + otherwise, PowerDown() returns when a wakeup event occurs.
1.147 +
1.148 + When PowerDown() returns, wakeup events must be considered as disabled.
1.149 +
1.150 + If iTargetState is EPwOff, then PowerDown() must never return.
1.151 + Typically, it turns the platform off, but may perform any other
1.152 + platform-specific action such as system reboot.
1.153 +
1.154 + @param aWakeupTime If not zero, specifies the system time when
1.155 + the system will wakeup.
1.156 +
1.157 + @see DPowerController::iTargetState
1.158 + @see TPowerState
1.159 + */
1.160 + virtual void PowerDown(TTimeK aWakeupTime) = 0;
1.161 + };
1.162 +
1.163 +#ifndef __X86__
1.164 +/**
1.165 +@internalTechnology
1.166 +@prototype 9.5
1.167 +*/
1.168 +class TPowerController
1.169 + {
1.170 +public:
1.171 + IMPORT_C static DPowerController* PowerController();
1.172 +public:
1.173 + static DPowerController* ThePowerController;
1.174 + };
1.175 +#endif
1.176 +
1.177 +/**
1.178 +@internalTechnology
1.179 +*/
1.180 +class DBatteryMonitor
1.181 + {
1.182 +public:
1.183 + IMPORT_C DBatteryMonitor();
1.184 + IMPORT_C void Register();
1.185 +public:
1.186 + virtual TSupplyStatus MachinePowerStatus() = 0;
1.187 + virtual void SystemTimeChanged(TInt anOldTime, TInt aNewTime) = 0;
1.188 + };
1.189 +
1.190 +/**
1.191 +@internalTechnology
1.192 +*/
1.193 +class DPowerHal : public DBase
1.194 + {
1.195 +public:
1.196 + IMPORT_C DPowerHal();
1.197 + IMPORT_C void Register();
1.198 +public:
1.199 + virtual TInt PowerHalFunction(TInt aFunction, TAny* a1, TAny* a2) = 0;
1.200 + };
1.201 +
1.202 +
1.203 +/**
1.204 +@publishedPartner
1.205 +@released
1.206 +
1.207 +Interface and support functions for a device driver's power-handler.
1.208 +
1.209 +There is typically one power handler object per peripheral. The object
1.210 +is typically implemented by the peripheral's device driver.
1.211 +
1.212 +The class defines the interface that the driver must provide to
1.213 +the generic kernel-side power manager.
1.214 +
1.215 +It also provides the driver with an API to the kernel-side power manager.
1.216 +*/
1.217 +class DPowerHandler : public DBase
1.218 + {
1.219 +public: // from DBase
1.220 + IMPORT_C ~DPowerHandler();
1.221 +public:
1.222 + IMPORT_C DPowerHandler(const TDesC& aName);
1.223 + IMPORT_C void Add();
1.224 + IMPORT_C void Remove();
1.225 + IMPORT_C void PowerUpDone();
1.226 + IMPORT_C void PowerDownDone();
1.227 + /** @deprecated, no replacement */
1.228 + IMPORT_C void SetCurrentConsumption(TInt aCurrent);
1.229 + /** @deprecated, no replacement */
1.230 + IMPORT_C void DeltaCurrentConsumption(TInt aCurrent);
1.231 +public:
1.232 + /**
1.233 + Requests peripheral power down.
1.234 +
1.235 + The power manager calls PowerDown() during a transition to standby
1.236 + or power off.
1.237 +
1.238 + The driver must signal the completion of peripheral power down to
1.239 + the power manager by calling PowerDownDone().
1.240 + Note that PowerDownDone() can be called from the path of PowerDown(),
1.241 + as well as asynchronously by another thread before or
1.242 + after PowerDown() returns.
1.243 +
1.244 + Note that the implementation of Add() & Remove() acquires
1.245 + an internal lock (a DMutex), which is also held when the power manager
1.246 + calls PowerDown(). This means that the device driver cannot hold a lock
1.247 + over Add() & Remove() calls if the same lock is acquired
1.248 + by PowerDown() implementations.
1.249 +
1.250 + You can find an example of synchronization between outgoing Add() & Remove()
1.251 + and incoming PowerDown() in e32/drivers/ecomm/d_comm.cpp.
1.252 +
1.253 + @param aState the target power state; can be EPwStandby or EPwOff only
1.254 + */
1.255 + virtual void PowerDown(TPowerState aState) = 0;
1.256 +
1.257 + /**
1.258 + Notifies the peripheral of system power up.
1.259 +
1.260 + The power manager calls PowerUp() during a transition from standby.
1.261 +
1.262 + It is up to the device driver's policy whether to power up the periphiral or not.
1.263 + The driver must signal the completion of the operation to the power manager by calling PowerUpDone().
1.264 + Note that PowerUpDone() can be called from the path of PowerUp(), as well as asynchronously by another
1.265 + thread before or after PowerUp() returns.
1.266 +
1.267 + Note that the implementation of Add() & Remove() acquires
1.268 + an internal lock (a DMutex), which is also held when the power manager
1.269 + calls PowerUp(). This means that the device driver cannot hold a lock
1.270 + over Add() & Remove() calls if the same lock is acquired
1.271 + by PowerUp() implementations.
1.272 +
1.273 + You can find an example of synchronization between outgoing Add() & Remove()
1.274 + and incoming PowerUp() in e32/drivers/ecomm/d_comm.cpp.
1.275 + */
1.276 + virtual void PowerUp() = 0;
1.277 +
1.278 +private:
1.279 + friend class DPowerManager;
1.280 +
1.281 + typedef TUint8 TStatus;
1.282 + enum { EDone = 0x01 };
1.283 +
1.284 + void Wait();
1.285 + void Done();
1.286 +
1.287 + const TDesC& iName;
1.288 + DPowerHandler* iNext;
1.289 + DPowerHandler* iPrev;
1.290 + NFastSemaphore* iSem;
1.291 + TStatus iStatus;
1.292 + TUint8 i_DPowerHandler_Spare[3];
1.293 + TInt iCurrent;
1.294 + };
1.295 +
1.296 +
1.297 +
1.298 +
1.299 +/**
1.300 +@publishedPartner
1.301 +@released
1.302 +
1.303 +The recommended interface for objects that represent shared power sources.
1.304 +
1.305 +The objects representing shared power sources are typically implemented by
1.306 +the variant and used by device drivers.
1.307 +
1.308 +We recommend that these objects implement the MPowerInput interface.
1.309 +*/
1.310 +class MPowerInput
1.311 + {
1.312 +public:
1.313 +
1.314 +
1.315 + /**
1.316 + Signals that the power source is in use.
1.317 +
1.318 + Typically, a driver calls this function when it needs the source
1.319 + to be powered on.
1.320 +
1.321 + A typical implementation associates a counter with the object.
1.322 + The initial counter's value is 0. Use() increments the counter and, if
1.323 + the counter's value changes from 0 to 1, powers on the source.
1.324 + */
1.325 + virtual void Use() = 0;
1.326 +
1.327 +
1.328 + /**
1.329 + Signals that the power source is not in use.
1.330 +
1.331 + Typically, a driver calls this function when it no longer needs
1.332 + the source to be powered on.
1.333 +
1.334 + A typical implementation associates a counter with the object.
1.335 + The initial counter's value is 0. While the implementation of
1.336 + Use() would increment the counter, Release() would decrement it.
1.337 + If the counter's value changes from 1 to 0, Release() powers off
1.338 + the source.
1.339 + */
1.340 + virtual void Release() = 0;
1.341 + };
1.342 +
1.343 +//
1.344 +// Kernel private
1.345 +//
1.346 +
1.347 +/**
1.348 +@internalAll
1.349 +*/
1.350 +class DPowerModel : public DBase
1.351 + {
1.352 +public:
1.353 + virtual void AbsoluteTimerExpired() = 0;
1.354 + virtual void RegisterUserActivity(const TRawEvent& anEvent) = 0;
1.355 +public:
1.356 + virtual void CpuIdle() = 0;
1.357 +public:
1.358 + virtual void SystemTimeChanged(TInt anOldTime, TInt aNewTime) = 0;
1.359 + virtual TSupplyStatus MachinePowerStatus() = 0;
1.360 +public:
1.361 + virtual TInt PowerHalFunction(TInt aFunction, TAny* a1, TAny* a2) = 0;
1.362 + };
1.363 +
1.364 +TInt PowerModelInit();
1.365 +
1.366 +#endif
1.367 +