// Copyright (c) 1998-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\include\nkern\nkern.h

// 

// WARNING: This file contains some APIs which are internal and are subject

//          to change without notice. Such APIs should therefore not be used

//          outside the Kernel and Hardware Services package.

//

#ifndef __NKERN_H__

#define __NKERN_H__

#ifdef	__STANDALONE_NANOKERNEL__

#undef	__IN_KERNEL__

#define	__IN_KERNEL__

#endif

#include <e32const.h>

#include <nklib.h>

#include <dfcs.h>

#include <nk_trace.h>

#include <e32atomics.h>

extern "C" {

/** @internalComponent */

IMPORT_C void NKFault(const char* file, TInt line);

/** @internalComponent */

void NKIdle(TUint32 aStage);

}

/**

@publishedPartner

@released

*/

#define FAULT()		NKFault(__FILE__,__LINE__)

#ifdef _DEBUG

/**

@publishedPartner

@released

*/

#define __NK_ASSERT_DEBUG(c)	((void) ((c)||(FAULT(),0)) )

#else

#define __NK_ASSERT_DEBUG(c)

#endif

/**

@publishedPartner

@released

*/

#define __NK_ASSERT_ALWAYS(c)	((void) ((c)||(FAULT(),0)) )

/**

	@publishedPartner

	@released

*/

const TInt KNumPriorities=64;

const TInt KMaxCpus=8;

class NThread;

/** Spin lock

	Used for protecting a code fragment against both interrupts and concurrent

	execution on another processor.

	@internalComponent

*/

class TSpinLock

	{

public:

	enum TOrder

		{

		// Bit 7 of order clear for locks used with interrupts disabled

		EOrderGenericIrqLow0	=0x00u,	// Device driver spin locks, low range

		EOrderGenericIrqLow1	=0x01u,	// Device driver spin locks, low range

		EOrderGenericIrqLow2	=0x02u,	// Device driver spin locks, low range

		EOrderGenericIrqLow3	=0x03u,	// Device driver spin locks, low range

		EOrderGenericIrqHigh0	=0x18u,	// Device driver spin locks, high range

		EOrderGenericIrqHigh1	=0x19u,	// Device driver spin locks, high range

		EOrderGenericIrqHigh2	=0x1Au,	// Device driver spin locks, high range

		EOrderGenericIrqHigh3	=0x1Bu,	// Device driver spin locks, high range

		// Bit 7 of order set for locks used with interrupts enabled, preemption disabled

		EOrderGenericPreLow0	=0x80u,		// Device driver spin locks, low range

		EOrderGenericPreLow1	=0x81u,		// Device driver spin locks, low range

		EOrderGenericPreHigh0	=0x9Eu,		// Device driver spin locks, high range

		EOrderGenericPreHigh1	=0x9Fu,		// Device driver spin locks, high range

		EOrderNone				=0xFFu	// No order check required (e.g. for dynamic ordering)

		};

public:

	IMPORT_C TSpinLock(TUint aOrder);

private:

	volatile TUint64 iLock;

	};

/** Macro to disable interrupts and acquire the lock.

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_IRQ(lock)					((void)NKern::DisableAllInterrupts())

/** Macro to release the lock and enable interrupts.

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_IRQ(lock)					(NKern::EnableAllInterrupts())

/** Macro to see if someone else is waiting for the lock, enabling IRQs 

    then disabling IRQs again.

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_IRQ(lock)					(NKern::EnableAllInterrupts(),(void)NKern::DisableAllInterrupts(),((TBool)TRUE))

/** Macro to remember original interrupt state then disable interrupts 

    and acquire the lock.

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_IRQSAVE(lock)				(NKern::DisableAllInterrupts())

/** Macro to release the lock then restore original interrupt state to that 

	supplied.

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_IRQRESTORE(lock,irq)		(NKern::RestoreInterrupts(irq))

/** Macro to see if someone else is waiting for the lock, enabling IRQs to

	the original state supplied then disabling IRQs again.

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_IRQRESTORE(lock,irq)		(NKern::RestoreInterrupts(irq),((void)NKern::DisableAllInterrupts()),((TBool)TRUE))

/** Macro to acquire the lock. This assumes the caller has already disabled 

    interrupts/preemption. 

	If interrupts/preemption is not disabled a run-time assert will occur

	This is to protect against unsafe code that might lead to same core 

	deadlock.

    In device driver code it is safer to use __SPIN_LOCK_IRQSAVE() instead, 

	although not as efficient should interrupts aleady be disabled for the 

	duration the lock is held.

@publishedPartner

@prototype

*/

#define __SPIN_LOCK(lock)

/** Macro to release the lock, don't change interrupt/preemption state.

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK(lock)

/**

@internalComponent

*/

#define __SPIN_FLASH(lock)						((TBool)FALSE)

/** Macro to see if someone else is waiting for the lock, enabling preemption 

    then disabling it again.

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_PREEMPT(lock)				((TBool)NKern::PreemptionPoint())

/** Read/Write Spin lock

	@internalComponent

*/

class TRWSpinLock

	{

public:

	IMPORT_C TRWSpinLock(TUint aOrder);		// Uses same order space as TSpinLock

private:

	volatile TUint64 iLock;

	};

/**

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_IRQ_R(lock)					((void)NKern::DisableAllInterrupts())

/**

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_IRQ_R(lock)				(NKern::EnableAllInterrupts())

/**

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_IRQ_R(lock)				(NKern::EnableAllInterrupts(),(void)NKern::DisableAllInterrupts(),((TBool)TRUE))

/**

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_IRQ_W(lock)					((void)NKern::DisableAllInterrupts())

/**

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_IRQ_W(lock)				(NKern::EnableAllInterrupts())

/**

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_IRQ_W(lock)				(NKern::EnableAllInterrupts(),(void)NKern::DisableAllInterrupts(),((TBool)TRUE))

/**

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_R(lock)						

/**

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_R(lock)					

/**

@internalComponent

*/

#define __SPIN_FLASH_R(lock)					((TBool)FALSE)

/**

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_W(lock)						

/**

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_W(lock)					

/**

@internalComponent

*/

#define __SPIN_FLASH_W(lock)					((TBool)FALSE)

/**

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_IRQSAVE_R(lock)				(NKern::DisableAllInterrupts())

/**

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_IRQRESTORE_R(lock,irq)	(NKern::RestoreInterrupts(irq))

/**

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_IRQRESTORE_R(lock,irq)		(NKern::RestoreInterrupts(irq),((void)NKern::DisableAllInterrupts()),((TBool)TRUE))

/**

@publishedPartner

@prototype

*/

#define __SPIN_LOCK_IRQSAVE_W(lock)				(NKern::DisableAllInterrupts())

/**

@publishedPartner

@prototype

*/

#define __SPIN_UNLOCK_IRQRESTORE_W(lock,irq)	(NKern::RestoreInterrupts(irq))

/**

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_IRQRESTORE_W(lock,irq)		(NKern::RestoreInterrupts(irq),((void)NKern::DisableAllInterrupts()),((TBool)TRUE))

/**

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_PREEMPT_R(lock)			((TBool)NKern::PreemptionPoint())

/**

@publishedPartner

@prototype

*/

#define __SPIN_FLASH_PREEMPT_W(lock)			((TBool)NKern::PreemptionPoint())

/** Nanokernel fast semaphore

	A light-weight semaphore class that only supports a single waiting thread,

	suitable for the Symbian OS thread I/O semaphore.

	Initialising a NFastSemaphore involves two steps:

	- Constructing the semaphore

	- Setting the semaphore owning thread (the one allowed to wait on it)

	For example, creating one for the current thread to wait on:

	@code

	NFastSemaphore sem;

	sem.iOwningThread = NKern::CurrentThread();

	@endcode

	@publishedPartner

	@released

*/

class NFastSemaphore

	{

public:

	inline NFastSemaphore();

	inline NFastSemaphore(NThreadBase* aThread);

	IMPORT_C void SetOwner(NThreadBase* aThread);

	IMPORT_C void Wait();

	IMPORT_C void Signal();

	IMPORT_C void SignalN(TInt aCount);

	IMPORT_C void Reset();

	void WaitCancel();

public:

	TInt iCount;				/**< @internalComponent */

	/** The thread allowed to wait on the semaphore

		@internalComponent

	*/

	NThreadBase* iOwningThread;	

	};

/** Create a fast semaphore

	@publishedPartner

	@released

*/

inline NFastSemaphore::NFastSemaphore()

	: iCount(0), iOwningThread(NULL)

	{}

/** Nanokernel fast mutex

	A light-weight priority-inheritance mutex that can be used if the following

	conditions apply:

	- Threads that hold the mutex never block.

	- The mutex is never acquired in a nested fashion

	If either of these conditions is not met, a DMutex object is more appropriate.

	@publishedPartner

	@released

*/

class NFastMutex

	{

public:

	IMPORT_C NFastMutex();

	IMPORT_C void Wait();

	IMPORT_C void Signal();

	IMPORT_C TBool HeldByCurrentThread();	/**< @internalComponent */

public:

	NThreadBase* iHoldingThread;	/**< @internalComponent */

	/** MUST ALWAYS BE 0 or 1

		@internalComponent

	*/

	TInt iWaiting;

	};

/**

@publishedPartner

@released

The type of the callback function used by the nanokernel timer. 

@see NTimer

*/

typedef void (*NTimerFn)(TAny*);

/**

@publishedPartner

@released

A basic relative timer provided by the nanokernel.

It can generate either a one-shot interrupt or periodic interrupts.

A timeout handler is called when the timer expires, either:

- from the timer ISR - if the timer is queued via OneShot(TInt aTime) or OneShot(TInt aTime, TBool EFalse), or

- from the nanokernel timer dfc1 thread - if the timer is queued via OneShot(TInt aTime, TBool ETrue) call, or

- from any other dfc thread that provided DFC belongs to - if the timer is queued via OneShot(TInt aTime, TDfc& aDfc) call.

Call-back mechanism cannot be changed in the life time of a timer.

These timer objects may be manipulated from any context.

The timers are driven from a periodic system tick interrupt,

usually a 1ms period.

@see NTimerFn

*/

class NTimer : public SDblQueLink

	{

public:

	/**

	Default constructor.

	*/

	inline NTimer()

		: iState(EIdle)

		{}

	/**

	Constructor taking a callback function and a pointer to be passed

	to the callback function.

	@param aFunction The callback function.

	@param aPtr      A pointer to be passed to the callback function 

	                 when called.

	*/

	inline NTimer(NTimerFn aFunction, TAny* aPtr)

		: iPtr(aPtr), iFunction(aFunction), iState(EIdle)

		{}

	IMPORT_C TInt OneShot(TInt aTime);

	IMPORT_C TInt OneShot(TInt aTime, TBool aDfc);

	IMPORT_C TInt OneShot(TInt aTime, TDfc& aDfc);

	IMPORT_C TInt Again(TInt aTime);

	IMPORT_C TBool Cancel();

	IMPORT_C TBool IsPending();

public:

/**

	@internalComponent

*/

	enum TState

		{

		EIdle=0,			// not queued

		ETransferring=1,	// being transferred from holding to ordered queue

		EHolding=2,			// on holding queue

		EOrdered=3,			// on ordered queue

		ECritical=4,		// on ordered queue and in use by queue walk routine

		EFinal=5,			// on final queue

		};

public:

	/** Argument for callback function or the pointer to TDfc */

	TAny* iPtr;				/**< @internalComponent */

	/** Pointer to callback function. NULL value indicates that queuing of provided Dfc queue will be done

	instead of calling callback function on completion */

	NTimerFn iFunction;		/**< @internalComponent */

	TUint32 iTriggerTime;	/**< @internalComponent */

	TUint8 iCompleteInDfc;	/**< @internalComponent */

	TUint8 iState;			/**< @internalComponent */

	TUint8 iPad1;			/**< @internalComponent */

	/** Available for timer client to use.

		@internalTechnology */

	TUint8 iUserFlags;

	};

/**

@internalTechnology

*/

#define	i_NTimer_iUserFlags	iUserFlags

/**

@internalComponent

*/

#define	i_NTimer_iState		iState

/**

	@publishedPartner

	@released

*/

typedef void (*NThreadFunction)(TAny*);

/**

	@publishedPartner

	@released

*/

typedef TDfc* (*NThreadExitHandler)(NThread*);

/**

	@publishedPartner

	@released

*/

typedef void (*NThreadStateHandler)(NThread*,TInt,TInt);