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

// e32utils\d_exc\minkda.cpp

// Example of LDD implementing a minimal kernel-side debug agent.

// 

//

#include <kernel/kern_priv.h>

#ifdef __MARM__

#include <arm.h>

#endif

#include "minkda.h"

// Uncomment following lines to enable traces in UREL builds

//#undef __KTRACE_OPT

//#define __KTRACE_OPT(c,b) b

#ifdef _DEBUG

// Panic category used for internal errors

static const char KFault[] = "MINKDA-ERROR, line:";

#endif

// Panic category and codes used when detecting programming error in

// user-side clients.

_LIT(KClientPanic, "MINKDA");

enum TPanic

	{

	EPanicTrapWhileRequestPending,

	EPanicNoCrashedThread,

	EPanicUnsupportedRequest,

	};

// As this LDD allows to bypass platform security, we need to restrict

// access to a few trusted clients.

const TUint32 KDexecSid = 0x101F7770;

//////////////////////////////////////////////////////////////////////////////

//

// Callback invoked on thread panic/exception and associated state.

//

class DCrashHandler : public DKernelEventHandler

	{

public:

	// construction & destruction

	inline DCrashHandler();

	TInt Create(DLogicalDevice* aDevice);

	~DCrashHandler();

public:

	void Trap(TRequestStatus* aRs, TAny* aCrashInfo);

	void CancelTrap();

	void KillCrashedThread();

private:

	static TUint EventHandler(TKernelEvent aEvent, TAny* a1, TAny* a2, TAny* aThis);

	void HandleCrash(TAny* aContext);

	void GetCpuExcInfo(const TAny* aContext, TDbgCpuExcInfo& aInfo);

private:

	DMutex* iHandlerMutex;		// serialise access to crash handler

	NFastSemaphore iSuspendSem; // for suspending crashed thread

	DMutex* iDataMutex;			// serialise access to following members

	DThread* iClient;			// client to signal on crash or NULL

	TRequestStatus* iTrapRq;	// signalled on crash (NULL if none)

	TAny* iCrashInfo;			// user-side buffer filled when crash trapped

	DThread* iCrashedThread;	// thread which took exception (NULL if none)

	DLogicalDevice* iDevice;	// open reference to LDD for avoiding lifetime issues

	};

inline DCrashHandler::DCrashHandler()

	: DKernelEventHandler(EventHandler, this)

	{

	}

//

// second-phase c'tor.  Called in thread critical section.

//

TInt DCrashHandler::Create(DLogicalDevice* aDevice)

	{

	TInt r;

	r = aDevice->Open();

	if (r != KErrNone)

		return r;

	iDevice = aDevice;

	_LIT(KHandlerMutexName, "CtHandlerMutex");

	r = Kern::MutexCreate(iHandlerMutex, KHandlerMutexName, KMutexOrdDebug);

	if (r != KErrNone)

		return r;

	_LIT(KDataMutexName, "CtDataMutex");

	r = Kern::MutexCreate(iDataMutex, KDataMutexName, KMutexOrdDebug-1);

	if (r != KErrNone)

		return r;

	return Add();

	}

//

// Called when reference count reaches zero.  At that point no threads

// are in the handler anymore and the handler has been removed from

// the queue.

//

DCrashHandler::~DCrashHandler()

	{

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("DCrashHandler::~DCrashHandler"));

	if (iDataMutex)

		iDataMutex->Close(NULL);

	if (iHandlerMutex)

		iHandlerMutex->Close(NULL);

	if (iDevice)

		iDevice->Close(NULL);

	}

inline TBool TookException(const DThread* aThread)

	{

    return aThread->iExitType == EExitPanic && 

			aThread->iExitReason == ECausedException && 

			aThread->iExitCategory == KLitKernExec;

	}

//

// Called by kernel when various kinds of events occur.  In thread critical

// section.

//

TUint DCrashHandler::EventHandler(TKernelEvent aEvent, TAny* a1, TAny* /*a2*/, TAny* aThis)

	{

	DThread* pC = &Kern::CurrentThread();

	switch (aEvent)

		{

	case EEventHwExc:

		((DCrashHandler*)aThis)->HandleCrash(a1);

		break;

	case EEventKillThread:

		if (pC->iExitType == EExitPanic && ! TookException(pC))

			((DCrashHandler*)aThis)->HandleCrash(NULL);

		break;

	default:

		// ignore other events

		break;

		}

	return ERunNext;

	}

//

// Called when an exception or panic occurs in context of thread which

// took the exception/panicked.  In thread critical section.

//

void DCrashHandler::HandleCrash(TAny* aContext)

	{

	DThread* pC = &Kern::CurrentThread();

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("HandleCrash context=0x%08X thread=%O", aContext, pC));

	// Quick exit if crashed thread is debugger (i.e. client thread

	// which issued trap request).

	if (pC == iClient)

		{

		__KTRACE_OPT(KDEBUGGER, Kern::Printf("ignoring debugger crash"));

		return;

		}

	// Set realtime state to off to allow us to write to possibly paged debugger thread.  This is

	// reasonable as this thread has already crashed.

	Kern::SetRealtimeState(ERealtimeStateOff);

	// Ensure that, at any time, at most one thread executes the following

	// code.  This simplifies user-side API.

	Kern::MutexWait(*iHandlerMutex);

	__ASSERT_DEBUG(iCrashedThread == NULL, Kern::Fault(KFault, __LINE__));

	// If there is a pending trap request, store basic information

	// about the panic/exception in user-supplied buffer and

	// freeze the crashed thread so it can be inspected.

	Kern::MutexWait(*iDataMutex);

	if (iTrapRq != NULL)

		{

		iCrashedThread = pC;

		iSuspendSem.iOwningThread = &(iCrashedThread->iNThread);

		TDbgCrashInfo info;

		info.iTid = iCrashedThread->iId;

		if (aContext)

			{

			GetCpuExcInfo(aContext, info.iCpu);

			info.iType = TDbgCrashInfo::EException;

			}

		else

			info.iType = TDbgCrashInfo::EPanic;

		TInt r = Kern::ThreadRawWrite(iClient, iCrashInfo, &info, sizeof(info));

		Kern::RequestComplete(iClient, iTrapRq, r);

		iClient = NULL;

		}

	Kern::MutexSignal(*iDataMutex);

	if (iCrashedThread)

		{

		__KTRACE_OPT(KDEBUGGER, Kern::Printf("freezing crashed thread"));

		NKern::FSWait(&(iSuspendSem));

		__KTRACE_OPT(KDEBUGGER, Kern::Printf("resuming crashed thread"));

		Kern::MutexWait(*iDataMutex);

		// Must protect in case a cancel executes concurrently.

		iCrashedThread = NULL;

		Kern::MutexSignal(*iDataMutex);

		}

	Kern::MutexSignal(*iHandlerMutex);

	}

void DCrashHandler::Trap(TRequestStatus* aRs, TAny* aCrashInfo)

	{

	if (iTrapRq != NULL)

		Kern::PanicCurrentThread(KClientPanic, EPanicTrapWhileRequestPending);

	NKern::ThreadEnterCS();

	Kern::MutexWait(*iDataMutex);

	iClient = &Kern::CurrentThread();

	iCrashInfo = aCrashInfo;

	iTrapRq = aRs;

	Kern::MutexSignal(*iDataMutex);

	NKern::ThreadLeaveCS();

	}

void DCrashHandler::CancelTrap()

	{

	__KTRACE_OPT(KDEBUGGER, Kern::Printf(">DCrashHandler::CancelTrap"));

	NKern::ThreadEnterCS();

	Kern::MutexWait(*iDataMutex);

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("cancel request (0x%08X)", iTrapRq));

	Kern::RequestComplete(iClient, iTrapRq, KErrCancel);

	iClient = NULL;

	if (iCrashedThread != NULL)

		{

		__KTRACE_OPT(KDEBUGGER, Kern::Printf("resume crashed thread"));

		NKern::FSSignal(&(iSuspendSem));

		}

	Kern::MutexSignal(*iDataMutex);

	NKern::ThreadLeaveCS();

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("<DCrashHandler::CancelTrap"));

	}

void DCrashHandler::KillCrashedThread()

	{

	if (iCrashedThread == NULL)

		Kern::PanicCurrentThread(KClientPanic, EPanicNoCrashedThread);

	NKern::FSSignal(&iSuspendSem);

	}

void DCrashHandler::GetCpuExcInfo(const TAny* aContext, TDbgCpuExcInfo& aInfo)

	{

#if defined(__MARM__)

	const TArmExcInfo* pE = (const TArmExcInfo*)aContext;

	aInfo.iFaultPc = pE->iR15;

	aInfo.iFaultAddress = pE->iFaultAddress;

	aInfo.iFaultStatus = pE->iFaultStatus;

	aInfo.iExcCode = (TDbgCpuExcInfo::TExcCode)pE->iExcCode;

	aInfo.iR13Svc = pE->iR13Svc;

	aInfo.iR14Svc = pE->iR14Svc;

	aInfo.iSpsrSvc = pE->iSpsrSvc;

#else

	(void) aContext; // silence warnings

	(void) aInfo;

#endif

	}

//////////////////////////////////////////////////////////////////////////////

//

// Channel initialisation and cleanup.  Dispatcher for user-side

// requests.  Crash-related requests are forwarded to DCrashHandler,

// others are implemented here.

//

class DKdaChannel : public DLogicalChannelBase

	{

public:

	~DKdaChannel();

protected:

	// from DLogicalChannelBase

	virtual TInt DoCreate(TInt aUnit, const TDesC8* anInfo, const TVersion &aVer);

	virtual TInt Request(TInt aFunction, TAny* a1, TAny* a2);

private:

	TInt ReadMem(RMinKda::TReadMemParams* aParams);

	TInt GetThreadInfo(TUint aTid, TAny* aInfo);

	void GetThreadCpuInfo(DThread* aThread, TDbgRegSet& aInfo);

	TInt GetCodeSegs(RMinKda::TCodeSnapshotParams* aParams);

	TInt GetCodeSegInfo(RMinKda::TCodeInfoParams* aParams);

	TInt OpenTempObject(TUint aId, TObjectType aType);

	void CloseTempObject();

private:

	DCrashHandler* iCrashHandler;

	DObject* iTempObj;			// automagically closed if abnormal termination

	};

//

// Called when user-side thread create new channel with LDD.  Called

// in context of that thread, in thread critical section.

//

TInt DKdaChannel::DoCreate(TInt /*aUnit*/, const TDesC8* /*aInfo*/, const TVersion &aVer)

	{

	if (Kern::CurrentThread().iOwningProcess->iS.iSecureId != KDexecSid)

		return KErrPermissionDenied;

	if (! Kern::QueryVersionSupported(KKdaLddVersion(), aVer))

		return KErrNotSupported;

	iCrashHandler = new DCrashHandler;

	if (iCrashHandler == NULL)

		return KErrNoMemory;

	return iCrashHandler->Create(iDevice);

	}

//

// Called when last reference to channel is closed, in context of

// closing thread, in thread critical section.

//

DKdaChannel::~DKdaChannel()

	{

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("DKdaChannel::~DKdaChannel"));

	Kern::SafeClose(iTempObj, NULL);

	if (iCrashHandler)

		{

		iCrashHandler->CancelTrap();

		iCrashHandler->Close();

		}

	}

//

// Request dispatcher. Called in context of requesting thread.

//

TInt DKdaChannel::Request(TInt aFunction, TAny* a1, TAny* a2)

	{

	__KTRACE_OPT(KDEBUGGER, Kern::Printf(">DKdaChannel::Request function=%d a1=0x%08X a2=0x%08X", aFunction, a1, a2));

	TInt r = KErrNone;

	switch (aFunction)

		{

	case RMinKda::ETrap:

		iCrashHandler->Trap((TRequestStatus*)a1, a2);

		break;

	case RMinKda::ECancelTrap:

		iCrashHandler->CancelTrap();

		break;

	case RMinKda::EKillCrashedThread:

		iCrashHandler->KillCrashedThread();

		break;

	case RMinKda::EGetThreadInfo:

		r = GetThreadInfo((TUint)a1, a2);

		break;

	case RMinKda::EReadMem:

		r = ReadMem((RMinKda::TReadMemParams*)a1);

		break;

	case RMinKda::EGetCodeSegs:

		r = GetCodeSegs((RMinKda::TCodeSnapshotParams*)a1);

		break;

	case RMinKda::EGetCodeSegInfo:

		r = GetCodeSegInfo((RMinKda::TCodeInfoParams*)a1);

		break;

	default:

		Kern::PanicCurrentThread(KClientPanic, EPanicUnsupportedRequest);

		break;

		}

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("<DKdaChannel::Request r=%d", r));

	return r;

	}

TInt DKdaChannel::ReadMem(RMinKda::TReadMemParams* aParams)

	{

	RMinKda::TReadMemParams params;

	umemget32(&params, aParams, sizeof(params));

	TInt destLen;

	TInt destMax;

	TUint8* destPtr = (TUint8*)Kern::KUDesInfo(*params.iDes, destLen, destMax);

	TInt r = OpenTempObject(params.iTid, EThread);

	if (r == KErrNone)

		{

		r = Kern::ThreadRawRead((DThread*)iTempObj, (TAny*)params.iAddr, destPtr, destMax);

		if (r == KErrNone)

			Kern::KUDesSetLength(*params.iDes, destMax);

		CloseTempObject();

		}

	return r;

	}

TInt DKdaChannel::GetThreadInfo(TUint aTid, TAny* aInfo)

	{

	TInt r = OpenTempObject(aTid, EThread);

	if (r == KErrNone)

		{

		DThread* pT = (DThread*)iTempObj;

		TDbgThreadInfo info;

		pT->FullName(info.iFullName);

		info.iPid = pT->iOwningProcess->iId;

		info.iStackBase = pT->iUserStackRunAddress;

		info.iStackSize = pT->iUserStackSize;

		info.iExitCategory = pT->iExitCategory;

		info.iExitReason = pT->iExitReason;

		GetThreadCpuInfo(pT, info.iCpu);

		umemput32(aInfo, &info, sizeof(info));

		CloseTempObject();

		}

	return r;

	}

// :FIXME: improve API

TInt DKdaChannel::GetCodeSegs(RMinKda::TCodeSnapshotParams* aParams)

	{

	RMinKda::TCodeSnapshotParams params;

	umemget32(&params, aParams, sizeof(params));

	TInt maxcount;

	umemget32(&maxcount, params.iCountPtr, sizeof(maxcount));

	__KTRACE_OPT(KDEBUGGER, Kern::Printf(">DKdaChannel::GetCodeSegs pid=%d maxcount=%d", params.iPid, maxcount));

	__ASSERT_DEBUG(! iTempObj, Kern::Fault(KFault, __LINE__));

	TInt r = OpenTempObject(params.iPid, EProcess);

	if (r != KErrNone)

		{

		__KTRACE_OPT(KDEBUGGER, Kern::Printf("<DKdaChannel::GetCodeSegs process not found"));

		return r;

		}

	DProcess* pP = (DProcess*)iTempObj;

	Kern::AccessCode();

	SDblQue q;

	TInt actcount = pP->TraverseCodeSegs(&q, NULL, DCodeSeg::EMarkDebug, DProcess::ETraverseFlagAdd);

	CloseTempObject();

	TInt n = Min(actcount, maxcount);

	SDblQueLink* pL = q.iA.iNext;

	r = KErrNone;

	for (TInt i=0; i<n; ++i, pL = pL->iNext)

		{

		DCodeSeg* pS = _LOFF(pL, DCodeSeg, iTempLink);

		XTRAP(r, XT_DEFAULT, umemput32(params.iHandles + i, &pS, sizeof(TAny*)));

		if (r != KErrNone)

			break;

		}

	DCodeSeg::EmptyQueue(q, DCodeSeg::EMarkDebug);

	Kern::EndAccessCode();

	if (r == KErrBadDescriptor)

		Kern::PanicCurrentThread(KLitKernExec, ECausedException);

	umemput32(params.iCountPtr, &actcount, sizeof(actcount));

	__KTRACE_OPT(KDEBUGGER, Kern::Printf("<DKdaChannel::GetCodeSegs actcount=%d", actcount));

	return r;

	}

// :FIXME: improve API

TInt DKdaChannel::GetCodeSegInfo(RMinKda::TCodeInfoParams* aParams)

	{

	RMinKda::TCodeInfoParams params;

	umemget32(&params, aParams, sizeof(params));

	// :FIXME: Currently code segments are always loaded at the same

	// location in every address space.  Consequently we can ignore

	// the PID provided by the client.

	DProcess* pP = NULL;

	TInt r = KErrNotFound;

	TFileName	nameBuffer;

	nameBuffer.Zero();

	Kern::AccessCode();

	DCodeSeg* pS = DCodeSeg::VerifyHandle(params.iHandle);

	if (pS)

		{

		TModuleMemoryInfo mmi;

		r = pS->GetMemoryInfo(mmi, pP);

		if (r == KErrNone)

			{

			params.iCodeBase = mmi.iCodeBase;

			params.iCodeSize = mmi.iCodeSize;

			XTRAP(r, XT_DEFAULT, nameBuffer.Append(*(pS->iFileName)));

			}

		}

	Kern::EndAccessCode();

	Kern::KUDesPut(*(params.iPathPtr), nameBuffer);

	if (r == KErrBadDescriptor)

		Kern::PanicCurrentThread(KLitKernExec, ECausedException);

	if (r == KErrNone)

		umemput32(aParams, &params, sizeof(params));

	return r;

	}

//

// Lookup a thread or process id and open the corresponding object.

//