--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Adaptation/GUID-DBEAD516-5DD4-5E33-B6DA-657C1AE60C4B.dita	Fri Oct 15 14:32:18 2010 +0100
@@ -0,0 +1,166 @@
+<?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-DBEAD516-5DD4-5E33-B6DA-657C1AE60C4B" xml:lang="en"><title>Dynamic
+Behaviour</title><shortdesc>Describes the dynamic behaviour of the Digitizer Driver. The description
+shows the use of the template port. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>The design assumes that interrupts are generated by pen-down events; however,
+there is no difficulty in adjusting your implementation to deal with interrupts
+generated by pen-up events. </p>
+<p>The heart of the design is a DFC that reads digitizer data samples when
+the pen goes down, and then samples the digitizer at regular intervals until
+the pen goes up. These samples are accumulated in a buffer in the platform
+independent layer. When enough samples have been gathered, the platform independent
+layer averages them, processes them, and issues pen movement events. </p>
+<table id="GUID-324D657A-DBA8-5862-BC0D-04F02CE2A9D4">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><p>In the template port, the behaviour of the platform specific layer
+is based on three states: </p> </entry>
+<entry><p>The template port represents these three states using the enum values
+of the enum <codeph>TSate,</codeph> defined within the scope of the <codeph>DTemplateDigitiser</codeph> class
+(derived from <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref>). The enum values are: </p> </entry>
+</row>
+<row>
+<entry><p>"power up" </p> </entry>
+<entry><p> <codeph> E_HW_PowerUp</codeph>  </p> </entry>
+</row>
+<row>
+<entry><p>"collect sample" </p> </entry>
+<entry><p> <codeph>E_HW_CollectSample</codeph>  </p> </entry>
+</row>
+<row>
+<entry><p>"pen up debounce" </p> </entry>
+<entry><p> <codeph>E_HW_PenUpDebounce</codeph>  </p> </entry>
+</row>
+</tbody>
+</tgroup>
+</table>
+<section id="GUID-7860EA0B-CE04-4D32-B813-9D23274999AD"><title>State diagram</title> <p>The flow of control through the digitizer
+is described by this state diagram. The notes following relate to this state
+diagram on the left-hand side. </p> <p>The diagram on the right-hand side
+shows, in a simplified form, the flow of control. The numbers correspond to
+the state diagram numbers. Calls into the platform independent layer are shown
+in green boxes; important functions are shown in purple boxes. </p> <table id="GUID-23381681-744E-54DA-AAA2-5F30AD486783">
+<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
+<tbody>
+<row>
+<entry><fig id="GUID-C7D88A4C-B5A0-5A1B-8710-188DC398B6CB">
+<image href="GUID-F127644A-6072-52CA-9B17-E9DDEA784BE0_d0e8997_href.png" placement="inline"/>
+</fig> </entry>
+<entry><fig id="GUID-F244E871-48C7-548E-AF69-43D4265F9C48">
+<image href="GUID-9173EEBA-CC84-51D9-9C8D-A75F7F494D62_d0e9004_href.png" placement="inline"/>
+</fig> </entry>
+</row>
+</tbody>
+</tgroup>
+</table> <ol id="GUID-B0BF0EE6-5059-5C43-BEE7-C500751CEC36">
+<li id="GUID-5E21DADA-B4C0-5F90-B7C7-DF44C4FAA0CC"><p>If the pen is down at
+power on, i.e. when in the <i>power up</i> state, the device keeps sampling
+the digitiser at regular intervals until the pen is up. In the template port,
+the interval is defined by the constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-EDA72AF2-460E-52F0-9EC7-634B7AC14D46">KPenUpPollTime</xref> </p> </li>
+<li id="GUID-DC234930-4914-54BB-B7D1-AF13832EB65F"><p>If the pen is up at
+power on, i.e. when in the <i>power up</i> state, or when the pen is first
+lifted, the sampling is initialised; see <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-4B0737BA-74E2-5FF2-BCE3-4BC822C14470">Step
+6 - initialise sampling</xref>  </p> </li>
+<li id="GUID-788762CA-2B94-5E8E-944E-8BC79F5E8E7B"><p>If the pen is down in
+the <i>collect sample</i> state, then the digitiser coordinates are sampled
+at regular intervals, and stored in a buffer allocated by the platform independent
+layer. When a group of samples has been taken, the platform specific layer
+calls <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-35568A81-14C1-39A2-A8AC-A1D1ED1C0E93"><apiname>DDigitiser::RawSampleValid()</apiname></xref> in the platform independent
+layer to start the processing of the samples. </p> <p>In the template port,
+the interval is defined by the constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-C8EC7A1D-7597-57BB-ADE4-0EDFFEB323D0">KInterSampleTime</xref>; see <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-4E84D583-7745-531B-AB62-65D012B4BCB2">Step
+7 - take sample readings</xref>. </p> </li>
+<li id="GUID-161E6630-D116-5559-BD19-10BA9A30FDEA"><p>If the pen is lifted
+while in the <i>collect sample</i> state, then the state changes to the <i>pen
+up debounce</i> state. This state describes the situation where a pen is lifted
+from the device and there is uncertainty as to whether this represents a positive
+move by the user, or whether the pen pressure has just been reduced momentarily.
+A delay is scheduled to decide to see which is case is true. At the end of
+the interval the state of the pen is checked again. If the pen is found to
+be down at the end of this interval, then the state changes back to the <i>collect
+sample</i> state, and the sample buffer is reset. </p> <p>In the template
+port, the delay interval is defined by the constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-9BFC5FDA-FC84-5B54-93AA-BED4035F2A59">KPenUpDebounceTime</xref>. </p> </li>
+<li id="GUID-FE0F5F20-683E-5860-81E8-940F9FD98794"><p>If the pen is found
+to be down at the end of this interval, then the state changes back to the <i>collect
+sample</i> state, and the sample buffer is reset. </p> </li>
+<li id="GUID-84C0E701-1076-517B-B212-A4A48F2F622B"><p>If the pen is found
+to be still up at the end of this interval, then the pen is assumed to be
+intentionally up. The sample buffer is reset in preparation for future readings,
+and the platform independent layer is notified that the pen is now up by calling <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-58094BAE-A932-366A-A2B0-977E3539540C"><apiname>DDigitiser::PenUp()</apiname></xref>. </p> </li>
+</ol> </section>
+<section id="GUID-CD820F5C-01F7-427F-8FFC-675CDE48F1BD"><title>Interaction between the two layers</title> <p>This section
+shows the main interactions between the two layers: </p> <p><b>1</b> </p> <fig id="GUID-BC82D3E5-C190-57F4-AAC4-38532E2225E9">
+<image href="GUID-4FDD1F7B-1A4E-5389-A0A4-22727CD42B5B_d0e9110_href.png" placement="inline"/>
+</fig> <p>When the device is started, the platform independent layer calls
+the function <codeph>DoCreate()</codeph>. This is where the power handler
+should be registered, interrupts bound and any other initialisation should
+take place. </p> <p>The platform independent layer then calls the function <codeph>WaitForPenDown()</codeph>.
+This is declared as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class
+and is implemented in the platform specific layer. This function is also called
+from the <codeph>ProcessPenUp()</codeph> function that runs in a DFC thread
+scheduled to run when the pen is lifted. This DFC is scheduled in the platform
+specific layer. </p> <p>See also <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-1A1194A0-DF74-59E7-B3AD-FD87D501F00F">Step
+4 - implement DDigitiser::WaitForPenDown()</xref>. </p> <p><b>2</b> </p> <fig id="GUID-3C50B57F-46A9-5CF0-94BB-50E63837D2CB">
+<image href="GUID-AE53C15E-0C0F-5726-BBA4-E7DCDA7F48B4_d0e9145_href.png" placement="inline"/>
+</fig> <p>The platform specific layer calls <codeph>RawSampleValid()</codeph> when
+it has a group of digitizer coordinates ready to be processed by the platform
+independent layer. This is called in the context of a DFC thread, the DFC
+being queued when the digitizer interrupt is fired. </p> <p><b>3</b> </p> <fig id="GUID-AAEC4068-6743-5E50-906D-AE05622A0627">
+<image href="GUID-DE7BD5C8-9966-5D5E-B81F-D57EA9FBA451_d0e9161_href.png" placement="inline"/>
+</fig> <p>The platform independent layer calls <codeph>WaitForPenUp()</codeph> to
+request another sample from the hardware. This is declared as pure virtual
+in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and is implemented in the platform
+specific layer. The function is called after the platform independent layer
+has processed a group of raw samples while the pen is down, and also tells
+the platform specific layer that the buffers in the platform independent layer
+can be re-used. </p> <p><b>4</b> </p> <fig id="GUID-5C3344EC-B07F-5D02-A107-7F4BB381EB55">
+<image href="GUID-C8450E58-A603-5CF8-993E-053C990DDA19_d0e9181_href.png" placement="inline"/>
+</fig> <p>The platform independent layer calls <codeph>WaitForPenUpDebounce()</codeph> if
+a group of collected samples is not good enough. This is declared as pure
+virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and is implemented in the
+platform specific layer. The function is called after the platform independent
+layer has processed a group of raw samples while the pen is down and also
+tells the platform specific layer that the buffers in the platform independent
+layer can be re-used. </p> <p><b>5</b> </p> <fig id="GUID-CAF3646F-0078-5F25-94A8-B03A42B132BC">
+<image href="GUID-465D1450-B1EF-568B-B518-34ACE8C1697C_d0e9201_href.png" placement="inline"/>
+</fig> <p>When the pen is lifted, the platform specific layer calls <codeph>PenUp()</codeph> in
+the platform independent layer, which then changes its internal state, issues
+a pen up event to the device, and then calls <codeph>WaitForPenDown()</codeph> in
+the platform specific layer. </p> <p><b>6</b> </p> <fig id="GUID-77BBAF4E-D737-54CF-B67C-292D5ABD5CB3">
+<image href="GUID-DB0EDBC2-8204-59F3-9029-EBBCE04A9E3C_d0e9220_href.png" placement="inline"/>
+</fig> <p>The platform independent layer calls <codeph>DigitiserOn()</codeph> when
+the device is turned on, or it may be called from the HAL. The function, implemented
+in the platform specific layer, and turns the hardware on if it is not already
+on. See also <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-A4B43E01-9638-5967-8EFA-0AABA33189EA">Step
+3 - implement power on behaviour</xref>. </p> <p><b>7</b> </p> <fig id="GUID-481F038C-2C5D-5D95-88A3-62F54EEDA713">
+<image href="GUID-2622DE31-AA12-5FAD-86FB-B13259EFC6D9_d0e9239_href.png" placement="inline"/>
+</fig> <p> <codeph>DigitiserOff()</codeph> turns the digitizer off, and may
+be called as a result of a power transition, or it may be called from the
+HAL. If it is called from the Power Manager, the digitizer may already be
+off if the platform is in silent running mode. See also <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-6DC8A3DB-452F-5738-9D60-7E34BF8A3596">Step 10 - implement DDigitiser::DigitiserOff()</xref>. </p> <p><b>8</b> </p> <p>There are two functions: <codeph>DigitiserToScreen()</codeph> and <codeph>ScreenToDigitiser()</codeph> that
+convert digitizer coordinates to and from screen coordinates. Both are declared
+as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class and need to be
+implemented in the platform specific layer. </p> <p><b>9</b> </p> <fig id="GUID-500D1D6B-85AE-5C1C-8F34-95036A6B9D82">
+<image href="GUID-3F0053A7-6EE2-5B59-81C2-27EC3CC7820A_d0e9276_href.png" placement="inline"/>
+</fig> <p>The platform independent layer provides the <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-1B59A40C-D023-5555-8E5E-DF18D653D321">HAL handler</xref> for the <xref href="GUID-E22F7F41-C578-36B4-A7AB-AE0AEF520A69.dita"><apiname>EHalGroupDigitiser</apiname></xref>  <xref href="GUID-9AE254D4-AA60-579E-8D9D-F2797106A413.dita#GUID-9AE254D4-AA60-579E-8D9D-F2797106A413/GUID-366CC4B8-C6BD-5DCC-B55D-6D87CD5C8E64">HAL groups and function-ids</xref>. This is <codeph>DDigitiser::HalFunction()</codeph>.
+It delegates the handling of 5 of the individual behaviours, as represented
+by the <xref href="GUID-86A737D5-0602-3DB3-9CFF-764C80A8D468.dita"><apiname>TDigitiserHalFunction</apiname></xref> function-ids, to the following
+functions, declared as pure virtual in the <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita"><apiname>DDigitiser</apiname></xref> class,
+and implemented by the platform specific layer: </p> <ul>
+<li id="GUID-A1F40F14-B2AB-5784-B5E9-35411C722CD0"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-1B0F51F0-C3F4-333A-AC7E-CE332248355E"><apiname>DDigitiser::SetXYInputCalibration()</apiname></xref>  </p> </li>
+<li id="GUID-2EC061EB-FBC4-5462-98E2-AA79B6BFD981"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-856B4F1A-ACE4-338B-B618-3DB3830CE0B9"><apiname>DDigitiser::CalibrationPoints()</apiname></xref>  </p> </li>
+<li id="GUID-4DBA15F8-34D3-5586-BF0C-89B648005EEE"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-90861298-19B7-3D1F-80CD-E49D4C500D49"><apiname>DDigitiser::SaveXYInputCalibration()</apiname></xref>  </p> </li>
+<li id="GUID-B6CCEBBA-93CD-5C2A-9343-9F22E7E1DD2D"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-4184805F-CF27-30AA-A551-684B595E4228"><apiname>DDigitiser::RestoreXYInputCalibration()</apiname></xref>  </p> </li>
+<li id="GUID-4626F772-B9E9-5313-80F3-AF7859F58ADD"><p> <xref href="GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9.dita#GUID-2EDAF642-2399-3594-986A-5E8A5EEA01B9/GUID-B2B3E681-018C-34A9-9686-580B60FE0D40"><apiname>DDigitiser::DigitiserInfo()</apiname></xref>  </p> </li>
+</ul> </section>
+</conbody></concept>
\ No newline at end of file