// 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.

 //

 // The object is stored in DKdaChannel::iTempObj to ensure it will be

 // closed even if the client thread terminates unexpectedly.  The

 // caller must call CloseTempObject() when it is finished with it.

 //

 TInt DKdaChannel::OpenTempObject(TUint aId, TObjectType aType)

 	{

 	__ASSERT_DEBUG(aType == EProcess || aType == EThread, Kern::Fault(KFault, __LINE__));

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

 	DObjectCon* pC = Kern::Containers()[aType];

 	NKern::ThreadEnterCS();

 	pC->Wait();

 	DObject* tempObj = (aType == EProcess) ? (DObject*)Kern::ProcessFromId(aId) : (DObject*)Kern::ThreadFromId(aId);

 	NKern::LockSystem();

 	iTempObj = tempObj;

 	TInt r = KErrNotFound;

 	if (iTempObj)

 		r = iTempObj->Open();

 	NKern::UnlockSystem();

 	pC->Signal();

 	NKern::ThreadLeaveCS();

 	return r;

 	}

 void DKdaChannel::CloseTempObject()

 	{

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

 	NKern::ThreadEnterCS();

 	iTempObj->Close(NULL);

 	iTempObj = NULL;

 	NKern::ThreadLeaveCS();

 	}

 #ifdef __MARM__

 void DKdaChannel::GetThreadCpuInfo(DThread* aThread, TDbgRegSet& aInfo)

 	{

 	__ASSERT_DEBUG(aThread != &Kern::CurrentThread(), Kern::Fault(KFault, __LINE__));

 	TArmRegSet regSet;

 	TUint32 unused;

 	NKern::ThreadGetUserContext(&(aThread->iNThread), &regSet, unused);

 	aInfo.iRn[0] = regSet.iR0;

 	aInfo.iRn[1] = regSet.iR1;

 	aInfo.iRn[2] = regSet.iR2;

 	aInfo.iRn[3] = regSet.iR3;

 	aInfo.iRn[4] = regSet.iR4;

 	aInfo.iRn[5] = regSet.iR5;

 	aInfo.iRn[6] = regSet.iR6;

 	aInfo.iRn[7] = regSet.iR7;

 	aInfo.iRn[8] = regSet.iR8;

 	aInfo.iRn[9] = regSet.iR9;

 	aInfo.iRn[10] = regSet.iR10;

 	aInfo.iRn[11] = regSet.iR11;

 	aInfo.iRn[12] = regSet.iR12;

 	aInfo.iRn[13] = regSet.iR13;

 	aInfo.iRn[14] = regSet.iR14;

 	aInfo.iRn[15] = regSet.iR15;

 	aInfo.iCpsr = regSet.iFlags;

 	}

 #else

 void DKdaChannel::GetThreadCpuInfo(DThread* /*aThread*/, TDbgRegSet& /*aInfo*/)

 	{

 	}

 #endif

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

 class DCtDevice : public DLogicalDevice

 	{

 public:

 	DCtDevice();

 	// from DLogicalDevice

 	virtual TInt Install();

 	virtual void GetCaps(TDes8& aDes) const;

 	virtual TInt Create(DLogicalChannelBase*& aChannel);

 	};

 DCtDevice::DCtDevice()

 	{

 	// iParseMask = 0;

 	// iUnitsMask = 0;

 	iVersion = KKdaLddVersion();

 	}

 TInt DCtDevice::Install()

 	{

 	return SetName(&KKdaLddName);

 	}

 void DCtDevice::GetCaps(TDes8& /*aDes*/) const

 	{

 	}

 TInt DCtDevice::Create(DLogicalChannelBase*& aChannel)

 	{

 	aChannel = new DKdaChannel;

 	return (aChannel != NULL) ? KErrNone : KErrNoMemory;

 	}

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

 DECLARE_STANDARD_LDD()

 	{

 	return new DCtDevice;

 	}