// 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);
	}