|
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 |
|
66 digitizer is powering down</b> </p> <p>The implementation for this case can |
|
67 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 |
|
68 power up and power down handling</xref>. </p> <p id="GUID-4B4CF159-E5B2-5EAA-8489-8E1921BA0AF1"><b>The |
|
69 digitizer is <i>not</i> powering down</b> </p> <p>To deal with this case, |
|
70 your implementation needs to: </p> <ul> |
|
71 <li id="GUID-633792DB-C955-57E0-8DB1-2FDB2EC20269"><p>clear the digitizer |
|
72 interrupt </p> </li> |
|
73 <li id="GUID-2F88C290-C412-50EF-8E2C-BE0CC5A489DA"><p>set up the hardware |
|
74 so that it can detect when the digitizer is touched. </p> </li> |
|
75 </ul> <p>The pen interrupt is now enabled; if the digitizer is now touched, |
|
76 the pen interrupt ISR (interrupt service routine) <codeph>DTemplatedigitizer::PenInterrupt()</codeph> is |
|
77 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 |
|
78 means that if the <codeph>KHARDWARE</codeph> tracing flag has been set, and |
|
79 tracing is on, then a single “I” is printed whenever the digitizer is touched. </p><b>Tracing |
|
80 note</b> <p>If the <codeph>KEXTENSION</codeph>, <codeph>KPOWER</codeph> and <codeph>KHARDWARE</codeph> tracing |
|
81 flags have been set, and tracing is on, then by the time <codeph>WaitForPenDown()</codeph> is |
|
82 called, you should be able to see the following sequence of calls in the trace:<ul> |
|
83 <li><p><codeph>DoCreate()</codeph></p></li> |
|
84 <li><p><codeph>digitizerPowerUp()</codeph></p></li> |
|
85 <li><p><codeph>WaitForPenDown()</codeph></p></li> |
|
86 </ul></p> </section> |
|
87 <section id="GUID-D74C94E4-83AD-5BC0-B435-754E7D3FECA4"><title>Implement the |
|
88 pen interrupt ISR</title> <p>In the template port, the interrupt service routine |
|
89 (ISR) that handles a pen interrupt is implemented by <b>DTemplatedigitizer::PenInterrupt()</b>. |
|
90 Note that this function is not derived from any base class function. </p> <p>There |
|
91 are two main things to consider here: </p> <ol id="GUID-4CD5BC52-AC79-55E8-B38F-EA9DCB048A04"> |
|
92 <li id="GUID-4D9F1CC5-E256-53F7-8E7D-B31ED3296C7D"><p>You need to add code |
|
93 to the start of the function to decide whether the pen is now up (i.e. removed |
|
94 from the screen panel), or whether the pen is now down (i.e. touching the |
|
95 digitizer panel). To make the decision, you may need to read the appropriate |
|
96 hardware register. The detail depends on the hardware. </p> </li> |
|
97 <li id="GUID-4FF2D674-4BB1-50EB-B55C-DF18652A1E5F"><p>If the pen is down, |
|
98 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> |
|
99 <li id="GUID-C238E00E-7A7C-5A44-A63D-5D214C30727D"><p>If the value is greater |
|
100 than zero, then you do not need to change the code at this time. The existing |
|
101 code just starts a timer to delay the beginning of the collection of samples. |
|
102 Note, however, that you will need to modify the debounce timer callback function <codeph>timerIntExpired()</codeph> to |
|
103 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 |
|
104 code to the debounce timer callback function</xref>. </p> </li> |
|
105 <li id="GUID-985A0D59-B45D-59D3-894F-9B9509B03E70"><p>If the value is zero, |
|
106 then you must clear the digitizer interrupt here in this function, <codeph>PenInterrupt()</codeph>. </p> </li> |
|
107 </ul> </li> |
|
108 <li id="GUID-B2766A95-D916-428F-84AE-2D4ADDFF999A"><p>To contribute the timing |
|
109 of pen interrupts as a source of random data for the Random Number Generator |
|
110 (see <xref href="GUID-8290AAF0-577C-51D2-8AC1-0D37A10F45CB.dita">CSPRNG Implementation |
|
111 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 |
|
112 made in the ISR.</p></li> |
|
113 </ol> </section> |
|
114 <section id="GUID-4B0737BA-74E2-5FF2-BCE3-4BC822C14470"><title>Initialise |
|
115 sampling</title> <p>In the template port, the initialisation of sampling is |
|
116 implemented in the first half of the function <b>DTemplatedigitizer::TakeSample()</b> function. |
|
117 Note that this function is not derived from any base class function. </p> <p>There |
|
118 are two main things to consider here: </p> <ol id="GUID-1101F7D6-EDEF-5B9F-832C-75D298ACF1E4"> |
|
119 <li id="GUID-A56C4872-FDD0-571C-A721-C267BB1DFD5C"><p>You need to decide whether |
|
120 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 |
|
121 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 |
|
122 do this you may need to read the appropriate hardware register - the detail |
|
123 depends on the hardware. </p> </li> |
|
124 <li id="GUID-4B498AD5-766B-57DF-8021-2A7BB7FB5C19"><p>Change the section of |
|
125 code that is executed when the pen is found to be up after a power on, i.e. |
|
126 the block of code: </p> <codeblock id="GUID-4CE73640-1D2F-50F2-AD85-92B2F0FA35DC" xml:space="preserve">if (iState==E_HW_PowerUp) |
|
127 { |
|
128 if (!penDown) |
|
129 { |
|
130 ... |
|
131 }</codeblock> <p>The block of code needs to do the following: </p> <ul> |
|
132 <li id="GUID-22297738-82AA-5F87-AE35-09903161E793"><p>reset the sample buffer </p> </li> |
|
133 <li id="GUID-D22ED4D2-B602-5270-9131-053E6B17191B"><p>clear the digitizer |
|
134 interrupt </p> </li> |
|
135 <li id="GUID-32A574A0-42D0-5953-AB00-BDFAABD4C82E"><p>set up the hardware |
|
136 so that it can detect when the digitizer is touched </p> </li> |
|
137 <li id="GUID-B422C5F4-D7F8-5BD1-B9B5-130B9EFBD44A"><p>enable the digitizer |
|
138 interrupt. </p> </li> |
|
139 </ul> </li> |
|
140 </ol> </section> |
|
141 <section id="GUID-4E84D583-7745-531B-AB62-65D012B4BCB2"><title>Take sample |
|
142 readings</title> <p>In the template port, the initialisation of sampling is |
|
143 implemented in the second half of the function <b>DTemplatedigitizer::TakeSample()</b> function. |
|
144 Note that this function is not derived from any base class function. </p> <p>This |
|
145 code is executed while the pen is down, and needs to do the following: </p> <ul> |
|
146 <li id="GUID-F9FB32EF-7967-5753-8D4F-BBEAF3BC2AC9"><p>read the hardware for |
|
147 the digitizer samples and put the results into the sample buffer. The sample |
|
148 buffer resides in the platform independent layer. </p> </li> |
|
149 <li id="GUID-E4F4B6D9-9455-5B43-A025-735A6A1235B0"><p>set up the hardware |
|
150 so that it can detect when the digitizer is touched </p> </li> |
|
151 <li id="GUID-642B38D4-658A-59A0-AA7C-D497CB6A0FF4"><p>schedule the reading |
|
152 of the next sample using a one shot timer; the time interval is defined by |
|
153 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> |
|
154 <li id="GUID-C3B71C41-8C33-5A39-B1D8-B08CD6D7AE6E"><p>when a complete group |
|
155 of samples has been taken, tell the platform independent layer by calling <codeph>RawSampleValid()</codeph>; |
|
156 the function is a member of the base class <xref href="GUID-52E09E60-E29C-359C-926B-9836D960EF20.dita"><apiname>Ddigitizer</apiname></xref>. </p> </li> |
|
157 </ul> <p><b>Tracing note </b> </p> <p>If the <codeph>KHARDWARE</codeph> tracing |
|
158 flag has been set, and tracing is on, then it should be possible to move the |
|
159 pen over the screen and see the raw sample values on the debug output. Check |
|
160 they are correct. </p> </section> |
|
161 <section id="GUID-7ADA202E-23F8-52E1-BE57-B44FF75C5612"><title>Add code to |
|
162 the debounce timer callback function</title> <p>In the template port, the |
|
163 debounce timer callback function is implemented by the local function <b>timerIntExpired()</b>. </p> <p>If |
|
164 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 |
|
165 the pen interrupt ISR</xref>, add code to this callback function to clear |
|
166 the digitizer interrupt. </p> </section> |
|
167 <section id="GUID-8F229C58-66B5-5D0A-9058-8C57586F5B45"><title>Deal with a |
|
168 pen up interrupt</title> <p>If the digitizer generates an interrupt when the |
|
169 pen is lifted, then you need to add code to the pen interrupt ISR to handle |
|
170 this. This is the same function, <b>DTemplatedigitizer::PenInterrupt()</b>, |
|
171 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 |
|
172 the pen interrupt ISR</xref>. </p> <p>The code should: </p> <ul> |
|
173 <li id="GUID-46619FF8-B3A0-556C-8B7F-D93CA3BAD2DA"><p>clear the digitizer |
|
174 interrupt. </p> </li> |
|
175 <li id="GUID-6E7353D8-118D-5FD9-9557-68DBCCBF32D9"><p>set up the hardware |
|
176 so that it can detect when the digitizer panel is touched. </p> </li> |
|
177 </ul> <p>If there is no pen up interrupt by design, then you need to add code |
|
178 into the <b>DTemplatedigitizer::TakeSample()</b> function at the point where |
|
179 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) |
|
180 { |
|
181 if (iState==E_HW_PenUpDebounce) |
|
182 { |
|
183 . . .</codeblock> <p>At this point, you should have almost all digitizer |
|
184 capability – pen up handling, pen down handling, and the taking of digitizer |
|
185 readings. </p> </section> |
|
186 <section id="GUID-6DC8A3DB-452F-5738-9D60-7E34BF8A3596"><title>Implement Ddigitizer::digitizerOff()</title> <p>This |
|
187 function is called when the digitizer is being powered down. </p> <p>If the |
|
188 device is powered on, then the function needs to do disable the digitizer |
|
189 interrupt. </p> <p>If the digitizer is in the <i>collect sample</i> state |
|
190 (i.e. <codeph>E_HW_CollectSample</codeph>), then it also needs to do the following: </p> <ul> |
|
191 <li id="GUID-7C5A6267-9CE2-587F-9092-F16DB89E8283"><p>set up the hardware |
|
192 so that the device wakes up from standby if the digitizer panel is touched. </p> </li> |
|
193 <li id="GUID-F606C7D1-A0FD-5845-B9A0-EAF13D3F5B01"><p>relinquish the request |
|
194 for power resources; this will place the peripheral hardware into a low power |
|
195 "sleep" mode, which is capable of detecting an interrupt. </p> </li> |
|
196 </ul> </section> |
|
197 <section id="GUID-FE7F24DF-6A65-5A7E-A9C8-DBCF7848DEA6"><title>Implement power |
|
198 up and power down handling</title> <p>At this point, the device should be |
|
199 working successfully. </p> <p>You now need to put the device into a low power |
|
200 "sleep" mode when it is switched off, and to bring it out of "sleep" mode |
|
201 when the digitizer is touched. </p> <ul> |
|
202 <li id="GUID-EE805C9C-62F1-5F03-A9F9-643BC025E047"><p>Add code to the template |
|
203 port function <b>DTemplatedigitizer::digitizerPowerUp()</b> to request power |
|
204 resources from the power controller. This will power the device up from sleep |
|
205 mode. </p> </li> |
|
206 <li id="GUID-141FEF1E-B284-5970-89CF-81F9C6CD3890"><p>Add code to the powering |
|
207 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 |
|
208 does the following: </p> <ul> |
|
209 <li id="GUID-310D240A-CCCC-5978-8798-75EE01B13E7D"><p>sets up the hardware |
|
210 to wake the device from standby if the digitizer is touched. </p> </li> |
|
211 <li id="GUID-D7C488F1-8727-5948-A7D1-3D1C4A306AF9"><p>relinquishes the request |
|
212 for power resources - this will place the peripheral hardware into a low power |
|
213 "sleep" mode, which is capable of detecting an interrupt. </p> </li> |
|
214 </ul> </li> |
|
215 </ul> </section> |
|
216 </conbody></concept> |