<?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-AF71FDC2-A8CC-5035-91FE-36212844BC07" xml:lang="en"><title>Channel

Implementation</title><shortdesc>Describes how to use the template port to implement the physical

channel for the Digitizer Driver. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-EA342370-0293-5762-86FD-E86DC6BC3006"><title>Define the

size of the digitizer</title> <p>The following four constants defined at the

top of the template implementation in <filepath>xyin.cpp</filepath> define

the origin and size of the digitizer device in pixels. Modify the values to

define your own origin and size. </p> <codeblock id="GUID-8A7E9CCC-D6A2-5E5D-B0DB-8AE3334F6EC9" xml:space="preserve">const TUint KConfigXyOffsetX    = 0;

const TUint KConfigXyOffsetY    = 0;

const TUint KConfigXyWidth = 640;  // pixels per line

const TUint KConfigXyHeight = 480; // lines per panel

</codeblock> <p>This is information that is returned when calls are made: </p> <ul>

<li id="GUID-003FE140-2DDF-58B4-AA1F-57F8A0FCF4E7"><p> <i>user side</i> to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> passing

the attribute(s) <xref href="GUID-696EDBEB-76B2-3F02-AD33-BA4977551F32.dita"><apiname>EPenX</apiname></xref> and <xref href="GUID-3E3B49CC-53F6-3341-A969-1DDC0A837B0B.dita"><apiname>EPenY</apiname></xref>  </p> </li>

<li id="GUID-0C5E452E-5564-5A27-B379-5BF3D9518E78"><p> <i>kernel side</i> to <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-DA115709-A225-3E2A-BCCD-6E2BB15979B9"><apiname>Kern::HalFunction()</apiname></xref>,

passing group <xref href="GUID-357CC84A-F701-3F56-AF4D-0C95002F1A8E.dita"><apiname>EHalGroupdigitizer</apiname></xref> and function-id <xref href="GUID-841ECDFD-7CAB-30BB-A301-CF70C029043B.dita"><apiname>EdigitizerHalXYInfo</apiname></xref>  </p> </li>

</ul> <p>See <xref href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">User-Side

Hardware Abstraction</xref>. </p> <p>The following four constants define the

digitizer origin and size in digitizer ADC coordinates. Modify the values

for your own digitizer: </p> <codeblock id="GUID-ED04E417-16B5-5AA2-96FB-B450BAC272A9" xml:space="preserve">const Tint KConfigXySpreadX = 4096; // maximum valid X spread

const Tint KConfigXySpreadY = 4096; // maximum valid Y spread

const Tint KConfigXyMinX = 0;       // minimum valid X value

const Tint KConfigXyMinY = 0;       // minimum valid Y value

</codeblock> </section>

<section id="GUID-A4B43E01-9638-5967-8EFA-0AABA33189EA"><title>Implement power

on behaviour</title> <p>In the template port, this is implemented by <b>DTemplatedigitizer::digitizerPowerUp()</b>.

Note that this function is not derived from any base class function. </p> <ul>

<li id="GUID-2B31DD8F-DACF-50FD-8FC6-DC6C55954CC5"><p>Add code to this function

to do these things: </p> <ol id="GUID-324D32A9-50F0-53F9-A717-AE026626A76E">

<li id="GUID-7A461F0B-EBEE-5F73-BFA1-031EEAB9BCF9"><p>Clear all digitizer

interrupts. </p> </li>

<li id="GUID-62182E91-A6B0-5C3C-8CC5-4C993235EF02"><p>Request power resources

from the power controller. This will power the device up from sleep mode.

Note that power up, and power down, can be implemented later. </p> </li>

<li id="GUID-D9CFB381-4D23-5E47-808B-C5CE52F99223"><p>Configure the hardware

so that it generates an interrupt when the digitizer is touched. </p> </li>

</ol> </li>

<li id="GUID-AFFF418C-9FD7-5EE6-9487-968FDCF7B795"><p>Make sure that the digitizer

interrupt is defined. In the template port, the interrupt id is defined as

the constant: </p> <codeblock id="GUID-7D7940D8-4708-501C-AA44-1C9A6961260A" xml:space="preserve">const TInt KIntIddigitizer=EAsspIntIdC</codeblock> <p>in

the file <filepath>...\template\template_assp\template_assp.h</filepath>. </p> </li>

<li id="GUID-EE388EFA-84D7-5E1E-A75F-66310EAEF8E5"><p>Make sure that the interrupt

controller is configured for the digitizer interrupt. See <xref href="GUID-76A30EC4-4B99-5471-9E80-F853C91485BC.dita">Interrupt

Dispatcher</xref>. </p> </li>

</ul> </section>

<section id="GUID-1A1194A0-DF74-59E7-B3AD-FD87D501F00F"><title>Implement Ddigitizer::WaitForPenDown()</title> <p>This

code is executed at startup or whenever the pen is lifted up. It implements

a request for an interrupt to be generated when the pen next touches the digitizer.

It is called by the platform independent layer: </p> <ul>

<li id="GUID-1D1D1ED7-12EC-51B9-A5B7-228E0390DF4C"><p>at startup </p> </li>

<li id="GUID-C8999684-87B6-5DDA-AB4F-D990B7512365"><p>when the pen is removed

from the digitizer after a pen-up event has been issued. </p> </li>

</ul> <p>There are two main cases to deal with: the digitizer is powering

down; the digitizer is not powering down </p> <p id="GUID-9DC378A0-05F9-52B0-A441-1E451E85D213"><b>The

digitizer is powering down</b> </p> <p>The implementation for this case can

be left until later. It is discussed in <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-FE7F24DF-6A65-5A7E-A9C8-DBCF7848DEA6">Implement

power up and power down handling</xref>. </p> <p id="GUID-4B4CF159-E5B2-5EAA-8489-8E1921BA0AF1"><b>The

digitizer is <i>not</i> powering down</b> </p> <p>To deal with this case,

your implementation needs to: </p> <ul>

<li id="GUID-633792DB-C955-57E0-8DB1-2FDB2EC20269"><p>clear the digitizer

interrupt </p> </li>

<li id="GUID-2F88C290-C412-50EF-8E2C-BE0CC5A489DA"><p>set up the hardware

so that it can detect when the digitizer is touched. </p> </li>

</ul> <p>The pen interrupt is now enabled; if the digitizer is now touched,

the pen interrupt ISR (interrupt service routine) <codeph>DTemplatedigitizer::PenInterrupt()</codeph> is

called. </p> <p>In the template port, the ISR includes the statement: </p> <codeblock id="GUID-351F56AC-8B3D-55F6-B3EC-77F623C18BE1" xml:space="preserve">__KTRACE_OPT(KHARDWARE,Kern::Printf("I"));</codeblock> <p>and

means that if the <codeph>KHARDWARE</codeph> tracing flag has been set, and

tracing is on, then a single “I” is printed whenever the digitizer is touched. </p><b>Tracing

note</b> <p>If the <codeph>KEXTENSION</codeph>, <codeph>KPOWER</codeph> and <codeph>KHARDWARE</codeph> tracing

flags have been set, and tracing is on, then by the time <codeph>WaitForPenDown()</codeph> is

called, you should be able to see the following sequence of calls in the trace:<ul>

<li><p><codeph>DoCreate()</codeph></p></li>

<li><p><codeph>digitizerPowerUp()</codeph></p></li>

<li><p><codeph>WaitForPenDown()</codeph></p></li>

</ul></p> </section>

<section id="GUID-D74C94E4-83AD-5BC0-B435-754E7D3FECA4"><title>Implement the

pen interrupt ISR</title> <p>In the template port, the interrupt service routine

(ISR) that handles a pen interrupt is implemented by <b>DTemplatedigitizer::PenInterrupt()</b>.

Note that this function is not derived from any base class function. </p> <p>There

are two main things to consider here: </p> <ol id="GUID-4CD5BC52-AC79-55E8-B38F-EA9DCB048A04">

<li id="GUID-4D9F1CC5-E256-53F7-8E7D-B31ED3296C7D"><p>You need to add code

to the start of the function to decide whether the pen is now up (i.e. removed

from the screen panel), or whether the pen is now down (i.e. touching the

digitizer panel). To make the decision, you may need to read the appropriate

hardware register. The detail depends on the hardware. </p> </li>

<li id="GUID-4FF2D674-4BB1-50EB-B55C-DF18652A1E5F"><p>If the pen is down,

you need to check the value of the configurable constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-587D0895-7B8D-5FA1-A2DE-2F346780BB78">KPenDownDelayTime</xref>. What you do next depends on the value of this constant: </p> <ul>

<li id="GUID-C238E00E-7A7C-5A44-A63D-5D214C30727D"><p>If the value is greater

than zero, then you do not need to change the code at this time. The existing

code just starts a timer to delay the beginning of the collection of samples.

Note, however, that you will need to modify the debounce timer callback function <codeph>timerIntExpired()</codeph> to

clear the digitizer interrupt - see <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-7ADA202E-23F8-52E1-BE57-B44FF75C5612">Add

code to the debounce timer callback function</xref>. </p> </li>

<li id="GUID-985A0D59-B45D-59D3-894F-9B9509B03E70"><p>If the value is zero,

then you must clear the digitizer interrupt here in this function, <codeph>PenInterrupt()</codeph>. </p> </li>

</ul> </li>

<li id="GUID-B2766A95-D916-428F-84AE-2D4ADDFF999A"><p>To contribute the timing

of pen interrupts as a source of random data for the Random Number Generator

(see <xref href="GUID-8290AAF0-577C-51D2-8AC1-0D37A10F45CB.dita">CSPRNG Implementation

in Kernel</xref>), ensure that a call to <xref href="GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3.dita#GUID-E7A7083C-97B9-39B9-A147-4A6E314EE3A3/GUID-C46E48EE-6F4A-3A61-A3C9-84B145119541"><apiname>Interrupt::AddTimingEntropy()</apiname></xref> is

made in the ISR.</p></li>

</ol> </section>

<section id="GUID-4B0737BA-74E2-5FF2-BCE3-4BC822C14470"><title>Initialise

sampling</title> <p>In the template port, the initialisation of sampling is

implemented in the first half of the function <b>DTemplatedigitizer::TakeSample()</b> function.

Note that this function is not derived from any base class function. </p> <p>There

are two main things to consider here: </p> <ol id="GUID-1101F7D6-EDEF-5B9F-832C-75D298ACF1E4">

<li id="GUID-A56C4872-FDD0-571C-A721-C267BB1DFD5C"><p>You need to decide whether

the pen is up or down. Set the variable <codeph>penDown</codeph> to <xref href="GUID-781E8158-805B-3784-8FED-D7A191822FC3.dita"><apiname>ETrue</apiname></xref> if

the pen is down or <xref href="GUID-A759CA2D-8327-348F-9337-4886E619D920.dita"><apiname>EFalse</apiname></xref> if the pen is up. </p> <p>To

do this you may need to read the appropriate hardware register - the detail

depends on the hardware. </p> </li>

<li id="GUID-4B498AD5-766B-57DF-8021-2A7BB7FB5C19"><p>Change the section of

code that is executed when the pen is found to be up after a power on, i.e.

the block of code: </p> <codeblock id="GUID-4CE73640-1D2F-50F2-AD85-92B2F0FA35DC" xml:space="preserve">if (iState==E_HW_PowerUp)

    {

    if (!penDown)

        {

        ...

        }</codeblock> <p>The block of code needs to do the following: </p> <ul>

<li id="GUID-22297738-82AA-5F87-AE35-09903161E793"><p>reset the sample buffer </p> </li>

<li id="GUID-D22ED4D2-B602-5270-9131-053E6B17191B"><p>clear the digitizer

interrupt </p> </li>

<li id="GUID-32A574A0-42D0-5953-AB00-BDFAABD4C82E"><p>set up the hardware

so that it can detect when the digitizer is touched </p> </li>

<li id="GUID-B422C5F4-D7F8-5BD1-B9B5-130B9EFBD44A"><p>enable the digitizer

interrupt. </p> </li>

</ul> </li>

</ol> </section>

<section id="GUID-4E84D583-7745-531B-AB62-65D012B4BCB2"><title>Take sample

readings</title> <p>In the template port, the initialisation of sampling is

implemented in the second half of the function <b>DTemplatedigitizer::TakeSample()</b> function.

Note that this function is not derived from any base class function. </p> <p>This

code is executed while the pen is down, and needs to do the following: </p> <ul>

<li id="GUID-F9FB32EF-7967-5753-8D4F-BBEAF3BC2AC9"><p>read the hardware for

the digitizer samples and put the results into the sample buffer. The sample

buffer resides in the platform independent layer. </p> </li>

<li id="GUID-E4F4B6D9-9455-5B43-A025-735A6A1235B0"><p>set up the hardware

so that it can detect when the digitizer is touched </p> </li>

<li id="GUID-642B38D4-658A-59A0-AA7C-D497CB6A0FF4"><p>schedule the reading

of the next sample using a one shot timer; the time interval is defined by

the value of the configurable constant <xref href="GUID-3574BE12-9DA9-573D-8545-3B073005A139.dita#GUID-3574BE12-9DA9-573D-8545-3B073005A139/GUID-C8EC7A1D-7597-57BB-ADE4-0EDFFEB323D0">KInterSampleTime</xref> </p> </li>

<li id="GUID-C3B71C41-8C33-5A39-B1D8-B08CD6D7AE6E"><p>when a complete group

of samples has been taken, tell the platform independent layer by calling <codeph>RawSampleValid()</codeph>;

the function is a member of the base class <xref href="GUID-52E09E60-E29C-359C-926B-9836D960EF20.dita"><apiname>Ddigitizer</apiname></xref>. </p> </li>

</ul> <p><b>Tracing note </b> </p> <p>If the <codeph>KHARDWARE</codeph> tracing

flag has been set, and tracing is on, then it should be possible to move the

pen over the screen and see the raw sample values on the debug output. Check

they are correct. </p> </section>

<section id="GUID-7ADA202E-23F8-52E1-BE57-B44FF75C5612"><title>Add code to

the debounce timer callback function</title> <p>In the template port, the

debounce timer callback function is implemented by the local function <b>timerIntExpired()</b>. </p> <p>If

not already done in <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-D74C94E4-83AD-5BC0-B435-754E7D3FECA4">Implement

the pen interrupt ISR</xref>, add code to this callback function to clear

the digitizer interrupt. </p> </section>

<section id="GUID-8F229C58-66B5-5D0A-9058-8C57586F5B45"><title>Deal with a

pen up interrupt</title> <p>If the digitizer generates an interrupt when the

pen is lifted, then you need to add code to the pen interrupt ISR to handle

this. This is the same function, <b>DTemplatedigitizer::PenInterrupt()</b>,

referred to in <xref href="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07.dita#GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07/GUID-D74C94E4-83AD-5BC0-B435-754E7D3FECA4">Implement

the pen interrupt ISR</xref>. </p> <p>The code should: </p> <ul>

<li id="GUID-46619FF8-B3A0-556C-8B7F-D93CA3BAD2DA"><p>clear the digitizer

interrupt. </p> </li>

<li id="GUID-6E7353D8-118D-5FD9-9557-68DBCCBF32D9"><p>set up the hardware

so that it can detect when the digitizer panel is touched. </p> </li>

</ul> <p>If there is no pen up interrupt by design, then you need to add code

into the <b>DTemplatedigitizer::TakeSample()</b> function at the point where

the pen is up and the digitizer is in the <i>pen up debounce</i> state (i.e. <codeph>E_HW_PenUpDebounce</codeph>): </p> <codeblock id="GUID-6AF28551-7F20-5C70-8D0E-E40F2DD50417" xml:space="preserve">if (!penDown)

    {

    if (iState==E_HW_PenUpDebounce)

        {

        . . .</codeblock> <p>At this point, you should have almost all digitizer

capability – pen up handling, pen down handling, and the taking of digitizer

readings. </p> </section>

<section id="GUID-6DC8A3DB-452F-5738-9D60-7E34BF8A3596"><title>Implement Ddigitizer::digitizerOff()</title> <p>This

function is called when the digitizer is being powered down. </p> <p>If the

device is powered on, then the function needs to do disable the digitizer

interrupt. </p> <p>If the digitizer is in the <i>collect sample</i> state

(i.e. <codeph>E_HW_CollectSample</codeph>), then it also needs to do the following: </p> <ul>

<li id="GUID-7C5A6267-9CE2-587F-9092-F16DB89E8283"><p>set up the hardware

so that the device wakes up from standby if the digitizer panel is touched. </p> </li>

<li id="GUID-F606C7D1-A0FD-5845-B9A0-EAF13D3F5B01"><p>relinquish the request

for power resources; this will place the peripheral hardware into a low power

"sleep" mode, which is capable of detecting an interrupt. </p> </li>

</ul> </section>

<section id="GUID-FE7F24DF-6A65-5A7E-A9C8-DBCF7848DEA6"><title>Implement power

up and power down handling</title> <p>At this point, the device should be

working successfully. </p> <p>You now need to put the device into a low power

"sleep" mode when it is switched off, and to bring it out of "sleep" mode

when the digitizer is touched. </p> <ul>

<li id="GUID-EE805C9C-62F1-5F03-A9F9-643BC025E047"><p>Add code to the template

port function <b>DTemplatedigitizer::digitizerPowerUp()</b> to request power

resources from the power controller. This will power the device up from sleep

mode. </p> </li>

<li id="GUID-141FEF1E-B284-5970-89CF-81F9C6CD3890"><p>Add code to the powering

down part of your implementation of <xref href="GUID-52E09E60-E29C-359C-926B-9836D960EF20.dita#GUID-52E09E60-E29C-359C-926B-9836D960EF20/GUID-43E7AF76-DF07-3688-984A-80365150C080"><apiname>Ddigitizer::WaitForPenDown()</apiname></xref> that

does the following: </p> <ul>

<li id="GUID-310D240A-CCCC-5978-8798-75EE01B13E7D"><p>sets up the hardware

to wake the device from standby if the digitizer is touched. </p> </li>

<li id="GUID-D7C488F1-8727-5948-A7D1-3D1C4A306AF9"><p>relinquishes the request

for power resources - this will place the peripheral hardware into a low power

"sleep" mode, which is capable of detecting an interrupt. </p> </li>

</ul> </li>

</ul> </section>