williamr@4: // Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).
williamr@4: // All rights reserved.
williamr@4: // This component and the accompanying materials are made available
williamr@4: // under the terms of the License "Eclipse Public License v1.0"
williamr@4: // which accompanies this distribution, and is available
williamr@4: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
williamr@4: //
williamr@4: // Initial Contributors:
williamr@4: // Nokia Corporation - initial contribution.
williamr@4: //
williamr@4: // Contributors:
williamr@4: //
williamr@4: // Description:
williamr@4: //
williamr@4: 
williamr@4: #ifndef __GPIO_H__
williamr@4: #define __GPIO_H__
williamr@4: 
williamr@4: class TGpioCallback;	//forward declaration
williamr@4: 
williamr@4: /**
williamr@4: GPIO interrupt handler
williamr@4: Takes a generic argument (TAny*)
williamr@4: */
williamr@4: typedef void (*TGpioIsr)(TAny*);
williamr@4: 
williamr@4: class GPIO
williamr@4: 	{
williamr@4: public:
williamr@4: 	/**
williamr@4: 	GPIO pin modes (to be requested on any pin):
williamr@4: 	- enabled,
williamr@4: 	- disabled,
williamr@4: 	- idling
williamr@4: 	*/
williamr@4: 	enum TGpioMode
williamr@4: 		{
williamr@4: 		EEnabled,
williamr@4: 		EDisabled,
williamr@4: 		EIdle
williamr@4: 		};
williamr@4: 
williamr@4: 		/**
williamr@4: 	GPIO pin directions (to be requested on any pin):
williamr@4: 	- input,
williamr@4: 	- output,
williamr@4: 	- tristated
williamr@4: 	*/
williamr@4: 	enum TGpioDirection
williamr@4: 		{
williamr@4: 		EInput,
williamr@4: 		EOutput,
williamr@4: 		ETriStated
williamr@4: 		};
williamr@4: 
williamr@4: 	/**
williamr@4: 	GPIO pin states (to be set on an output or read from an input or output):
williamr@4: 	- electrical Low,
williamr@4: 	- electrical High,
williamr@4: 	- state compatible with idling the pin (module)
williamr@4: 	*/
williamr@4: 	enum TGpioState
williamr@4: 		{
williamr@4: 		ELow,
williamr@4: 		EHigh,
williamr@4: 		EIdleState
williamr@4: 		};
williamr@4: 
williamr@4: 	/**
williamr@4: 	GPIO programmable bias:
williamr@4: 	- no drive,
williamr@4: 	- pulled down (Low),
williamr@4: 	- pulled up (High)
williamr@4: 	*/
williamr@4: 	enum TGpioBias
williamr@4: 		{
williamr@4: 		ENoDrive,
williamr@4: 		EPullDown,
williamr@4: 		EPullUp
williamr@4: 		};
williamr@4: 
williamr@4: 	/**
williamr@4: 	GPIO interrupt and/or wakeup triger configuration (to be requested on an input
williamr@4:  						 that supports interrupts or wakeup function):
williamr@4: 	- Level triggered, low level,
williamr@4: 	- Level triggered, high level,
williamr@4: 	- Edge triggered, falling edge,
williamr@4: 	- Edge triggered, rising edge,
williamr@4: 	- Edge triggered, both edges,
williamr@4: 	*/
williamr@4: 	enum TGpioDetectionTrigger
williamr@4: 		{
williamr@4: 		ELevelLow,
williamr@4: 		ELevelHigh,
williamr@4: 		EEdgeFalling,
williamr@4: 		EEdgeRising,
williamr@4: 		EEdgeBoth
williamr@4: 		};
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the pin mode.
williamr@4:     
williamr@4:     @param aId   The pin Id.
williamr@4:     @param aMode The pin mode.
williamr@4: 
williamr@4:     @return KErrNone, if successful; KErrArgument, if aId is invalid;
williamr@4:             KErrNotReady, when a pin that has requested to be Idle is not ready to do
williamr@4:  											     so;
williamr@4:             KErrNotSupported, if a pin cannot be used as a GPIO because it  has been
williamr@4:  							     assigned an alternative function.
williamr@4: 
williamr@4: 	When disabling a pin, the module which the pin is a part of may not be disabled,
williamr@4:  								but KErrNone is still returned.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetPinMode(TInt aId, TGpioMode aMode);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the pin mode.
williamr@4:     
williamr@4:     @param aId   The pin Id.
williamr@4:     @param aMode On return contains the pin mode.
williamr@4: 
williamr@4:     @return KErrNone, if successful; KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if reading the pin mode is not supported.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetPinMode(TInt aId, TGpioMode& aMode);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the pin direction.
williamr@4:     
williamr@4:     @param aId        The pin Id.
williamr@4:     @param aDirection The pin direction.
williamr@4: 
williamr@4:     @return KErrNone, if successful; KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if a pin cannot operate in the direction specified.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetPinDirection(TInt aId, TGpioDirection aDirection);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the pin direction.
williamr@4:     
williamr@4:     @param aId        The pin Id.
williamr@4:     @param aDirection On return contains the pin direction.
williamr@4: 
williamr@4:     @return KErrNone, if successful; KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if reading the pin direction is not supported.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetPinDirection(TInt aId, TGpioDirection& aDirection);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the bias on a pin.
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aBias  The drive on the pin.
williamr@4: 
williamr@4:     @return KErrNone, if successful; KErrArgument, if aId is invalid;
williamr@4: 		   KErrNotSupported, if a pin does not support setting the drive.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetPinBias(TInt aId, TGpioBias aBias);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the bias on a pin.
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aBias  On return contains the bias previoulsy set on the pin (or the
williamr@4:  								   default bias if first time).
williamr@4: 
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if reading the pin bias is not supported.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetPinBias(TInt aId, TGpioBias& aBias);
williamr@4: 
williamr@4: 	/**
williamr@4: 	Sets the idle configuration and state. The pin configuration is the 
williamr@4: 	same that the pin should have when setting the mode to EIdle and the
williamr@4: 	state same it should present when setting the output state to EIdleState.
williamr@4: 
williamr@4: 	@param aId    The pin Id.
williamr@4: 	@param aConf  An implementation specific token specifying the idle
williamr@4: 				  configration and state.
williamr@4: 	
williamr@4: 	@return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if setting the pin idle configuration and state
williamr@4: 							  are not supported.
williamr@4: 	*/
williamr@4: 	IMPORT_C static TInt SetPinIdleConfigurationAndState(TInt aId, TInt aConf);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the pin idle configuration and state.
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aConf  On return contains the idle configuration and state previoulsy
williamr@4: 				  set on the pin.
williamr@4: 
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if reading the pin idle configuration and state
williamr@4: 							  is not supported.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetPinIdleConfigurationAndState(TInt aId, TInt& aConf);
williamr@4: 
williamr@4:     /**
williamr@4:     Associates the specified interrupt service routine (ISR) function with the
williamr@4:     								specified interrupt Id.
williamr@4:     
williamr@4:     @param aId     The pin Id.
williamr@4:     @param anIsr   The address of the ISR function. 
williamr@4:     @param aPtr    32-bit value that is passed to the ISR.
williamr@4:                    This is designated a TAny* type as it is usually a pointer to the
williamr@4:                    owning class or data to be used in the ISR, although it can be any
williamr@4:                    32-bit value.
williamr@4:                  
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support interrupts;
williamr@4:             KErrInUse, if an ISR is already bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt BindInterrupt(TInt aId, TGpioIsr aIsr, TAny* aPtr);
williamr@4: 
williamr@4:     /**
williamr@4:     Unbinds the interrupt service routine (ISR) function from the specified interrupt
williamr@4:     id.
williamr@4:     
williamr@4:     @param aId The pin Id.
williamr@4:     
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support interrupts;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt UnbindInterrupt(TInt aId);
williamr@4: 
williamr@4:     /**
williamr@4:     Enables the interrupt on specified pin.
williamr@4:     
williamr@4:     @param aId  The pin Id.
williamr@4:     
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support interrupts;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt EnableInterrupt(TInt aId);
williamr@4: 
williamr@4:     /**
williamr@4:     Disables the interrupt on specified pin.
williamr@4:     
williamr@4:     @param aId  The pin Id.
williamr@4:     
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support interrupts;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt DisableInterrupt(TInt aId);
williamr@4: 
williamr@4:     /**
williamr@4:     Checks if interrupt is enabled on pin.
williamr@4:     
williamr@4:     @param aId     The pin Id.
williamr@4:     @param aEnable On return contains the enable/disable state of interrupt 
williamr@4:  								       		 (TRUE=enabled).
williamr@4:     
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support interrupts;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt IsInterruptEnabled(TInt aId, TBool& aEnable);
williamr@4: 
williamr@4:     /**
williamr@4:     Clears any pending interrupt on the specified pin.
williamr@4:     
williamr@4:     @param aId The pin Id.
williamr@4:     
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if clearing interrupt signal is not supported on this
williamr@4:  											    pin;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt ClearInterrupt(TInt aId);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the interrupt state as output by the GPIO interrupt controller.
williamr@4:     
williamr@4:     @param aId     The pin Id.
williamr@4:     @param aActive On return contains the state of the interrupt signal as output by
williamr@4:  						      GPIO interrupt controller (TRUE=active).
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if reading interrupt state is not supported;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetMaskedInterruptState(TInt aId, TBool& aActive);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the interrupt state on the specified pin before any masking.
williamr@4:     
williamr@4:     @param aId     The pin Id.
williamr@4:     @param aActive On return contains state of the interrupt signal on the pin
williamr@4:  										  (TRUE=active).
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if reading raw interrupt state is not supported;
williamr@4:             KErrGeneral, if there is no ISR bound to this interrupt.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetRawInterruptState(TInt aId, TBool& aActive);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the interrupt trigger on the specified pin.
williamr@4:     
williamr@4:     @param aId      The pin Id.
williamr@4:     @param aTrigger The trigger type.
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support interrupts.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetInterruptTrigger(TInt aId, TGpioDetectionTrigger aTrigger);
williamr@4: 
williamr@4:     /**
williamr@4:     Enables the wakeup on specified pin.
williamr@4:     
williamr@4:     @param aId  The pin Id.
williamr@4:     
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support wakeup.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt EnableWakeup(TInt aId);
williamr@4: 
williamr@4:     /**
williamr@4:     Disables the wakeup on specified pin.
williamr@4:     
williamr@4:     @param aId  The pin Id.
williamr@4:     
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support wakeup.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt DisableWakeup(TInt aId);
williamr@4: 
williamr@4:     /**
williamr@4:     Checks if wakeup is enabled on pin.
williamr@4:     
williamr@4:     @param aId     The pin Id.
williamr@4:     @param aEnable On return contains the enable/disable state of wakeup 
williamr@4:  								       		 (TRUE=enabled).
williamr@4:     
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support wakeups;
williamr@4:     */
williamr@4: 	IMPORT_C static TInt IsWakeupEnabled(TInt aId, TBool& aEnable);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the wakeup trigger on the specified pin.
williamr@4:     
williamr@4:     @param aId      The pin Id.
williamr@4:     @param aTrigger The trigger type.
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support wakeup.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetWakeupTrigger(TInt aId, TGpioDetectionTrigger aTrigger);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the debouncing time on the specified pin.
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aTime  The debouncing time in microseconds.
williamr@4: 
williamr@4:     @return KErrNone, if the time is succesfully changed or no change is needed (see
williamr@4:                                                 			         below);
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support debouncing.
williamr@4: 
williamr@4:     If the requested time is greater than the common value for the module, the latter
williamr@4:     is increased to the value requested.
williamr@4:     If the requested time is lesser than the common value for the module then the
williamr@4:     common value is unchanged, unless it is set to the value requested on this pin.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetDebounceTime(TInt aId, TInt aTime);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the debouncing time on the specified pin.
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aTime  On return contains the debouncing time in microseconds.
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported if pin does not support debouncing.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetDebounceTime(TInt aId, TInt& aTime);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the state of an input (synchronously).
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aState On return contains the pin state.
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4:             KErrArgument, if aId is invalid.
williamr@4:             KErrNotSupported, if reading the state synchronously is not supported.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetInputState(TInt aId, TGpioState& aState);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the output pin to one of the supported states (synchronously).
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aState The pin state.
williamr@4: 
williamr@4:     @return KErrNone, if successful;
williamr@4: 			KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if the state is not supported or if setting its state synchronously is not supported.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetOutputState(TInt aId, TGpioState aState);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the output pin states (synchronously).
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aState On return contains the pin state. On systems where the state of an
williamr@4:  			 ouptut pin cannot be read directly from hardware, or takes a non
williamr@4: 			 negligible time to be retrieved, the implementation must cache it.
williamr@4: 
williamr@4:     @return KErrNone, if successful; 
williamr@4:             KErrArgument, if aId is invalid.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetOutputState(TInt aId, TGpioState& aState);
williamr@4: 
williamr@4:     /**
williamr@4:     Reads the state of an input (asynchronously).
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aCb    A pointer to a GPIO callback object.
williamr@4: 
williamr@4:     @return KErrNone, if accepted;
williamr@4:             KErrArgument, if aId is invalid.
williamr@4:             KErrNotSupported, if reading the state asynchronously is not supported.
williamr@4: 
williamr@4: 	This API should be used with off-chip GPIO modules only;
williamr@4: 	The result of the read operation and the state of the input pin will be passed as an argument to the callback function;
williamr@4:     */
williamr@4: 	IMPORT_C static TInt GetInputState(TInt aId, TGpioCallback* aCb);
williamr@4: 
williamr@4:     /**
williamr@4:     Sets the output pin to one of the supported states (asynchronously).
williamr@4:     
williamr@4:     @param aId    The pin Id.
williamr@4:     @param aState The pin state.
williamr@4:     @param aCb    A pointer to a GPIO callback object.
williamr@4: 
williamr@4:     @return KErrNone, if accepted;
williamr@4: 			KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if setting its state asynchronously is not supported.
williamr@4: 
williamr@4:     This API should be used with off-chip GPIO modules only;
williamr@4: 	The result of the set operation will be passed as an argument to the callback function;
williamr@4:     */
williamr@4: 	IMPORT_C static TInt SetOutputState(TInt aId, TGpioState aState, TGpioCallback* aCb);
williamr@4: 
williamr@4: 	/**
williamr@4:     Allows the platform specific implementation to extend the API.
williamr@4: 
williamr@4:     @param aId        The pin Id.
williamr@4: 	@param aCmd       A PSL extension function id.
williamr@4: 	@param aArg1      An argument to be passed to the PSL extension function.
williamr@4: 	@param aArg2      An argument to be passed to the PSL extension function.
williamr@4: 
williamr@4:     @return KErrNone, if accepted;
williamr@4: 			KErrArgument, if aId is invalid;
williamr@4:             KErrNotSupported, if static extensions are not supported.
williamr@4: 			Any other system wide error code.
williamr@4:     */
williamr@4: 	IMPORT_C static TInt StaticExtension(TInt aId, TInt aCmd, TAny* aArg1, TAny* aArg2);
williamr@4: 	};
williamr@4: 
williamr@4: /**
williamr@4: GPIO asynchronous callback function
williamr@4: */
williamr@4: typedef void (*TGpioCbFn)(TInt				/*aPinId*/,
williamr@4: 						  GPIO::TGpioState	/*aState*/,
williamr@4:                           TInt				/*aResult*/,
williamr@4:                           TAny*				/*aParam*/);
williamr@4: /**
williamr@4: GPIO asynchronous callback DFC
williamr@4: The client must create one of these to be passed to each asynchronous call to GetInputState and SetOutputState
williamr@4: The callback function is called in the context supplied by the client when creating an object of this kind (aQue)
williamr@4: The callback function takes as arguments the pin id and the state, so it can be common to all TGpioCallback
williamr@4: */
williamr@4: class TGpioCallback : public TDfc
williamr@4: 	{
williamr@4: public:
williamr@4: 	inline TGpioCallback(TGpioCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority) : TDfc(DfcFunc, this, aQue, aPriority), iParam(aPtr), iCallback(aFn) 
williamr@4: 			{}
williamr@4: private:
williamr@4:     inline static void DfcFunc(TAny* aPtr)
williamr@4:         {
williamr@4:         TGpioCallback* pCb = (TGpioCallback*) aPtr;
williamr@4:         pCb->iCallback(pCb->iPinId, pCb->iState, pCb->iResult, pCb->iParam);
williamr@4:         }
williamr@4: public:
williamr@4: 	TInt iPinId;		// the Id of the pin on which the asynchronous operation is performed
williamr@4: 	GPIO::TGpioState iState;	// either the state the output pin should be moved to or the state the input pin is at
williamr@4: 	TInt iResult;		// the result of this transaction as a system wide error
williamr@4: 	TAny* iParam;
williamr@4: 	TGpioCbFn iCallback;
williamr@4: 	};
williamr@4: #endif