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

// e32\kernel\sutils.cpp

// 

//

#include <kernel/kern_priv.h>

#include "execs.h"

#include <e32panic.h>

_LIT(KLitDfcThread,"DfcThread");

extern const SNThreadHandlers EpocThreadHandlers;

/**

Adds a HAL entry handling function for the specified group of HAL entries.

@param	aId   The HAL group attribute that this function handles, as defined by

              one of the THalFunctionGroup enumerators.

@param	aFunc Pointer to the handler function

@param	aPtr  Pointer which is passed to the handler function when it is

              called. This is usually a pointer to an object which handles

              the HAL attribute.

@return KErrNone, if successful; KErrArgument if aId is EHalGroupKernel, EHalGroupVariant or EHalGroupPower,

or aId is greater than or equal to KMaxHalGroups; KErrInUse, if a handler is already registered.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked.

@pre No fast mutex can be held.

@pre Call in a thread context.

@pre Suitable for use in a device driver.

@see THalFunctionGroup

@see KMaxHalGroups

*/

EXPORT_C TInt Kern::AddHalEntry(TInt aId, THalFunc aFunc, TAny* aPtr)

	{

	return Kern::AddHalEntry(aId, aFunc, aPtr, 0);

	}

/**

Adds a HAL entry handling function for the specified group of HAL entries.

@param	aId   The HAL group attribute that this function handles, as defined by

              one of the THalFunctionGroup enumerators.

@param	aFunc Pointer to the handler function

@param	aPtr  Pointer which is passed to the handler function when it is

              called. This is usually a pointer to an object which handles

              the HAL attribute.

@param  aDeviceNumber

			  The device number (eg. screen number).

@return KErrNone, if successful; KErrArgument if aId is EHalGroupKernel, EHalGroupVariant or EHalGroupPower,

or aId is greater than or equal to KMaxHalGroups; KErrInUse, if a handler is already registered.

@pre Calling thread must be in a critical section

@pre Interrupts must be enabled.

@pre Kernel must be unlocked.

@pre No fast mutex can be held.

@pre Call in a thread context.

@pre Suitable for use in a device driver.

@see THalFunctionGroup

@see KMaxHalGroups

*/

EXPORT_C TInt Kern::AddHalEntry(TInt aId, THalFunc aFunc, TAny* aPtr, TInt aDeviceNumber)

	{

	CHECK_PRECONDITIONS(MASK_THREAD_CRITICAL,"Kern::AddHalEntry(TInt aId, THalFunc aFunc, TAny* aPtr, TInt aDeviceNumber)");			

	__KTRACE_OPT(KEXTENSION,Kern::Printf("Kern::AddHalEntry %d %08x %08x",aId,aFunc,aPtr));

	if (aId==(TInt)EHalGroupKernel || aId==(TInt)EHalGroupVariant || aId==(TInt)EHalGroupPower || aId>=KMaxHalGroups || (TUint)aDeviceNumber>=(TUint)KMaxHalEntries)

		return KErrArgument;

	TInt r=KErrInUse;

	if (aDeviceNumber>0)

		{

		TBool delete_entry = EFalse;

		NKern::LockSystem();

		SHalEntry2* p = &K::HalEntryArray[aId];

		SHalEntry* extended_entry = p->iExtendedEntries;

		if(!extended_entry)

			{

			NKern::UnlockSystem();

			extended_entry = (SHalEntry*)Kern::AllocZ((KMaxHalEntries-1)*sizeof(SHalEntry));

			if(!extended_entry)

				return KErrNoMemory;

			NKern::LockSystem();

			if(!p->iExtendedEntries)

				p->iExtendedEntries = extended_entry;

			else

				delete_entry = ETrue;

			}

		if(!extended_entry[aDeviceNumber-1].iFunction)

			{

			extended_entry[aDeviceNumber-1].iFunction = aFunc;

			extended_entry[aDeviceNumber-1].iPtr = aPtr;

			r = KErrNone;

			}

		NKern::UnlockSystem();

		if(delete_entry)

			Kern::Free(extended_entry);

		}

	else

		{

		NKern::LockSystem();

		SHalEntry2& e=K::HalEntryArray[aId];

		if (!e.iFunction)

			{

			e.iFunction=aFunc;

			e.iPtr=aPtr;

			r=KErrNone;

			}

		NKern::UnlockSystem();

		}

	__KTRACE_OPT(KEXTENSION,Kern::Printf("Kern::AddHalEntry returns %d",r));

	return r;

	}

/**

Removes a HAL entry handling function for the specified group of HAL entries.

@param	aId The HAL group attribute, as defined by one of the THalFunctionGroup

            enumerators, for which the handler function is to be removed.

@return KErrNone, if successful; KErrArgument if aId is EHalGroupKernel,

                  EHalGroupVariant or EHalGroupMedia, or aId is greater than

                  or equal KMaxHalGroups.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked.

@pre No fast mutex can be held.

@pre Call in a thread context.

@pre Can be used in a device driver.

@see THalFunctionGroup

@see KMaxHalGroups

*/

EXPORT_C TInt Kern::RemoveHalEntry(TInt aId)

	{

	return Kern::RemoveHalEntry(aId,0);

	}

/**

Removes a HAL entry handling function for the specified group of HAL entries.

@param	aId The HAL group attribute, as defined by one of the THalFunctionGroup

            enumerators, for which the handler function is to be removed.

@param  aDeviceNumber The device number (eg. screen number)

@return KErrNone, if successful; KErrArgument if aId is EHalGroupKernel,

                  EHalGroupVariant or EHalGroupMedia, or aId is greater than

                  or equal KMaxHalGroups.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked.

@pre No fast mutex can be held.

@pre Call in a thread context.

@pre Can be used in a device driver.

@see THalFunctionGroup

@see KMaxHalGroups

*/

EXPORT_C TInt Kern::RemoveHalEntry(TInt aId, TInt aDeviceNumber)

	{

	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::RemoveHalEntry(TInt aId, TInt aDeviceNumber)");			

	__KTRACE_OPT(KEXTENSION,Kern::Printf("Kern::RemoveHalEntry %d %d",aId,aDeviceNumber));

	if (aId<(TInt)EHalGroupPower || aId>=KMaxHalGroups || (TUint)aDeviceNumber>=(TUint)KMaxHalEntries)

		return KErrArgument;

	NKern::LockSystem();

	SHalEntry2* pE=&K::HalEntryArray[aId];

	if(aDeviceNumber>0)

		{

		SHalEntry* pBase=pE->iExtendedEntries;

		if(pBase)

			{

			pBase[aDeviceNumber-1].iFunction=NULL;

			pBase[aDeviceNumber-1].iPtr=NULL;

			}

		}

	else

		{		

		pE->iFunction=NULL;

		pE->iPtr=NULL;

		}

	NKern::UnlockSystem();

	return KErrNone;

	}

/**

Gets the HAL entry handling function for the specified group of HAL entries.

@param	aId The HAL group attribute, as defined by one of the THalFunctionGroup

            enumerators, for which the handler function is required.

@return A pointer to handler information containing the handler function; NULL

        if aId is negative or is greater than or equal to KMaxHalGroups, or no

        handler function can be found.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked.

@pre No fast mutex can be held.

@pre Call in a thread context.

@pre Can be used in a device driver.

@see THalFunctionGroup

@see KMaxHalGroups

*/

EXPORT_C SHalEntry* Kern::FindHalEntry(TInt aId)

	{

	return Kern::FindHalEntry(aId,0);

	}

/**

Gets the HAL entry handling function for the specified group of HAL entries.

@param	aId The HAL group attribute, as defined by one of the THalFunctionGroup

            enumerators, for which the handler function is required.

@param  aDeviceNumber The device number (eg. screen number)

@return A pointer to handler information containing the handler function; NULL

        if aId is negative or is greater than or equal to KMaxHalGroups, or no

        handler function can be found.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked.

@pre No fast mutex can be held.

@pre Call in a thread context.

@pre Can be used in a device driver.

@see THalFunctionGroup

@see KMaxHalGroups

*/

EXPORT_C SHalEntry* Kern::FindHalEntry(TInt aId, TInt aDeviceNumber)

	{

	CHECK_PRECONDITIONS(MASK_THREAD_STANDARD,"Kern::FindHalEntry(TInt aId, TInt aDeviceNumber)");			

	__KTRACE_OPT(KEXTENSION,Kern::Printf("Kern::FindHalEntry %d %d",aId,aDeviceNumber));

	if (aId<0 || aId>=KMaxHalGroups || TUint(aDeviceNumber)>=TUint(KMaxHalEntries))

		return NULL;

	SHalEntry2* p=&K::HalEntryArray[0]+aId;

	SHalEntry* pBase=(SHalEntry*)p;

	if(aDeviceNumber>0)

		{

		if(p->iExtendedEntries)

			pBase=p->iExtendedEntries + (aDeviceNumber-1);

		}

	if(!pBase->iFunction)

		return NULL;

	return pBase;

	}

/**

Returns the active debug mask obtained by logically ANDing the global debug mask

in the super page with the per-thread debug mask in the current DThread object.

If the current thread is not a symbian OS thread the global debug mask is used.

Only supports the first 32 global debug trace bits.

@return The debug mask.

*/

EXPORT_C TInt KDebugMask()

	{

	TInt m=TheSuperPage().iDebugMask[0];

	NThread* nt = NCurrentThread();

	if (nt && nt->iHandlers==&EpocThreadHandlers)

		m &= TheCurrentThread->iDebugMask;

	return m;

	}

/**

Returns the state (ETrue or EFalse) of given bit in the active debug mask

which is obtained by logically ANDing the global debug mask in the super page 

with the per-thread debug mask in the current DThread object.

If the current thread is not a symbian OS thread the global debug mask is used.

@return The state of the debug mask bit number.

*/

EXPORT_C TBool KDebugNum(TInt aBitNum)

	{

	TInt m = 0;

	// special case for KALWAYS

	if (aBitNum == KALWAYS)

		{

		m = TheSuperPage().iDebugMask[0] ||

			TheSuperPage().iDebugMask[1] ||

			TheSuperPage().iDebugMask[2] ||

			TheSuperPage().iDebugMask[3] ||

			TheSuperPage().iDebugMask[4] ||

			TheSuperPage().iDebugMask[5] ||

			TheSuperPage().iDebugMask[6] ||

		    TheSuperPage().iDebugMask[7];

		}

	else if  ( (aBitNum > KMAXTRACE) || (aBitNum < 0) )

		m = 0;

	else

		{

		TInt index = aBitNum >> 5;

		m = TheSuperPage().iDebugMask[index];

		m &= 1 << (aBitNum & 31);

		if (!index)

			{

			// if index is zero then AND in the per thread debug mask

			NThread* nt = K::Initialising ? 0 : NCurrentThread();

			if (nt && nt->iHandlers==&EpocThreadHandlers)

				m &= TheCurrentThread->iDebugMask;

			}

		}

	return (m != 0);

	}

/**

Prints a formatted string on the debug port.

The function uses Kern::AppendFormat() to do the formatting.

Although it is safe to call this function from an ISR, it polls the output

serial port and may take a long time to complete, invalidating any

real-time guarantee.

If called from an ISR, it is possible for output text to be intermingled

with other output text if one set of output interrupts or preempts another.

Some of the formatting options may not work inside an ISR.

Be careful not to use a string that is too long to fit onto the stack.

@param aFmt The format string. This must not be longer than 256 characters.

@param ...	A variable number of arguments to be converted to text as dictated

            by the format string.

@pre Calling thread can either be in a critical section or not.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked

@pre Call in any context.

@pre Suitable for use in a device driver

@see Kern::AppendFormat()

*/

EXPORT_C void Kern::Printf(const char* aFmt, ...)

	{

	TBuf8<256> printBuf;

	VA_LIST list;

	VA_START(list,aFmt);

	Kern::AppendFormat(printBuf,aFmt,list);

	K::TextTrace(printBuf,EKernelTrace);

	}

void AppendNumBuf(TDes8& aDes, const TDesC8& aNum, TInt width, char fill)

	{

	TInt l=aNum.Length();

	for (; l<width; ++l)

		aDes.Append(TChar(fill));

	aDes.Append(aNum);

	}

/**

Formats and appends text to the specified narrow descriptor without making any

executive calls.

The function takes a format string and a variable number of arguments. The

format specifiers in the format string are used to interpret and the arguments.

Format directives have the following syntax:

@code

<format-directive> ::= 

	"%" [<padding-character>] [<field-width>] [<long-flag>] <conversion-specifier>

@endcode

If a field width is specified and the width of the formatted field is less

than this width, then the field is padded with the padding character.

The only supported padding characters are ' ' (default) and '0'.

The long flag specifier ('l') modifies the semantic of the conversion

specifier as explained below.

The possible values for the conversion specifiers, the long flag and the way in

which arguments are interpreted, are as follows:

@code

d	Interpret the argument as a TInt decimal representation

ld	NOT SUPPORTED - use lx instead

u	Interpret the argument as a TUint decimal representation

lu	NOT SUPPORTED - use lx instead

x	Interpret the argument as a TUint hexadecimal representation

X	As above

lx	Interpret the argument as a Uint64 hexadecimal representation

lX	As above

c	Interpret the argument as a character

s	Interpret the argument as a pointer to narrow C string

ls	Interpret the argument as a pointer to narrow C string

S 	Interpret the argument as a pointer to narrow descriptor or NULL

lS	NOT SUPPORTED - use S instead

O	Interpret the argument as a pointer to DObject or NULL 

	Generates the object full name or 'NULL'

o	Interpret the argument as a pointer to DObject or NULL

	Generates the object name or 'NULL'

M	Interpret the argument as a pointer to a fast mutex or NULL

	Generates the name, if this is a well-known fast mutex, address otherwise

m	Interpret the argument as a pointer to a fast semaphore or NULL

	Generates the owning thread name, if this is a well-known fast semaphore, address otherwise

T	Interpret the argument as a pointer to a nanothread or NULL 

	Generates the full name, if this is a Symbian OS thread, address otherwise

C	Interpret the argument as a pointer to a DCodeSeg or NULL

	Generates the filename and module version number

G	Interpret the argument as a pointer to a nanothread group or NULL 

	Generates the full name if this corresponds to a Symbian OS process, address otherwise

@endcode

The function can be called from the interrupt context, but extreme caution is advised as it

may require a lot of stack space and interrupt stacks are very small.

@param aDes 	Narrow descriptor that must be big-enough to hold result

@param aFmt 	The format string

@param aList 	A variable number of arguments to be converted to text as dictated by the format string

@pre Calling thread can be either in a critical section or not.

@pre Interrupts must be enabled.

@pre Kernel must be unlocked

@pre Call in any context.

@pre Suitable for use in a device driver

@panic The set of panics that can be raised when appending data to descriptors.

@see   TDes8

*/

EXPORT_C void Kern::AppendFormat(TDes8& aDes, const char* aFmt, VA_LIST aList)

	{

#define NEXT_FMT(c,p) if (((c)=*(p)++)==0) return

	_LIT8(NullDescriptor,"(null)");

	_LIT8(KLitNULL,"NULL");

	_LIT8(KLitSysLock,"SysLock");

	_LIT8(KLitObjLock,"ObjLock");

	_LIT8(KLitMsgLock,"MsgLock");

	_LIT8(KLitLogonLock,"LogonLock");

	_LIT8(KLitMiscNtfMgrLock,"MiscNtfMgrLock");

	TBuf8<24> NumBuf;

	FOREVER

		{

		char c;

		NEXT_FMT(c,aFmt);

		if (c=='%')

			{

			char fill=' ';

			TInt width=0;

			TBool long_arg=EFalse;

			TBool ok=ETrue;

			NEXT_FMT(c,aFmt);

			if (c=='0')

				{

				fill='0';

				NEXT_FMT(c,aFmt);

				}

			while(c>='0' && c<='9')

				{

				width=width*10+c-'0';

				NEXT_FMT(c,aFmt);

				}

			if (c=='l')

				{

				long_arg=ETrue;

				NEXT_FMT(c,aFmt);

				}

			switch(c)

				{

				case 'd':

					{

					if (long_arg)

						ok=EFalse;

					else

						{

						TInt val=VA_ARG(aList,TInt);

						NumBuf.Num(val);

						AppendNumBuf(aDes,NumBuf,width,fill);

						}

					break;

					}

				case 'u':

					{

					if (long_arg)

						ok=EFalse;

					else

						{

						TUint val=VA_ARG(aList,TUint);

						NumBuf.Num(val,EDecimal);

						AppendNumBuf(aDes,NumBuf,width,fill);

						}

					break;

					}

				case 'x':

				case 'X':

					{

					if (long_arg)

						{

						Uint64 val=VA_ARG(aList,Uint64);

						TUint vl=(TUint)val;

						TUint vh=(TUint)(val>>32);

						if (vh)

							{

							NumBuf.Num(vh,EHex);