// 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\include\e32rom.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 __E32ROM_H__

#define __E32ROM_H__

#include <e32cmn.h>

#include <e32def_private.h>

//

#ifndef __SECURITY_INFO_DEFINED__

#define __SECURITY_INFO_DEFINED__

/**

@internalTechnology

*/

//This struct must be identical in size and offset to the one in e32cmn.h

//Functions need not be duplicated.  But must be same structurally.

struct SCapabilitySet

	{

	enum {ENCapW=2};

	TUint32 iCaps[ENCapW];

	inline const TUint32& operator[] (TInt aIndex) const { return iCaps[aIndex]; }

	inline TUint32& operator[] (TInt aIndex) { return iCaps[aIndex]; }

	};

/**

@internalTechnology

*/

//This struct must be identical in size and offset to the one in e32cmn.h

//Functions need not be duplicated.  But must be same structurally.

struct SSecurityInfo

	{

	TUint32	iSecureId;

	TUint32	iVendorId;

	SCapabilitySet iCaps;	

	};

#endif

/**

@internalTechnology

@prototype

*/

struct SDemandPagingConfig

	{

	TUint16 iMinPages;

	TUint16 iMaxPages;

	TUint16 iYoungOldRatio;

	TUint16 iSpare[3];		// iSpare[0:1] are used for emulated rom paging, 

							// iSpare[2] is used for the old to oldest ratio.

	};

/**

@internalTechnology

@prototype

*/

struct SRomPageInfo

	{

	enum TAttributes

		{

		EPageable = 1<<0

		};

	enum TCompression  // todo: compression type not exclusive to rom pages

		{

		ENoCompression,

		EBytePair,

		};

	TUint32 iDataStart;

	TUint16 iDataSize;

	TUint8  iCompressionType;

	TUint8  iPagingAttributes;

	};

/**

@publishedPartner

@released

Defines the size of the header for a ROM image.

@see TRomHeader

*/

const TUint KRomHeaderSize=0x200;

//

/**

@publishedPartner

@released

The format of the header for a ROM image.

This is retained as part of the ROM image.

It is generated by the rombuild tool, and is used by the Bootstrap and

the kernel.

*/

class TRomHeader

	{

public:

	enum { KDefaultDebugPort = -1 };

	enum { KNumTraceMask = 8 };  // this is also defined in e23const.h

__ASSERT_COMPILE(KNumTraceMask==KNumTraceMaskWords);

public:

    /**

    Reserved for a small amount of Bootstrap code, if required.

    The first 4 bytes of the binary image typically contains

    a branch instruction which jumps to code at offset 0x100.

    */

	TUint8 iJump[124]; 

    /**

    The restart vector.

    */	                                     

	TLinAddr iRestartVector;

	/**

	The date and time that the ROM image was built, in microseconds.

	*/

	TInt64 iTime;

	/**

	The high order 32 bits of the ROM image build date & time.

	*/

	TUint32 iTimeHi;

	/**

	The virtual address of the base of the ROM.

	*/

	TLinAddr iRomBase;

	/**

	The size of the ROM image, in bytes.

	This includes the second section for sectioned ROMs.

	*/

	TUint32 iRomSize;

	/**

	The virtual address of the TRomRootDirectoryList structure.

    @see TRomRootDirectoryList 

	*/

	TLinAddr iRomRootDirectoryList;

	/**

	The virtual address of kernel data, when in RAM.

	*/

	TLinAddr iKernDataAddress;

	/**

	The virtual address of the top of the kernel region, when in RAM.

	*/

	TLinAddr iKernelLimit;

	/**

	The virtual address of the primarys ROM file image header.

    @see TRomImageHeader 

	*/

	TLinAddr iPrimaryFile;

	/**

	The virtual address of the secondarys ROM file image header.

	@see TRomImageHeader 

	*/

	TLinAddr iSecondaryFile;

	/**

	A computed constant that causes the 32-bit checksum of the image to equal

	the value specified by the "romchecksum" keyword.

	*/

	TUint iCheckSum;

	/**

	A unique number identifying the hardware for which this ROM image

	has been built.

    Note that this is only used for testing purposes.

	*/

	TUint32 iHardware;

	/**

	A bitmask identifying which of the languages are supported by the ROM image,

	as specified by the "languages" keyword.

    Note that this is only used for testing purposes.

	*/

	TInt64 iLanguage;

	/**

	Contains the flags that define the security options in force.

	@see TKernelConfigFlags

	*/

	TUint32 iKernelConfigFlags;

	/**

	The virtual address of the TRomExceptionSearchTable structure.

	@see TRomExceptionSearchTable

	*/

	TLinAddr iRomExceptionSearchTable;

	/**

	Current size of ROM header (Previously iUnused3)

	If value is 0x69966996 then header size = 0x100

	*/

	TUint32 iRomHeaderSize;

	/**

	The virtual address of the ROM section header, if the ROM is sectioned.

	@see TRomSectionHeader

	*/

	TLinAddr iRomSectionHeader;

	/**

	The total supervisor data size, i.e. the amount of memory mapped for

	the kernel data chunk.

	*/

	TInt iTotalSvDataSize;

	/**

	The virtual address of the TRomEntry for the Variant file.

	@see TRomEntry

	*/

	TLinAddr iVariantFile;

	/**

	The virtual address of TRomEntry for the first extension file, if it exists.

	If there is more than one extension, then the next extension field in

	the extensions TRomImageHeader points to the TRomEntry for

	that next extension.

    @see TRomImageHeader::iNextExtension

   	@see TRomImageHeader

	@see TRomEntry

	*/

	TLinAddr iExtensionFile;

	/**

	The virtual adress of the first area to be relocated into RAM, as defined

	using the "area" keyword.

	*/

	TLinAddr iRelocInfo;

	/**

	The old position of the kernel trace mask, see iTraceMask below

	*/

	TUint32  iOldTraceMask;		// The old location of the kernel tracemask

	/**

	The virtual address of the user data area.

	*/

	TLinAddr iUserDataAddress;	// non-MMU stuff

	/**

	The total size of the user data.

	*/

	TInt iTotalUserDataSize;	// non-MMU stuff

	/**

	A value that is interpreted by the Bootstrap and kernel as the debug port

	to be used.

	*/

	TUint32 iDebugPort;			// semantic is ASSP-specific

	/**

	The ROM version number.

	*/

	TVersion iVersion;

	/**

	The type of compression used for the image.

	This is a UID, or 0 if there is no compression.

	*/

	TUint32 iCompressionType;	// compression type used

	/**

	The size of the image after compression.

	*/

	TUint32 iCompressedSize;	// Size after compression

	/**

	The size of the image before compression.

	*/

	TUint32 iUncompressedSize;	// Size before compression

	/**

	*/

	TUint32 iDisabledCapabilities[2];   // 2==SSecurityInfo::ENCapW

	/**

	The initial value for the kernel trace masks.

	*/

	TUint32  iTraceMask[KNumTraceMask];  // The kernel debug trace masks

	/**

	Initial values for fast-trace filter.

	*/

	TUint32 iInitialBTraceFilter[8];

	/**

	Initial value for size of fast-trace buffer.

	*/

	TInt iInitialBTraceBuffer;

	/**

	Initial value for size of fast-trace mode.

	*/

	TInt iInitialBTraceMode;

	/**

	Offset, in bytes from ROM start, for the start of the pageable ROM area.

	*/

	TInt iPageableRomStart;

	/**

	Size, in bytes, of the pageable ROM area.

	*/

	TInt iPageableRomSize;

	/**

	Offset, in bytes from ROM start, for the page index. (Array of SRomPageInfo objects.)

	@internalTechnology

	@prototype

	*/

	TInt iRomPageIndex;

	/**

	@internalTechnology

	@prototype

	*/

	SDemandPagingConfig iDemandPagingConfig;

	/**

	Offset, in bytes from ROM start, for the start of compressed un-paged ROM area

	@internalTechnology

	@prototype

	*/

	TUint32 iCompressedUnpagedStart;

	/**

	Size, in bytes of the un-paged part of image after compression.

	@internalTechnology

	@prototype

	*/

	TUint32 iUnpagedCompressedSize;

	/**

	Size, in bytes of the un-paged part of image before compression.

	@internalTechnology

	@prototype

	*/

	TUint32 iUnpagedUncompressedSize;

	/**

	The virtual address at which the start of the HCR repository file is located in the unpaged part of the Core ROM Image.

	@internalTechnology

	@prototype

	*/

	TUint32 iHcrFileAddress;

	/**

	@internalComponent

	*/

	TUint32 iSpare[36];   // spare : force size to be correct

	};

__ASSERT_COMPILE(sizeof(TRomHeader)==KRomHeaderSize);

__ASSERT_COMPILE(SCapabilitySet::ENCapW==2); // TRomHeader::iDisabledCapabilities has hard coded 2 because h2inc.pl does not parse scoped identifiers

/**

@publishedPartner

@released

Contains information about a root directory.

A variable number of these are contained in a TRomRootDirectoryList structure.

@see TRomRootDirectoryList

*/

class TRootDirInfo

	{

public:

    /**

    The hardware variant for this root directory entry.

    */

	TUint iHardwareVariant;

	/**

	The virtual address of the root directory.

	@see TRomDir

	*/

	TLinAddr iAddressLin;

	};

/**

@publishedPartner

@released

A structure that allows you to find the root directories for each hardware

Variant supported by the ROM.

Usually, there is only one Variant and one root directory. However, a ROM can

have multiple root directories and directory trees, one for each hardware Variant

supported by the ROM. This ensures that the file server only sees the files

that are relevant to the hardware on which it is running. In this case, there

are multiple entries in the table describing each root directory.

*/

class TRomRootDirectoryList

	{

public:

    /**

    The number of root directory entries.

    */

	TInt iNumRootDirs;

	/**

	The root directory entries.

    The number of entries is defined by iNumRootDirs.

	*/

	TRootDirInfo iRootDir[1];

	};

/**

@publishedPartner

@released

The format of a ROM section header.

*/

class TRomSectionHeader

	{

public:

    /**

    The ROM version number.

    */

	TVersion iVersion;

	/**

	A computed constant that causes the 32-bit checksum of the upper

	section to equal zero.

	Upper sections checksum to zero so that the overall ROM checksum in

	the TRomHeader is unaffected by changes to this section.

	@see TRomHeader

	*/

	TUint iCheckSum;

	/**

	The date and time that the ROM image was built, in microseconds.

	*/

	TInt64 iTime;

	/**

	A bitmask identifying which of the languages are supported by the ROM image,

	as specified by the "languages" keyword.