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