<?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>This topic describes how to implement an interrupt driven
keyboard driver. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<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-&gt;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.
It can also optionally contribute the timing of key 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>). 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)
	{
	Interrupt::Disable(KIntIdKeyboard);
	
	// Add the timing of key interrupts as entropy data for the RNG
	Interrupt::AddTimingEntropy();
	
	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)-&gt;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&amp;~KFlagKeyPressed;
        TUint8 stdKey=convertCode[bareCode];
        if (keyCode&amp;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>