// Copyright (c) 1995-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\execs.txt

/*

Description file declaring all executive calls

Syntax:

<TYPE>	{

	keyword1 [= argument1]

	keyword2 [= argument2]

	...

}

where <TYPE> is either fast or slow and indicates the type of executive call

and the keywords describe the executive call. Keywords may take a single argument

(shown in square brackets above.)

In the following table, the first line specifies the keyword name and any synonyms,

applicability to fast or slow executive calls and whether an argument is required,

is optional or is not used. For example

KEYWORD(SYNONYM) FAST SLOW ARG	KEYWORD applies to fast and slow and always takes

								an argument. SYNONYM is a synonym for KEYWORD.

KEYWORD SLOW					KEYWORD applies only to slow and never takes an

								argument.

KEYWORD SLOW OPTIONAL			KEYWORD applies only to slow and may or may not

								take an argument.

Note that any unambiguous abbreviation of a keyword is also acceptable.

The following keywords are supported:

name	FAST SLOW ARG

	Specifies generic name for the executive call

	Unless overridden by other options:

		enumerator name is EExec<name> or EFastExec<name>

		user function name is Exec::<name>

		kernel function name is ExecHandler::<name>

	The class definitions for Exec:: and ExecHandler:: classes are generated.

	No other function declarations are generated.

number	FAST SLOW ARG

	Specify that a particular dispatch number should be used for this call

user	FAST SLOW ARG

	Override the name of the user-side executive function

	Usable in the following ways:

	user=CLASS			Function name is CLASS::<name>

	user=::FUNC			Function name is FUNC

	user=CLASS::FUNC	Function name is CLASS::FUNC

	user=special		Don't generate either a declaration or a definition

						for the user side function.

specialuser	FAST SLOW

	Generate a declaration for the user side function if it's in the Exec::

	class but don't generate a definition.

kernel	FAST SLOW ARG

	Override the name of the kernel-side executive function

	Usable in the following ways:

	kernel=CLASS		Function name is CLASS::<name>

	kernel=::FUNC		Function name is FUNC

	kernel=CLASS::FUNC	Function name is CLASS::FUNC

	kernel=special		Don't generate either a declaration or a definition

						for the kernel side function. Only applicable to fast

						executive call number 0.

specialkernel	FAST SLOW ARG

	Override the function name in the kernel dispatch table but leave the

	declaration in class ExecHandler:: unchanged.

export	FAST SLOW

	Export the user side executive function.

return	FAST SLOW ARG

	Set the return type. If this keyword is not present, defaults to void.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

arg1	FAST SLOW ARG

	Specify the type of argument 1. If handle lookup is being used this can be

	omitted and will be defaulted to TInt.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

arg2	SLOW ARG

	Specify the type of argument 2.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

arg3	SLOW ARG

	Specify the type of argument 3.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

arg4	SLOW ARG

	Specify the type of argument 4.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

karg1	FAST SLOW ARG

	Override the type of argument 1 on the kernel side. By default is the same

	as arg1. If handle lookup is being used this can be omitted and will be

	defaulted to Dxxxx* as appropriate to the type of handle.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

karg2	SLOW ARG

	Override the type of argument 2 on the kernel side. By default is the same

	as arg2.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

karg3	SLOW ARG

	Override the type of argument 3 on the kernel side. By default is the same

	as arg3.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

karg4	SLOW ARG

	Override the type of argument 4 on the kernel side. By default is the same

	as arg4.

	NOTE:	Only simple types (i.e. 32 bit integers, pointers and references)

			are permitted.

unprotected	SLOW

	Specify that no locking or unlocking or handle lookup should be done in the

	executive call dispatcher. May be omitted since it is the default option.

lock	SLOW

	Specify that the system lock should be held on the way in to the executive

	call and should be released on the way out.

norelease (nr)	SLOW

	This is used in conjunction with the lock or handle keywords to specify that

	the system lock should not be released on exit from the kernel function.

	The system lock will still be acquired on entry.

handle	SLOW ARG

	Specify that the first argument is a handle which should be translated into

	a pointer to a DObject-derived class on the way in to the executive call.

	This keyword automatically enables the lock keyword. It also automatically

	sets the type of the first argument on both user and kernel side.

	The argument specifies the type of object referred to by the handle. The

	following values are accepted (synonyms in brackets):

		thread

		process

		chunk

		library

		semaphore

		mutex

		timer

		server

		session

		logicaldevice		(ldevice)

		physicaldevice		(pdevice)

		logicalchannel		(channel)

		changenotifier		(chnotifier)

		undertaker

		msgqueue

		property

		condvar

		shpool

		shbuf

		any

	As with keywords, any unambiguous abbreviation will be accepted.

	The following keywords indicate IPC handle lookups:

		ipcmessaged

		ipcmessage

		ipcclient

asm		FAST SLOW OPTIONAL

	Specifies that the kernel side function is implemented in assembler and

	that an assembler label should be called rather than a C++ function.

	The assembler label used is always _asm_exec_<name> where <name> is the

	argument of the name keyword. It is not overridden by the kernel or

	specialkernel keywords.

	If an argument is supplied to the asm keyword it specifies a preprocessor

	macro name which is used to conditionally enable the use of assembler,

	for example:

	asm = __MESSAGE_MACHINE_CODED__

	will give rise to

	#ifdef __MESSAGE_MACHINE_CODED__

	DECLARE_ASM_FUNC(<assembler label>, <C++ name>)

	#else

	DECLARE_FUNC(<C++ name>)

	#endif

	Note that the C++ name is still supplied to the assembler declaration macro

	so that targets which don't support the use of assembler labels can revert

	to the C++ name.

ifdef	FAST SLOW ARG

	Specifies that this executive call only exists if ARG is defined at compile

	time. Can be specified multiple times with different arguments - in that

	case the executive call is valid only if all the ARGs are defined.

ifndef	FAST SLOW ARG

	Specifies that this executive call only exists if ARG is not defined at

	compile	time. Can be specified multiple times with different arguments - in

	that case the executive call is valid only if none of the ARGs are defined.

	Can also be used in conjunction with the ifdef keyword. The executive call

	is then valid only if all the ifdef arguments and none of the ifndef

	arguments are defined.

hw (noemulator)	FAST SLOW

	Specifies that this executive call is only valid on hardware targets, not

	emulator targets. Will be treated as an invalid executive call on emulator

	targets. Equivalent to ifdef = __EPOC32__.

emulator	FAST SLOW

	Specifies that this executive call is only valid on emulator targets, not

	hardware targets. Will be treated as an invalid executive call on hardware

	targets. Equivalent to ifndef = __EPOC32__.

extended	SLOW ARG

	Specifies that this executive call uses the extended argument passing

	mechanism. The argument to this keyword specifies the number of extended

	arguments and must be between 2 and 8 inclusive.

	There must be at least 3 normal arguments to use this keyword.

*/

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

 * Fast executive calls

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

fast {

	name = WaitForAnyRequest

	return = void

	number = 0

	kernel = special

}

fast {

	name = Heap

	return = RAllocator*

}

fast {

	name = HeapSwitch

	return = RAllocator*

	arg1 = RAllocator*

}

fast {

	name = PushTrapFrame

	return = TTrapHandler*

	arg1 = TTrap*

}

fast {

	name = PopTrapFrame

	return = TTrap*

}

fast {

	name = ActiveScheduler

	return = CActiveScheduler*

}

fast {

	name = SetActiveScheduler

	arg1 = CActiveScheduler*

}

fast {

	name = LockPeriod

	return = TTimerLockSpec

}

fast {

	name = TrapHandler

	return = TTrapHandler*

}

fast {

	name = SetTrapHandler

	return = TTrapHandler*

	arg1 = TTrapHandler*

}

fast {

	name = DebugMask

	return = TUint32

}

fast {

	name = DebugMaskIndex

	return = TUint32

	arg1 = TUint

}

fast {

	name = SetDebugMask

   	arg1 = TUint32

}

fast {

	name = FastCounter

	return = TUint32

	kernel = NKern::FastCounter

}

fast {

	name = NTickCount

	return = TUint32

	kernel = NKern::TickCount

}

fast {

	name = LockRamDrive

	user = UserSvr

	kernel = TInternalRamDrive::Lock

	export

}

fast {

	name = UnlockRamDrive

	user = UserSvr

	export

}

fast {

	name = RomHeaderAddress

	user = UserSvr

	export

	return = TLinAddr

	hw

}

fast {

	name = RomRootDirectoryAddress

	user = UserSvr

	export

	return = TLinAddr

	hw

}

fast {

	name = SetReentryPoint

	arg1 = TLinAddr

}

fast {

	name = KernelConfigFlags

	kernel = K::KernelConfigFlags

	return = TUint32

}

fast {

	name = UTCOffset

	return = TInt

}

fast {

	name = GetGlobalUserData

	arg1 = TInt

	return = TInt

}

fast {

	name = CheckFilter

	user = BTrace

	kernel = BTrace::CheckFilter

	arg1 = TUint32

	return = TBool

	export

}

fast {

	name = FastAtomicAxo64

	arg1 = SAtomicOpInfo64*

	ifdef = __ATOMIC64_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicCas64

	arg1 = SAtomicOpInfo64*

	return = TBool

	ifdef = __ATOMIC64_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAdd64

	arg1 = SAtomicOpInfo64*

	ifdef = __ATOMIC64_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicTau64

	arg1 = SAtomicOpInfo64*

	ifdef = __ATOMIC64_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicTas64

	arg1 = SAtomicOpInfo64*

	ifdef = __ATOMIC64_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAxo32

	arg1 = SAtomicOpInfo32*

	return = TUint32

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAdd32

	arg1 = SAtomicOpInfo32*

	return = TUint32

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicCas32

	arg1 = SAtomicOpInfo32*

	return = TBool

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicTau32

	arg1 = SAtomicOpInfo32*

	return = TUint32

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicTas32

	arg1 = SAtomicOpInfo32*

	return = TInt32

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAxo16

	arg1 = SAtomicOpInfo32*

	return = TUint16

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAdd16

	arg1 = SAtomicOpInfo32*

	return = TUint16

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicCas16

	arg1 = SAtomicOpInfo32*

	return = TBool

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicTau16

	arg1 = SAtomicOpInfo32*

	return = TUint16

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicTas16

	arg1 = SAtomicOpInfo32*

	return = TInt16

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAxo8

	arg1 = SAtomicOpInfo32*

	return = TUint8

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {

	name = FastAtomicAdd8

	arg1 = SAtomicOpInfo32*

	return = TUint8

	ifdef = __ATOMIC_USE_FAST_EXEC__

	user = special

}

fast {