// Copyright (c) 2007-2009 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:

//

// Description:

// template\template_variant\specific\keyboard.cpp

// Access to Template polled keyboard

// The code here implements a simple polled keyboard driver.

// This is an alternative to the interrupt-driven driver in keyboard_interrupt.cpp.

// This example assumes that we have a non-intelligent keyboard

// consisting of a number of i/o lines arranged in a grid.

// You can use this code as a starting point and modify it to suit

// your hardware.

// 

//

#include <template_assp.h>

#include "platform.h"

#include <kernel/kpower.h>

#include <e32keys.h>

// The TKeyboardState class is used to encapsulate the state of 

// the keyboard. i.e which keys are currently being pressed.

// To determine which keys are being pressed, typically a voltage

// is applied to each row in turn (or column, depending on the hardware) 

// and the output is read resulting in a bitmask for each row.

//

// For example, the keys could be arranged as follows (where a '1' indicates

// that a key is currently being pressed :

// EXAMPLE ONLY

//

//																						Translated

//				Column#	0	1	2	3	4	5	6	7	8	9	A	B	C	D	E	F	KeyCode

//			Row#	

//			6			0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	60	to	6F

//			5			0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	50	to	5F

//			4			0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	40	to	4F

//			3			0	0	0	0	0	0	1	0	0	0	0	0	0	0	0	0	30	to	3F

//	Input->	2			0	0	0	1	0	0	0	0	1	0	0	0	0	0	0	0	20	to	2F

//			1			0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	10	to	1F

//			0			0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	0	00	to	0F	

//	

//	output->			0	0	0	1	0	0	0	0	1	0	0	0	0	0	0	0	

//

// TO DO: (mandadory)

// Modify TKeyboardState (or provide an alternative) to model the 

// real keyboard state

//

// EXAMPLE ONLY

class TKeyboardState

	{

public:

	enum TDimensions

	{

	KRows = 7,

	KColumns = 16

	};

public:

	TKeyboardState();

	void Clear();

	TBool IsKeyReady();

	TUint32 GetKeyCode();

	TKeyboardState operator&(const TKeyboardState& aState);

	TKeyboardState operator|(const TKeyboardState& aState);

	TKeyboardState operator~();

public:

	TUint32 iKeyBitMask[KRows];

	};

/**

Constructor

*/

TKeyboardState::TKeyboardState()

	{

	Clear();

	}

/**

Clears the array of bitmasks 

*/

void TKeyboardState::Clear()

	{

	for (TInt row=0; row<KRows; row++)

		iKeyBitMask[row] = 0;

	}

/**

Determines whether any keys are being pressed by examining the 

array of bitmasks to determine whether any bits are set

@return	ETrue if one or more keys are being pressed

*/

TBool TKeyboardState::IsKeyReady()

	{

	for (TInt row=0; row<KRows; row++)

		{

		if (iKeyBitMask[row] != 0)

			return ETrue;

		}

	return EFalse;

	}

/**

Scans the array of bitmasks and returns a keycode representing

the first bit that it finds that is on.

E.g. :

if the first bit on the first row is set, then 1 is returned,

if the third bit on the first row is set, then 3 is returned. etc.

Once a bit is found it is cleared to avoid reading it again.

NB Before calling this function, IsKeyReady() should be called 

to determine whether a key code is available.

@return	a 32-bit keycode representing a key that is currently pressed

*/

TUint32 TKeyboardState::GetKeyCode()

	{

	TInt keyNum = 0;

	for (TInt row=0; row<KRows; row++)

		{

		TUint32 bitMask = 1;

		for (TInt col=0; col<KColumns; col++)

			{

			if (iKeyBitMask[row] & bitMask)

				{

				iKeyBitMask[row] &= ~bitMask;

				return keyNum;

				}

			bitMask<<= 1;

			keyNum++;

			}

		}

	return 0;

	}

/**

Perform a bitwise AND between two TKeyboardState objects

by AND-ing together all the 32-bit integers

@return	a new instance of a TKeyboardState object containing the result

*/

TKeyboardState TKeyboardState::operator&(const TKeyboardState& aState)

	{

	TKeyboardState state = *this;

	for (TInt row=0; row<KRows; row++)

		state.iKeyBitMask[row]&= aState.iKeyBitMask[row];;

	return state;

	}

/**

Perform a bitwise OR between two TKeyboardState objects

by OR-ing together all the 32-bit integers

@return	a new instance of a TKeyboardState object containing the result

*/

TKeyboardState TKeyboardState::operator|(const TKeyboardState& aState)

	{

	TKeyboardState state = *this;

	for (TInt row=0; row<KRows; row++)

		state.iKeyBitMask[row]|= aState.iKeyBitMask[row];;

	return state;

	}

/**

Perform a bitwise NOT (one's complement) of a KeyboardState object

by NOT-ing all the 32-bit integers

@return	a new instance of a TKeyboardState object containing the result

*/

TKeyboardState TKeyboardState::operator~()

	{

	TKeyboardState state = *this;

	for (TInt row=0; row<KRows; row++)

		state.iKeyBitMask[row] = ~state.iKeyBitMask[row];

	return state;

	}

//

//

// TO DO: (optional)

//

// Modify this conversion table to suit your keyboard layout

// EXAMPLE ONLY

//

const TUint8 convertCode[] =

	{

//Row 0 (bottom row)

	EStdKeyLeftAlt		,	EStdKeyHash			,	EStdKeyNull			,	EStdKeyLeftCtrl				,

	EStdKeyLeftFunc		,	EStdKeyEscape		,	'1'					,	'2'							,

	'9'					,	'0'					,	EStdKeyMinus		,	EStdKeyEquals				,

	EStdKeyNull			,	EStdKeyBackspace	,	EStdKeyNull			,	EStdKeyNull					,

//Row 1

	EStdKeyNull			,	EStdKeyBackSlash	,	EStdKeyLeftShift	,	EStdKeyNull					,

	EStdKeyNull			,	EStdKeyDelete		,	EStdKeyNull			,	'T'							,

	'Y'					,	'U'					,	'I'					,	 EStdKeyEnter				,

	EStdKeyRightShift	,	EStdKeyDownArrow	,	EStdKeyNull			,	EStdKeyNull					,

//Row 2

	EStdKeyNull			,	EStdKeyTab			,	EStdKeyNull			,	 EStdKeyNull				,

	EStdKeyNull			,	'Q'					,	'W'					,	'E'							,

	'R'					,	'O'					,	'P'					,	EStdKeySquareBracketLeft	,

	EStdKeyNull			,	EStdKeySquareBracketRight,EStdKeyNull		,	EStdKeyNull					,

//Row 3

	EStdKeyNull			,	'Z'					,	EStdKeyNull			,	EStdKeyNull					,

	EStdKeyNull			,	EStdKeyCapsLock		,	EStdKeyNull			,	EStdKeyNull					,

	'K'					,	'L'					,	EStdKeySemiColon	,	EStdKeySingleQuote			,

	EStdKeyNull			,	EStdKeyUpArrow		,	EStdKeyNull			,	EStdKeyNull					,

//Row 4

	EStdKeyNull			,	EStdKeyTab			,	EStdKeyNull			,	EStdKeyNull,

	EStdKeyNull			,	'Q'					,	'W'					,	'E'							,

	'R'					,	'O'					,	'P'					,	EStdKeySquareBracketLeft	,

	EStdKeyNull			,	EStdKeySquareBracketRight,	EStdKeyNull		,	EStdKeyNull					,

//Row 5

	EStdKeyNull			,	'X'					,	EStdKeyNull			,	EStdKeyNull					,

	EStdKeyNull			,	'C'					,	'V'					,	'B'							,

	'N'					,	'M'					,	EStdKeyComma		,	EStdKeyFullStop				,

	EStdKeyNull			,	EStdKeySpace		,	EStdKeyNull			,	EStdKeyNull					,

//Row 6

	EStdKeyNull			,	EStdKeyNull			,	EStdKeyNull			,	EStdKeyNull					,

	EStdKeyNull			,	'3'					,	'4'					,	'5'							,

	'6'					,	'7'					,	'8'					,	EStdKeyMenu					,

	EStdKeyNull			,	EStdKeyRightArrow	,	EStdKeyNull			,	EStdKeyNull					

	};

// EXAMPLE ONLY

const TKeyboard	KConfigKeyboardType = EKeyboard_Full;

const TInt KConfigKeyboardDeviceKeys = 0;

const TInt KConfigKeyboardAppsKeys = 0;

//

// TO DO: (optional)

//

// Set the keyboard scan rate in milliseconds

//

// EXAMPLE ONLY

const TInt KScanRate = 50;	// poll every 1/20 of a second (i.e. every 50 milliseconds)

_LIT(KLitKeyboard,"Keyboard");

//

// TO DO: (optional)

//

// Add any private functions and data you require

//

NONSHARABLE_CLASS(DKeyboardTemplate) : public DPowerHandler

	{

public:

	DKeyboardTemplate();

	TInt Create();

	// from DPowerHandler

	void PowerUp();

	void PowerDown(TPowerState);

private:

	static void HandleMessage(TAny* aPtr);

	void HandleMsg(TMessageBase* aMsg);

	static TInt HalFunction(TAny* aPtr, TInt aFunction, TAny* a1, TAny* a2);

	TInt HalFunction(TInt aFunction, TAny* a1, TAny* a2);

	static void PowerUpDfcFn(TAny* aPtr);

	void PowerUpDfc();

	static void PowerDownDfcFn(TAny* aPtr);

	void PowerDownDfc();

	static void TimerCallback(TAny* aDriver);

	static void TimerDfcFn(TAny* aDriver);

	void Poll();

	void KeyboardInfo(TKeyboardInfoV01& aInfo);

	void KeyboardOn();

	void KeyboardOff();

	void KeyboardPowerUp();

private:

	TDfcQue* iDfcQ;

	TMessageQue iMsgQ;	

	TDfc iPowerUpDfc;

	TDfc iPowerDownDfc;	

	TBool iKeyboardOn;

	NTimer iTimer;

	TInt iTimerTicks;

	TDfc iTimerDfc;

	// a bitmask indicating which keys were pressed down on the last timer tick

	TKeyboardState iKeyStateLast;

	// a bitmask indicating the set of keys for which we have sent an EKeyDown event

	TKeyboardState iKeysDown;			

	};

/**

constructor

*/

DKeyboardTemplate::DKeyboardTemplate()

	:	DPowerHandler(KLitKeyboard), 

		iMsgQ(HandleMessage, this, NULL, 1),

		iPowerUpDfc(PowerUpDfcFn, this, 6),

		iPowerDownDfc(PowerDownDfcFn, this, 7),

		iTimer(&DKeyboardTemplate::TimerCallback, (TAny*) this),

		iTimerDfc(TimerDfcFn, this, 1)

	{

	// Convert the scan rate from milliseconds to nanokernel ticks (normally 1/64 of a second)

	iTimerTicks = NKern::TimerTicks(KScanRate);

	}

/**

Second-phase constructor 

Assigns queues for all the DFCs and starts the keyboard-polling timer

Called by factory function at ordinal 0

*/

TInt DKeyboardTemplate::Create()

	{

	iDfcQ=Kern::DfcQue0();

	iKeyboardOn = EFalse;	

	// install the HAL function

	TInt r = Kern::AddHalEntry(EHalGroupKeyboard, DKeyboardTemplate::HalFunction, this);

	if (r != KErrNone)

		return r;

	iTimerDfc.SetDfcQ(iDfcQ);

	iPowerUpDfc.SetDfcQ(iDfcQ);

	iPowerDownDfc.SetDfcQ(iDfcQ);

	iMsgQ.SetDfcQ(iDfcQ);

	iMsgQ.Receive();

	// install the power handler

	Add();

	// Power up the device and start the timer

	KeyboardPowerUp();

	return r;

	}

/**

Calback for the keyboard-polling timer

Called in the context of an ISR

@param	aPtr A pointer to an instance of DKeyboardTemplate

*/

void DKeyboardTemplate::TimerCallback(TAny *aPtr)

	{

	// schedule a DFC

	DKeyboardTemplate& k=*(DKeyboardTemplate*)aPtr;

	k.iTimerDfc.Add();

	}

/**

DFC scheduled by the keyboard-polling timer when it expires

@param	aPtr A pointer to an instance of DKeyboardTemplate

*/

void DKeyboardTemplate::TimerDfcFn(TAny* aPtr)

	{

	((DKeyboardTemplate*)aPtr)->Poll();

	}

/**

Reads scan codes from the keyboard until there are none left

Called from the keyboard-polling timer's DFC

*/

void DKeyboardTemplate::Poll()

	{

	__KTRACE_OPT(KHARDWARE,Kern::Printf("DKeyboardTemplate::EventDfc"));

	TKeyboardState keyState;

	//

	// TO DO: (mandatory)

	// Read new key state into the array of bitmasks in keyState

	// This typically involves applying a voltage to each row from 0 to KRows-1, 

	// reading the output state of the i/o lines at every step 

	// - this represents the keys that are pressed on each row -

	// and storing the output of each row as a bitmask into keyState.iKeyBitMask[n], 

	// where n = the row being accessed

	//

	// To enable a simple de-bouncing algorithm, 

	// work out which keys have been pressed down for at least two timer 

	// ticks by AND-ing together the last bitmask with the current bitmask

	TKeyboardState keysStillDown =  keyState & iKeyStateLast;

	// Similarly, work out which keys have been "un-pressed" for at least two timer 

	// ticks by AND-ing together the one's complement of the last bitmask with the 

	// one's complement of the current bitmask and 

	// then AND-ing this with the set of keys for which we have sent an EKeyDown 

	// event to give the set of keys for which we need to send an EKeyUp event

	TKeyboardState keysStillUp =  (~keyState & ~iKeyStateLast) & iKeysDown;

	// save the current state for next time

	iKeyStateLast = keyState;

	// update the set of keys for which we have sent an EKeyDown event

	iKeysDown = iKeysDown | keysStillDown;

	iKeysDown = iKeysDown & ~keysStillUp;

	// process all the key-down events

	while (keysStillDown.IsKeyReady())						// while there are keys we haven't processed

		{

		TRawEvent e;

		TUint keyCode = keysStillDown.GetKeyCode();			// Read keycodes from bitmask 

		__KTRACE_OPT(KHARDWARE,Kern::Printf("EKeyDown: #%02x\n",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:

		//

		__ASSERT_DEBUG(keyCode < (sizeof(convertCode) / sizeof(TUint8)), Kern::Fault("Keyboard", __LINE__));

		TUint8 stdKey = convertCode[keyCode];

		e.Set(TRawEvent::EKeyDown, stdKey, 0);

		Kern::AddEvent(e);

		}

	// process all the key-up events

	while (keysStillUp.IsKeyReady())						// while there are keys we haven't processed

		{

		TRawEvent e;

		TUint keyCode = keysStillUp.GetKeyCode();			// Read keycodes from bitmask 

		__KTRACE_OPT(KHARDWARE,Kern::Printf("EKeyUp: #%02x\n",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:

		//

		__ASSERT_DEBUG(keyCode < (sizeof(convertCode) / sizeof(TUint8)), Kern::Fault("Keyboard", __LINE__));

		TUint8 stdKey = convertCode[keyCode];

		e.Set(TRawEvent::EKeyUp, stdKey, 0);

		Kern::AddEvent(e);

		}

	// start the timer again

	iTimer.OneShot(iTimerTicks);

	}

/**

Notifies the peripheral of system power up.

Called by the power manager during a transition from standby.

Schedules a DFC to handle the power up.

*/

void DKeyboardTemplate::PowerUp()

	{

	iPowerUpDfc.Enque();

	}

/**

static DFC to handle powering up the keyboard

@param	aPtr A pointer to an instance of DKeyboardTemplate

*/

void DKeyboardTemplate::PowerUpDfcFn(TAny* aPtr)

	{

	((DKeyboardTemplate*)aPtr)->PowerUpDfc();

	}

/**

DFC to handle powering up the keyboard

*/

void DKeyboardTemplate::PowerUpDfc()

	{

	__KTRACE_OPT(KPOWER, Kern::Printf("DKeyboardTemplate::PowerUpDfc()"));

	KeyboardOn();

	// Indicate to power handle that powered up is complete

	PowerUpDone();

	}

/**

Powers up the keyboard

May be called as a result of a power transition or from the HAL

*/

void DKeyboardTemplate::KeyboardOn()

	{

	__KTRACE_OPT(KPOWER,Kern::Printf("DKeyboardTemplate::KeyboardOn() iKeyboardOn=%d", iKeyboardOn));

	if (!iKeyboardOn)	// make sure we don't initialize more than once

		KeyboardPowerUp();

	}

/**

Powers up the keyboard

Assumes that the keyboard is currently powered off

*/

void DKeyboardTemplate::KeyboardPowerUp()

	{

	__KTRACE_OPT(KPOWER,Kern::Printf("DKeyboardTemplate::KeyboardPowerUp()"));

	iKeyboardOn = ETrue;

	iKeyStateLast.Clear();

	iKeysDown.Clear();

	// Send key up events for EStdKeyOff (Fn+Esc) event 

	TRawEvent e;

	e.Set(TRawEvent::EKeyUp,EStdKeyEscape,0);

	Kern::AddEvent(e);

	e.Set(TRawEvent::EKeyUp,EStdKeyLeftFunc,0);

	Kern::AddEvent(e);

	// Start the periodic tick for the selected rate.

	// This will call TimerCallback() in the context of an ISR

	iTimer.OneShot(iTimerTicks);

	}

/**

Requests keyboard to power down.

Called by the power manager during a transition to standby or power off

Schedules a DFC to handle the power up.

@param aPowerState the current power state

*/

void DKeyboardTemplate::PowerDown(TPowerState)

	{

	iPowerDownDfc.Enque();

	}

/**

static DFC to handle powering down the keyboard

@param	aPtr A pointer to an instance of DKeyboardTemplate

*/

void DKeyboardTemplate::PowerDownDfcFn(TAny* aPtr)

	{

	((DKeyboardTemplate*)aPtr)->PowerDownDfc();

	}

/**

DFC to handle powering down the keyboard

*/

void DKeyboardTemplate::PowerDownDfc()

	{

	__KTRACE_OPT(KPOWER, Kern::Printf("DKeyboardTemplate::PowerDownDfc()"));

	KeyboardOff();

	PowerDownDone();

	}

/**

Powers down the keyboard

May be called as a result of a power transition or from the HAL

*/

void DKeyboardTemplate::KeyboardOff()

	{

	__KTRACE_OPT(KPOWER,Kern::Printf("DKeyboardTemplate::KeyboardOff() iKeyboardOn=%d", iKeyboardOn));

	// cancel the keyboard-polling timer

	iTimerDfc.Cancel();

	iTimer.Cancel();

	iKeyboardOn = EFalse;

	}

/**

static message handler for processing power up/down messages 

posted internally from HalFunction()

@param	aPtr A pointer to an instance of DKeyboardTemplate

*/

void DKeyboardTemplate::HandleMessage(TAny* aPtr)

	{

	DKeyboardTemplate& h=*(DKeyboardTemplate*)aPtr;

	TMessageBase* pM=h.iMsgQ.iMessage;

	if (pM)

		h.HandleMsg(pM);

	}

/**

Message handler for processing power up/down messages 

posted internally from HalFunction()

param	aMsg A message indicating whether to power the keyboard on or off

*/

void DKeyboardTemplate::HandleMsg(TMessageBase* aMsg)

	{

	if (aMsg->iValue)

		KeyboardOn();

	else

		KeyboardOff();

	aMsg->Complete(KErrNone,ETrue);

	}

/**

Retrieves information about the keyboard

Called from HalFunction()

@param	aInfo a caller-supplied class which on return contains information about the keyboard

*/

void DKeyboardTemplate::KeyboardInfo(TKeyboardInfoV01& aInfo)

	{

	__KTRACE_OPT(KEXTENSION,Kern::Printf("DKeyboardTemplate::KeyboardInfo"));

	aInfo.iKeyboardType=KConfigKeyboardType;

	aInfo.iDeviceKeys=KConfigKeyboardDeviceKeys;

	aInfo.iAppsKeys=KConfigKeyboardAppsKeys;

	}

/**

HAL handler function

@param	aPtr a pointer to an instance of DLcdPowerHandler

@param	aFunction the function number

@param	a1 an arbitrary parameter

@param	a2 an arbitrary parameter

*/

TInt DKeyboardTemplate::HalFunction(TAny* aPtr, TInt aFunction, TAny* a1, TAny* a2)

	{

	DKeyboardTemplate* pH=(DKeyboardTemplate*)aPtr;

	return pH->HalFunction(aFunction,a1,a2);

	}

/**

a HAL entry handling function for HAL group attribute EHalGroupKeyboard

@param	a1 an arbitrary argument

@param	a2 an arbitrary argument

@return	KErrNone if successful

*/

TInt DKeyboardTemplate::HalFunction(TInt aFunction, TAny* a1, TAny* a2)

	{

	TInt r=KErrNone;

	__KTRACE_OPT(KEXTENSION,Kern::Printf("DKeyboardTemplate::HalFunction %d", aFunction));

	switch(aFunction)

		{

		case EKeyboardHalKeyboardInfo:

			{

			TPckgBuf<TKeyboardInfoV01> kPckg;

			KeyboardInfo(kPckg());

			Kern::InfoCopy(*(TDes8*)a1,kPckg);

			break;

			}

		case EKeyboardHalSetKeyboardState:

			{

			if(!Kern::CurrentThreadHasCapability(ECapabilityPowerMgmt,__PLATSEC_DIAGNOSTIC_STRING("Checked by Hal function EKeyboardHalSetKeyboardState")))

				return KErrPermissionDenied;

			if ((TBool)a1)

				{

				TThreadMessage& m=Kern::Message();

				m.iValue = ETrue;

				m.SendReceive(&iMsgQ);		// send a message and block Client thread until keyboard has been powered up

				}

			else

				{

				TThreadMessage& m=Kern::Message();

				m.iValue = EFalse;

				m.SendReceive(&iMsgQ);		// send a message and block Client thread until keyboard has been powered down

				}

			}

			break;

		case EKeyboardHalKeyboardState:

			kumemput32(a1, &iKeyboardOn, sizeof(TBool));

			break;

		default:

			r=KErrNotSupported;

			break;

		}

	return r;

	}

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;

	}