<?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-4D55CE6D-050B-401F-9F89-B5164AE1FB19" xml:lang="en"><title>Using
the GPIO SHAI in a device driver</title><shortdesc>Describes how to use the GPIO SHAI in a device driver.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>GPIO is often used to provide input and output for a device driver. </p>
<section id="GUID-F368B344-3015-4E57-BD7F-84261BB5ED1C">       <title>Configuration
and initialization</title>       <p>When a device driver uses input and output
from GPIO, typically the driver is a PDD and GPIO is a kernel extension, the
driver being a client of GPIO. Unlike all other MHA implementations except
Resource Manager, a GPIO implementation must have an initial state reflecting
the configuration of the pins as determined by the hardware connected to them
and by the OS Loader (NLoader). GPIO therefore needs to be configured at boot,
and this is done using the hardware configuration repository (HCR) which is
also a kernel extension. For this reason, HCR must be loaded at boot before
GPIO and any other kernel extension which uses pins. HCR supplies the following
items of data to GPIO.</p><ul>
<li><p>The number of pin banks.</p></li>
<li><p>The base address of all pin banks.</p></li>
<li><p>The total number of pins.</p></li>
<li><p>What functions are not supported by the hardware.</p></li>
</ul><p>HCR also supplies GPIO with the following data about individual pins.</p><p>For
each pin:</p><ul>
<li><p>The numeric value corresponding to the logical pin name.</p></li>
<li><p>The run mode pin direction.</p></li>
<li><p>The alternate mode value, if the pin is to be used in alternate mode.</p></li>
<li><p>The run mode pin bias.</p></li>
<li><p>The pin configuration for power saving mode if the SOC supports power
saving.</p></li>
</ul><p>For each output pin:</p><ul>
<li><p>The value of the state corresponding to the logical state</p></li>
</ul><p>For each input pin:</p><ul>
<li><p>The debounce time</p></li>
<li><p>The wakeup trigger, if the pin is configured in GPIO mode</p></li>
</ul><p>For each input pin used as an interrupt source:</p><ul>
<li><p>The input trigger configuration</p></li>
</ul><p>GPIO uses these values as arguments of the appropriate API functions
to set the values. For instance, if the debounce time for a certain pin has
been retrieved, that value is passed to a call to <xref href="GUID-837F3EC5-5379-3B88-B27B-A092E9F2E422.dita"><apiname>SetDebounceTime()</apiname></xref>.</p><p>Some
pins are not constrained by hardware and need to be configured by the client
in the mode required for its own operation. For each pin not constrained by
hardware the client must:</p><ul>
<li><p>Set the pin to GPIO enabled.</p></li>
<li><p>Set the pin direction.</p></li>
<li><p>Set the pin bias.</p></li>
<li><p>Set the numeric value of alternative modes where needed.</p></li>
</ul><p>Power aware drivers may need to configure the input pins which they
use to wake up the system and the driver itself so it can respond to signals
on those pins. Some output pins may also need to be configured.</p>     </section>
<section id="GUID-6F041BDE-9D24-4B3D-B701-4C4071CFE66C"><title>Steady state
of the client</title><p>Once initialization is complete, the client enters
its 'steady state' and begins operations. </p><p>If the client is using the
pins to input and output data it calls the GPIO functions <xref href="GUID-EB28CB99-7191-345B-90FC-7708E9D190C7.dita"><apiname>SetOutputState()</apiname></xref> and <xref href="GUID-9BFB4B87-1400-33C0-B116-AC6FA349BE1E.dita"><apiname>GetInputState()</apiname></xref> as
required.</p><p>If the client driver is using pins as a source of interrupts
it must define an interrupt service routine (ISR) to be dispatched by the
interrupt handler. After an interrupt the client must stop the GPIO hardware
from interrupting the CPU with calls to the GPIO APIs <xref href="GUID-3B91EDB8-1BD0-3C13-BF9F-E0A11EC39F84.dita"><apiname>GetMaskedInterruptState()</apiname></xref> and <xref href="GUID-1F8A4B69-BF3D-31C6-934D-93BF47E3E407.dita"><apiname>ClearInterrupt()</apiname></xref>.</p></section>
<section id="GUID-C3DFA412-8ADD-4FD6-A827-53E672A30345"><title>Unloading and
stopping the client</title><p>When the client is unloaded it must disable
the interupts with calls to the GPIO functions <xref href="GUID-E00AE446-FF29-3B97-A38D-5A6B05F51D81.dita"><apiname>DisableInterrupt()</apiname></xref> and <xref href="GUID-590E49F1-73A2-3770-80D9-14710982B661.dita"><apiname>UnbindInterrupt()</apiname></xref> and
set the output pins to idle with calls to the GPIO functions <xref href="GUID-EB28CB99-7191-345B-90FC-7708E9D190C7.dita"><apiname>SetOutputState()</apiname></xref> and <xref href="GUID-47A5FEB0-144E-398B-A3B0-8A524A59B7F2.dita"><apiname>SetPinMode()</apiname></xref>,
and it must also set the output pins to idle when it is stopped.</p></section>
</conbody></concept>