--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-745273E3-BB3A-59BF-9C33-6C8BB3D850A9.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,256 @@
+<?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>
\ No newline at end of file