diff -r 000000000000 -r a41df078684a kernel/eka/include/drivers/pbus.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/kernel/eka/include/drivers/pbus.h Mon Oct 19 15:55:17 2009 +0100 @@ -0,0 +1,809 @@ +// Copyright (c) 1998-2009 Nokia Corporation and/or its subsidiary(-ies). +// All rights reserved. +// This component and the accompanying materials are made available +// under the terms of the License "Eclipse Public License v1.0" +// which accompanies this distribution, and is available +// at the URL "http://www.eclipse.org/legal/epl-v10.html". +// +// Initial Contributors: +// Nokia Corporation - initial contribution. +// +// Contributors: +// +// Description: +// e32\include\drivers\pbus.h +// +// + +/** + @file + @publishedPartner + @released +*/ + +#ifndef __P32STD_H__ +#define __P32STD_H__ +#include + +#ifdef _DEBUG +#define __ENABLE_SIMULATED_MEDIA_CHANGE // Enables simulation of media change events using ControlIO +#endif + +/******************************************** + * Peripheral Bus Definitions + ********************************************/ + +/** +Defines the maximum number of media change objects. + +@see DMediaChangeBase +*/ +const TInt KMaxMediaChanges=4; + + + +/** +Defines the maximum number of power supply unit (PSU) objects. + +@see DPBusPsuBase +*/ +const TInt KMaxPBusVccs=4; + + + + +/** + Defines the state of the media, i.e. whether the media door is + open or closed. + + A value of this type is returned by DMediaChangeBase::MediaState(). + + @see DMediaChangeBase::MediaState() +*/ +enum TMediaState { + /** + Indicates that the media door is open. + */ + EDoorOpen, + + /** + Indicates that the media door is closed. + */ + EDoorClosed}; + + + + +enum TPBusType {EPBusTypeNone,EPBusTypePcCard,EPBusTypeMultiMedia,EPBusTypeUSB}; + + + + +enum TPBusState + { + EPBusCardAbsent=0, + EPBusOff=1, + EPBusPoweringUp=2, + EPBusOn=3, + EPBusPsuFault=4, + EPBusPowerUpPending=5, + }; + +typedef void (*TPBusCallBackFn)(TAny* aPtr, TInt aReason, TAny* a1, TAny* a2); +typedef void (*TPBusIsr)(TAny* aPtr, TInt anId); + +class DPBusSocket; +class TPBusCallBack : public SDblQueLink + { +public: + enum TCallBackReason + { + EPBusStateChange=0, + EPBusCustomNotification=1, // Make this the last value + }; +public: + IMPORT_C TPBusCallBack(); + IMPORT_C TPBusCallBack(TPBusCallBackFn aFunction, TAny* aPtr); + IMPORT_C TPBusCallBack(TPBusIsr anIsr, TAny* aPtr, TUint anIntMask); +public: + inline void NotifyPBusStateChange(TInt aState, TInt anError); + inline void NotifyCustom(TInt aParam, TInt anError); + inline void Isr(TInt anId); +public: + inline TInt PowerUp(); + inline TInt PBusState(); + inline TDfcQue* DfcQ(); + inline void Add(); + IMPORT_C void SetSocket(TInt aSocket); + IMPORT_C void Remove(); +public: + DPBusSocket* iSocket; + TPBusCallBackFn iFunction; + TUint iIntMask; + TPBusIsr iIsr; + TAny* iPtr; + }; + + + +class DMediaChangeBase : public DBase +/** +Abstract Base class to handle the insertion and removal of removable media. + +This class is intended for derivation at the media and variant layers, +which handles the media/variant specific functionality such as interrupt detection, +and passes notifications of media change to the peripheral bus socket layers. + +@see DMMCMediaChange + +@publishedPartner +@released +*/ + { +public: + IMPORT_C DMediaChangeBase(TInt aMediaChangeNum); + IMPORT_C virtual TInt Create(); +public: + IMPORT_C void DoorOpenService(); + IMPORT_C void DoorClosedService(); + void MediaChangeEvent(TBool aDoorOpened); + void AcknowledgeEvent(TBool aDoorOpened); + static void DoorOpenDfcFn(TAny* aPtr); +public: + /** + * Implemented at the media and variant layers. + * Forces a media change, performs actions as if a door open has occurred. + * Used for powering down and restarting media. + * + * @see DMediaChangeBase::DoDoorOpen() + */ + IMPORT_C virtual void ForceMediaChange()=0; + + /** + * Called by DMediaChangeBase::AcknowledgeEvent when the door is opened. + * Implemented at the media and variant layer, DoDoorOpen is invoked + * in response to the variant calling ::DoDoorOpenService upon detection of + * a door open event. + * + * @see DMediaChangeBase::DoorOpenService() + * @see DMediaChangeBase::DoDoorClosed() + */ + IMPORT_C virtual void DoDoorOpen()=0; + + /** + * Called by DMediaChangeBase::AcknowledgeEvent when the door is closed. + * Implemented at the media and variant layer, DoDoorClosed is invoked + * in response to the variant calling ::DoorOpenService upon detection of + * a door closed event. + * + * @see DMediaChangeBase::DoorOpenService() + * @see DMediaChangeBase::DoDoorOpen() + */ + IMPORT_C virtual void DoDoorClosed()=0; + + /** + * Returns the current state of the door. + * Implemented at the variant layer to provide information as to the state of the door. + * + * @return TMediaState enumeration describing the state of door (EDoorOpen, EDoorClosed) + */ + IMPORT_C virtual TMediaState MediaState()=0; +public: + /** Unique media change ID, identification scheme is defined by derived classes*/ + TInt iMediaChangeNum; + + /** Count of media events yet to be acknowledged.*/ + TInt iReplyCount; + + /** Door Open DFC queue.*/ + TDfc iDoorOpenDfc; + }; + + + + +/** + Defines the required state of the PSU. + + A value of this type is passed to DPBusPsuBase::DoSetState(). + + @see DPBusPsuBase::DoSetState() +*/ +enum TPBusPsuState { + /** + Indicates that the PSU is to be turned off. + */ + EPsuOff, + + /** + Indicates that the PSU is to be turned on in current + limit mode. + + Some power supplies can be turned on in a mode that only + supplies a limited amount of current to the device. + A faulty device drawing excessive current would cause + the PSU output voltage to fall, and would be detected + by the PSU's voltage checking mechanism. After a brief + checking period in current limit mode, the PSU is + subsequently turned fully on. + + For PSU's that don't support current limit mode, this is + treated in the same way as EPsuOnFull. + */ + EPsuOnCurLimit, + + /** + Indicates that the PSU is to be turned fully on. + */ + EPsuOnFull + }; + + + + +enum TPBusPsuStatus {EPsuStatOff,EPsuStatOn,EPsuStatError}; + + + + +const TInt KPBusPsuTickInterval=1000000; // Units 1uS + + + + +/** + A bit value that is set into the TPBusPsuInfo::iVoltCheckInterval member to + indicate that the checking of the PSU voltage level can be performed when + the power supply is first turned on. +*/ +const TUint KPsuChkWhileOn=0x00000001; + + + + +/** + A bit value that is set into the TPBusPsuInfo::iVoltCheckInterval member to + indicate that the checking of the PSU voltage level can be performed + periodically when the power supply is on. +*/ +const TUint KPsuChkOnPwrUp=0x00000002; + + + + +/** + Defines the methods that can be used by the platform hardware for checking + the VCC voltage while on. +*/ +enum TPsuVoltChkMethod { + /** + Indicates a simple good/bad check method normally using + a comparator arrangement. + */ + EPsuChkComparator, + + /** + Not implemented. + */ + EPsuChkADCType1, + + /** + Not implemented. + */ + EPsuChkADCType2 + }; + + + + +/** + Encapsulates power supply information. + + An object of this type is passed to concrete implementations of + DPBusPsuBase::PsuInfo(), which are required to fill + the data members of the object. +*/ +class TPBusPsuInfo + { +public: + /** + Indicates the voltage level, or range of voltages supported . + + The voltage level, or range of voltages is reported as a bit mask + in the same format as defined for the OCR register. + + If the PSU supports voltage adjustment, rather than a single fixed value, + then bit31 should be set to indicate this fact + as well as setting the appropriate bits to indicate the adjustable voltage + range supported. + */ + TUint iVoltageSupported; + + /** + The maximum current (in microAmps) that the PSU is able to supply. + */ + TInt iMaxCurrentInMicroAmps; + + /** + Indicates whether the platform hardware has support for checking whether + the voltage level of the PSU is within its expected voltage limit while turned on. + + Such a mechanism could detect when a faulty card is drawing excessive current. + + Set one or both of the bits KPsuChkWhileOn and KPsuChkOnPwrUp, + if there is support for voltage checking. + Set neither bit if there is no support for voltage checking. + + @see KPsuChkWhileOn + @see KPsuChkOnPwrUp + */ + TUint iVoltCheckInterval; + + /** + Indicates the method used by the platform hardware for checking + the VCC voltage while on. + + The method used is identified using the values of + the TPsuVoltChkMethod enum. + + @see TPsuVoltChkMethod + @see DPBusPsuBase::DoCheckVoltage() + */ + TPsuVoltChkMethod iVoltCheckMethod; + + /** + Bus not locked timeout period, in seconds, when no clients are registered. + + Set to 0 to disable the not locked timer. + */ + TInt iNotLockedTimeOut; + + /** + Bus inactivity timeout period, in seconds, when clients are registered. + + Set to 0 to disable the inactivity timer. + */ + TInt iInactivityTimeOut; + }; + + +typedef void (*PsuPwrDownCheckFn)(TAny*); +/** +Perherpial bus base class to control the power supply. + +This class is intended for derivation at both the media driver and variant layer, +which respectively handle the media/variant specific functionality of the power supply. + +@see DMMCPsu + +@publishedPartner +@released +*/ +class DPBusPsuBase : public DBase + { +public: + /** Currently not in use. */ + enum TResetMode { + /** Currently not in use.*/ + ENormalAndRestorable, + /** Currently not in use.*/ + EQuickButRestorable, + /** Currently not in use.*/ + EQuickAndNotRestorable + }; +public: + DPBusPsuBase(TInt aPsuNum, TInt aMediaChangeNum); + IMPORT_C TInt SetState(TPBusPsuState aState); + TPBusPsuStatus Status(); + TInt CheckVoltage(TUint aCheckStatus); + void Reset(); +public: + TInt Create(); + IMPORT_C virtual TInt DoCreate(); + IMPORT_C virtual void DoTickService(); + IMPORT_C virtual TBool IsLocked(); +public: + IMPORT_C virtual void DoSetState(TPBusPsuState aState)=0; + + /** + Base abstract method. + Checks the voltage level of the PSU is as expected. + The result is returned by a call to DPBusPsuBase::ReceiveVoltageCheckResult(), + passing either KErrNone, KErrGeneral to indicate the pass/fail state or + KErrNotReady if the voltage check isn't complete. + + Provided at the variant layer. + */ + IMPORT_C virtual void DoCheckVoltage()=0; + + /** + Fills in the supplied TPBusPsuInfo object with the characteristics of the platform. + Provided at the variant layer. + + @param anInfo A reference to a TPBusPsuInfo to be filled in with the PSU characteristics. + */ + IMPORT_C virtual void PsuInfo(TPBusPsuInfo &anInfo)=0; + + IMPORT_C virtual void ReceiveVoltageCheckResult(TInt anError); +public: + inline TUint VoltageSupported(); + inline void SetCurrLimited(); + inline TBool IsOff(); + inline TInt MaxCurrentInMicroAmps(); + inline void ResetInactivityTimer(); +public: + void PwrDownCheck(); + static void DoPwrDownCheck(TAny* aPtr); +public: + /** Unique power supply unit identification number.*/ + TInt iPsuNum; + + /** Currently not in use. */ + TInt iMediaChangeNum; + + /** + Indicates the method used by the platform hardware for checking + the VCC voltage while on. + + The method used is identified using the values of + the TPsuVoltChkMethod enum. + + @see TPsuVoltChkMethod + @see DPBusPsuBase::DoCheckVoltage() + */ + TPsuVoltChkMethod iVoltCheckMethod; + + /** + Current PSU State. + @see TPBusPsuState + */ + TPBusPsuState iState; + + /** PSU current is limited to a safe level. */ + TBool iCurrLimited; + + /** PSU Tick Timer */ + TTickLink iTickLink; + + /** + Indicates the voltage level, or range of voltages supported . + + The voltage level, or range of voltages is reported as a bit mask + in the same format as defined for the OCR register. + + If the PSU supports voltage adjustment, rather than a single fixed value, + then bit31 should be set to indicate this fact + as well as setting the appropriate bits to indicate the adjustable voltage + range supported. + */ + TUint iVoltageSupported; + + /** The maximum current (in microAmps) that the PSU is able to supply. */ + TInt iMaxCurrentInMicroAmps; + + /** + Indicates whether the platform hardware has support for checking whether + the voltage level of the PSU is within its expected voltage limit while turned on. + + Such a mechanism could detect when a faulty card is drawing excessive current. + + Set one or both of the bits KPsuChkWhileOn and KPsuChkOnPwrUp, + if there is support for voltage checking. + Set neither bit if there is no support for voltage checking. + + @see KPsuChkWhileOn + @see KPsuChkOnPwrUp + */ + TUint iVoltCheckInterval; + + /** Bus inactivity counter. */ + TInt iInactivityCount; + + /** Bus not locked counter. */ + TInt iNotLockedCount; + + /** Bus inactivity timeout period, in seconds, when clients are registered. */ + TInt iInactivityTimeout; + + /** Bus not locked timeout period, in seconds, when no clients are registered. */ + TInt iNotLockedTimeout; + + /** DPBusSocket which the PSU powers. */ + DPBusSocket* iSocket; // for the moment assume a PSU only powers one socket + + /** + DFC to handle PSU Tick. + @see DPBusPsuBase::DoTickService() + @see TDfc + */ + TDfc iPsuDfc; + + /** Power Down Function to be utilised, default is PwrDownCheck */ + PsuPwrDownCheckFn iPwrDownCheckFn; + +private: + TUint32 reserved[4]; + }; + +NONSHARABLE_CLASS(DPBusPowerHandler) : public DPowerHandler + { +public: + DPBusPowerHandler(DPBusSocket* aSocket); +public: // from DPowerHandler + // signals from manager to client + void PowerUp(); + void PowerDown(TPowerState); +public: + DPBusSocket* iSocket; + }; + +/** Abstract base class for a PBUS socket. + DPBusSocket derived class object oversees the power supply and media change functionality with the socket. +*/ +NONSHARABLE_CLASS(DPBusSocket) : public DBase + { +public: + /** + Panic codes to handle the invalid powerup and powerdown state of the PBUS. + @see TPBusState + */ + enum TPanic + { + /** + Indicates the invalid door close state. + */ + EDoorCloseInvalidState=0, + + /** + Indicates the invalid powerup state of PBUS, considered as invalid if iState is other than TPBusState while powering up. + */ + EPowerUpInvalidState=1, + + /** Indicates invalid handler state corresponding to powerup event */ + EPowerUpInvalidHandlerState=2, + + /** Invalid return code corresponding to powerup event */ + EPowerUpInvalidReturnCode=3, + + /** + Indicates the invalid powerdown state of the media device, + considered as invalid if iState is other than TPBusState while powering down. + */ + EEmergencyPowerDownInvalidState=4, + + /** + Indicates the invalid powerup state of the media device, + considered as invalid if iState is not in (EPBusCardAbsent,EPBusOff and EPBusPowerUpPending) while on transition from standby. + */ + EMcPowerUpInvalidState=5, + }; + + /** + The purpose of this enumeration is to handle the postponed events corresponding to media change and power down event. + */ + enum TPostponedEvent + { + /** Handles the postponed media change event */ + EMediaChange=1, + + /** Handles the postponed power down event */ + EPowerDown=2, + }; + + /** + Enumeration for handling debug functionality. + */ + enum TPBusDebugFunction + { + /** Media state used for simulation purposes */ + EControlMediaState + }; + + /** + PBUS simulated media states. + */ + enum TPBusSimulateMediaState + { + /** Normal State */ + EPeriphBusMediaNormal=0, + + /** Simulated door open */ + EPeriphBusDoorOpen=1, + + /** Simulated door close with media absent */ + EPeriphBusMediaRemoved=2, + + /** Simulated door close with media present */ + EPeriphBusMediaPresent=3, + + /** Simulate two consecutive door open interrupts */ + EPeriphBusMediaDoubleDoorOpen=4 + }; + +public: + DPBusSocket(TInt aSocketNumber); + IMPORT_C static DPBusSocket* SocketFromId(TInt anId); + IMPORT_C static void Panic(DPBusSocket::TPanic aPanic); +public: + virtual TInt Create(const TDesC* aName); + virtual TInt Init(); + + /** + Initiates a power up sequence on the stack. This method should be implemented by the derived class. + The implementation should call PowerUpSequenceComplete() to notify the status on completion of power up sequence. + + @see DMMCSocket::InitiatePowerUpSequence() + @see DMMCStack::PowerUpStack() + */ + virtual void InitiatePowerUpSequence()=0; + + /** + Indicates the presence of a card. This method should be implemented by the derived class. + The implementation should use variant specific implementation of CardDetect() method to detect the card presence. + + @return ETrue if a card is present, else EFalse + @see DMMCStack::CardDetect() + */ + virtual TBool CardIsPresent()=0; + + /** + Resets the socket. This method should be implemented by the derived class. + The implementation should cancel powerup timer and DFC queue if any of this request is outstanding, + Power down the stack. + + @see DMMCSocket::Reset1() + */ + virtual void Reset1()=0; + + /** + Resets the socket on media change event.This method should be implemented by the derived class. + The implementation should remove any allocated memory following a media change event. + + */ + virtual void Reset2()=0; +public: + inline TInt State(); + inline TDfcQue* DfcQ(); + inline TMediaState MediaState(); +public: + IMPORT_C void Add(TPBusCallBack* aCallBack); + IMPORT_C TInt PowerUp(); + IMPORT_C void ForceMediaChange(); + IMPORT_C TInt InCritical(); + IMPORT_C void EndInCritical(); + IMPORT_C void DeltaCurrentConsumption(TInt aDelta); + IMPORT_C void PowerUpSequenceComplete(TInt anError); + void PsuFault(TInt anError); + void PsuTimeout(); + void ResetSocket(TBool aFullReset); + void ChangeState(TInt aState, TInt anError); + void MediaChangeEvent(TBool aDoorOpened); + void DoorOpenEvent(); + void DoorCloseEvent(); + void Isr(TInt anId); + void DoPowerUp(); + void DoPowerDown(); + IMPORT_C void PowerDownComplete(); + IMPORT_C void RequestAsyncPowerDown(); + IMPORT_C virtual TInt ControlIO(TInt aFunction, TAny* aParam1, TAny* aParam2); +public: + /** + Current PBus type. + @see TPBusType + */ + TPBusType iType; + /** + Current socket number. + */ + TInt iSocketNumber; + /** + Name of the socket. + */ + const TDesC* iName; + /** + Current state of Peripheral bus controller. + @see TPBusState + */ + TInt iState; + /** + Counter to keep track of postponed events. + */ + TInt iPostponeCount; + /** + Current postponed events. + @see TPostponedEvent + */ + TUint16 iPostponedEvents; + /** + Current simulated state of the Media. + @see TPBusSimulateMediaState + */ + TUint16 iSimulatedMediaState; + /** + The call back functions queue. + @see SDblQue + */ + SDblQue iCallBackQ; + /** + Pointer to DPBusPowerController object. + @see DPBusPowerHandler + */ + DPBusPowerHandler* iPowerHandler; + + /** + Holds media change number. + @see MediaChangeFromSocket + */ + TInt iMediaChangeNumber; + + /** + Pointer to DMediaChangeBase object. + @see DMediaChangeBase + */ + DMediaChangeBase* iMediaChange; + + /** + Holds the state of media door. + Updated when there is change in media event corresponing to Door open. + @see DMediaChangeBase::DoorOpenService() + @see TMediaState + */ + TBool iDoorOpened; + + /** + Pointer to DPBusPsuBase object. + @see DPBusPsuBase + */ + DPBusPsuBase* iVcc; + + /** + Indicates the device is in standby state (i.e. Sets to ETrue when the device is in standby state). + */ + TBool iStandby; + + /** + DFC to handle media change events like (DoorOpen,DoorClose). + @see DMediaChangeBase::AcknowledgeEvent + @see TDfc + */ + TDfc iMediaChangeDfc; + + /** + DFC to handle powering up of the device. + @see TDfc + */ + TDfc iPowerUpDfc; + + /** + DFC to handle powerdown state of the device. + + @see TDfc + */ + TDfc iPowerDownDfc; + + /** + DFC to handle PSU Tick. + @see DPBusPsuBase::DoTickService() + @see TDfc + */ + TDfc iPsuDfc; + + /** + The DFC queue used for driver functions. + @see TDfcQue + */ + TDfcQue iDfcQ; + + /** + Used when there is request for power down of the device from client. + */ + TInt iRequestPowerDownCount; + }; + +GLREF_D DMediaChangeBase* TheMediaChanges[KMaxMediaChanges]; +GLREF_D DPBusSocket* TheSockets[KMaxPBusSockets]; +GLREF_D DPBusPsuBase* TheVccs[KMaxPBusVccs]; +GLREF_D DPBusPsuBase* TheVccCores[KMaxPBusVccs]; + +#include +#endif