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

 // Purpose: Kernel-side tracking of debug agent information associated

 // with each process being debugged.

 // 

 //

 #include <e32def.h>

 #include <e32def_private.h>

 #include <e32cmn.h>

 #include <e32cmn_private.h>

 #include <kernel/kernel.h> 

 #include <kernel/kern_priv.h>

 #include <nk_trace.h>

 #include <arm.h>

 #include "d_process_tracker.h"

 #include "debug_logging.h"

 #include "d_debug_agent.h"

 #include "debug_utils.h"

 using namespace Debug;

 #define NUMBER_OF_EVENTS_TO_QUEUE 100

 #define CRITICAL_BUFFER_SIZE (NUMBER_OF_EVENTS_TO_QUEUE - 50)

 // ctor

 DDebugAgent::DDebugAgent(TUint64 aId)

 : iId(aId),

   iEventInfo(NULL),

   iEventQueue(NUMBER_OF_EVENTS_TO_QUEUE, 0),

   iRequestGetEventStatus(NULL),

   iClientThread(0),

   iHead(0),

   iTail(0),

   iIgnoringTrace(EFalse)

 	{

 	LOG_MSG("DDebugAgent::DDebugAgent() ");

 	// Initialize all the Event Actions to Ignore

 	for(TInt i=0; i<EEventsLast; i++)

 		{

 		iEventActions[i] = EActionIgnore;

 		}

 	}

 DDebugAgent* DDebugAgent::New(TUint64 aId)

 	{

 	LOG_MSG("DDebugAgent::New()");

 	DDebugAgent* agent = new DDebugAgent(aId);

 	if(agent == NULL)

 		{

 		return (NULL);

 		}

 	if(KErrNone != agent->Construct())

 		{

 		delete agent;

 		return (NULL);

 		}

 	return agent;

 	}

 TInt DDebugAgent::Construct()

 	{

 	// Empty the event queue

 	LOG_MSG("DDebugAgent::Construct()");

 	TDriverEventInfo emptyEvent;

 	for (TInt i=0; i<NUMBER_OF_EVENTS_TO_QUEUE; i++)

 		{

 		TInt err = iEventQueue.Append(emptyEvent);

 		if (KErrNone != err)

 			{

 			LOG_MSG("Error appending blank event entry");

 			return err;

 			}

 		}

 	return KErrNone;

 	}

 // dtor

 DDebugAgent::~DDebugAgent()

 	{

 	iEventQueue.Reset();

 	}

 // Associate an action with a particular kernel event

 TInt DDebugAgent::SetEventAction(TEventType aEvent, TKernelEventAction aEventAction)

 	{

 	// Valid Event?

 	if (aEvent >= EEventsLast)

 		{

 		LOG_MSG2("DDebugAgent::EventAction: Bad Event number %d",aEvent);

 		return KErrArgument;

 		}

 	iEventActions[aEvent] = aEventAction;

 	return KErrNone;

 	}

 /* Get the aEventAction associated with aEvent

  *

  * Returns : aEventAction (always +ve), or KErrArgument.

  */

 TInt DDebugAgent::EventAction(TEventType aEvent)

 	{

 	// Validate the Event id

 	if (aEvent >= EEventsLast)

 		{

 		LOG_MSG2("DDebugAgent::EventAction: Bad Event number %d",aEvent);

 		return KErrArgument;

 		}

 	// Return the action associated with this event

 	return iEventActions[aEvent];

 	}

 // Obtain the details of the latest kernel event (if it exists) and place the details in aEventInfo

 // If there is no event in the queue for this process+agent combination, store the details

 // so that it can be notified later when an event actually occurs.

 //

 // @param aAsyncGetValueRequest - TClientDataRequest object used for pinning user memory

 // @param aEventInfo - Address of TEventInfo structure to place event data when available

 // @param aClientThread - The ThreadId of the requesting user-side process. In this case the DSS.

 void DDebugAgent::GetEvent(TClientDataRequest<TEventInfo>* aAsyncGetValueRequest, TEventInfo* aEventInfo, DThread* aClientThread)

 	{

 	iClientThread = aClientThread;

 	if (BufferEmpty())

 		{

 		LOG_MSG("no events available");

 		// store the pointer so we can modify it later

 		iEventInfo = (TEventInfo *)aEventInfo;

 		iRequestGetEventStatus = aAsyncGetValueRequest;

 		return;

 		}

 	LOG_MSG("Event available");

 	// returning the event to the client

 	TInt err = iEventQueue[iTail].WriteEventToClientThread(aAsyncGetValueRequest,iClientThread);

 	if (KErrNone != err)

 		{

 		LOG_MSG2("Error writing event info: %d", err);

 		return;

 		}

 	// signal the DSS thread

 	Kern::QueueRequestComplete(iClientThread, aAsyncGetValueRequest, KErrNone);

 	iEventQueue[iTail].Reset();

 	// move to the next slot

 	IncrementPosition(iTail);

 	}

 // Stop waiting for an event to occur. This means events will be placed in the iEventQueue

 // until GetEvent is called.

 TInt DDebugAgent::CancelGetEvent(void)

 	{

 	Kern::QueueRequestComplete(iClientThread, iRequestGetEventStatus, KErrCancel);

 	iEventInfo = NULL;

     iRequestGetEventStatus = 0;

 	iClientThread = 0;

 	return KErrNone;

 	}

 // Signal a kernel event to the user-side DSS when it occurs, or queue it for later

 // if the user-side has not called GetEvent (see above).

 //

 // @param aEventInfo - the details of the event to queue.

 void DDebugAgent::NotifyEvent(const TDriverEventInfo& aEventInfo)

 	{

 	LOG_MSG("DDebugAgent::NotifyEvent()");

 	// Action depends on the TKernelEvent type in aEventInfo.iType

 	// Added to fix the pass by value issue seen in Coverity.  

 	// Function is changed to pass by reference but temp object is explicitly created.

 	TDriverEventInfo eventInfo = aEventInfo;

 	if(aEventInfo.iEventType >= EEventsLast)

 		{

 		// unknown event type so return

 		return;

 		}

 	TKernelEventAction action = iEventActions[eventInfo.iEventType];

 	switch (action)

 		{

 		case EActionSuspend:

 			{

 			LOG_MSG("DDebugAgent::NotifyEvent() Suspend thread");

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

 			switch(eventInfo.iEventType)

 				{

 				case EEventsAddLibrary:

 				case EEventsRemoveLibrary:

 					currentThread = DebugUtils::OpenThreadHandle(eventInfo.iThreadId);

 					if(currentThread)

 						{

 						currentThread->Close(NULL);

 						}

 					break;

 				default:

 					break;

 				}

 			TInt err = TheDProcessTracker.SuspendThread(currentThread, eventInfo.FreezeOnSuspend());

 			if(!( (err == KErrNone) || (err == KErrAlreadyExists) ))

 				{

 				// Is there anything we can do in the future to deal with this error having happened?

 				LOG_MSG2("DDebugAgent::NotifyEvent() Problem while suspending thread: %d", err);

 				}

 			// now drop through to the continue case, which typically notifies

 			// the debug agent of the event

 			}

 		case EActionContinue:

 			LOG_MSG("DDebugAgent::NotifyEvent() Continue");

 			// Tell the user about this event

 			if (iEventInfo && iClientThread)

 			{

 				LOG_MSG("Completing event\r\n");

 				// returning the event to the client

 				TInt err = eventInfo.WriteEventToClientThread(iRequestGetEventStatus,iClientThread);

 				if (KErrNone != err)

 				{

 					LOG_MSG2("Error writing event info: %d", err);

 				}

 				// clear this since we've completed the request

 				iEventInfo = NULL;

 				// signal the debugger thread

 				Kern::QueueRequestComplete(iClientThread, iRequestGetEventStatus, KErrNone);

 			}

 			else

 			{

 				LOG_MSG("Queuing event\r\n");

 				QueueEvent(eventInfo);

 			}

 			break;

 		case EActionIgnore:

 		default:

 			LOG_MSG("DDebugAgent::NotifyEvent() fallen through to default case");

 			// Ignore everything we don't understand.

 			return;

 		}

 	}

 // Used to identify which Debug Agent this DDebugAgent is associated with.

 TUint64 DDebugAgent::Id(void)

 	{

 	return iId;

 	}

 // Used to add an event to the event queue for this debug agent

 void DDebugAgent::QueueEvent(TDriverEventInfo& aEventInfo)

 	{

 	// Have we caught the tail?

 	if(BufferFull())

 		{

 		return;

 		}

 	//check to see if we wish to ignore this event - we dump trace events as they are lower priority than the other events

 	if(BufferAtCriticalLevel())

 		{

 		if(aEventInfo.iEventType == EEventsUserTrace)

 			{

 			if(!iIgnoringTrace)

 				{

 				//if this is the first time we are ignoring trace events, we need to issue a EEventsUserTracesLost event

 				aEventInfo.Reset();

 				aEventInfo.iEventType = EEventsUserTracesLost;

 				iIgnoringTrace = ETrue;

 				}

 			else

 				{

 				//otherwise, ignore this event

 				return;

 				}

 			}

 		}

 	else

 		{

 		//reset the iIgnoringTrace flag as we are not at critical level

 		iIgnoringTrace = EFalse; 

 		}	

 	// only one space left so store a EEventsBufferFull event

 	if(!BufferCanStoreEvent())

 		{

 		aEventInfo.Reset();

 		aEventInfo.iEventType = EEventsBufferFull;

 		}

 	__NK_ASSERT_DEBUG(iEventQueue[iHead].iEventType == EEventsUnknown); // we think there is space but the slot is not marked empty

 	// Insert the event into the ring buffer at iHead

 	iEventQueue[iHead] = aEventInfo;

 	IncrementPosition(iHead);

 	}

 // Checks whether the event queue is empty

 TBool DDebugAgent::BufferEmpty() const

 	{

 	return (NumberOfEmptySlots() == NUMBER_OF_EVENTS_TO_QUEUE);

 	}

 // Checks whether the event queue is full

 TBool DDebugAgent::BufferFull() const

 	{

 	return (NumberOfEmptySlots() == 0);

 	}

 // Checks whether there is room in the event queue to store an event (i.e. at least two free slots)

 TBool DDebugAgent::BufferCanStoreEvent() const

 	{

 	return (NumberOfEmptySlots() > 1);

 	}

 //This looks to see if the buffer is close to being full and should only accept higher priority debug events (user trace is the only low priority event) 

 TBool DDebugAgent::BufferAtCriticalLevel() const

 	{

 	return (NumberOfEmptySlots() < NUMBER_OF_EVENTS_TO_QUEUE - CRITICAL_BUFFER_SIZE);

 	}

 // increments aPosition, wrapping at NUMBER_OF_EVENTS_TO_QUEUE if necessary

 void DDebugAgent::IncrementPosition(TInt& aPosition)

 	{

 	aPosition = (aPosition + 1) % NUMBER_OF_EVENTS_TO_QUEUE;

 	}

 // finds the number of empty slots in the event queue

 TInt DDebugAgent::NumberOfEmptySlots() const

 	{

 	if(iHead < iTail)

 		{

 		return (iTail - iHead) - 1;

 		}

 	// iHead >= iTail

 	return NUMBER_OF_EVENTS_TO_QUEUE - (iHead - iTail);

 	}