// 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\include\kernel\kernel.h

// Public header for device drivers

// 

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

#define __K32STD_H__

#include <kernel/klib.h>

#include <e32kpan.h>

#include <u32std.h>

#include <e32ldr.h>

#include <e32ldr_private.h>

#include <e32event.h>

#include <e32event_private.h>

#include <d32locd.h>

#include <kernel/localise.h>

#include <nkern.h>

#include <kernel/sproperty.h>

class DObject;

class DObjectCon;

class DThread;

class DCodeSeg;

class DProcess;

class DLibrary;

class DMutex;

class DSemaphore;

class DChunk;

class DShPool;

class DShBuf;

/** Data type for physical addresses

@publishedPartner

@released

*/

typedef TUint32 TPhysAddr;

/**

A constant representing an invalid physical address.

@publishedPartner

@released

*/

const TPhysAddr KPhysAddrInvalid=0xFFFFFFFFu;

/** @internalComponent */

_LIT(KLitKernExec, "KERN-EXEC");

/********************************************

 * HAL entry array

 ********************************************/

/** @internalTechnology */

const TInt KMaxHalGroups=32;

/**

@publishedPartner

@released

Defines the signature for a HAL handler function.

*/

typedef TInt (*THalFunc)(TAny*,TInt,TAny*,TAny*);

/** @internalTechnology */

const TInt KMaxHalEntries=8;

/** @internalTechnology */

struct SHalEntry

	{

	THalFunc iFunction;

	TAny* iPtr;

	};

/** @internalTechnology */

struct SHalEntry2 : public SHalEntry

	{

	SHalEntry* iExtendedEntries;

	};

/********************************************

 * Exports from layer 1 of the kernel

 ********************************************/

class TThreadMessage;

class DObjectCon;

class DPowerModel;

class TSuperPage;

class TMachineConfig;

/********************************************

 * Thread creation info block

 ********************************************/

/**

@publishedPartner

@released

Defines a set of thread types.

*/

enum TThreadType

	{

	/** The thread is the initial thread

		@internalComponent

	*/

	EThreadInitial,

	/** The thread runs in supervisor mode */

	EThreadSupervisor,

	/** The thread runs in supervisor mode and has no handles array */

	EThreadMinimalSupervisor,

	/** The thread runs in user mode */

	EThreadUser,

	/** The thread is the initial thread on a non-boot processor (SMP only)

		@internalComponent

	*/

	EThreadAPInitial,

	};

/********************************************

 * Kernel Mutex Ordering

 ********************************************/

const TUint8 KMutexOrdNone				= 0xff; /**< @internalComponent */

const TUint8 KMutexOrdUser				= 0xfe; /**< @internalComponent */

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral7			= 0xf7;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral6			= 0xf6;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral5			= 0xf5;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral4			= 0xf4;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral3			= 0xf3;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral2			= 0xf2;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral1			= 0xf1;

/**

Mutex order value for general purpose use. This value is higher than any used internally

by the kernel, therefore there are no mutex ordering restrictions that limit which kernel

functions may be called whilst a mutex of this order is held.

@see Kern::MutexCreate()

@publishedPartner

@released

*/

const TUint8 KMutexOrdGeneral0			= 0xf0;

const TUint8 KMutexOrdRamDrive			= KMutexOrdGeneral7; /**< @internalComponent */

const TUint8 KMutexOrdDmaChannel		= 0x70; /**< @internalComponent */

const TUint8 KMutexOrdShPool			= 0x68; /**< @internalComponent */

const TUint8 KMutexOrdCodeSegLock		= 0x60; /**< @internalComponent */

const TUint8 KMutexOrdPubSub2			= 0x5e; /**< @internalComponent */

/**

@internalComponent

@prototype

*/

const TUint8 KMutexOrdPageIn			= 0x5c;

const TUint8 KMutexOrdRamDefrag			= 0x59; /**< @internalComponent */

const TUint8 KMutexOrdPowerMgr			= 0x58; /**< @internalComponent */

const TUint8 KMutexOrdPubSub			= 0x50; /**< @internalComponent */

const TUint8 KMutexOrdProcessLock		= 0x48; /**< @internalComponent */

const TUint8 KMutexOrdDebug				= 0x47; /**< @internalComponent */

const TUint8 KMutexOrdTimer				= 0x40; /**< @internalComponent */

const TUint8 KMutexOrdObjectCon2		= 0x38;	/**< @internalComponent */ // servers

const TUint8 KMutexOrdHandle			= 0x30; /**< @internalComponent */

const TUint8 KMutexOrdObjectCon			= 0x28; /**< @internalComponent */

const TUint8 KMutexOrdMachineConfig		= 0x20; /**< @internalComponent */

const TUint8 KMutexOrdEntropyPool		= 0x12; /**< @internalComponent */

const TUint8 KMutexOrdRandNumGeneration = 0x11; /**< @internalComponent */

const TUint8 KMutexOrdHwChunk			= 0x10; /**< @internalComponent */

const TUint8 KMutexOrdKernelHeap		= 0x08; /**< @internalComponent */

const TUint8 KMutexOrdRamAlloc			= 0x04; /**< @internalComponent */

#if defined(__MEMMODEL_FLEXIBLE__)

const TUint8 KMutexOrdSyncPhysMem		= 0x03; /**< @internalComponent */

const TUint8 KMutexOrdPageOut			= 0x02; /**< @internalComponent */

#endif

const TUint8 KMutexOrdResourceManager	= 0x01; /**< @internalComponent */

/********************************************

 * Kernel Extension Priority Ordering

 ********************************************/

/**

@internalComponent

@prototype 9.5

*/

const TUint8 KExtensionMaximumPriority = 0xff;

/**

@internalComponent

@prototype 9.5

*/

const TUint8 KExtensionStandardPriority = 0;

/**

Defines a function type that implements a polling operation.

A function of this type takes a single TAny* type argument, and returns

a TBool type, and is passed as an argument to Kern::PollingWait().

@see Kern::PollingWait()

@publishedPartner

@released

*/

typedef TBool (*TPollFunction)(TAny*);

/**

Structure used to specify parameters to Kern::ChunkCreate()

@see Kern::ChunkCreate()

@publishedPartner

@released

*/

class TChunkCreateInfo

    {

public:

    /**

    Enumeration representing the type of chunk to be created.

    */

    enum TType

        {

        /**

        A chunk which may only be opened by one user side process at a time.

        Chunks of this type are slightly more efficient than the 

        ESharedKernelMultiple type when used on the Moving Memory Model.

        */

        ESharedKernelSingle = 9,

        /**

        A chunk which may be opened by any number of user side processes.

        */

        ESharedKernelMultiple = 10,

        };

    /**

    The chunk type to be created.

    @see TChunkCreateInfo::TType

    */

    TType iType;

    /**

    The size of linear address space to reserve for this chunk.

    */

    TInt iMaxSize;

    /**

    Caching attributes for the chunks memory.

    This is a value constructed from the TMappingAttributes values.

    E.g. EMapAttrFullyBlocking (no caching) or EMapAttrCachedMax (full caching).

    Note that if the MMU doesn't support the requested attributes then a lesser

    cached attribute will be used. The actual value used is returned in aMapAttr of

    Kern::ChunkCreate()

    @see TMappingAttributes

    */

    TUint32 iMapAttr;

    /**

    Set to true if the chunk is to own its committed memory. In which case all

    memory committed to the chunk will come from the system's free pool and will be

    returned there when the chunk is destroyed.

    */

    TUint8 iOwnsMemory;

    /**

    @internalComponent

    Reserved for future expansion.

    */

    TInt8 iSpare8[3];

    /**

    Pointer to a DFC which will be queued on destruction of chunk.

    */

    TDfc* iDestroyedDfc;

    /**

    @internalComponent

    Reserved for future expansion.

    */

    TInt32 iSpare32[2];

public:

    /**

    Constructor which zeros all member data.

    */

    inline TChunkCreateInfo()

        { memset(this,0,sizeof(*this)); }

    };

/**

Generic kernel hook function.

@internalComponent

*/

typedef TInt (*TKernelHookFn)();

/**

Available kernel hooks.

@internalComponent

*/

enum TKernelHookType

	{

	EHookTrace,

	EHookNanoWait,

	EHookInitialTime,

	ENumKernelHooks

	};

/*

Specifies the origin of the log when calling trace handler hook.

@publishedPartner

@released

*/

enum TTraceSource

	{

	/**

	User side tracing

	@see User::DebugPrint

	*/

	EUserTrace,

	/**

	Kernel tracing

	@see Kern::Print

	*/

	EKernelTrace,

	/**

	Platform security tracing

	*/

	EPlatSecTrace,

	};

/*

Trace handler hook

@param aText      Debug log. The content of the descriptor resides in kernel memory.

@param aTraceType Identifies the origin of the debug log.

@see TTraceHandlerType

@return Specifies whether the log is processed or not.

        If ETrue,  the log is processed. Kernel will drop the log (it won't be passed to trace port - UART)

        If EFalse, the log is not processed. Kernel will pass the log to the trace port, as well.

@publishedPartner

@released

*/

typedef TBool (*TTraceHandler)(const TDesC8& /*aText*/, TTraceSource /*aTraceSource*/);

/**

Defines the prototype of the kernel hook for the Kern::NanoWait implementation.

@see Kern::NanoWait

@see Kern::SetNanoWaitHandler

@publishedPartner

@released

*/

typedef void (*TNanoWaitHandler)(TUint32 aInterval);

/**

Defines the prototype of the kernel hook to get the initial system time.

The hook is called during boot to get the inital system time.  It should attempt

to read the time from the hardware RTC.  If the contents of the RTC are invalid

it should return KErrCorrupt.

@return The time in seconds from 00:00:00 01-01-2000, or one of the

system-wide error codes.

@see Kern::SetInitialTimeHandler

@see P::InitSystemTime

@publishedPartner

@released

*/

typedef TInt (*TInitialTimeHandler)();

/**

A thread's realtime state.

Some non-realtime behaviour can be detected by the kernel. When it does so, action is taken

depending on the thread state:

-	ERealtimeStateOff - no action.

-	ERealtimeStateOn - the the thread will be panicked with KERN-EXEC 61 (EIllegalFunctionForRealtimeThread).

-	ERealtimeStateWarn - no action. However, if the kernel trace flag KREALTIME is enabled

	then tracing will be emitted as if the thread state was ERealtimeStateOn.

@publishedPartner

@released

*/

enum TThreadRealtimeState

	{

	ERealtimeStateOff,	/**< Thread is not realtime */

	ERealtimeStateOn,	/**< Thread is realtime */

	ERealtimeStateWarn	/**< Thread is realtime but doesn't want this enforced */

	};

/**

A DFC queue intended to be created and destroyed as needed.

This class extends the TDfcQue class with a destroy method.

@publishedPartner

@released

*/

class TDynamicDfcQue : public TDfcQue

	{

public:

	TDynamicDfcQue();

	IMPORT_C void Destroy();

	IMPORT_C void SetRealtimeState(TThreadRealtimeState aNewState);

private:	

	TDfc iKillDfc;

	};

/**

An object representing an asynchronous request from a user thread, containing a TRequestStatus

pointer.

It can be queued for completion when the thread next returns to user-mode, to move the impact of any

page faults from the thread posting the completion to the thread that made the request.

@publishedPartner

@released

*/

class TClientRequest : public TUserModeCallback

	{

public:

	IMPORT_C TInt SetStatus(TRequestStatus*);

	IMPORT_C void Reset();

	IMPORT_C TRequestStatus* StatusPtr();

	IMPORT_C TBool IsReady();

public:

	void Close();