--- a/Symbian3/PDK/Source/GUID-2E42E7EA-FED8-522C-8A5F-F65D799476C9.dita Thu Mar 11 15:24:26 2010 +0000
+++ b/Symbian3/PDK/Source/GUID-2E42E7EA-FED8-522C-8A5F-F65D799476C9.dita Thu Mar 11 18:02:22 2010 +0000
@@ -1,124 +1,124 @@
-<?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-2E42E7EA-FED8-522C-8A5F-F65D799476C9" xml:lang="en"><title>Keyboard
-Driver Implementation Tutorial</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
-<p>This topic describes how to implement an interrupt driven keyboard driver. </p>
-<p>The steps are: </p>
-<ul>
-<li id="GUID-BC3A7259-A750-5D5F-8363-6F8BBC03E8EB"><p>Implement the driver
-entry point function and initialisation code. This function is called when
-the extension is loaded. </p> <p>The initialisation code binds the hardware
-interrupt to the Interrupt Service Routine (ISR) and enables the interrupt. </p> </li>
-<li id="GUID-3A050F21-FE10-5C0F-8BFE-C44692C0BDE2"><p>Implement an ISR to
-handle key events. The ISR queues a keyboard DFC. </p> </li>
-<li id="GUID-6580FC61-3D9E-5370-88AD-50CC1FB28E5F"><p>Implement a keyboard
-DFC. This function interrogates the keyboard, converts the scancode to a keypress
-event, and places it onto the kernel's event queue. </p> </li>
-</ul>
-<section id="GUID-B4B6A6C6-39D0-49FC-A630-1979368056B0"><title>Set Up</title> <p>In the template reference board port, the <filepath>.mmp</filepath> file
-for the keyboard driver is <filepath>...\template_variant\exkey_inttemplate.mmp</filepath>.
-This is one of the PRJ_MMPFILES referenced in the template variant's <filepath>bld.inf</filepath> file
-in the <filepath>...\template_variant\...</filepath> directory, and means
-that the keyboard driver is built as part of the Variant. </p> <p>The source
-for the driver is contained entirely within <filepath>...\template_variant\specific\keyboard_interrupt.cpp</filepath>. </p> <p>The
-driver is defined as a kernel extension and is loaded early in the boot sequence. </p> </section>
-<section id="GUID-547A2791-82D8-4C86-86E6-B4B9CEF04E3B"><title>Entry point implementation</title> <p>The driver functionality
-is encapsulated by the <codeph>DKeyboardTemplate</codeph> class, and an instance
-of this is created when the extension is loaded. </p> <p>As the driver is
-a kernel extension, it must have a <codeph>DECLARE_STANDARD_EXTENSION()</codeph> statement.
-In the template port, this is implemented: </p> <codeblock id="GUID-69F707CF-642D-5D03-AC78-4914549C4413" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
- {
- __KTRACE_OPT(KEXTENSION,Kern::Printf("Starting keyboard driver"));
-
- // create keyboard driver
- TInt r=KErrNoMemory;
- DKeyboardTemplate* pK=new DKeyboardTemplate;
- if (pK)
- r=pK->Create();
-
- __KTRACE_OPT(KEXTENSION,Kern::Printf("Returns %d",r));
- return r;
- }
-
-</codeblock> <p>It simply creates an instance of the <codeph>DKeyboardTemplate</codeph> class
-and then performs a second-phase initialisation, which is a common pattern
-in Symbian platform and third party applications. </p> <p><b>Initialisation
-on construction</b> </p> <p>The constructor of the <codeph>DKeyboardTemplate</codeph> class
-has the following signature: </p> <codeblock id="GUID-5D247843-FF8C-5157-8BE5-53B5883F00B2" xml:space="preserve">DKeyboardTemplate::DKeyboardTemplate()
- : DPowerHandler(KLitKeyboard),
- iMsgQ(rxMsg,this,NULL,1),
- iPowerUpDfc(PowerUpDfcFn,this,6),
- iPowerDownDfc(PowerDownDfcFn,this,7),
- iEventDfc(EventDfcFn,this,1)
- {
- }
-
-</codeblock> <p>See also <xref href="GUID-3C34724F-B476-5329-B0B1-6D5A34294979.dita">Interrupt
-Dispatcher Tutorial</xref>. </p> </section>
-<section id="GUID-F11265AA-D280-4B4E-92DA-38F12E7D5E30"><title> Interrupt Service Routine (ISR) implementation</title> <p>The
-ISR (Interrupt Service Routine) just schedules the DFC that handles the keypress.
-On the template reference board, this is implemented as: </p> <codeblock id="GUID-866CEA65-78AC-5A2C-AF08-29DF8FE53DD5" xml:space="preserve">void DKeyboardTemplate::Isr(TAny* aPtr)
- {
- DKeyboardTemplate& k=*(DKeyboardTemplate*)aPtr;
- Interrupt::Disable(KIntIdKeyboard);
- k.iEventDfc.Add();
- }
-</codeblock> <p>The ISR disables the keyboard interrupt, as repeated ISRs
-are not allowed to queue further DFC routines. </p> </section>
-<section id="GUID-E53E0FE1-3100-4B8B-BE90-250C1BDDE15C"><title>DFC function implementation</title> <p>The DFC is the function <codeph>DKeyboardTemplate::EventDfcFn</codeph> which
-is implemented as a call to <codeph>DKeyboardTemplate::EventDfc()</codeph>. </p> <codeblock id="GUID-2A1B334A-441E-57C3-B40C-603D992F934F" xml:space="preserve">void DKeyboardTemplate::EventDfcFn(TAny* aPtr)
- {
- ((DKeyboardTemplate*)aPtr)->EventDfc();
- }
-
-void DKeyboardTemplate::EventDfc()
- {
- __KTRACE_OPT(KHARDWARE,Kern::Printf("DKeyboardTemplate::EventDfc"));
-
- TInt irq=NKern::DisableAllInterrupts();
- while (IsKeyReady()) // while there are keys in the controller's output buffer
- {
- NKern::RestoreInterrupts(irq);
- TRawEvent e;
- TUint keyCode=GetKeyCode(); // Read keycodes from controller
- __KTRACE_OPT(KHARDWARE,Kern::Printf("#%02x",keyCode));
-
- //
- // TO DO: (mandatory)
- //
- // Convert from hardware scancode to EPOC scancode and send the scancode as an event (key pressed or released)
- // as per below EXAMPLE ONLY:
- //
- TUint bareCode=keyCode&~KFlagKeyPressed;
- TUint8 stdKey=convertCode[bareCode];
- if (keyCode&KFlagKeyPressed)
- e.Set(TRawEvent::EKeyUp,stdKey,0);
- else
- e.Set(TRawEvent::EKeyDown,stdKey,0);
- Kern::AddEvent(e);
- NKern::Sleep(1); // pause before reading more keycodes
- irq=NKern::DisableAllInterrupts();
- }
- Interrupt::Enable(KIntIdKeyboard);
- NKern::RestoreInterrupts(irq);
- }</codeblock> <p>This: </p> <ul>
-<li id="GUID-8A202894-34F8-5E7B-B791-20D4B6C8B914"><p>reads the scan code
-data by calling <codeph>DKeyboardTemplate::GetKeyCode()</codeph> </p> </li>
-<li id="GUID-D553B662-F60C-575F-893D-347A9344F9B9"><p>re-enables the keyboard
-interrupt, now that the DFC has freed up the input data register </p> </li>
-<li id="GUID-BFC75E95-A9AE-584E-8A17-CCAF9C2F5913"><p>translates the keypress
-event into a Symbian scancode </p> </li>
-<li id="GUID-20BC22AF-C58C-56DC-B777-B5C8681668D6"><p>puts the translated
-event on to the event queue. </p> </li>
-</ul> </section>
-<section id="GUID-437735D9-916C-4308-913C-3839CC7F0002"><title>See also</title> <p> <xref href="GUID-EB76FAF8-CD4B-5CB6-9F23-C852ED91866F.dita">Concepts</xref> </p> </section>
+<?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-2E42E7EA-FED8-522C-8A5F-F65D799476C9" xml:lang="en"><title>Keyboard
+Driver Implementation Tutorial</title><shortdesc/><prolog><metadata><keywords/></metadata></prolog><conbody>
+<p>This topic describes how to implement an interrupt driven keyboard driver. </p>
+<p>The steps are: </p>
+<ul>
+<li id="GUID-BC3A7259-A750-5D5F-8363-6F8BBC03E8EB"><p>Implement the driver
+entry point function and initialisation code. This function is called when
+the extension is loaded. </p> <p>The initialisation code binds the hardware
+interrupt to the Interrupt Service Routine (ISR) and enables the interrupt. </p> </li>
+<li id="GUID-3A050F21-FE10-5C0F-8BFE-C44692C0BDE2"><p>Implement an ISR to
+handle key events. The ISR queues a keyboard DFC. </p> </li>
+<li id="GUID-6580FC61-3D9E-5370-88AD-50CC1FB28E5F"><p>Implement a keyboard
+DFC. This function interrogates the keyboard, converts the scancode to a keypress
+event, and places it onto the kernel's event queue. </p> </li>
+</ul>
+<section id="GUID-B4B6A6C6-39D0-49FC-A630-1979368056B0"><title>Set Up</title> <p>In the template reference board port, the <filepath>.mmp</filepath> file
+for the keyboard driver is <filepath>...\template_variant\exkey_inttemplate.mmp</filepath>.
+This is one of the PRJ_MMPFILES referenced in the template variant's <filepath>bld.inf</filepath> file
+in the <filepath>...\template_variant\...</filepath> directory, and means
+that the keyboard driver is built as part of the Variant. </p> <p>The source
+for the driver is contained entirely within <filepath>...\template_variant\specific\keyboard_interrupt.cpp</filepath>. </p> <p>The
+driver is defined as a kernel extension and is loaded early in the boot sequence. </p> </section>
+<section id="GUID-547A2791-82D8-4C86-86E6-B4B9CEF04E3B"><title>Entry point implementation</title> <p>The driver functionality
+is encapsulated by the <codeph>DKeyboardTemplate</codeph> class, and an instance
+of this is created when the extension is loaded. </p> <p>As the driver is
+a kernel extension, it must have a <codeph>DECLARE_STANDARD_EXTENSION()</codeph> statement.
+In the template port, this is implemented: </p> <codeblock id="GUID-69F707CF-642D-5D03-AC78-4914549C4413" xml:space="preserve">DECLARE_STANDARD_EXTENSION()
+ {
+ __KTRACE_OPT(KEXTENSION,Kern::Printf("Starting keyboard driver"));
+
+ // create keyboard driver
+ TInt r=KErrNoMemory;
+ DKeyboardTemplate* pK=new DKeyboardTemplate;
+ if (pK)
+ r=pK->Create();
+
+ __KTRACE_OPT(KEXTENSION,Kern::Printf("Returns %d",r));
+ return r;
+ }
+
+</codeblock> <p>It simply creates an instance of the <codeph>DKeyboardTemplate</codeph> class
+and then performs a second-phase initialisation, which is a common pattern
+in Symbian platform and third party applications. </p> <p><b>Initialisation
+on construction</b> </p> <p>The constructor of the <codeph>DKeyboardTemplate</codeph> class
+has the following signature: </p> <codeblock id="GUID-5D247843-FF8C-5157-8BE5-53B5883F00B2" xml:space="preserve">DKeyboardTemplate::DKeyboardTemplate()
+ : DPowerHandler(KLitKeyboard),
+ iMsgQ(rxMsg,this,NULL,1),
+ iPowerUpDfc(PowerUpDfcFn,this,6),
+ iPowerDownDfc(PowerDownDfcFn,this,7),
+ iEventDfc(EventDfcFn,this,1)
+ {
+ }
+
+</codeblock> <p>See also <xref href="GUID-3C34724F-B476-5329-B0B1-6D5A34294979.dita">Interrupt
+Dispatcher Tutorial</xref>. </p> </section>
+<section id="GUID-F11265AA-D280-4B4E-92DA-38F12E7D5E30"><title> Interrupt Service Routine (ISR) implementation</title> <p>The
+ISR (Interrupt Service Routine) just schedules the DFC that handles the keypress.
+On the template reference board, this is implemented as: </p> <codeblock id="GUID-866CEA65-78AC-5A2C-AF08-29DF8FE53DD5" xml:space="preserve">void DKeyboardTemplate::Isr(TAny* aPtr)
+ {
+ DKeyboardTemplate& k=*(DKeyboardTemplate*)aPtr;
+ Interrupt::Disable(KIntIdKeyboard);
+ k.iEventDfc.Add();
+ }
+</codeblock> <p>The ISR disables the keyboard interrupt, as repeated ISRs
+are not allowed to queue further DFC routines. </p> </section>
+<section id="GUID-E53E0FE1-3100-4B8B-BE90-250C1BDDE15C"><title>DFC function implementation</title> <p>The DFC is the function <codeph>DKeyboardTemplate::EventDfcFn</codeph> which
+is implemented as a call to <codeph>DKeyboardTemplate::EventDfc()</codeph>. </p> <codeblock id="GUID-2A1B334A-441E-57C3-B40C-603D992F934F" xml:space="preserve">void DKeyboardTemplate::EventDfcFn(TAny* aPtr)
+ {
+ ((DKeyboardTemplate*)aPtr)->EventDfc();
+ }
+
+void DKeyboardTemplate::EventDfc()
+ {
+ __KTRACE_OPT(KHARDWARE,Kern::Printf("DKeyboardTemplate::EventDfc"));
+
+ TInt irq=NKern::DisableAllInterrupts();
+ while (IsKeyReady()) // while there are keys in the controller's output buffer
+ {
+ NKern::RestoreInterrupts(irq);
+ TRawEvent e;
+ TUint keyCode=GetKeyCode(); // Read keycodes from controller
+ __KTRACE_OPT(KHARDWARE,Kern::Printf("#%02x",keyCode));
+
+ //
+ // TO DO: (mandatory)
+ //
+ // Convert from hardware scancode to EPOC scancode and send the scancode as an event (key pressed or released)
+ // as per below EXAMPLE ONLY:
+ //
+ TUint bareCode=keyCode&~KFlagKeyPressed;
+ TUint8 stdKey=convertCode[bareCode];
+ if (keyCode&KFlagKeyPressed)
+ e.Set(TRawEvent::EKeyUp,stdKey,0);
+ else
+ e.Set(TRawEvent::EKeyDown,stdKey,0);
+ Kern::AddEvent(e);
+ NKern::Sleep(1); // pause before reading more keycodes
+ irq=NKern::DisableAllInterrupts();
+ }
+ Interrupt::Enable(KIntIdKeyboard);
+ NKern::RestoreInterrupts(irq);
+ }</codeblock> <p>This: </p> <ul>
+<li id="GUID-8A202894-34F8-5E7B-B791-20D4B6C8B914"><p>reads the scan code
+data by calling <codeph>DKeyboardTemplate::GetKeyCode()</codeph> </p> </li>
+<li id="GUID-D553B662-F60C-575F-893D-347A9344F9B9"><p>re-enables the keyboard
+interrupt, now that the DFC has freed up the input data register </p> </li>
+<li id="GUID-BFC75E95-A9AE-584E-8A17-CCAF9C2F5913"><p>translates the keypress
+event into a Symbian scancode </p> </li>
+<li id="GUID-20BC22AF-C58C-56DC-B777-B5C8681668D6"><p>puts the translated
+event on to the event queue. </p> </li>
+</ul> </section>
+<section id="GUID-437735D9-916C-4308-913C-3839CC7F0002"><title>See also</title> <p> <xref href="GUID-EB76FAF8-CD4B-5CB6-9F23-C852ED91866F.dita">Concepts</xref> </p> </section>
</conbody></concept>
\ No newline at end of file