1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-AF71FDC2-A8CC-5035-91FE-36212844BC07" xml:lang="en"><title>Channel

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

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

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

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

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

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

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

    20 const TUint KConfigXyOffsetY    = 0;

    21 const TUint KConfigXyWidth = 640;  // pixels per line

    22 const TUint KConfigXyHeight = 480; // lines per panel

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

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

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

    26 <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>,

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

    28 </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

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

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

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

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

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

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

    35 </codeblock> </section>

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

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

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

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

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

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

    42 interrupts. </p> </li>

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

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

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

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

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

    48 </ol> </li>

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

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

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

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

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

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

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

    56 </ul> </section>

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

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

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

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

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

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

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

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

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

    66 down</b> </p> <p>The implementation for this case can be left until later.

    67 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

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

    69 down</b> </p> <p>To deal with this case, your implementation needs to: </p> <ul>

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

    71 interrupt </p> </li>

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

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

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

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

    76 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   102 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

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

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

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

   106 </ul> </li>

   107 </ol> </section>

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

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

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

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

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

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

   114 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

   115 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

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

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

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

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

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

   121     {

   122     if (!penDown)

   123         {

   124         ...

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

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

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

   128 interrupt </p> </li>

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

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

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

   132 interrupt. </p> </li>

   133 </ul> </li>

   134 </ol> </section>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   158 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

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

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

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

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

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

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

   165 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

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

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

   168 interrupt. </p> </li>

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

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

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

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

   173 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)

   174     {

   175     if (iState==E_HW_PenUpDebounce)

   176         {

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

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

   179 readings. </p> </section>

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

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

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

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

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

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

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

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

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

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

   190 </ul> </section>

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

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

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

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

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

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

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

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

   199 mode. </p> </li>

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

   201 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

   202 does the following: </p> <ul>

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

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

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

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

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

   208 </ul> </li>

   209 </ul> </section>

   210 </conbody></concept>