<?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>