1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/kernelhwsrv/kernel/eka/include/drivers/gpio.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,537 @@
1.4 +// Copyright (c) 2008-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\drivers\gpio.h
1.18 +//
1.19 +//
1.20 +
1.21 +#ifndef __GPIO_H__
1.22 +#define __GPIO_H__
1.23 +
1.24 +class TGpioCallback; //forward declaration
1.25 +
1.26 +/**
1.27 +@publishedPartner
1.28 +@prototype 9.6
1.29 +
1.30 +GPIO interrupt handler
1.31 +Takes a generic argument (TAny*)
1.32 +*/
1.33 +typedef void (*TGpioIsr)(TAny*);
1.34 +
1.35 +/**
1.36 +@publishedPartner
1.37 +@prototype 9.6
1.38 +
1.39 +GPIO class handler
1.40 +*/
1.41 +class GPIO
1.42 + {
1.43 +public:
1.44 + /**
1.45 + GPIO pin modes (to be requested on any pin):
1.46 + - enabled,
1.47 + - disabled,
1.48 + - idling
1.49 + */
1.50 + enum TGpioMode
1.51 + {
1.52 + EEnabled,
1.53 + EDisabled,
1.54 + EIdle
1.55 + };
1.56 +
1.57 + /**
1.58 + GPIO pin directions (to be requested on any pin):
1.59 + - input,
1.60 + - output,
1.61 + - tristated
1.62 + */
1.63 + enum TGpioDirection
1.64 + {
1.65 + EInput,
1.66 + EOutput,
1.67 + ETriStated
1.68 + };
1.69 +
1.70 + /**
1.71 + GPIO pin states (to be set on an output or read from an input or output):
1.72 + - electrical Low,
1.73 + - electrical High,
1.74 + - state compatible with idling the pin (module)
1.75 + */
1.76 + enum TGpioState
1.77 + {
1.78 + ELow,
1.79 + EHigh,
1.80 + EIdleState
1.81 + };
1.82 +
1.83 + /**
1.84 + GPIO programmable bias:
1.85 + - no drive,
1.86 + - pulled down (Low),
1.87 + - pulled up (High)
1.88 + */
1.89 + enum TGpioBias
1.90 + {
1.91 + ENoDrive,
1.92 + EPullDown,
1.93 + EPullUp
1.94 + };
1.95 +
1.96 + /**
1.97 + GPIO interrupt and/or wakeup triger configuration (to be requested on an input
1.98 + that supports interrupts or wakeup function):
1.99 + - Level triggered, low level,
1.100 + - Level triggered, high level,
1.101 + - Edge triggered, falling edge,
1.102 + - Edge triggered, rising edge,
1.103 + - Edge triggered, both edges,
1.104 + */
1.105 + enum TGpioDetectionTrigger
1.106 + {
1.107 + ELevelLow,
1.108 + ELevelHigh,
1.109 + EEdgeFalling,
1.110 + EEdgeRising,
1.111 + EEdgeBoth
1.112 + };
1.113 +
1.114 + /**
1.115 + Sets the pin mode.
1.116 +
1.117 + @param aId The pin Id.
1.118 + @param aMode The pin mode.
1.119 +
1.120 + @return KErrNone, if successful; KErrArgument, if aId is invalid;
1.121 + KErrNotReady, when a pin that has requested to be Idle is not ready to do
1.122 + so;
1.123 + KErrNotSupported, if a pin cannot be used as a GPIO because it has been
1.124 + assigned an alternative function.
1.125 +
1.126 + When disabling a pin, the module which the pin is a part of may not be disabled,
1.127 + but KErrNone is still returned.
1.128 + */
1.129 + IMPORT_C static TInt SetPinMode(TInt aId, TGpioMode aMode);
1.130 +
1.131 + /**
1.132 + Reads the pin mode.
1.133 +
1.134 + @param aId The pin Id.
1.135 + @param aMode On return contains the pin mode.
1.136 +
1.137 + @return KErrNone, if successful; KErrArgument, if aId is invalid;
1.138 + KErrNotSupported, if reading the pin mode is not supported.
1.139 + */
1.140 + IMPORT_C static TInt GetPinMode(TInt aId, TGpioMode& aMode);
1.141 +
1.142 + /**
1.143 + Sets the pin direction.
1.144 +
1.145 + @param aId The pin Id.
1.146 + @param aDirection The pin direction.
1.147 +
1.148 + @return KErrNone, if successful; KErrArgument, if aId is invalid;
1.149 + KErrNotSupported, if a pin cannot operate in the direction specified.
1.150 + */
1.151 + IMPORT_C static TInt SetPinDirection(TInt aId, TGpioDirection aDirection);
1.152 +
1.153 + /**
1.154 + Reads the pin direction.
1.155 +
1.156 + @param aId The pin Id.
1.157 + @param aDirection On return contains the pin direction.
1.158 +
1.159 + @return KErrNone, if successful; KErrArgument, if aId is invalid;
1.160 + KErrNotSupported, if reading the pin direction is not supported.
1.161 + */
1.162 + IMPORT_C static TInt GetPinDirection(TInt aId, TGpioDirection& aDirection);
1.163 +
1.164 + /**
1.165 + Sets the bias on a pin.
1.166 +
1.167 + @param aId The pin Id.
1.168 + @param aBias The drive on the pin.
1.169 +
1.170 + @return KErrNone, if successful; KErrArgument, if aId is invalid;
1.171 + KErrNotSupported, if a pin does not support setting the drive.
1.172 + */
1.173 + IMPORT_C static TInt SetPinBias(TInt aId, TGpioBias aBias);
1.174 +
1.175 + /**
1.176 + Reads the bias on a pin.
1.177 +
1.178 + @param aId The pin Id.
1.179 + @param aBias On return contains the bias previoulsy set on the pin (or the
1.180 + default bias if first time).
1.181 +
1.182 + @return KErrNone, if successful;
1.183 + KErrArgument, if aId is invalid;
1.184 + KErrNotSupported, if reading the pin bias is not supported.
1.185 + */
1.186 + IMPORT_C static TInt GetPinBias(TInt aId, TGpioBias& aBias);
1.187 +
1.188 + /**
1.189 + Sets the idle configuration and state. The pin configuration is the
1.190 + same that the pin should have when setting the mode to EIdle and the
1.191 + state same it should present when setting the output state to EIdleState.
1.192 +
1.193 + @param aId The pin Id.
1.194 + @param aConf An implementation specific token specifying the idle
1.195 + configration and state.
1.196 +
1.197 + @return KErrNone, if successful;
1.198 + KErrArgument, if aId is invalid;
1.199 + KErrNotSupported, if setting the pin idle configuration and state
1.200 + are not supported.
1.201 + */
1.202 + IMPORT_C static TInt SetPinIdleConfigurationAndState(TInt aId, TInt aConf);
1.203 +
1.204 + /**
1.205 + Reads the pin idle configuration and state.
1.206 +
1.207 + @param aId The pin Id.
1.208 + @param aConf On return contains the idle configuration and state previoulsy
1.209 + set on the pin.
1.210 +
1.211 + @return KErrNone, if successful;
1.212 + KErrArgument, if aId is invalid;
1.213 + KErrNotSupported, if reading the pin idle configuration and state
1.214 + is not supported.
1.215 + */
1.216 + IMPORT_C static TInt GetPinIdleConfigurationAndState(TInt aId, TInt& aConf);
1.217 +
1.218 + /**
1.219 + Associates the specified interrupt service routine (ISR) function with the
1.220 + specified interrupt Id.
1.221 +
1.222 + @param aId The pin Id.
1.223 + @param anIsr The address of the ISR function.
1.224 + @param aPtr 32-bit value that is passed to the ISR.
1.225 + This is designated a TAny* type as it is usually a pointer to the
1.226 + owning class or data to be used in the ISR, although it can be any
1.227 + 32-bit value.
1.228 +
1.229 + @return KErrNone, if successful;
1.230 + KErrArgument, if aId is invalid;
1.231 + KErrNotSupported if pin does not support interrupts;
1.232 + KErrInUse, if an ISR is already bound to this interrupt.
1.233 + */
1.234 + IMPORT_C static TInt BindInterrupt(TInt aId, TGpioIsr aIsr, TAny* aPtr);
1.235 +
1.236 + /**
1.237 + Unbinds the interrupt service routine (ISR) function from the specified interrupt
1.238 + id.
1.239 +
1.240 + @param aId The pin Id.
1.241 +
1.242 + @return KErrNone, if successful;
1.243 + KErrArgument, if aId is invalid;
1.244 + KErrNotSupported if pin does not support interrupts;
1.245 + KErrGeneral, if there is no ISR bound to this interrupt.
1.246 + */
1.247 + IMPORT_C static TInt UnbindInterrupt(TInt aId);
1.248 +
1.249 + /**
1.250 + Enables the interrupt on specified pin.
1.251 +
1.252 + @param aId The pin Id.
1.253 +
1.254 + @return KErrNone, if successful;
1.255 + KErrArgument, if aId is invalid;
1.256 + KErrNotSupported if pin does not support interrupts;
1.257 + KErrGeneral, if there is no ISR bound to this interrupt.
1.258 + */
1.259 + IMPORT_C static TInt EnableInterrupt(TInt aId);
1.260 +
1.261 + /**
1.262 + Disables the interrupt on specified pin.
1.263 +
1.264 + @param aId The pin Id.
1.265 +
1.266 + @return KErrNone, if successful;
1.267 + KErrArgument, if aId is invalid;
1.268 + KErrNotSupported if pin does not support interrupts;
1.269 + KErrGeneral, if there is no ISR bound to this interrupt.
1.270 + */
1.271 + IMPORT_C static TInt DisableInterrupt(TInt aId);
1.272 +
1.273 + /**
1.274 + Checks if interrupt is enabled on pin.
1.275 +
1.276 + @param aId The pin Id.
1.277 + @param aEnable On return contains the enable/disable state of interrupt
1.278 + (TRUE=enabled).
1.279 +
1.280 + @return KErrNone, if successful;
1.281 + KErrArgument, if aId is invalid;
1.282 + KErrNotSupported if pin does not support interrupts;
1.283 + KErrGeneral, if there is no ISR bound to this interrupt.
1.284 + */
1.285 + IMPORT_C static TInt IsInterruptEnabled(TInt aId, TBool& aEnable);
1.286 +
1.287 + /**
1.288 + Clears any pending interrupt on the specified pin.
1.289 +
1.290 + @param aId The pin Id.
1.291 +
1.292 + @return KErrNone, if successful;
1.293 + KErrArgument, if aId is invalid;
1.294 + KErrNotSupported if clearing interrupt signal is not supported on this
1.295 + pin;
1.296 + KErrGeneral, if there is no ISR bound to this interrupt.
1.297 + */
1.298 + IMPORT_C static TInt ClearInterrupt(TInt aId);
1.299 +
1.300 + /**
1.301 + Reads the interrupt state as output by the GPIO interrupt controller.
1.302 +
1.303 + @param aId The pin Id.
1.304 + @param aActive On return contains the state of the interrupt signal as output by
1.305 + GPIO interrupt controller (TRUE=active).
1.306 +
1.307 + @return KErrNone, if successful;
1.308 + KErrArgument, if aId is invalid;
1.309 + KErrNotSupported if reading interrupt state is not supported;
1.310 + KErrGeneral, if there is no ISR bound to this interrupt.
1.311 + */
1.312 + IMPORT_C static TInt GetMaskedInterruptState(TInt aId, TBool& aActive);
1.313 +
1.314 + /**
1.315 + Reads the interrupt state on the specified pin before any masking.
1.316 +
1.317 + @param aId The pin Id.
1.318 + @param aActive On return contains state of the interrupt signal on the pin
1.319 + (TRUE=active).
1.320 +
1.321 + @return KErrNone, if successful;
1.322 + KErrArgument, if aId is invalid;
1.323 + KErrNotSupported if reading raw interrupt state is not supported;
1.324 + KErrGeneral, if there is no ISR bound to this interrupt.
1.325 + */
1.326 + IMPORT_C static TInt GetRawInterruptState(TInt aId, TBool& aActive);
1.327 +
1.328 + /**
1.329 + Sets the interrupt trigger on the specified pin.
1.330 +
1.331 + @param aId The pin Id.
1.332 + @param aTrigger The trigger type.
1.333 +
1.334 + @return KErrNone, if successful;
1.335 + KErrArgument, if aId is invalid;
1.336 + KErrNotSupported if pin does not support interrupts.
1.337 + */
1.338 + IMPORT_C static TInt SetInterruptTrigger(TInt aId, TGpioDetectionTrigger aTrigger);
1.339 +
1.340 + /**
1.341 + Enables the wakeup on specified pin.
1.342 +
1.343 + @param aId The pin Id.
1.344 +
1.345 + @return KErrNone, if successful;
1.346 + KErrArgument, if aId is invalid;
1.347 + KErrNotSupported if pin does not support wakeup.
1.348 + */
1.349 + IMPORT_C static TInt EnableWakeup(TInt aId);
1.350 +
1.351 + /**
1.352 + Disables the wakeup on specified pin.
1.353 +
1.354 + @param aId The pin Id.
1.355 +
1.356 + @return KErrNone, if successful;
1.357 + KErrArgument, if aId is invalid;
1.358 + KErrNotSupported if pin does not support wakeup.
1.359 + */
1.360 + IMPORT_C static TInt DisableWakeup(TInt aId);
1.361 +
1.362 + /**
1.363 + Checks if wakeup is enabled on pin.
1.364 +
1.365 + @param aId The pin Id.
1.366 + @param aEnable On return contains the enable/disable state of wakeup
1.367 + (TRUE=enabled).
1.368 +
1.369 + @return KErrNone, if successful;
1.370 + KErrArgument, if aId is invalid;
1.371 + KErrNotSupported if pin does not support wakeups;
1.372 + */
1.373 + IMPORT_C static TInt IsWakeupEnabled(TInt aId, TBool& aEnable);
1.374 +
1.375 + /**
1.376 + Sets the wakeup trigger on the specified pin.
1.377 +
1.378 + @param aId The pin Id.
1.379 + @param aTrigger The trigger type.
1.380 +
1.381 + @return KErrNone, if successful;
1.382 + KErrArgument, if aId is invalid;
1.383 + KErrNotSupported if pin does not support wakeup.
1.384 + */
1.385 + IMPORT_C static TInt SetWakeupTrigger(TInt aId, TGpioDetectionTrigger aTrigger);
1.386 +
1.387 + /**
1.388 + Sets the debouncing time on the specified pin.
1.389 +
1.390 + @param aId The pin Id.
1.391 + @param aTime The debouncing time in microseconds.
1.392 +
1.393 + @return KErrNone, if the time is succesfully changed or no change is needed (see
1.394 + below);
1.395 + KErrArgument, if aId is invalid;
1.396 + KErrNotSupported if pin does not support debouncing.
1.397 +
1.398 + If the requested time is greater than the common value for the module, the latter
1.399 + is increased to the value requested.
1.400 + If the requested time is lesser than the common value for the module then the
1.401 + common value is unchanged, unless it is set to the value requested on this pin.
1.402 + */
1.403 + IMPORT_C static TInt SetDebounceTime(TInt aId, TInt aTime);
1.404 +
1.405 + /**
1.406 + Reads the debouncing time on the specified pin.
1.407 +
1.408 + @param aId The pin Id.
1.409 + @param aTime On return contains the debouncing time in microseconds.
1.410 +
1.411 + @return KErrNone, if successful;
1.412 + KErrArgument, if aId is invalid;
1.413 + KErrNotSupported if pin does not support debouncing.
1.414 + */
1.415 + IMPORT_C static TInt GetDebounceTime(TInt aId, TInt& aTime);
1.416 +
1.417 + /**
1.418 + Reads the state of an input (synchronously).
1.419 +
1.420 + @param aId The pin Id.
1.421 + @param aState On return contains the pin state.
1.422 +
1.423 + @return KErrNone, if successful;
1.424 + KErrArgument, if aId is invalid.
1.425 + KErrNotSupported, if reading the state synchronously is not supported.
1.426 + */
1.427 + IMPORT_C static TInt GetInputState(TInt aId, TGpioState& aState);
1.428 +
1.429 + /**
1.430 + Sets the output pin to one of the supported states (synchronously).
1.431 +
1.432 + @param aId The pin Id.
1.433 + @param aState The pin state.
1.434 +
1.435 + @return KErrNone, if successful;
1.436 + KErrArgument, if aId is invalid;
1.437 + KErrNotSupported, if the state is not supported or if setting its state synchronously is not supported.
1.438 + */
1.439 + IMPORT_C static TInt SetOutputState(TInt aId, TGpioState aState);
1.440 +
1.441 + /**
1.442 + Reads the output pin states (synchronously).
1.443 +
1.444 + @param aId The pin Id.
1.445 + @param aState On return contains the pin state. On systems where the state of an
1.446 + ouptut pin cannot be read directly from hardware, or takes a non
1.447 + negligible time to be retrieved, the implementation must cache it.
1.448 +
1.449 + @return KErrNone, if successful;
1.450 + KErrArgument, if aId is invalid.
1.451 + */
1.452 + IMPORT_C static TInt GetOutputState(TInt aId, TGpioState& aState);
1.453 +
1.454 + /**
1.455 + Reads the state of an input (asynchronously).
1.456 +
1.457 + @param aId The pin Id.
1.458 + @param aCb A pointer to a GPIO callback object.
1.459 +
1.460 + @return KErrNone, if accepted;
1.461 + KErrArgument, if aId is invalid.
1.462 + KErrNotSupported, if reading the state asynchronously is not supported.
1.463 +
1.464 + This API should be used with off-chip GPIO modules only;
1.465 + The result of the read operation and the state of the input pin will be passed as an argument to the callback function;
1.466 + */
1.467 + IMPORT_C static TInt GetInputState(TInt aId, TGpioCallback* aCb);
1.468 +
1.469 + /**
1.470 + Sets the output pin to one of the supported states (asynchronously).
1.471 +
1.472 + @param aId The pin Id.
1.473 + @param aState The pin state.
1.474 + @param aCb A pointer to a GPIO callback object.
1.475 +
1.476 + @return KErrNone, if accepted;
1.477 + KErrArgument, if aId is invalid;
1.478 + KErrNotSupported, if setting its state asynchronously is not supported.
1.479 +
1.480 + This API should be used with off-chip GPIO modules only;
1.481 + The result of the set operation will be passed as an argument to the callback function;
1.482 + */
1.483 + IMPORT_C static TInt SetOutputState(TInt aId, TGpioState aState, TGpioCallback* aCb);
1.484 +
1.485 + /**
1.486 + Allows the platform specific implementation to extend the API.
1.487 +
1.488 + @param aId The pin Id.
1.489 + @param aCmd A PSL extension function id.
1.490 + @param aArg1 An argument to be passed to the PSL extension function.
1.491 + @param aArg2 An argument to be passed to the PSL extension function.
1.492 +
1.493 + @return KErrNone, if accepted;
1.494 + KErrArgument, if aId is invalid;
1.495 + KErrNotSupported, if static extensions are not supported.
1.496 + Any other system wide error code.
1.497 + */
1.498 + IMPORT_C static TInt StaticExtension(TInt aId, TInt aCmd, TAny* aArg1, TAny* aArg2);
1.499 + };
1.500 +
1.501 +/**
1.502 +@publishedPartner
1.503 +@prototype 9.6
1.504 +
1.505 +GPIO asynchronous callback function
1.506 +*/
1.507 +typedef void (*TGpioCbFn)(TInt /*aPinId*/,
1.508 + GPIO::TGpioState /*aState*/,
1.509 + TInt /*aResult*/,
1.510 + TAny* /*aParam*/);
1.511 +/**
1.512 +@publishedPartner
1.513 +@prototype 9.6
1.514 +
1.515 +GPIO asynchronous callback DFC
1.516 +The client must create one of these to be passed to each asynchronous call to GetInputState and SetOutputState
1.517 +The callback function is called in the context supplied by the client when creating an object of this kind (aQue)
1.518 +The callback function takes as arguments the pin id and the state, so it can be common to all TGpioCallback
1.519 +*/
1.520 +class TGpioCallback : public TDfc
1.521 + {
1.522 +public:
1.523 + inline TGpioCallback(TGpioCbFn aFn, TAny* aPtr, TDfcQue* aQue, TInt aPriority) : TDfc(DfcFunc, this, aQue, aPriority), iParam(aPtr), iCallback(aFn)
1.524 + {}
1.525 +private:
1.526 + inline static void DfcFunc(TAny* aPtr)
1.527 + {
1.528 + TGpioCallback* pCb = (TGpioCallback*) aPtr;
1.529 + pCb->iCallback(pCb->iPinId, pCb->iState, pCb->iResult, pCb->iParam);
1.530 + }
1.531 +public:
1.532 + TInt iPinId; // the Id of the pin on which the asynchronous operation is performed
1.533 + GPIO::TGpioState iState; // either the state the output pin should be moved to or the state the input pin is at
1.534 + TInt iResult; // the result of this transaction as a system wide error
1.535 + TAny* iParam;
1.536 + TGpioCbFn iCallback;
1.537 + };
1.538 +
1.539 +#endif /*__GPIO_H__*/
1.540 +