// 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 <kernel/kpower.h>

#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