<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-745273E3-BB3A-59BF-9C33-6C8BB3D850A9" xml:lang="en"><title>GPIO

Design Considerations</title><shortdesc> General design considerations involved in implementing the Symbian

platform <apiname>GPIO</apiname> class.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-CC35EB0E-6156-50F9-9AFC-7D89F2BE2D8A"><title>Pin IDs</title> <p>To

manipulate a GPIO interface at the level of the pin it is necessary to have

a method of specifying individual pins which is both systematic and intuitive.

For the purposes of porting we need a systematic way of identifying a pin

by its module and bit number: this means specifying the module by its register

address and the bit number by a bit mask. However, device driver writers need

a way of identifying pins which makes it obvious what function each pin serves:

this means an enumeration of human readable names of pins. The implementation

must provide a translation between the names in the enumeration and their

values, which are pairs of module addresses and pin bit numbers. This translation

should be determined at build time from values held in the Configuration Repository. </p> </section>

<section id="GUID-6342758A-C4B6-5915-944C-B5FDA43D8708"><title>Electric states

and logical states</title> <p>For the purposes of GPIO functionality a pin

is in one of two logical states, True or False. Normally the True logical

state is implemented as the High electrical state and the False logical state

as the Low electrical state. This convention is assumed in the documentation

of the Symbian platform GPIO interface. Some platforms use the opposite convention,

True == Low and False == High: this is called negative logic. If GPIO is to

be implemented on a negative logic platform, implementers must make the appropriate

translation. </p> </section>

<section id="GUID-65A90119-F6CF-5EF3-B670-4A85557462D2"><title>Pin and module

modes</title> <p>At the level of the module (and the platform) logical states

other than <codeph>True</codeph> and <codeph>False</codeph> are possible:

the module may be disabled or idle and therefore the pin may be too. These

states are called modes. A GPIO module only works if it is enabled, that is

if power and clocks are supplied to it. A module may be completely disabled

or in a partially enabled state, called idle, in which it is on low power

but some functions such as wakeups and interrupts are enabled. </p> <p>The

Symbian platform GPIO class is specified at the level of the pin and so are

the modes: a pin has three modes: <codeph>Enabled</codeph>, <codeph>Disabled</codeph> and <codeph>Idle</codeph> as

specified in the enumeration <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>TGpioMode</apiname></xref>. The

mode of the pin affects the mode of the module. When a pin is set to Enabled

or Disabled mode, the implementation should set the module to the same mode.

When a pin is set to Idle, the implementation should attempt to set the module

to Idle, but the state and configuration of the other pins on the module may

override this. When a module is set to Idle the implementation should set

its pins to Idle too. </p> </section>

<section id="GUID-2BAF85D5-2E78-5A4B-A525-453F74AC6A18"><title>Idle mode and

idle state</title> <p>When a pin is in Idle mode it is in a third electrical

state, different from High and Low. This state is called <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>DefaultIdleState</apiname></xref> and

does not correspond to the logical state of the pin. A pin should never be

in this state when its direction is input because input pins are always in

Enabled or Disabled mode. (A pin might theoretically be in <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>DefaultIdleState</apiname></xref> because

it has never been enabled, but that would be a programming error.) However,

when a module enters the Idle state so do its pins. There are also circumstances

when it is necessary to know the electrical state of an output pin because

it cannot be deduced from the logical state. For this reason the Symbian platform <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GPIO</apiname></xref> class specifies functions to get and set the

electrical state of a pin for three values and not two: </p> <ul>

<li id="GUID-954DF6D9-0772-5239-BC71-EC31E5217AF6"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GetPinMode()</apiname></xref>  </p> </li>

<li id="GUID-9D03EDBF-D28B-5716-AB8C-EC619B3F45DF"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>SetPinMode()</apiname></xref>  </p> </li>

</ul> </section>

<section id="GUID-69FFCA37-FB93-543C-8938-9AA1A49720B9"><title>Pin directions</title> <p>Pins

are used as inputs or outputs of binary signals. The Symbian platform GPIO

class does not support bidirectional pins. However, some platforms allow pins

to be in a quiescent state (also called floating or tri-stated). In this case

a pin can be in one of three logical states: True, False or quiescent as specified

in the enumeration <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>TGpioDirection</apiname></xref>. The relevant

three-valued logic is specified in this table. </p> <table id="GUID-0FACE87C-4EAA-5392-A335-8706F6460EB6">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Input </entry>

<entry>Output</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><table id="GUID-0095FACD-4149-5743-8D73-652C3B32EA92">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<tbody>

<row>

<entry><p>A</p> </entry>

<entry><p>B</p> </entry>

</row>

<row>

<entry><p>0</p> </entry>

<entry><p>0</p> </entry>

</row>

<row>

<entry><p>1</p> </entry>

<entry><p>0</p> </entry>

</row>

<row>

<entry><p>0</p> </entry>

<entry><p>1</p> </entry>

</row>

<row>

<entry><p>1</p> </entry>

<entry><p>1</p> </entry>

</row>

</tbody>

</tgroup>

</table> </p> </entry>

<entry><p><table id="GUID-401A92A7-FE3F-5757-866D-3DC17BFACD39">

<tgroup cols="1"><colspec colname="col0"/>

<tbody>

<row>

<entry><p>C</p> </entry>

</row>

<row>

<entry><p>Z</p> </entry>

</row>

<row>

<entry><p>Z</p> </entry>

</row>

<row>

<entry><p>0</p> </entry>

</row>

<row>

<entry><p>1</p> </entry>

</row>

</tbody>

</tgroup>

</table> </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The electrical states corresponding to True and False are High

and Low. The quiescent logical state is often implemented as a high impedance

electrical state. </p> </section>

<section id="GUID-5A0C6110-0EFB-5F93-8645-7C03A3579DF7"><title>Debouncing</title> <p>Debouncing

means filtering out distortions of the signal caused, for instance, by physical

pressure on a key. Some platforms provide hardware mechanisms for debouncing,

otherwise implementers must provide for debouncing by software. Both hardware

and software debouncing involve sampling the signal at a specified interval:

the Symbian platform <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GPIO</apiname></xref> class provides

a function <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>SetDebounceTime()</apiname></xref> to supply that

interval but does not impose any restrictions on the implementation. Software

debouncing can be performed at the level of the pin rather than the module,

and this is strongly recommended where debouncing is performed by software. </p> </section>

<section id="GUID-8A9811B4-C0B5-5692-AF7D-8DD90C08FCF2"><title>Triggers</title> <p>A

trigger is the electrical waveform which signals an interrupt and sometimes

a wakeup. Triggers are detected either by their level (high or low) or by

their edge (rising, falling or both). When you associate an interrupt with

a trigger you must specify the type (level or edge) and then the subtype.

Some configurations of type and subtype are incompatible, for instance level

trigger with rising edge. The Symbian platform GPIO class specifies the possible

combinations in the enumeration <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>TGpioDetectionTrigger</apiname></xref>.

It is for the implementation to check that a given pin supports a consistent

configuration. </p> </section>

<section id="GUID-DF6588F5-0D6C-5BFD-A098-87F69E02C449"><title>Wakeups</title> <p>One

important use of GPIO input pins is to signal a wakeup request to the CPU.

Wakeup requests will usually take place when the system is idling and clocks

are switched off. This means that the kind of trigger used to signal wakeups

must be detected asynchronously (not on a clock edge) and hence that a wakeup

trigger should probably be configured for edge detection and not level detection.

Since a wakeup is generic to the whole CPU regardless of its origin, wakeups

are usually combined into a single signal by a logical OR operation. </p> </section>

<section id="GUID-5FFB000A-6ACF-54B1-B731-93FAA12BC1E9"><title>Bias</title> <p>Many

platforms will provide programmable bias capability. This means programmable

hardware to stabilise the state of a pin to its high or low state. For input

pins the mechanism is usually a resistor: a pull-up resistor causes a pin

to default to the high state and a pull-down resistor to the low state. Output

pins may also be stablised by resistors or sometimes by a weak drive. The

Symbian platform GPIO class supports three bias modes specified in the enumeration <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>TGpioBias</apiname></xref>: </p> <ul>

<li id="GUID-3B093EE2-F7E6-5317-BD6B-11EE3B190A4A"><p>pull-up, a bias to the

high state, </p> </li>

<li id="GUID-A399964E-2C3B-55C3-8198-0A78735C9207"><p>pull-down, a bias to

the low state, and </p> </li>

<li id="GUID-2741ACA5-B824-522F-88A0-D5D3036B5905"><p>no drive, an absence

of bias. </p> </li>

</ul> <p>These names refer to electrical states and are not intended to specify

the hardware mechanism used or the logical state corresponding to the electrical

state. </p> </section>

<section id="GUID-C66F5655-2444-5453-A556-DF1F947A0E45"><title>Interrupts</title> <p>A

common use for a pin is as a hardware interrupt source. The treatment of interrupts

is platform dependent. Typically, the hardware multiplexes all interrupts

from a module into a hardware controller: in this case it is part of the GPIO

implementation to demultiplex the requests. A GPIO implementation with the

capability to demultiplex will also have the capability to enable and disable

interrupts and to bind and unbind their handlers. The Symbian platform <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GPIO</apiname></xref> class specifies functions to do this: </p> <ul>

<li id="GUID-94D6091C-7BEC-51AB-A755-247801582289"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>BindInterrupt()</apiname></xref>  </p> </li>

<li id="GUID-DAB9AE04-760D-5C4C-8141-01418D2360F0"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>UnbindInterrupt()</apiname></xref>  </p> </li>

<li id="GUID-023E90D0-2C30-5C09-BA0B-F9779701703E"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>EnableInterrupt()</apiname></xref>  </p> </li>

<li id="GUID-8F6D74ED-16A3-5C10-9BFC-7C6D0A8A6B14"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>DisableInterrupt()</apiname></xref>  </p> </li>

</ul> <p>In implementing interrupt capability it is important to know whether

or not the hardware clears an interrupt source when the interrupt status has

been read. </p> <p>If it does not, there is a need for a function which explicitly

clears the source, and the Symbian platform <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GPIO</apiname></xref> class

provides one to be implemented. If it does, it is not possible to determine

whether the interrupt is still active after the clear operation. Some hardware

allows you to read the raw state of the pin, and doing so will answer that

question: other hardware does not. That is why the interface specifies two

functions to read the interrupt state, one raw and one masked: </p> <ul>

<li id="GUID-DF29D3D3-1CA6-540F-8337-7EEA10A38CCE"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GetMaskedInterruptState()</apiname></xref>  </p> </li>

<li id="GUID-74FCC2DC-2953-5D8C-BB7B-C318BB6D7B08"><p> <xref href="GUID-C93C53D3-2BE8-36AE-83B8-4CDB4195649B.dita"><apiname>GetRawInterruptState()</apiname></xref>  </p> </li>

</ul> </section>

<section id="GUID-0D3C2E2D-BCE4-5E2A-BCC9-42C64D9F5BA3"><title>Pin sharing</title> <p>There

is no general reason why a pin which is available for use for GPIO should

not also be available for some other function, and the Symbian platform GPIO

specification allows for this. There are certain circumstances where pin sharing

should be prevented, for instance when a pin is in use as an interrupt source,

and these cases are specified individually. </p> </section>

<section id="GUID-1C7F0D25-D9D6-528B-B9F5-6353DF560E03"><title>Use of the

API on-chip and off-chip</title> <p>The Symbian platform GPIO class API is

intended for use with both on-chip and off-chip modules. This is why the functions

to get and set the pin state are specified in two versions, synchronous and

asynchronous: </p> <ul>

<li id="GUID-AEE9C49A-59B3-5D30-AD58-E4216964BF62"><p> <codeph>GetInputState(TInt

aId, TGpioState&amp; aState)</codeph>  </p> </li>

<li id="GUID-7168FAB3-63A0-572F-B103-2217C256E7B7"><p> <codeph>GetInputState(TInt

aId, TGpioCallback* aCb)</codeph>  </p> </li>

<li id="GUID-3A0ABE44-D241-5FCB-928D-96EDBCB1B227"><p> <codeph>SetOutputState(TInt

aId, TGpioState aState)</codeph>  </p> </li>

<li id="GUID-38D365F2-F49A-56B4-9DD7-320FA460EA9E"><p> <codeph>SetOutputState(TInt

aId,TGpioState aState,TGpioCallback*                 aCb)</codeph>  </p> </li>

</ul> <p>When the API is used on-chip the operations execute near-instantaneously

in the context of a single calling thread. Under these circumstances it is

appropriate to use synchronous versions of the functions. </p> <p>When the

API is used off-chip the operations do not execute instantaneously, may block

and take a fast mutex, and may pass control to a different thread. Under these

circumstances it is appropriate to use asynchronous versions of the functions

using callbacks. </p> <p>It is possible to implement the API using the synchronous

versions of the functions with off-chip modules. In this case the implementation

must take care to block the client thread during the execution of the API. </p> </section>

<section id="GUID-1E838852-C9D2-50F4-9955-5371FC2AB703"><title>Preconditions

for use of the API</title> <p>The preconditions for using the API are different

when used with on-chip modules and off-chip modules. </p> <p>The preconditions

for using all functions of the API with on-chip modules are: </p> <ul>

<li id="GUID-1213783F-35E3-5A12-9071-00183C9C315A"><p>call in any context

(no preconditions). </p> </li>

</ul> <p>The preconditions for using all functions of the API with off-chip

modules are: </p> <ul>

<li id="GUID-F1443579-585F-5F51-86B7-98C12641B760"><p>kernel must be unlocked, </p> </li>

<li id="GUID-5DDC3022-D187-5940-80C0-6BA1CC7FAC7D"><p>no fast mutex must be

held, </p> </li>

<li id="GUID-FE2D9025-DE4B-5E05-A519-AC8F8F1B5018"><p>interrupts must be enabled,

and </p> </li>

<li id="GUID-A21599F7-683D-5B55-B026-EED8D719A611"><p>call must be from thread

context. </p> </li>

</ul> </section>

<section id="GUID-29CD6B92-9DC3-5839-918E-4C0C5ABC4ADC"><title>Locks</title> <p>It

is expected that the implementation of all the API functions will involve

the use of locks. In principle locks are not necessary where a function can

be implemented exclusively by a single read, write or modify call to the hardware

register API. </p> </section>

</conbody><related-links>

<link href="GUID-0E15C8C4-E511-569F-8AB4-895CA00331AB.dita"><linktext>GPIO Features</linktext>

</link>

<link href="GUID-48AEF60B-D2B6-55B5-96FD-55C1F1868A3F.dita"><linktext>GPIO Implementation

Guide</linktext></link>

</related-links></concept>